Add id's to various elements in protocol.sgml

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

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.

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
/messages/by-id/8315c0ca-7758-8823-fcb6-f37f9413e6b6@2ndquadrant.com

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

On Dec 14, 2021 at 20:47, Alvaro Herrera wrote:

Hmm, I think we tend to avoid xreflabels; see
/messages/by-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
/messages/by-id/20200611223836.GA2507@momjian.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?

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
/messages/by-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"

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.

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?

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.

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

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.

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?

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

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/

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.

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

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

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.

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>

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.