Re: Please provide stable target anchors

Hello,

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).

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?

Sorry for not being more helpful: I don't know much about the sgml toolchain.

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.

Cheers.

-- Daniele

[1] http://initd.org/psycopg/docs/connection.html#connection.get_backend_pid
[2] http://www.postgresql.org/docs/8.4/static/libpq-status.html#AEN33590
[3] http://www.postgresql.org/docs/8.4/static/bookindex.html

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.

> 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.

> 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?

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

On tor, 2010-07-08 at 20:01 +0100, Daniele Varrazzo wrote:
> 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.

Sure, if you have an idea how to do that.

> 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.

I think this is a design decision. The index entries mean, "this topic
is discussed in this section", rather than "this is the line the word is
mentioned".

> 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?

I think the index stuff has nothing to do with your actual problem. You
need to id attributes to the places you link to, or devise a way to
generate stable link anchors in some other way.

On Thu, Jul 8, 2010 at 11:01 PM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:
> On tor, 2010-07-08 at 20:01 +0100, Daniele Varrazzo wrote:
>> 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.
>
> Sure, if you have an idea how to do that.

Attached there is a patch adding an id to the indexterms currently
referred by psycopg documentation, to be applied to the current head.
However I've tried to render the html docs with the head itself and I
see anchors are not generated anymore, while they are generated by the
makefile shipped in 8.4.4. Is this a decision or it just happened? In
the former case there is no point in applying the patch then.

I've also played with good results with a script to inject ids in all
the indexterm, but if the decision is to not provide anchors in the
middle of the page I think you wouldn't be interested in it.

Regards.

-- Daniele

On ons, 2010-07-21 at 03:16 +0100, Daniele Varrazzo wrote:
> Attached there is a patch adding an id to the indexterms currently
> referred by psycopg documentation, to be applied to the current head.
> However I've tried to render the html docs with the head itself and I
> see anchors are not generated anymore, while they are generated by the
> makefile shipped in 8.4.4. Is this a decision or it just happened? In
> the former case there is no point in applying the patch then.

Hmm, never noticed that, but it appears to come from the changes we made
in the build process to not build the index twice and thus speed up the
build.

> I've also played with good results with a script to inject ids in all
> the indexterm, but if the decision is to not provide anchors in the
> middle of the page I think you wouldn't be interested in it.

I think it's a bit weird to link to indexentry elements. I can't quite
wrap my head around it. I think you could just as well link to the
varlistentry elements or some other element close by. Check out how we
link to the configuration parameters in config.sgml.

Btw., try to use some kind of hierarchical scheme for the id's. If
something is in the libpq chapter, use something like
id="libpq-pqtransactionstatus".

On Wed, Jul 21, 2010 at 8:32 PM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:
> On ons, 2010-07-21 at 03:16 +0100, Daniele Varrazzo wrote:

>> I've also played with good results with a script to inject ids in all
>> the indexterm, but if the decision is to not provide anchors in the
>> middle of the page I think you wouldn't be interested in it.
>
> I think it's a bit weird to link to indexentry elements.  I can't quite
> wrap my head around it.  I think you could just as well link to the
> varlistentry elements or some other element close by.  Check out how we
> link to the configuration parameters in config.sgml.

That would probably do. My point is that libpq functions currently
provides no URL to reference. I was thinking to use the indexentry id
after analysing what is in the html, but if there is a better tool in
sgml I'd rather use that.

I didn't notice the config entries had url: this is exactly what I was
expecting from the libpq entries. I think you will not mind then if I
add ids to them the same way.

If I had to provide a patch, what would be the best source tree to
modify? Is master on http://git.postgresql.org/gitweb?p=postgresql.git
ok?

> Btw., try to use some kind of hierarchical scheme for the id's.  If
> something is in the libpq chapter, use something like
> id="libpq-pqtransactionstatus".

I thought that a hierarchy was implied by the fact that the id is the
fragment of the url (that would be then
http://www.pg.org/docs/.../libpq.html#funcname) but no problem in
adding a prefix to the id too (I guess it would be useful for internal
cross reference).

-- Daniele

On Thu, Jul 22, 2010 at 5:23 AM, Daniele Varrazzo
<daniele(dot)varrazzo(at)gmail(dot)com> wrote:
> If I had to provide a patch, what would be the best source tree to
> modify? Is master on http://git.postgresql.org/gitweb?p=postgresql.git
> ok?

That git repo is mildly out of sync with CVS, but it should be
adequate for this purpose.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company

On Wed, Jul 21, 2010 at 8:32 PM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:
> On ons, 2010-07-21 at 03:16 +0100, Daniele Varrazzo wrote:
>> Attached there is a patch adding an id to the indexterms currently
>> referred by psycopg documentation, to be applied to the current head.
>> However I've tried to render the html docs with the head itself and I
>> see anchors are not generated anymore, while they are generated by the
>> makefile shipped in 8.4.4. Is this a decision or it just happened? In
>> the former case there is no point in applying the patch then.
>
> Hmm, never noticed that, but it appears to come from the changes we made
> in the build process to not build the index twice and thus speed up the
> build.
>
>> I've also played with good results with a script to inject ids in all
>> the indexterm, but if the decision is to not provide anchors in the
>> middle of the page I think you wouldn't be interested in it.
>
> I think it's a bit weird to link to indexentry elements.  I can't quite
> wrap my head around it.  I think you could just as well link to the
> varlistentry elements or some other element close by.  Check out how we
> link to the configuration parameters in config.sgml.
>
> Btw., try to use some kind of hierarchical scheme for the id's.  If
> something is in the libpq chapter, use something like
> id="libpq-pqtransactionstatus".

I have prepared patches to add ids style 'libpq-pqconnectdb' to
varlistentry relative to libpq functions. This results in stable
anchors in html output. The ids have been generated using the script
available in <http://bitbucket.org/dvarrazzo/pg-doc-anchors/>.

lobj.sgml doesn't use libpq so I've added ids to the sect2 tags, which
are local enough. I've added them manually as are not so many.

Patches are available from the git clone at
<http://github.com/dvarrazzo/postgres>. I've prepared patches for 8.4
and 9.0 (branches "fixanchor-8-4" and "fixanchor-9-0").

Feedback is appreciated. Regards.

-- Daniele

On Wed, Aug 4, 2010 at 3:03 PM, Daniele Varrazzo
<daniele(dot)varrazzo(at)gmail(dot)com> wrote:
> I have prepared patches to add ids style 'libpq-pqconnectdb' to
> varlistentry relative to libpq functions. This results in stable
> anchors in html output. The ids have been generated using the script
> available in <http://bitbucket.org/dvarrazzo/pg-doc-anchors/>.
>
> lobj.sgml doesn't use libpq so I've added ids to the sect2 tags, which
> are local enough. I've added them manually as are not so many.
>
> Patches are available from the git clone at
> <http://github.com/dvarrazzo/postgres>. I've prepared patches for 8.4
> and 9.0 (branches "fixanchor-8-4" and "fixanchor-9-0").

Could you post a diff?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company

On Sun, Aug 8, 2010 at 2:38 PM, Daniele Varrazzo
<daniele(dot)varrazzo(at)gmail(dot)com> wrote:
> On Fri, Aug 6, 2010 at 7:01 PM, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>> On Wed, Aug 4, 2010 at 3:03 PM, Daniele Varrazzo
>> <daniele(dot)varrazzo(at)gmail(dot)com> wrote:
>
>>> Patches are available from the git clone at
>>> <http://github.com/dvarrazzo/postgres>. I've prepared patches for 8.4
>>> and 9.0 (branches "fixanchor-8-4" and "fixanchor-9-0").
>>
>> Could you post a diff?
>
> Attached

Thanks, this looks nice. And useful. Committed.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company