[Openmcl-devel] Interest in documentation reorganization?

[Dan Knapp]

   Alan asked about moving the docs to the wiki, and Brian asked about 
moving
them to texinfo.

   Although I am a great believer in wikis, one thing about moving the 
docs to the
wiki would be that the table of contents and index could no longer be 
built
automatically (which they can be, at present), and if pages were 
renamed, the
links to them would have to be updated by hand. Perhaps some futuristic 
wiki
engine could use docbook or texinfo as its internal format?  That would 
take care
of that problem.

   So far, I'm liking docbook (which I haven't used before).  It has 
specific templates
for things like function reference pages, and it's easily edited using 
nxml mode in
Emacs.  Nxml is a powerful mode which contains a full DTD parser and 
validator.

   By making links target the xml id of a tag rather than the title or 
number of a
section, docbook makes it possible to rearrange content with no fear of 
breaking
any links to it.  When an xref is used for a link, it even lets you 
change the title of
a section and have all links to it also change their titles.

   Also, as I said, docbook generates tables of contents and indices 
with very little
assistance.

   I haven't used texinfo before, either, although I would be willing to 
learn.
I suppose the main advantage of it is being able to read it from within 
emacs.
Of course, it ought to be possible to achieve a similar level of 
convenience with
any webbed documentation through trivial modifications of the 
hyperspec-lookup
package.  So, the relevant questions are, does texinfo provide similar 
features to
these ones?  And is there a convenient way to semi-automatically 
convert 350k
of docbook source into texinfo source?

-- Dan Knapp