Re: doc: add missing "id" attributes to extension packaging page - Mailing list pgsql-hackers

On Tue, 4 Apr 2023 21:52:31 +0200
Brar Piening <brar@gmx.de> wrote:

> On 04.04.2023 at 16:54, Peter Eisentraut wrote:

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

I like this idea.  A lot. (Including which stylesheets were copied
from.)

> > 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 too would consider this a feature.  If you don't style your
html presentation, you see everything.  The "#" links to content
are, well, content.

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

I would argue the opposite.  The HTML/CSS is delivered to the browser
which is then free to present the content to the user in the
form preferred by the user.  This puts control of presentation
in the hands of the end-user, where, IMO, it belongs.

Using JavaScript to manipulate the DOM is all well and good when
using AJAX to interact with the server to produce dynamic content.
But otherwise manipulating the DOM with JavaScript seems overly
heavy-handed, even though popular.  It seems like JavaScript is
used more because CSS is difficult and an "extra technology" when
instead JavaScript can "do everything".  So CSS is put aside.

I may be biased, not being a JavaScript fan.  (I tend to be one
of those cranky individuals who keep JavaScript turned off.)
I'd rather not have code executing when such overhead/complication
can be avoided.  (Insert here exciting argument about "what is code
and what is data".)

Glancing at the documentation source, I don't see JavaScript used
at all.  Introducing it would be adding something else to the mix.
Not that this would be bad if it provides value.

In the end, I don't _really_ care.  And don't do web development
all day either so my fundamentals could be just wrong.  But
this is my take.

> > Moreover, it would avoid tight coupling between the website and the
> > documentation sources. 

I don't really understand this statement.  Are you saying that
the documentation's source CSS needn't/shouldn't be the CSS used
on the website?  That seems counter-intuitive.  But then I don't
understand why the default CSS used when developing the documentation
is not the CSS used on the website.

I can imagine administrative arguments around server maintenance for
wanting to keep the website decoupled from the PG source code.
(I think.)  But I can't speak to any of that.

Regards,

Karl <kop@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein