Feedback-ID: i131946ab:Fastmail
Message-ID: <184dc41b-7407-1bb9-7fd4-7fb35db8b993@enterprisedb.com>
Date: Tue, 4 Apr 2023 16:54:23 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:102.0)
 Gecko/20100101 Thunderbird/102.9.1
Subject: Re: doc: add missing "id" attributes to extension packaging page
Content-Language: en-US
To: Brar Piening <brar@gmx.de>, Alvaro Herrera <alvherre@alvh.no-ip.org>,
 "Karl O. Pinc" <kop@karlpinc.com>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, vignesh C <vignesh21@gmail.com>,
 Ian Lawrence Barwick <barwick@gmail.com>,
 pgsql-hackers <pgsql-hackers@postgresql.org>
References: <20230323093555.3icw7zetwtmtrrzu@alvherre.pgsql>
 <a41ed60d-2f95-da52-ba8b-b0b1cc37f3a4@gmx.de>
From: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
In-Reply-To: <a41ed60d-2f95-da52-ba8b-b0b1cc37f3a4@gmx.de>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
Archived-At: <https://www.postgresql.org/message-id/184dc41b-7407-1bb9-7fd4-7fb35db8b993%40enterprisedb.com>
Precedence: bulk

On 23.03.23 20:08, Brar Piening wrote:
> I've also attached the (unchanged)  make_html_ids_discoverable patch for
> convenience so this email now contains two patches for postgresql
> (ending with .postgresql.patch) and one patch for pgweb (ending with
> .pgweb.patch).

Here is my view on this:

First of all, it works very nicely and is very useful.  Very welcome.

The XSLT implementation looks sound to me.  It would be a touch better 
if it had some comments about which parts of the templates were copied 
from upstream stylesheets and which were changed.  There are examples of 
such commenting in the existing customization layer.  Also, avoid 
introducing whitespace differences during said copying.

However, I wonder if this is the right way to approach this.  I don't 
think we should put these link markers directly into the HTML.  It feels 
like this is the wrong layer.  For example, if you have CSS turned off, 
then all these # marks show up by default.

It seems to me that the correct way to do this is to hook in some 
JavaScript that does this transformation directly on the DOM.  Then we 
don't need to carry this presentation detail in the HTML.  Moreover, it 
would avoid tight coupling between the website and the documentation 
sources.  You can produce the exact same DOM, that part seems okay, just 
do it elsewhere.  Was this approach considered?  I didn't see it in the 
thread.