[postgis-devel] Update Documentation

[Kevin Neufeld]

Paul Ramsey wrote:
> ...
> - 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
>   
So, after a little digging and experimentation with DocBook, I found out 
that:

- cross-referencing in DocBook is quite straight forward.  We can 
reference between functions and from the main manual into the reference 
pages.
- replacing the <variablelist> concept for listing the functions with 
<refsection> tags results in a separate html file for every function 
when generating "chunked-html".  If we add lots of content to every 
method, then I think this is preferable anyway.
- splitting source xml files into several files and merging them on 
build is very easy as well.  This makes managing the files simpler as 
per Regina's suggestion.

Cheers,
-- Kevin