[Openmcl-devel] Interest in documentation reorganization?

[Alan Ruttenberg]

On Jun 7, 2004, at 6:26 PM, Dan Knapp wrote:

>> 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).
>
>   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.

You put your finger on the advantage - the amount of work involved. But 
let's do this, - I'll go over the archives and collect a set of them 
and we'll see what it looks like.

Most excellent progress! I'm looking forward to seeing the results!

-Alan

>
>   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
>
> _______________________________________________
> Openmcl-devel mailing list
> Openmcl-devel at clozure.com
> http://clozure.com/mailman/listinfo/openmcl-devel