[postgis-devel] Docbook ID's and <a name> links

[Kevin Neufeld]

I agree that further investigation is in order, but I think we can do 
what we need to do *without* bringing in the entire xsl directory tree.

In my spare time, I've been playing with different customization 
paramaters for DocBook.  This is what I've come up with thus far:
http://postgis.refractions.net/files/tmp/index.html
http://postgis.refractions.net/files/tmp/ch07.html

This is the same documentation we have in SVN (with some tweaking of the 
Makefile and structure of some of the other xml docs), but with a new 
chapter 7 that I hope will eventually replace the current reference 
chapter 6.  I obviously still have to add the major section titles, but 
with everyone's help, my plan was to run this chapter in parallel with 
the what we have and slowly move the functions from ch6 to ch7, 
converting from the current <listitem> to <refentry> concept.

Dane, you'll see that structuring the docs this way will give the links 
you were looking for since every function will have it's own page.

I was planning to do a little more investigation, but if this is the 
direction we think the documentation could take, I'll commit what I've 
done thus far tonight so we can move this idea forward together.

Cheers,
Kevin


Paul Ramsey wrote:
> Unfortunately there's 1155 files in that tree, so it's a pretty big
> dependency to stick in.  There's a certain amount that can be done
> with over-rides though, so before we go there, maybe some further
> investigation of the working parts of the docbook-xsl package is in
> order.
> 
> P.
> 
> On Mon, Jul 14, 2008 at 1:41 PM, Obe, Regina <robe.dnd at cityofboston.gov> wrote:
>> That was one thing I wanted to do anyway.  I think at some point with our
>> splitting of pages, generation of meta data comments etc. we are going to
>> have the xsl in our distribution anyway.  Plus I find it annoying I have to
>> point the xsl doc dir of styles to somewhere.
>>  Just my two cents.
>> Regina
>> ________________________________
>> From: postgis-devel-bounces at postgis.refractions.net on behalf of Paul Ramsey
>> Sent: Mon 7/14/2008 4:15 PM
>> To: PostGIS Development Discussion
>> Subject: Re: [postgis-devel] Docbook ID's and <a name> links
>>
>> Right now we're using a stock XSL sheet from red hat linux.  We'd have
>> to bring the XSL into our distribution and start hacking it,
>> probably...  not that that is a bad thing, necessarily.
>>
>> P
>>
>> On Mon, Jul 14, 2008 at 12:49 PM, Dane Springmeyer <blake at hailmail.net>
>> wrote:
>>> I find the ability to link to a specific a named term in the postgis
>>> documentation very useful.
>>>
>>> ie:
>>>
>>> http://postgis.refractions.net/documentation/manual-svn/ch06.html#AddGeometryColumn
>>>
>>> I can see that Docbook xsl turns entries with ID's like:
>>>
>>> <varlistentry id="AddGeometryColumn">
>>>          <term>AddGeometryColumn(varchar, varchar, varchar, integer,
>>> varchar, integer)</term>
>>>
>>> into:
>>>
>>> <a name="AddGeometryColumn"></a><span
>>> class="term">AddGeometryColumn(varchar, varchar, varchar, integer,
>>> varchar,
>>> integer)</span>
>>>
>>> I'm wondering if there are any customization hooks with Docbook such that
>>> the reference.xml terms could be transformed into something more like:
>>>
>>> <a name="AddGeometryColumn" href="#AddGeometryColumn"><span class="term"
>>> id="AddGeometryColumn">AddGeometryColumn(varchar, varchar, varchar,
>>> integer,
>>> varchar, integer)</span></a>
>>>
>>> This latter option would allow each entry title to be a hyperlink to
>>> itself
>>> and a quick click will give you the appropriate direct link in the browser
>>> address bar.
>>>
>>> Anyone know the right way to approach this given the current use of
>>> Docbook?
>>>
>>> Thanks,
>>>
>>> Dane
>>>
>>> _______________________________________________
>>> postgis-devel mailing list
>>> postgis-devel at postgis.refractions.net
>>> http://postgis.refractions.net/mailman/listinfo/postgis-devel
>>>
>> _______________________________________________
>> postgis-devel mailing list
>> postgis-devel at postgis.refractions.net
>> http://postgis.refractions.net/mailman/listinfo/postgis-devel
>>
>> ________________________________
>>
>> The substance of this message, including any attachments, may be
>> confidential, legally privileged and/or exempt from disclosure pursuant to
>> Massachusetts law. It is intended solely for the addressee. If you received
>> this in error, please contact the sender and delete the material from any
>> computer.
>>
>> ________________________________
>>
>> Help make the earth a greener place. If at all possible resist printing this
>> email and join us in saving paper.
>>
>> _______________________________________________
>> postgis-devel mailing list
>> postgis-devel at postgis.refractions.net
>> http://postgis.refractions.net/mailman/listinfo/postgis-devel
>>
>>
> _______________________________________________
> postgis-devel mailing list
> postgis-devel at postgis.refractions.net
> http://postgis.refractions.net/mailman/listinfo/postgis-devel