[postgis-devel] Update Documentation

[Kevin Neufeld]

Obe, Regina wrote:
> Kevin
> 
> Very cool.  I especially like the addition of pictures.  One thing I am
> thinking to minimize on work. Do we have any XSLT wizards that can take
> the first paragraph of each function and 
> wrap it in an abstract clause similar to what Dane did already.  His
> patch seems pretty decent although it generated some invalid inserts
> presumably because of inconsistencies in the documentation.  

I'm all for minimizing the work and as a starting point this may work. 
But eventually, I think we'll have to revisit the content anyway.  I had 
a very good laugh when someone pointed out our descriptive definitions. 
  Honestly, I never paid much attention to this before:

ST_ConvexHull() - returns the convex hull of this geometry
ST_Centroid() - return the centroid of the geometry
ST_Touches() - returns true if the geometries "spatial touch"
ST_Crosses() - return true if the geometries "spatial cross"

... etc, they're almost all like this.
Not so meaningful.

> 
> Kevin are you thinking the abstract would be the <refpurpose> and
> <refsection> would be the full description.

Yes, this is one place that such an abstract could go.  As you can see, 
it has has the advantage of getting a nice function TOC for free.  I 
don't know it's possible yet in Docbook, but I would additionally like 
to see a sideframe with all the function names in alphabetical order, 
each linking to their generated function html page.  But if we go this 
route, rather than having one large page like we currently have, I don't 
think we can use the <refpurpose> tag.  More research is clearly in order.

> 
> The other nit-pick I have is that the current documentation within each
> section is not in alphabetical order.  Is there a reason for that?

Nope. I just quickly threw together a couple of blank refsections to 
test the TOC.

> 
> The other thought is that having all this in a single .xml file is too
> much and we'll want to split each out in a separate xml and stitch back
> together (maybe that was Kevin's intent anyway - just thought I would
> mention it in passing).  I haven't explored docBook enough to know how
> much of an effort this is.

In the end, I think this would be the best approach.  But I'm not sure 
about stitching it back together.  I think a single page would be far 
too large to load (with all the new content and pictures for every 
function).  Perhaps a single page for constructors, a page for 
accessors, etc.

> 
> *REALITY CHECK kicking in oh oh - I hate when this happens:
> I would be willing to put in some effort into this since I feel its very
> important.  
> 
> Jumping from where we are now to where we want to be (Kevin's vision) -
> seems like a lot of work.

Definitely agree here.

> 
> So I propose taking baby steps. 
> 
> 1) Lets first get current doc in some format that has abstracts
> separated out into a separate tag so our parsing into db comments fields
> is more or less perfect.  Then when we have that much done - reconvene.
> 
> 
> 2) Next step after that I think - is blow up the document - again seems
> like it is currently structured enough that with an XSLT transform we
> can break chapter 6 out into separate little documents - one for each
> function.  I presume each file would need another tag to denote what
> section of the main document it slides into.  I didn't see that in
> Kevin's xml example.
> 

Sounds good to me.  The first "baby step" would then be convert the 
current <varlistentry> tag concept with <refsections> and test includes 
and cross-referencing within DocBook.

Thanx for your comments,
Cheers,
Kevin