[postgis-devel] Update Documentation

[Kevin Neufeld]

Paul Ramsey wrote:
> Kevin,
> 
> I think this looks great, and the XSLT transform doesn't seem to
> mangle it up too much!
> 
> Couple style notes:
> 
> - Avoid the urge to do tables just to obtain formatting effects.
> Better to just inline things and let the chips fall where they may.
> Use tables when the information you are presenting is naturally
> tabular.
> - If you "go for it", perhaps consider a naming convention for the
> images, so that it is easy to see what image files belong to what
> section.

And speaking of sections, did we still want to go with the OpenGIS and 
PostGIS Extensions breakup?  Personally, I'd like to see the functions 
grouped by type (operators, constructors, accessors, spatial predicates, 
etc) and if necessary, add a comment "This method is a [PostGIS 
extension | OpenGIS ] function" or something.  For example, is 
ST_Distance() an OpenGIS or PostGIS function?  Oh wait ... it's in both 
sections :)


> - Consider doing the DI9M set mathematics using entity symbols so they
> are rendered as real symbols rather than an embedded image.

Absolutely.  Docbook has a tag called mathphrase that permits adding 
text and symbols available in v4.5.  Or alternatively we could try the 
MathML module.  I tried to get the mathphrase to work, but my xsltproc 
needs upgrading.

> - Test out cross-referencing so you can cross-reference _ST_Crosses
> from ST_Crosses, for example.

Agreed.

> - Research the implications of doing includes in docbook, so that the
> main manual can reference into the reference pages.  The PostgreSQL
> documentation is in multiple sections, and might provide guidance
> (though they were using SGML, not XML, so the lesson might not be
> helpful).

Yup.. also important.

-- Kevin