xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sean Kelly" <ke...@mail2a.jpl.nasa.gov>
Subject Re: PDF Documentation
Date Sat, 27 May 2000 16:14:05 GMT
Andy Clark:

Overall, the PDF docs look pretty good.  You're using FOP to produce these
PDF documents?  Would you mind sharing your XSL file?  (I'd like to "compare
notes" with my own FOP usage for the XML Resume Library at
http://ad1440.net/~kelly/sw/xml-resume/ ).

My background in typesetting is begging to make a few suggestions (these
will probably affect both the XML source and the XSL transformation):

US letter size paper is too wide for a single column of text to nearly reach
the margins; this makes it more difficult for the eye to trace back to the
beginning of a line.  I'd consider using either multiple columns (don't know
how well the current FOP supports that) or using the contemporary style of
having a generous left margin with hanging headings.  That gives people to
scrawl notes, too.

For online viewing, having the table of contents hyperlink to their
corresponding sections would be great (again, FOP permitting).  Likewise for
the text in blue that would link to various xml.apache.org and w3.org
websites.

Tufte would recommend dropping the rules in tables, if possible.  I might
also suggest left-justifying the text in the tables, too.

In the section on installation, the commands to unjar the packages appear in
bulleted lists instead of in the gray-background used to demonstrate other
commands.

The leading between bullets in section 3 ought to be increased a bit (it
looks like the paragraph that describes the Attr interface, for example,
goes with the following bullet item, CDATASection).  Also, the DOMParser and
SAXParser classes lack an explanation paragraph.

If possible, keep the paragraph for the Element interface with the Element
bullet.  Same goes for SAXParseException.

Under "Runing TreeViewer", I'd drop the bullet item "Or:", and just append
the text "; or" to the end of the bullet starting "JDK1.1.8 ...".

It looks like on page 26 there's a FOP problem with a table cell falling
onto the next page.  Similarly, the table on page 34 breaks in a bad place.

The note under the FAQ "Is this Xerces-J version 100% pure Java compliant?"
is typeset differently from the other notes so far (serif versus
sans-serif).

The code under the FAQ "How do I read data from a stream as it arrives?" is
indented oddly.

Some text in the table under the FAQ "How do I migrate my code from XML4J
Version 2.0.x?" exceeds its boundaries.

Otherwise, good job on creating this release!

Take care,
--Sean


Mime
View raw message