public inbox for [email protected]
help / color / mirror / Atom feedFrom: Brar Piening <[email protected]>
To: Peter Eisentraut <[email protected]>
To: Alvaro Herrera <[email protected]>
To: Karl O. Pinc <[email protected]>
Cc: Tom Lane <[email protected]>
Cc: vignesh C <[email protected]>
Cc: Ian Lawrence Barwick <[email protected]>
Cc: pgsql-hackers <[email protected]>
Subject: Re: doc: add missing "id" attributes to extension packaging page
Date: Tue, 4 Apr 2023 21:52:31 +0200
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
<[email protected]>
<[email protected]>
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
view thread (35+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
Subject: Re: doc: add missing "id" attributes to extension packaging page
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox