Date: Fri, 3 Jan 2020 10:35:20 -0300
From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: helix84 <helix84@centrum.sk>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: doc: Add anchors in create_table.sgml
Message-ID: <20200103133520.GA29959@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAGdvKqgHpOwo2+XRY_1W_FF46UvuDe=zODN_iGiS7V4mfB-8gw@mail.gmail.com>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk

Hi,

On 2020-Jan-02, helix84 wrote:

> Hi, I prefer to bookmark docs pointing to the exact term I need and
> with pg docs it's often been the case that the exact term doesn't have
> an anchor or only has unstable, generated anchors. So I would very
> much like to add stable anchors in many more places. I haven't
> contributed to pg before, so this patch is me testing the waters. If
> there is interest, I'd like to add stable anchors to wherever we'll
> agree it makes sense - preferably in an automated or semi-automated
> way.
> 
> I read an older thread on this topic [1] which links to a custom SGML
> parser in Python for this specific task [2]. I have experience with
> XSLT, but not so much with SGML processing, so I would appreciate if
> you could point me whether a custom parser is the way to go for this
> task or I should look into a more generic SGML processing tool.

Ah,
https://www.postgresql.org/message-id/AANLkTikAgIyYfwy_2Zj8GafoC7ZFlGv5iCdab1l7VuDp@mail.gmail.com
(We prefer our own archive to GMane's.)  That thread is so old that
Peter feels the need to point out that the Git mirror was out of date
with CVS ... I can no longer even remember the commit process for CVS
anymore.  We also converted from SGML to XML in the meantime, so you can
probably make do with a standard XML parser without having to write a
custom SGML one.  (Daniele Varrazzo's patch ended up as 477319829c2e.)

TBH I've felt the need for anchors for <varlistentry> tags in the
past also (IIRC the runtime-config page would be improved by them),
but I'm not sure about adding them to every single keyword of every
single reference page.  Is that really useful?

> Thanks in advance and let me take this opportunity to thank you all
> for this wonderful piece of software.

You're welcome.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services