Message-ID: <c6690867-4b06-ad16-b784-4824fcd4d43a@gmx.de>
Date: Tue, 4 Apr 2023 21:52:31 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101
 Thunderbird/102.9.1
Subject: Re: doc: add missing "id" attributes to extension packaging page
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>,
 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>
 <184dc41b-7407-1bb9-7fd4-7fb35db8b993@enterprisedb.com>
Content-Language: de-DE
From: Brar Piening <brar@gmx.de>
In-Reply-To: <184dc41b-7407-1bb9-7fd4-7fb35db8b993@enterprisedb.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: quoted-printable
UI-OutboundReport: notjunk:1;M01:P0:7rwwYi/iUYY=;3oHSkdVfAg2hou8OsjOIK3wqoqL
 Id1J7fAbU6rdSITDuwvK2zfmboZo3iSpp1zFLckpXRcITvz15ADwmkuk998+hWGNuosUYgMgw
 gMfHpvCuqS9vhUSAWakeooU54PHfU6Q1Px98ZLJVNjutboSexXBcLiKH+hxlLVxigr69Y+Xca
 MkY/Ma8K7MYUHCn5tdXhzXhlZ/7h+y6iaDQ3yP8CmvjxxIU+OBTEWvj9FQSEQenKIlWHxb3CW
 wZn65Ec7owkAIUUch/aOw3Up3ce+w/YcomAvrOOm0ReFSiPDiKQNhq0jTcLbWj4UiwxlbuUws
 /n4/CxL3ZbT31urlBxANKM+dwjjJtBv3VjAj2ED3zoAa1Krh+HNCwPpdQ6k9OSt+IHLVmgnhf
 /v+Bpq/vOcsW9OvBBEM2qPbfo+rW2Z3ttDOZLjMD1Dbx9ni8onW5iA3Tn/pSwxqUkPLIps4FF
 yKuab2QnkuYuMkeZWMJRpasuZQ1ZwztR2peWaXX0+H2WkclVjdGJYQxhExOJ0k8IXBSWbGeTp
 W4CV6OYGedaUkjvKKxYHvKzEZrBDTnjBwczgdKLVTyNGu6iDO7c65oTZUTlzYyUfOGwp8v2qe
 bz2h/bCxTFkrM7A11SUsmvgvnF3hUzzat9XLSa7NVecWkolV+3qWl0Mpjvs/ra8f5Jek9tcRC
 472wwJgAE6b/aZIhrMXYBBKNprQkO5h4x6hY5jCelbP1iaOyLJKcz1qzokfTguaXLh/xQfAd+
 vaK6MLu83c8SIluAOuFnoKj02qp9uDuoqVhYmiMYZ1ZCquwMuAObwCSPfQli1f88zlqJmdYdL
 ARZ/vs5ceeqoxbNuD7Mvo964UjmZ9KA6akZ5nKKzY6S/KNNMu4SBrZcViU0iyTBIv87C+f1XR
 kbgOWd/I5c+BN0wK9QpgLG5Ubs0II4/2a4h9tj6Z6vcJYxPtMXWRDLIxGAM0YpBBLezfUhE0h
 EGrBwpk59yHMRSzRkLE0LqBKy3U=
Archived-At: <https://www.postgresql.org/message-id/c6690867-4b06-ad16-b784-4824fcd4d43a%40gmx.de>
Precedence: bulk

On 04.04.2023 at 16:54, Peter Eisentraut wrote:
>
> First of all, it works very nicely and is very useful.=C2=A0 Very welcom=
e.

Thank you!


> The XSLT implementation looks sound to me.=C2=A0 It would be a touch bet=
ter
> if it had some comments about which parts of the templates were copied
> from upstream stylesheets and which were changed.=C2=A0 There are exampl=
es
> of such commenting in the existing customization layer.=C2=A0 Also, avoi=
d
> introducing whitespace differences during said copying.

I will amend the patch if we agree that this is the way forward.


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

I'd consider this a feature rather than a problem but this is certainly
debatable. I cannot reliably predict what expectations a user who is
browsing the docs with CSS disabled might have. The opposite is true
too. If we'd move the id links feature to javascript, a user who has
javascript disabled will not see them. Is this what they'd want? I don't
know.

Also, while about 1-2% of users have Javascript disabled, I haven't
heard of disabling CSS except for debugging purposes.

In general I'd consider the fact that CSS or Javascript might be
disabled a niche problem that isn't really worth much debating but there
is definitely something to consider regarding people using screen
readers who might suffer from one or the other behavior and I'd
definitely be interested what behavior these users would expect. Would
they want to use the id link feature or would the links rather disrupt
their reading experience - I have no idea TBH and I hate speculating
about other people's preferences.


> 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.=C2=A0 You can produce the exact same DOM, that part seems okay,
> just do it elsewhere.=C2=A0 Was this approach considered?=C2=A0 I didn't=
 see it
> in the thread.

I briefly touched the topic in [1] and [2] but we didin't really follow
up on the best approach.


Regards,

Brar


[1]
https://www.postgresql.org/message-id/68b9c435-d017-93cc-775a-c604db9ec683=
%40gmx.de

[2]
https://www.postgresql.org/message-id/a75b6d7c-3fa4-d6a8-cf23-6b5180237392=
%40gmx.de