Re: doc: add missing "id" attributes to extension packaging page

On 04.04.2023 at 16:54, Peter Eisentraut wrote:
>
> First of all, it works very nicely and is very useful.  Very welcome.

Thank you!


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

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

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

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