[OpenAFS] RE: Jan 2005 report on Doncumetation Project

[ted creedon]

Accomplished:

1. Alpha release of Texified documents sent to reviewers.

2. The alpha release depends on material converted from html by others.
While it is a good prototype many of the finer details in the IBM
documentation were filtered out by html2latex.pl. Hyperlinks, images,
various fonts, paragraphing, alltt instead of verbatim, etc.

3. During Jan html2latex was patched and extended (and Perl was also learned
after a raid on Powell's Book Store) and using the DDD debugger all of the
information in the IBM .htm docs can be salvaged (if needed). A bug in DDD
that prevented pagination in Perl mode was also fixed.

4. The Admin Guide has been converted from the .htm files in the OpenAFS
release. These files are cleaned up versions of the docs on the IBM web
site.

5. Current deficiencies are:

   Note: causes margin overruns because it is converted to tablular and
should be text. This was done manually in the alpha release. The beta should
recurse through the parse tree to see if the string "Note:" is in a row.
Hope this can be figured out.

   Long pathnames like /aaa/bbb/ccc... Cause margin overruns.

   Long rows in the tabular environment cause margin overruns. Not sure how
to do word wrap a la Excel. The small number of pages would survive in
landscape mode.

   Each of the 26 auagd0xx.htm files are individual documents, however
revisions in the xml setup have been made to allow index.tex to include all
26 .htm files.

   Special characters (@special in Latex.pm) need to be converted
differently if in an alltt environment. Verbatim doesn't work due to
\textbf{}.

6. The conversion perl script seems to replicate the original document
fairly well, including the copyright...

7. The alpha had a Table of Contents and numbered sections. This is easily
accomplished by changing section* to section in the beta xml setup file.

8. Using the numbered, paginated version is recommended because it allows
referring to a particular section by chapter and number.

9. As a general comment, IBM's doc's are a work of art. Various fonts,
sizes, bold, italic, etc. are used extensively for effective emphasis.

Tedc