[Openmcl-devel] First draft!

[Dan Knapp]

   Well, I'm ready for y'all to see what I've done with the 
documentation.  This is by no means
finished; it's barely begun.  However, it's at the point where it's not 
as bad as what was up
before.  (If I say so myself!)  Therefore, it is my pleasure to 
announce a first draft for
review.  No critique is too large, nor too small.

   The chapter I've edited most heavily is the threading one.  I went 
through the "dictionary"
section there and did thorough content edits.  The changes I made there 
illustrate what I
want to do for all the dictionary sections.  I was quite heavy-handed 
with it, and I'm
wondering whether Gary will take issue with any of the things I did to 
his prose. ^_^

   I've changed wording where it took too much knowledge for granted, 
which usually
happened because it was presuming the reader had just gone through all 
the preceding
descriptions in order.  I wrote one-sentence abstracts for every 
function and variable, which
appear in the listing of that section.  I changed the formatting of the 
syntax summaries, and made
the wording, particularly that of the parameter descriptions, conform 
to some style rules
which I really should write down.

   I added extensive hyperlinks and cross-references, and applied 
formatting to function and
variable names which appear in the body text.  I eliminated footnotes, 
because they break
flow (call it a personal preference); they are either integrated into 
the text, or moved into a
separate notes section at the bottom of the page, depending on their 
relevance.

   The chapter I've edited least is the FFI one, which is ironic as the 
FFI docs were a large
part of my motivation for this endeavor.  That's the only chapter in 
which the dictionary
hasn't been separated out and put into <refentry> format.

   Anyhow, your reward for reading all the way to the end of the email 
is that you get the
link to my provisional copy of the document:

	http://www.accela.net/~dankna/openmcl-docs/

   The front page includes a link to an automatically-updated tarball, 
which should work
for local browsing as well as online.  The tarball includes all the 
source and stylesheets,
as well as the final html.

   Gary, I guess I'll need commit access to the website CVS now, but 
before this goes
live, there are several things which you will need to check by building 
manually on
the webserver.

   First, check that the makefile works at all, and with the same 
arguments which cron
gives it.

  Second, check the site-navigation menu at the top of the page.  It's 
now added by
xsl, which means the files which tell the webserver to add it are 
redundant.  I haven't
touched those files because I have no way of testing my changes.  Also, 
I note that you
have now put up the wiki, and I don't know whether removing the 
root-level
menu.mc and autohandler will break the navigation menu for it.  Let me 
know if there's
any problem.  I'm hoping it can be made to work the way I have it, 
because the way
it was, users wind up seeing invalid html, and the <title> is not 
visible.

   Third, check that the standard xsl stylesheets are being read from 
the local system
and not from the Internet.  This makes a major difference in the build 
time.  I wrote a
description in the makefile of what exactly this means and how you 
check it.

   If there's any difficulty, please write and let me know.

-- Dan Knapp