Re: Please provide stable target anchors

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