[postgis-devel] Update Documentation

[Paul Ramsey]

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.
- Consider doing the DI9M set mathematics using entity symbols so they
are rendered as real symbols rather than an embedded image.
- Test out cross-referencing so you can cross-reference _ST_Crosses
from ST_Crosses, for example.
- 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).

Paul

On Sun, Jun 22, 2008 at 11:00 PM, Kevin Neufeld
<kneufeld at refractions.net> wrote:
> There has recently been some discussion on the uses list about
> self-documenting code.  That is, having comments extracted from postgis.xml
> into database comments on functions.
>
> I personally, like this idea, but I think we first need to work on
> structuring our documentation to perhaps include an abstract sentence
> description, a full description and perhaps an example section for every
> method. In this way, the short abstract could be extracted into db comments,
> or even used in a function table of contents lookup using DocBook.
>
> I spent a little time on this and here is what I've come up with for a
> starting point for a template.
> http://postgis.refractions.net/files/tmp/reference.html
>
> This page was generated by a docbook xml file.
> http://postgis.refractions.net/files/tmp/reference.xml
>
> I think I may have a few cycles to spare coming up to work more on this (I'm
> not sure yet), but I wanted to first get a documentation template out there
> for your thoughts.
>
> I propose that we totally rework Chapter 6 of the PostGIS docs to this type
> of DocBook reference pages.  With this type of rework, functional abstract
> sentences can be easily extracted.  You'll also notice that this style looks
> just like a unix man page.  I'm finding that DocBook is pretty powerful.
>
> What are your thoughts/feedback/suggestions ... Good idea or bad?
>
> -- Kevin
> _______________________________________________
> postgis-devel mailing list
> postgis-devel at postgis.refractions.net
> http://postgis.refractions.net/mailman/listinfo/postgis-devel
>