Horton

Thread

Commits

  1. Add id's to various elements in protocol.sgml

  2. Improve parallel vacuum implementation.

  1. Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2021-12-05T15:50:47Z

    When working with the Frontend/Backend Protocol implementation in Npgsql
and discussing things with the team, I often struggle with the fact that
you can't set deep links to individual message formats in the somewhat
lengthy html docs pages.

The attached patch adds id's to various elements in protocol.sgml to
make them more accesssible via the public html documentation interface.

I've tried to follow the style that was already there in a few of the
elements.

Do you consider this useful and worth merging?

Is there anything I can improve?

Best Regards,

Brar

  2. Re: Add id's to various elements in protocol.sgml

    Daniel Gustafsson <daniel@yesql.se> — 2021-12-05T16:15:12Z

    > On 5 Dec 2021, at 16:51, Brar Piening <brar@gmx.de> wrote:

> The attached patch adds id's to various elements in protocol.sgml to
> make them more accesssible via the public html documentation interface.

Off the cuff without having checked the compiled results yet, it seems like a good idea.

—
Daniel Gustafsson

  3. Re: Add id's to various elements in protocol.sgml

    Corey Huinker <corey.huinker@gmail.com> — 2021-12-14T18:58:49Z

    On Sun, Dec 5, 2021 at 11:15 AM Daniel Gustafsson <daniel@yesql.se> wrote:

> > On 5 Dec 2021, at 16:51, Brar Piening <brar@gmx.de> wrote:
>
> > The attached patch adds id's to various elements in protocol.sgml to
> > make them more accesssible via the public html documentation interface.
>
> Off the cuff without having checked the compiled results yet, it seems
> like a good idea.
>
> —
> Daniel Gustafsson
>

I wanted to do something similar for every function specification in the
docs. This may inspire me to take another shot at that.

  4. Re: Add id's to various elements in protocol.sgml

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-12-14T19:47:35Z

    On 2021-Dec-05, Brar Piening wrote:

> When working with the Frontend/Backend Protocol implementation in Npgsql
> and discussing things with the team, I often struggle with the fact that
> you can't set deep links to individual message formats in the somewhat
> lengthy html docs pages.
> 
> The attached patch adds id's to various elements in protocol.sgml to
> make them more accesssible via the public html documentation interface.
> 
> I've tried to follow the style that was already there in a few of the
> elements.

Hmm, I think we tend to avoid xreflabels; see
https://www.postgresql.org/message-id/8315c0ca-7758-8823-fcb6-f37f9413e6b6@2ndquadrant.com


-- 
Álvaro Herrera              Valdivia, Chile  —  https://www.EnterpriseDB.com/

  5. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2021-12-15T11:07:47Z

    On Dec 14, 2021 at 20:47, Alvaro Herrera wrote:
>
> Hmm, I think we tend to avoid xreflabels; see
> https://www.postgresql.org/message-id/8315c0ca-7758-8823-fcb6-f37f9413e6b6@2ndquadrant.com

Ok, thank you for the hint.
I added them because <varlistentry> doesn't automatically generate
labels and they were present in the current docs for
CREATE_REPLICATION_SLOT
(https://github.com/postgres/postgres/blob/22bd3cbe0c284758d7174321f5596763095cdd55/doc/src/sgml/protocol.sgml#L1944).

After reading the aforementioned thread to
https://www.postgresql.org/message-id/20200611223836.GA2507%40momjian.us
I infer the following conclusions:
a) Do *not* include xreflabel for elements that get numbered.
b) There should be some general utility for the xreflabel, not just the
linking needs of one particular source location.
c) Generally, xreflabels are a bit of antipattern, so there need to be
solid arguments in favor of adding more.

Since I can't argue towards some general utility for the xreflabels and
don't have any other solid argument in favor of adding more, I will
remove them from my current patch but leave the existing ones intact.

Objections?

  6. Re: Add id's to various elements in protocol.sgml

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-12-15T14:49:21Z

    On 2021-Dec-15, Brar Piening wrote:

> On Dec 14, 2021 at 20:47, Alvaro Herrera wrote:
> > 
> > Hmm, I think we tend to avoid xreflabels; see
> > https://www.postgresql.org/message-id/8315c0ca-7758-8823-fcb6-f37f9413e6b6@2ndquadrant.com
> 
> Ok, thank you for the hint.
> I added them because <varlistentry> doesn't automatically generate
> labels and they were present in the current docs for
> CREATE_REPLICATION_SLOT
> (https://github.com/postgres/postgres/blob/22bd3cbe0c284758d7174321f5596763095cdd55/doc/src/sgml/protocol.sgml#L1944).

Hmm, now that you mention it, we do have xreflabels for varlistentrys in
quite a few places.  Maybe we need to update README.links to mention
this.

> Since I can't argue towards some general utility for the xreflabels and
> don't have any other solid argument in favor of adding more, I will
> remove them from my current patch but leave the existing ones intact.

Yeah, I think not adding them until we have a use for them might be
wisest.

-- 
Álvaro Herrera           39°49'30"S 73°17'W  —  https://www.EnterpriseDB.com/
"La vida es para el que se aventura"

  7. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2021-12-15T15:59:19Z

    On Dec 15, 2021 at 15:49, Alvaro Herrera wrote:
> On 2021-Dec-15, Brar Piening wrote:
>> Since I can't argue towards some general utility for the xreflabels
>> and don't have any other solid argument in favor of adding more, I
>> will remove them from my current patch but leave the existing ones
>> intact.
> Yeah, I think not adding them until we have a use for them might be
> wisest.
A new version of the patch that doesn't add xreflabels is attached.
Thanks for your support.

  8. Re: Add id's to various elements in protocol.sgml

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2021-12-17T07:13:51Z

    On 15.12.21 16:59, Brar Piening wrote:
> On Dec 15, 2021 at 15:49, Alvaro Herrera wrote:
>> On 2021-Dec-15, Brar Piening wrote:
>>> Since I can't argue towards some general utility for the xreflabels
>>> and don't have any other solid argument in favor of adding more, I
>>> will remove them from my current patch but leave the existing ones
>>> intact.
>> Yeah, I think not adding them until we have a use for them might be
>> wisest.
> A new version of the patch that doesn't add xreflabels is attached.

Now this patch adds a bunch of ids, but you can't use them to link to, 
because as soon as you do, you will get complaints about a missing 
xreflabel.  So what is the remaining purpose?

  9. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2021-12-17T23:53:54Z

    On Dec 17, 2021 at 08:13, Peter Eisentraut wrote:
> On 15.12.21 16:59, Brar Piening wrote:
>> On Dec 15, 2021 at 15:49, Alvaro Herrera wrote:
>>> On 2021-Dec-15, Brar Piening wrote:
>>>> Since I can't argue towards some general utility for the xreflabels
>>>> and don't have any other solid argument in favor of adding more, I
>>>> will remove them from my current patch but leave the existing ones
>>>> intact.
>>> Yeah, I think not adding them until we have a use for them might be
>>> wisest.
>> A new version of the patch that doesn't add xreflabels is attached.
>
> Now this patch adds a bunch of ids, but you can't use them to link to,
> because as soon as you do, you will get complaints about a missing
> xreflabel.  So what is the remaining purpose?

The purpose is that you can directly link to the id in the public html
docs which still gets generated (e. g.
https://www.postgresql.org/docs/14/protocol-replication.html#PROTOCOL-REPLICATION-BASE-BACKUP).

Essentially it gives people discussing the protocol and pointing to a
certain command or message format the chance to link to the very thing
they are discussing instead of the top of the lengthy html page.

  10. Re: Add id's to various elements in protocol.sgml

    Robert Haas <robertmhaas@gmail.com> — 2021-12-20T15:09:35Z

    On Fri, Dec 17, 2021 at 6:54 PM Brar Piening <brar@gmx.de> wrote:
> The purpose is that you can directly link to the id in the public html
> docs which still gets generated (e. g.
> https://www.postgresql.org/docs/14/protocol-replication.html#PROTOCOL-REPLICATION-BASE-BACKUP).
>
> Essentially it gives people discussing the protocol and pointing to a
> certain command or message format the chance to link to the very thing
> they are discussing instead of the top of the lengthy html page.

As a data point, this is something I have also wanted to do, from time
to time. I am generally of the opinion that any place the
documentation has a long list of things, which should add ids, so that
people can link to the particular thing in the list to which they want
to draw someone's attention.

-- 
Robert Haas
EDB: http://www.enterprisedb.com

  11. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2021-12-21T07:47:27Z

    On 20.12.2021 at 16:09, Robert Haas wrote:
> As a data point, this is something I have also wanted to do, from time
> to time. I am generally of the opinion that any place the
> documentation has a long list of things, which should add ids, so that
> people can link to the particular thing in the list to which they want
> to draw someone's attention.
>
Thank you.

If there is consensus on generally adding links to long lists I'd take
suggestions for other places where people think that this would make
sense and amend my patch.

  12. Re: Add id's to various elements in protocol.sgml

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-02-24T12:18:36Z

    On 18.12.21 00:53, Brar Piening wrote:
> The purpose is that you can directly link to the id in the public html
> docs which still gets generated (e. g.
> https://www.postgresql.org/docs/14/protocol-replication.html#PROTOCOL-REPLICATION-BASE-BACKUP). 
> 
> Essentially it gives people discussing the protocol and pointing to a
> certain command or message format the chance to link to the very thing
> they are discussing instead of the top of the lengthy html page.

Is there a way to obtain those URLs other than going into the HTML 
sources and checking if there is an anchor near where you want go?

  13. Re: Add id's to various elements in protocol.sgml

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2022-02-24T13:59:04Z

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:

> On 18.12.21 00:53, Brar Piening wrote:
>> The purpose is that you can directly link to the id in the public html
>> docs which still gets generated (e. g.
>> https://www.postgresql.org/docs/14/protocol-replication.html#PROTOCOL-REPLICATION-BASE-BACKUP). 
>> Essentially it gives people discussing the protocol and pointing to a
>> certain command or message format the chance to link to the very thing
>> they are discussing instead of the top of the lengthy html page.
>
> Is there a way to obtain those URLs other than going into the HTML
> sources and checking if there is an anchor near where you want go?

I use the jump-to-anchor extension: https://github.com/brettz9/jump-to-anchor/

Some sites have javascript that adds a link next to the element that
becomes visible when hovering, e.g. the NAME and other headings on
https://metacpan.org/pod/perl.

- ilmari

  14. Re: Add id's to various elements in protocol.sgml

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2022-02-24T15:46:28Z

    On 2022-Feb-24, Dagfinn Ilmari Mannsåker wrote:

> Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:

> > Is there a way to obtain those URLs other than going into the HTML
> > sources and checking if there is an anchor near where you want go?
> 
> I use the jump-to-anchor extension: https://github.com/brettz9/jump-to-anchor/
> 
> Some sites have javascript that adds a link next to the element that
> becomes visible when hovering, e.g. the NAME and other headings on
> https://metacpan.org/pod/perl.

Would it be possible to create such anchor links as part of the XSL
stylesheets for HTML?

-- 
Álvaro Herrera           39°49'30"S 73°17'W  —  https://www.EnterpriseDB.com/

  15. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-02-24T16:07:07Z

    On 24.02.2022 at 16:46, Alvaro Herrera wrote:
> On 2022-Feb-24, Dagfinn Ilmari Mannsåker wrote:
>
>> Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
>>> Is there a way to obtain those URLs other than going into the HTML
>>> sources and checking if there is an anchor near where you want go?
>> I use the jump-to-anchor extension: https://github.com/brettz9/jump-to-anchor/
>>
>> Some sites have javascript that adds a link next to the element that
>> becomes visible when hovering, e.g. the NAME and other headings on
>> https://metacpan.org/pod/perl.
> Would it be possible to create such anchor links as part of the XSL
> stylesheets for HTML?
>
Initially I thought that most use cases would involve developers who
would be perfectly capable of extracting the id they need from the html
sources but I agree that making that a bit more comfortable (especially
given the fact that others do that too) seems worthwhile.

I'll investiogate our options and report back.

  16. Re: Add id's to various elements in protocol.sgml

    Kyotaro Horiguchi <horikyota.ntt@gmail.com> — 2022-02-25T00:52:35Z

    At Tue, 21 Dec 2021 08:47:27 +0100, Brar Piening <brar@gmx.de> wrote in 
> On 20.12.2021 at 16:09, Robert Haas wrote:
> > As a data point, this is something I have also wanted to do, from time
> > to time. I am generally of the opinion that any place the

+1 from me.  When I put an URL in the answer for inquiries, I always
look into the html for name/id tags so that the inquirer quickly find
the information source (or the backing or reference point) on the
page.  If not found, I place a snippet instead.

> > documentation has a long list of things, which should add ids, so that
> > people can link to the particular thing in the list to which they want
> > to draw someone's attention.
> >
> Thank you.
> 
> If there is consensus on generally adding links to long lists I'd take
> suggestions for other places where people think that this would make
> sense and amend my patch.

I don't think there is.

I remember sometimes wanted ids on some sections(x.x) and
items(x.x.x or lower) (or even clauses, ignoring costs:p)

FWIW in that perspecive, there's no requirement from me that it should
be human-readable.  I'm fine with automatically-generated ids.

regards.

-- 
Kyotaro Horiguchi
NTT Open Source Software Center

  17. Re: Add id's to various elements in protocol.sgml

    Chapman Flack <chap@anastigmatix.net> — 2022-02-25T01:01:56Z

    On 02/24/22 19:52, Kyotaro Horiguchi wrote:
> FWIW in that perspecive, there's no requirement from me that it should
> be human-readable.  I'm fine with automatically-generated ids.

One thing I would be −many on, though, would be automatically-generated ids
that are not, somehow, stable. I've been burned too many times making links
to auto-generated anchors in other projects' docs that change every time
they republish the wretched things.

Regards,
-Chap

  18. Re: Add id's to various elements in protocol.sgml

    Maciek Sakrejda <m.sakrejda@gmail.com> — 2022-02-25T02:03:55Z

    On Thu, Feb 24, 2022, 16:52 Kyotaro Horiguchi <horikyota.ntt@gmail.com>
wrote:

> At Tue, 21 Dec 2021 08:47:27 +0100, Brar Piening <brar@gmx.de> wrote in
> > On 20.12.2021 at 16:09, Robert Haas wrote:
> > > As a data point, this is something I have also wanted to do, from time
> > > to time. I am generally of the opinion that any place the
>
> +1 from me.  When I put an URL in the answer for inquiries, I always
> look into the html for name/id tags so that the inquirer quickly find
> the information source (or the backing or reference point) on the
> page.


+1 here as well. I often do the exact same thing. It's not hard, but it's a
little tedious, especially considering most modern doc systems support
linkable sections.

  19. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-02-25T05:36:52Z

    On 24.02.2022 at 17:07, Brar Piening wrote:
> On 24.02.2022 at 16:46, Alvaro Herrera wrote:
>> Would it be possible to create such anchor links as part of the XSL
>> stylesheets for HTML?
>>
> I'll investiogate our options and report back.
>
Yes, that would be possible. In fact appending a link and optionally
adding a tiny bit of CSS like I show below does the trick.

The major problem in that regard would probably be my lack of
XSLT/docbook skills but if no one can jump in here, I can see if I can
make it work.

Obviously adding the links via javascript would also work (and even be
easier for me personally) but that seems like the second best solution
to me since it involves javascript where no javasript is needed.

Personally I consider having ids to link to and making them more
comfortable to use/find as orthogonal problems in that case (mostly
developer documentation) so IMHO solving this doesn't necessarily need
to hold back the original patch.

<dl class="variablelist">
   <dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-INSERT">
     <span class="term">Insert</span>
     <a href="#PROTOCOL-LOGICALREP-MESSAGE-FORMATS-INSERT"
class="anchor">#</a></dt>
   <dd>...</dd>
</dl>

<!-- Optional style to hide the links and make them visible on hover -->
<style>
.variablelist a.anchor {
   visibility: hidden;
}
.variablelist *:hover > a.anchor,
.variablelist a.anchor:focus {
   visibility: visible;
}
</style>

  20. Re: Add id's to various elements in protocol.sgml

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-02-25T13:31:01Z

    On 25.02.22 06:36, Brar Piening wrote:
> Yes, that would be possible. In fact appending a link and optionally
> adding a tiny bit of CSS like I show below does the trick.
> 
> The major problem in that regard would probably be my lack of
> XSLT/docbook skills but if no one can jump in here, I can see if I can
> make it work.

I think that kind of stuff would be added in via the web site 
stylesheets, so you wouldn't have to deal with XSLT at all.

  21. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-02-28T08:41:14Z

    On Feb 25, 2022 at 14:31, Peter Eisentraut wrote:
> I think that kind of stuff would be added in via the web site
> stylesheets, so you wouldn't have to deal with XSLT at all.

True for the CSS but  adding the HTML (<a
href="#PROTOCOL-LOGICALREP-MESSAGE-FORMATS-INSERT" class="anchor">#</a>)
will need either XSLT or Javascript.

  22. Re: Add id's to various elements in protocol.sgml

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-02-28T09:24:16Z

    On 28.02.22 09:41, Brar Piening wrote:
> On Feb 25, 2022 at 14:31, Peter Eisentraut wrote:
>> I think that kind of stuff would be added in via the web site
>> stylesheets, so you wouldn't have to deal with XSLT at all.
> 
> True for the CSS but  adding the HTML (<a
> href="#PROTOCOL-LOGICALREP-MESSAGE-FORMATS-INSERT" class="anchor">#</a>)
> will need either XSLT or Javascript.

That is already done by your proposed patch, isn't it?

  23. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-02-28T11:17:11Z

    On 28.02.2022 at 10:24, Peter Eisentraut wrote:
> On 28.02.22 09:41, Brar Piening wrote:
>> On Feb 25, 2022 at 14:31, Peter Eisentraut wrote:
>>> I think that kind of stuff would be added in via the web site
>>> stylesheets, so you wouldn't have to deal with XSLT at all.
>>
>> True for the CSS but  adding the HTML (<a
>> href="#PROTOCOL-LOGICALREP-MESSAGE-FORMATS-INSERT" class="anchor">#</a>)
>> will need either XSLT or Javascript.
>
> That is already done by your proposed patch, isn't it?
>
No it isn't. My proposed patch performs the simple task of adding ids to
the dt elements (e.g. <dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-INSERT">).

This makes them usable as targets for links but they remain invisible to
users of the docs who don't know about them, and unusable to users who
don't know how to extract them from the HTML source code.

The links (e.g. <a href="#PROTOCOL-LOGICALREP-MESSAGE-FORMATS-INSERT"
class="anchor">#</a>) aren't added by the current XSLT transformations
from Docbooc to HTML.

Adding them would create a visible element (I propose a hash '#') next
to the description term (inside the <dt> element after the text) that
you can click on to put the link into the address bar, from where it can
be copied for further usage.

  24. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-02-28T19:41:13Z

    On Feb 25, 2022 at 06:36, Brar Piening wrote:
> The major problem in that regard would probably be my lack of
> XSLT/docbook skills but if no one can jump in here, I can see if I can
> make it work.

Ok, I've figured it out.

Attached is an extended version of the patch that changes the XSL and
CSS stylesheets to add links to the ids that are visible when hovering.

  25. Re: Add id's to various elements in protocol.sgml

    Chapman Flack <chap@anastigmatix.net> — 2022-02-28T20:06:20Z

    On 02/28/22 14:41, Brar Piening wrote:
> Attached is an extended version of the patch that changes the XSL and
> CSS stylesheets to add links to the ids that are visible when hovering.

That works nicely over here.

I think that in other recent examples I've seen, there might be
(something like a) consensus forming around the Unicode LINK SYMBOL
&#x1f517; rather than # as the symbol for such things.

... and now that the concept is proven, how hard would it be to broaden
that template's pattern to apply to all the other DocBook constructs
(such as section headings) that emit anchors?

Regards,
-Chap

  26. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-03-01T17:27:38Z

    On Feb 28, 2022 at 21:06, Chapman Flack wrote:
> I think that in other recent examples I've seen, there might be
> (something like a) consensus forming around the Unicode LINK SYMBOL
> &#x1f517; rather than # as the symbol for such things.

I intentionally opted for an ASCII character as that definitely won't
cause any display/font/portability issues but changing that is no problem.

> ... and now that the concept is proven, how hard would it be to broaden
> that template's pattern to apply to all the other DocBook constructs
> (such as section headings) that emit anchors?

As long as we stick to manually assigned ids in the same way my patch
does it, it shouldn't be too hard. Speaking of autogenerated ids, I
failed to make use of them since I wasn't able to reproduce the same
autogenerated id twice in order to use it for the link.

Also I'm not sure how well the autogenerated ids are reproducible over
time/versions/builds, and if it is wise to use them as targets to link
to from somewhere else.

  27. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-03-01T19:50:39Z

    On Mar 01, 2022 at 18:27, Brar Piening wrote:
> On Feb 28, 2022 at 21:06, Chapman Flack wrote:
>> I think that in other recent examples I've seen, there might be
>> (something like a) consensus forming around the Unicode LINK SYMBOL
>> &#x1f517; rather than # as the symbol for such things.
>
> I intentionally opted for an ASCII character as that definitely won't
> cause any display/font/portability issues but changing that is no
> problem.

TBH I don't like the visual representation of the unicode link symbol
(U+1F517) in my browser. It's a bold black fat thing that doesn't
inherit colors. I've tried to soften it by decreasing the size but that
doesn't really solve it for me. Font support also doesn't seem
overwhelming. Anyway, I've changed my patch to use it so that you can
judge it yourself.

>> ... and now that the concept is proven, how hard would it be to broaden
>> that template's pattern to apply to all the other DocBook constructs
>> (such as section headings) that emit anchors?
>
> As long as we stick to manually assigned ids in the same way my patch
> does it, it shouldn't be too hard.

Patch is attached. I don't think it should get applied this way, though.
The fact that you only get links for section headers that have manually
assigned ids would be pretty surprising for users of the docs and in
some files (e.g. protocol-flow.html) only every other section has a
manually assigned id. It would be easy to emit a message (or even fail)
whenever the template fails to find an id and then manually assign ids
until they are everywhere (currently that means all varlistentries and
sections) but that would a) be quite some work and b) make the patch
quite heavy, so I wouldn't even start this before there is really
consensus that this is the right direction.

  28. Re: Add id's to various elements in protocol.sgml

    Chapman Flack <chap@anastigmatix.net> — 2022-03-01T20:33:21Z

    On 03/01/22 14:50, Brar Piening wrote:
> TBH I don't like the visual representation of the unicode link symbol
> (U+1F517) in my browser. It's a bold black fat thing that doesn't
> inherit colors. I've tried to soften it by decreasing the size but that
> doesn't really solve it for me. Font support also doesn't seem
> overwhelming.

That sounds like it's probably in less wide use than I thought, and if the
font support is spotty, that seems like a good enough reason not to go
there. I've no objection to the # symbol. Maybe this should really get
a comment from someone more actively involved in styling the web site.

>> As long as we stick to manually assigned ids in the same way my patch
>> does it, it shouldn't be too hard.
> 
> Patch is attached. I don't think it should get applied this way, though.
> The fact that you only get links for section headers that have manually
> assigned ids would be pretty surprising for users of the docs and in
> some files (e.g. protocol-flow.html) only every other section has a
> manually assigned id. It would be easy to emit a message (or even fail)
> whenever the template fails to find an id and then manually assign ids
> until they are everywhere (currently that means all varlistentries and
> sections) but that would a) be quite some work and b) make the patch
> quite heavy, so I wouldn't even start this before there is really
> consensus that this is the right direction.

This sounds like a bigger deal, and I wonder if it is big enough to merit
splitting the patch, so the added ids can go into protocol.sgml promptly
(and not be any harder to find than any of our fragment ids currently are),
and "improve html docs to expose fragment ids" can get more thought.

As long as we haven't assigned ids to all sections, I could almost think
of the surprising behavior as a feature, distinguishing the links you can
reasonably bet on being stable from the ones you can't. (Maybe the latter
should have their own symbol! 1F3B2?) But you're probably right that it
would seem surprising and arbitrary. And I don't know how much enthusiasm
there will be for assigning ids everywhere.

Regards,
-Chap

  29. Re: Add id's to various elements in protocol.sgml

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-03-02T09:37:36Z

    On 01.03.22 20:50, Brar Piening wrote:
> Patch is attached. I don't think it should get applied this way, though.
> The fact that you only get links for section headers that have manually
> assigned ids would be pretty surprising for users of the docs and in
> some files (e.g. protocol-flow.html) only every other section has a
> manually assigned id. It would be easy to emit a message (or even fail)
> whenever the template fails to find an id and then manually assign ids
> until they are everywhere (currently that means all varlistentries and
> sections) but that would a) be quite some work and b) make the patch
> quite heavy, so I wouldn't even start this before there is really
> consensus that this is the right direction.

I have applied the part of your patch that adds the id's.  The 
discussion about the formatting aspect can continue.

I changed the id's for the protocol messages to mixed case, so that it 
matches how these are commonly referred to elsewhere.  It doesn't affect 
the output.

  30. Re: Add id's to various elements in protocol.sgml

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-03-02T09:40:18Z

    On 01.03.22 18:27, Brar Piening wrote:
> Also I'm not sure how well the autogenerated ids are reproducible over
> time/versions/builds, and if it is wise to use them as targets to link
> to from somewhere else.

Autogenerated ids are stable across builds of the same source.  They 
would change if the document structure is changed, for example, a 
section is inserted.

  31. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-03-02T17:46:22Z

    On 02.03.2022 at 10:37, Peter Eisentraut wrote:
> I have applied the part of your patch that adds the id's.  The
> discussion about the formatting aspect can continue.

Thank you!

I've generated some data by outputting the element name whenever a
section or varlistentry lacks an id. That's how the situation in the
docs currently looks like:

    element    | count
--------------+-------
  sect2        |   275
  sect3        |    94
  sect4        |    20
  simplesect   |    20
  varlistentry |  3976

Looking at this, I think that manually assigning an id to all ~400
sections currently lacking one to make them referable in a consistent
way is a bit of work but feasible.

Once we consitently have stable ids on section headers IMHO it makes
sense to also expose them as links. I'd probably also make the
stylesheet emit a non-terminating message/comment whenever it finds a
section without id in order to help keeping the layout consistent over time.

With regard to varlistentry I'd suggest to decide whether to add ids or
not on a case by case base. I already offered to add ids to long lists
upon request but I wouldn't want to blindly add ~4k ids that nobody
cares about. That part can also grow over time by people adding ids as
they deem them useful.

Any objections/thoughts?

  32. Re: Add id's to various elements in protocol.sgml

    Chapman Flack <chap@anastigmatix.net> — 2022-03-02T17:54:08Z

    On 03/02/22 12:46, Brar Piening wrote:
> With regard to varlistentry I'd suggest to decide whether to add ids or
> not on a case by case base. I already offered to add ids to long lists
> upon request but I wouldn't want to blindly add ~4k ids that nobody

Perhaps there are a bunch of variablelists where no one cares about
linking to any of the entries.

So maybe a useful non-terminating message to add eventually would
be one that identifies any varlistentry lacking an id, with a
variablelist where at least one other entry has an id.

Regards,
-Chap

  33. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-03-03T14:17:12Z

    On 02.03.2022 at 18:54, Chapman Flack wrote:
> Perhaps there are a bunch of variablelists where no one cares about
> linking to any of the entries.
>
> So maybe a useful non-terminating message to add eventually would
> be one that identifies any varlistentry lacking an id, with a
> variablelist where at least one other entry has an id.

That sounds like areasonable approach for now.

Is there anybody objecting to pursue this? Do you need more examples how
it would look like?

It would be a bit hurtful to generate a patch that manually adds ~600
ids just to have it rejected as unwanted.

  34. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-03-09T19:43:45Z

    On 03.03.2022 at 15:17, Brar Piening wrote:
> On 02.03.2022 at 18:54, Chapman Flack wrote:
>> Perhaps there are a bunch of variablelists where no one cares about
>> linking to any of the entries.
>>
>> So maybe a useful non-terminating message to add eventually would
>> be one that identifies any varlistentry lacking an id, with a
>> variablelist where at least one other entry has an id.
>
> That sounds like areasonable approach for now.

Attached is a pretty huge patch that adds ids to all sections and all 
the varlistentries where the containing variablelist already had at 
least one id (plus a few additional ones that I stumbled upon and deemed 
useful). It also adds html links next to the respective heading in the 
html documentation and emits a build message and a comment when a 
section or a relevant (see before) varlistentry doesn't have an id.

I don't really like how the length of the id tends to grow for deeply 
nested elements if you try to create it in a systematic way, so if 
sonebody has a better idea for somewhat mnemonic manual ids or wants to 
put an upper limit to the length, please say so. Personally I don't care 
that much since for me they are meant for copy-paste anyway.

I didn't change any existing id, even if that meant that ids of sibling 
elements end up being inconsistent. I did so because I consider URLs as 
user interface that shouldn't change without a really good reason.

I also didn't add any ids to refsect{1:2:3} elements, although we should 
probably discuss this since within the docs there ist no real visual 
difference between a sect{1;2;3} and a refsect{1:2:3}.

Here are some stats about elements where at least one currently has an 
id before and after my patch for today's HEAD.

Before:
      name      | with_id | without_id | id_coverage | max_id_len
---------------+---------+------------+-------------+------------
  sect1         |     726 |          0 |      100.00 |         46
  refentry      |     306 |          0 |      100.00 |         37
  chapter       |      74 |          0 |      100.00 |         24
  biblioentry   |      23 |          0 |      100.00 |         15
  appendix      |      15 |          0 |      100.00 |         23
  part          |       8 |          0 |      100.00 |         20
  co            |       4 |          0 |      100.00 |         30
  figure        |       3 |          0 |      100.00 |         28
  reference     |       3 |          0 |      100.00 |         18
  anchor        |       1 |          0 |      100.00 |         21
  bibliography  |       1 |          0 |      100.00 |          8
  book          |       1 |          0 |      100.00 |         10
  index         |       1 |          0 |      100.00 |         11
  legalnotice   |       1 |          0 |      100.00 |         13
  preface       |       1 |          0 |      100.00 |          9
  glossentry    |     115 |         14 |       89.15 |         32
  sect2         |     568 |        274 |       67.46 |         45
  table         |     280 |        161 |       63.49 |         46
  example       |      27 |         16 |       62.79 |         42
  refsect3      |       5 |          3 |       62.50 |         24
  sect3         |     110 |         94 |       53.92 |         49
  refsect2      |      39 |         55 |       41.49 |         36
  sect4         |       8 |         20 |       28.57 |         27
  footnote      |       5 |         18 |       21.74 |         32
  step          |      25 |        128 |       16.34 |         28
  varlistentry  |     746 |       3976 |       15.80 |         58
  refsect1      |     151 |       1326 |       10.22 |         40
  informaltable |       1 |         15 |        6.25 |         25
  phrase        |       1 |         81 |        1.22 |         20
  indexterm     |       5 |       3225 |        0.15 |         26
  variablelist  |       1 |        800 |        0.12 |         21
  function      |       4 |       4000 |        0.10 |         28
  entry         |      10 |      17609 |        0.06 |         40
  para          |       3 |      25180 |        0.01 |         27


  After:
      name      | with_id | without_id | id_coverage | max_id_len
---------------+---------+------------+-------------+------------
  sect2         |     842 |          0 |      100.00 |         49
  sect1         |     726 |          0 |      100.00 |         46
  refentry      |     306 |          0 |      100.00 |         37
  sect3         |     204 |          0 |      100.00 |         57
  chapter       |      74 |          0 |      100.00 |         24
  sect4         |      28 |          0 |      100.00 |         47
  biblioentry   |      23 |          0 |      100.00 |         15
  simplesect    |      20 |          0 |      100.00 |         39
  appendix      |      15 |          0 |      100.00 |         23
  part          |       8 |          0 |      100.00 |         20
  co            |       4 |          0 |      100.00 |         30
  figure        |       3 |          0 |      100.00 |         28
  reference     |       3 |          0 |      100.00 |         18
  anchor        |       1 |          0 |      100.00 |         21
  bibliography  |       1 |          0 |      100.00 |          8
  book          |       1 |          0 |      100.00 |         10
  index         |       1 |          0 |      100.00 |         11
  legalnotice   |       1 |          0 |      100.00 |         13
  preface       |       1 |          0 |      100.00 |          9
  glossentry    |     115 |         14 |       89.15 |         32
  table         |     280 |        161 |       63.49 |         46
  example       |      27 |         16 |       62.79 |         42
  refsect3      |       5 |          3 |       62.50 |         24
  refsect2      |      39 |         55 |       41.49 |         36
  varlistentry  |    1607 |       3115 |       34.03 |         61
  footnote      |       5 |         18 |       21.74 |         32
  step          |      25 |        128 |       16.34 |         28
  refsect1      |     151 |       1326 |       10.22 |         40
  informaltable |       1 |         15 |        6.25 |         25
  phrase        |       1 |         81 |        1.22 |         20
  indexterm     |       5 |       3225 |        0.15 |         26
  variablelist  |       1 |        800 |        0.12 |         21
  function      |       4 |       4000 |        0.10 |         28
  entry         |      10 |      17609 |        0.06 |         40
  para          |       3 |      25180 |        0.01 |         27

Regards,

Brar

  35. Re: Add id's to various elements in protocol.sgml

    Brar Piening <brar@gmx.de> — 2022-03-13T10:26:25Z

    On 09.03.2022 at 20:43, Brar Piening wrote:
> Attached is a pretty huge patch that adds ids to all sections and all
> the varlistentries where the containing variablelist already had at
> least one id (plus a few additional ones that I stumbled upon and
> deemed useful). It also adds html links next to the respective heading
> in the html documentation and emits a build message and a comment when
> a section or a relevant (see before) varlistentry doesn't have an id.

I have uploaded a doc build with the patch applied to
https://pgdocs.piening.info/ to make it easier for you all to review the
results and see what is there and what isn't and how it feels UI-wise.

You may want to look at https://pgdocs.piening.info/app-psql.html where
the patch adds ids and links to all varlistentries but doesn't do so for
the headings (because they are refsect1 headings not sect1 headings).

https://pgdocs.piening.info/protocol-flow.html is pretty much the
opposite. The patch adds ids and links to the headings (they are sect2
headings) but doesn't add them to the varlistentries (yet - because I
mostly sticked to the algorithm suggested at
https://www.postgresql.org/message-id/621FAF40.5070507%40anastigmatix.net
to contain the workload).