Automatic conversion to xdoc of th remaining legacy documentation in
  the ACL2 community books
November 24, 2014
Matt Kaufmann

The data in this directory can give a sense of how to convert legacy
documentation strings in ACL2 to defxdoc forms.

First, I created subdirectories output-raw and output, as well as a
saved executable by starting ACL2(h) and running these forms:

(include-book "system/doc/convert-legacy-doc/export-acl2doc" :dir :system
              :ttags (:open-output-channel))
:q
(save-exec "my-acl2" "Includes export-acl2doc")

I ran the following command at the shell to find the files that have
legacy doc strings, and used the output to create file convert.lsp:

grep -i '^[^;]*":doc-section' `find . -name "*.lisp"` | fgrep -v acl2-doc.lisp

Next, I executed the forms in convert.lsp, with a new ./my-acl2
session for each call of xdoc::make-xdoc-file.  This wrote a file
containing xdoc forms to the :out argument of xdoc::make-xdoc-file.

Then, after loading Emacs file
books/system/doc/convert-legacy-doc/fix.el, I ran meta-x fix on each
file in the output-raw/ directory, and saved the result (a prettied-up
version of the file on which meta-x fix operated) to the output/
directory.

Finally, I installed resulting files into the community books, as
described in comments in convert.lsp.

Of course, the process was more iterative then is suggested above,
with various false starts.  But by the end, the process was quite
stable.  Not discussed above are some tweaks required when modifying
the books, such as one manual conversion in
books/clause-processors/basic-examples.lisp and removing a redundant
definition of xor that had a legacy doc string (from 9 files).
