[Openmcl-devel] Interest in documentation reorganization?

[Dan Knapp]

> Another great source of documentation is the mailing list. If there is 
> interest, I could go through the archives and pull together a 
> selection of postings that have concentrated technical information 
> (mostly written by Gary).
>
> Not sure what the format would be, maybe a list of references from 
> sections of the existing documentation to relevant postings.

   Actually, I was thinking along the lines of performing minor content 
edits to make it fit into
an appropriate section of the reference manual, and then simply 
including it as part of the
manual, without a cross-reference.

   I consider this more useful, because readers will be able to find the 
content much
more easily.  It will also make it possible to update it with the rest 
of the docs, as the
software changes with time, to keep it up to date.  When updating, it 
would be much
more tedious to go through a list of cross-linked postings to look for 
things affected by
a change.

   Keyword tagging could possibly be implemented by adding a subject 
index linking to
various sections.  I'll look into how difficult this would be.  If it's 
placed in a section which
is about its primary subject, though, the tagging is not so vital.

   Do you see any strong advantage to the other approach, keeping this 
content formatted
as emails?

   I was intending to do this only for future posts, not for past ones, 
because it would be a large undertaking to go through the archives and 
pick out important posts.  If you would like to select
past posts which contain important information, feel free; all you need 
to provide me with is a
list of the articles in some form, or a flat file containing them.  I 
will not actually go about
integrating these into the docs until I have a version actually live on 
the site.

   By way of a status report:  The re-org has been coming along.  I'm 
almost done with
converting all the function definitions to refentry format, as 
described in a past post; and
I've written a small amount of xsl (stylesheets controlling how the 
html is generated) to fix
what I consider vital presentation issues.  I expect a few more days of 
work before what
I have is ready to go up on the site - which is by no means the same as 
it being finished;
I doubt any documentation ever is.

   The largest issue which is holding me back from release, at this 
point, is the makefile.
It needs to be changed because I added my own xsl stylesheet which 
wraps around the
standard one, and because the reference manual is stored in a single 
xml file which
produces multiple html files, while for the rest of the site it's 1:1.  
I've done some work on
this already, and, although it was difficult for a while, I think I 
have a handle on the
problem at this point.  Because of the significant changes, I'll want 
Gary to check
whether the docs build correctly on the server before anything is 
checked into CVS.

   Specifically, I've done three things so far in xsl.  I've added a 
timestamp to each
page, for the convenience of people who download local copies.  I've 
made the
website's navigation header be generated as part of each page, rather 
than, as it
previously was, by a crude hack which used a special feature of the 
webserver and
resulted in invalid html.  Finally, I've set up the html base url so 
that everything can
refer to one css stylesheet stored at the root of the site.  That last 
was a bit of work,
because the docbook translator wanted to generate links which didn't 
take it into
account.

   The two remaining things which I need to do in xsl are making a list 
of refentries
appear in the chapter where they are defined (without this, they appear 
only in the
index); and making the table of contents for each chapter come after 
any introductory
text to the chapter, rather than before.  These are both important, 
although I would
probably only delay a release for the first one.  The thing about the 
ToC is important
because when the ToC is a little bit longer than one screen of text, 
and there are
only a few paragraphs beneath it, a reader would quite likely not 
realize the
paragraphs were there at all.

-- Dan Knapp