[Openmcl-devel] Interest in documentation reorganization?
alanr-l at mumble.net
Mon Jun 7 21:05:35 EDT 2004
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!
> 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
> 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
More information about the Openmcl-devel