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

[Paul Ramsey]

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
>