Re: Please provide stable target anchors

On Thu, Jul 8, 2010 at 7:09 PM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:
> On tor, 2010-07-08 at 15:54 +0100, Daniele Varrazzo wrote:
>> In psycopg documentation I've often referenced specific parts of
>> PostgreSQL docs, e.g. libpq functions, using the anchors found in the
>> html docs (see [1] for example). Unfortunately these anchors are not
>> stable and the ones I've linked to have changed, leaving half-broken
>> links referring to the correct page but to not existing fragments ([2]
>> for the example above).
>
> If you can tell us which places you want to link to, we can make stable
> anchors.

I can surely provide you a list, there are just a dozen of them (I'll
tell you which ones later, now I can't). But then I should bother you
every time I need a new link, or write a patch for it and wait for it
to be applied and then for the result to be rendered and published on
/docs... so I thought generating all of them programmatically would
improve the docs quality and would be a better solution for the
future.

>> The html anchors seem generated from the <indexterm> tags in the sgml
>> documentation. Would it be possible to generate stable anchors for
>> these targets, e.g. "slugifying" the content of the <primary> tag
>> contained in them?
>
> No, the anchors are made from the id attributes.  But if there is no id
> attribute, the toolchain generates an identifier for the anchor, which
> is some number that is obviously not stable.  The fix is then to put
> id's into these places.

Yes, this is what I expected. So I assume it is a Jade limitation.

>> Uhm... looking at the currently published html doc, it seems there is
>> a problem: the index [3] doesn't use these anchors at all. See for
>> example the entries for any libpq function.
>
> I'm not sure I'm seeing what you're seeing.  Could you provide examples?

If you open the manual index [1], scroll down manually to the "PQflush
" entry and click on the link, you will be redirected on the correct
page, but at its top. An anchor to be placed on the correct point is
available (at the time of writing it is [2]) but the index doesn't
refer to it. It seems a bug.

For love of consistency I may (try to) write a script to be run once
which would add an id to all the indexterm (or wherever they should be
added) based on the "primary" value. There is the possibility that
this would fix the index bug (the index entry for the sections seem
correct and they refer to the id), it should be tested. Would it be of
interest?

-- Daniele

[1] http://www.postgresql.org/docs/8.4/static/bookindex.html
[2] http://www.postgresql.org/docs/8.4/static/libpq-async.html#AEN34717