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
