[Gd-hackers] GD library documentation

[Dustin Voss]

Okay, so I am creating updated web-pages for Gwydion Dylan libraries  
(excluding the the matrix, testworks, and internal libraries like  
compiler-base).

My motivation is
   a) the existing docs at http://wwwopendylan.org/gdref/gdlibs.html  
are out-of-date in various ways;
   b) they are also very incomplete; and
   c) it's hard to find things in the existing docs.

I am currently transcribing the current gdlibs.html docs, updating as  
I go. Next, I intend to look through the Open Dylan docs and document  
the bindings that were transferred over as part of the Common Dylan  
effort. Finally, I will look for any other undocumented bindings, and  
document them using what I can gather from the source code.

The final documentation is a series of static HTML pages with various  
indices and cross references. For example, each class is cross- 
referenced with the functions on or returning an instance of that class.

I have put the pages I've done to date in a ZIP file, at http:// 
idisk.mac.com/d_j_v-Public/cpage/html.zip.

These HTML pages are generated from the following process:

  1) I ran the .lib.du files through the refman tool I wrote.
  2) This generated an XML file in the style of Open Dylan's XML  
export facility, containing all the bindings and information that  
could be extracted from the .lib.du files.
  3) I ran the XML file through an XSL transform I wrote that created  
a series of cross-referenced text files, one for each binding,  
library, or module.
  4) I hand-edit the text files to fix places where the information  
extracted from the .lib.du file is inadequate.
  5) The text files are ran through a version of NaturalDocs that I  
customized slightly.
  6) That generates the HTML pages.

Since text files are rather more versatile than the refman XML  
format, I am treating the text files as the documentation's source  
material. My plan is to add them to SVN trunk/documentation/gwydion/ 
gdcore, along with a README. The refman tool is already part of the  
GD source tree. The XSLT and NaturalDocs tools are available from my  
iDisk, so I don't currently intend to add them to SVN -- though I  
certainly could, if that is preferred.

hannes suggested that the HTML files be generated automatically by  
the web-server when the source material changes, like how the gdlibs  
pages are generated now. That sounds fine to me. (An alternative is  
to add the HTML files to SVN directly, but that is about 1100 small  
files.)

Once the web-server thing is set up, and the HTML is ready, I intend  
to add a link from http://opendylan.org/gdref.phtml to the new docs.  
Maybe gdlibs.html could then be moved to the "Older Manuals" section.

As for ongoing maintenance, I was thinking I'd first re-create the  
skeletal text files from step 3 and check those in. Then, I would  
replace them with the hand-edited files. As the libraries change in  
the future, we could do ancestor merges between the currently-checked  
in files, and new skeletal files that include the library changes,  
using the original skeletal files as an ancestor. I am not sure if  
that would work well, though.

SO, that's the plan so far. I didn't want this to be a surprise to  
anyone, hence this e-mail. Comments/concerns/suggestions?