[Openmcl-devel] Interest in documentation reorganization?
dankna at accela.net
Tue Jun 1 18:11:28 EDT 2004
Alan asked about moving the docs to the wiki, and Brian asked about
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
automatically (which they can be, at present), and if pages were
links to them would have to be updated by hand. Perhaps some futuristic
engine could use docbook or texinfo as its internal format? That would
of that problem.
So far, I'm liking docbook (which I haven't used before). It has
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
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
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
I haven't used texinfo before, either, although I would be willing to
I suppose the main advantage of it is being able to read it from within
Of course, it ought to be possible to achieve a similar level of
any webbed documentation through trivial modifications of the
package. So, the relevant questions are, does texinfo provide similar
these ones? And is there a convenient way to semi-automatically
of docbook source into texinfo source?
-- Dan Knapp
More information about the Openmcl-devel