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

[Paul Ramsey]

Answering my questions:

http://docbook.sourceforge.net/release/xsl/current/doc/html/use.id.as.filename.html

P

On Mon, Jul 14, 2008 at 2:32 PM, Paul Ramsey <pramsey at cleverelephant.ca> wrote:
> Hm, goodish and badish... the direct links are nice, the fact that the
> names are meaningless is not, particularly since inserting a new
> function will probably result in the re-numbering of all the other
> pages...
>
> P.
>
> On Mon, Jul 14, 2008 at 2:24 PM, Kevin Neufeld <kneufeld at refractions.net> wrote:
>> 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
>>
>> _______________________________________________
>> postgis-devel mailing list
>> postgis-devel at postgis.refractions.net
>> http://postgis.refractions.net/mailman/listinfo/postgis-devel
>>
>