Re: Add id's to various elements in protocol.sgml
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).
Re: Add id's to various elements in protocol.sgml
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.
Re: Add id's to various elements in protocol.sgml
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
Re: Add id's to various elements in protocol.sgml
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?
Re: Add id's to various elements in protocol.sgml
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.
Re: Add id's to various elements in protocol.sgml
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.
Re: Add id's to various elements in protocol.sgml
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
Re: Add id's to various elements in protocol.sgml
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
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.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 1c5ab00879..cb138b53ad 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1810,7 +1810,7 @@ Replication commands are logged in the server log when
The commands accepted in replication mode are:
-
+
IDENTIFY_SYSTEM
IDENTIFY_SYSTEM
@@ -1875,7 +1875,7 @@ The commands accepted in replication mode are:
-
+
SHOW name
SHOW
@@ -1899,7 +1899,7 @@ The commands accepted in replication mode are:
-
+
TIMELINE_HISTORY tli
TIMELINE_HISTORY
@@ -2084,7 +2084,7 @@ The commands accepted in replication mode are:
-
+
CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] {
PHYSICAL [ RESERVE_WAL ] |
LOGICAL output_plugin [
EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT |
USE_SNAPSHOT | TWO_PHASE ] }
@@ -2095,7 +2095,7 @@ The commands accepted in replication mode are:
-
+
READ_REPLICATION_SLOT slot_name
READ_REPLICATION_SLOT
@@ -2143,7 +2143,7 @@ The commands accepted in replication mode are:
-
+
START_REPLICATION [ SLOT
slot_name ] [
PHYSICAL ] XXX/XXX [ TIMELINE
tli ]
START_REPLICATION
@@ -2201,7 +2201,7 @@ The commands accepted in replication mode are:
-
+
XLogData (B)
@@ -2270,7 +2270,7 @@ The commands accepted in replication mode are:
-
+
Primary keepalive message (B)
@@ -2334,7 +2334,7 @@ The commands accepted in replication mode are:
-
+
Standby status update (F)
@@ -2415,7 +2415,7 @@ The commands accepted in replication mode are:
-
+
Hot Standby feedback message (F)
@@ -2497,7 +2497,7 @@ The commands accepted in replication mode are:
-
+
START_REPLICATION SLOT
slot_name
LOGICAL XXX/XXX
[ ( option_name [
option_value ] [, ...] ) ]
@@ -2572,7 +2572,7 @@ The commands accepted in replication mode are:
-
+
DROP_REPLICATION_SLOT slot_name WAIT
DROP_REPLICATION_SLOT
@@ -3266,7 +3266,7 @@ of any individual CopyData message cannot be
interpretable on their own.)
-
+
AuthenticationOk (B)
@@ -3311,7 +3311,7 @@ AuthenticationOk (B)
-
+
AuthenticationKerberosV5 (B)
@@ -3355,7 +3355,7 @@ AuthenticationKerberosV5 (B)
-
+
AuthenticationCleartextPassword (B)
@@ -3399,7 +3399,7 @@ AuthenticationCleartextPassword (B)
-
+
AuthenticationMD5Password (B)
@@ -3454,7 +3454,7 @@ AuthenticationMD5Password (B)
-
+
AuthenticationSCMCredential (B)
@@ -3499,7 +3499,7 @@ AuthenticationSCMCredential (B)
-
+
AuthenticationGSS (B)
@@ -3544,7 +3544,7 @@ AuthenticationGSS (B)
-
+
AuthenticationGSSContinue (B)
@@ -3599,7 +3599,7 @@ AuthenticationGSSContinue (B)
-
+
AuthenticationSSPI (B)
@@ -3644,7 +3644,7 @@ AuthenticationSSPI (B)
-
+
AuthenticationSASL (B)
@@ -3705,7 +3705,7 @@ following:
-
+
AuthenticationSASLContinue (B)
@@ -3760,7 +3760,7
Re: Add id's to various elements in protocol.sgml
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 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.
Re: Add id's to various elements in protocol.sgml
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 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
Re: Add id's to various elements in protocol.sgml
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.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 1c5ab00879..cb138b53ad 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1810,7 +1810,7 @@ Replication commands are logged in the server log when
The commands accepted in replication mode are:
-
+
IDENTIFY_SYSTEM
IDENTIFY_SYSTEM
@@ -1875,7 +1875,7 @@ The commands accepted in replication mode are:
-
+
SHOW name
SHOW
@@ -1899,7 +1899,7 @@ The commands accepted in replication mode are:
-
+
TIMELINE_HISTORY tli
TIMELINE_HISTORY
@@ -2084,7 +2084,7 @@ The commands accepted in replication mode are:
-
+
CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] {
PHYSICAL [ RESERVE_WAL ] |
LOGICAL output_plugin [
EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT |
USE_SNAPSHOT | TWO_PHASE ] }
@@ -2095,7 +2095,7 @@ The commands accepted in replication mode are:
-
+
READ_REPLICATION_SLOT slot_name
READ_REPLICATION_SLOT
@@ -2143,7 +2143,7 @@ The commands accepted in replication mode are:
-
+
START_REPLICATION [ SLOT
slot_name ] [
PHYSICAL ] XXX/XXX [ TIMELINE
tli ]
START_REPLICATION
@@ -2201,7 +2201,7 @@ The commands accepted in replication mode are:
-
+
XLogData (B)
@@ -2270,7 +2270,7 @@ The commands accepted in replication mode are:
-
+
Primary keepalive message (B)
@@ -2334,7 +2334,7 @@ The commands accepted in replication mode are:
-
+
Standby status update (F)
@@ -2415,7 +2415,7 @@ The commands accepted in replication mode are:
-
+
Hot Standby feedback message (F)
@@ -2497,7 +2497,7 @@ The commands accepted in replication mode are:
-
+
START_REPLICATION SLOT
slot_name
LOGICAL XXX/XXX
[ ( option_name [
option_value ] [, ...] ) ]
@@ -2572,7 +2572,7 @@ The commands accepted in replication mode are:
-
+
DROP_REPLICATION_SLOT slot_name WAIT
DROP_REPLICATION_SLOT
@@ -3266,7 +3266,7 @@ of any individual CopyData message cannot be
interpretable on their own.)
-
+
AuthenticationOk (B)
@@ -3311,7 +3311,7 @@ AuthenticationOk (B)
-
+
AuthenticationKerberosV5 (B)
@@ -3355,7 +3355,7 @@ AuthenticationKerberosV5 (B)
-
+
AuthenticationCleartextPassword (B)
@@ -3399,7 +3399,7 @@ AuthenticationCleartextPassword (B)
-
+
AuthenticationMD5Password (B)
@@ -3454,7 +3454,7 @@ AuthenticationMD5Password (B)
-
+
AuthenticationSCMCredential (B)
@@ -3499,7 +3499,7 @@ AuthenticationSCMCredential (B)
-
+
AuthenticationGSS (B)
@@ -3544,7 +3544,7 @@ AuthenticationGSS (B)
-
+
AuthenticationGSSContinue (B)
@@ -3599,7 +3599,7 @@ AuthenticationGSSContinue (B)
-
+
AuthenticationSSPI (B)
@@ -3644,7 +3644,7 @@ AuthenticationSSPI (B)
-
+
AuthenticationSASL (B)
@@ -3705,7 +3705,7 @@ following:
-
+
AuthenticationSASLContinue (B)
@@ -3760,7 +3760,7 @@ AuthenticationSASLContinue (B)
-
+
AuthenticationSASLFinal (B)
@@ -3816,7 +3816,7 @@ AuthenticationSASLFinal (B)
-
+
BackendKeyData (B)
@@ -3873,7 +3873,7 @@ BackendKeyData (B)
-
+
Bind (F)
@@ -4026,7 +4026,7 @@ Bind (F)
-
+
BindComplete (B)
@@ -4061,7 +4061,7 @@ BindComplete (B)
-
+
CancelRequest (F)
@@ -4119,7 +4119,7 @@ CancelRequest (F)
-
+
Close (F)
@@ -4176,7 +4176,7 @@ Close (F)
-
+
CloseComplete (B)
@@ -4211,7 +4211,7 @@ CloseComplete (B)
-
+
CommandComplete (B)
@@ -4310,7 +4310,7 @@ CommandComplete (B)
-
+
CopyData (F B)
@@ -4356,7 +4356,7 @@ CopyData (F B)
-
+
CopyDone (F B)
@@ -4391,7 +4391,7 @@ CopyDone (F B)
-
+
CopyFail (F)
@@ -4436,7 +4436,7 @@ CopyFail (F)
-
+
CopyInResponse (B)
@@ -4512,7 +4512,7 @@ CopyInResponse (B)
-
+
CopyOutResponse (B)
@@ -4585,7 +4585,7 @@ CopyOutResponse (B)
-
+
CopyBothResponse (B)
@@ -4658,7 +4658,7 @@ CopyBothResponse (B)
-
+
DataRow (B)
@@ -4730,7 +4730,7 @@ DataRow (B)
-
+
Describe (F)
@@ -4787,7 +4787,7 @@ Describe (F)
-
+
EmptyQueryResponse (B)
@@ -4823,7 +4823,7 @@ EmptyQueryResponse (B)
-
+
ErrorResponse (B)
@@ -4889,7 +4889,7 @@ ErrorResponse (B)
-
+
Execute (F)
@@ -4946,7 +4946,7 @@ Execute (F)
-
+
Re: Add id's to various elements in protocol.sgml
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 (#) 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. ). 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. #) 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 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.
Re: Add id's to various elements in protocol.sgml
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 (#) will need either XSLT or Javascript. That is already done by your proposed patch, isn't it?
Re: Add id's to various elements in protocol.sgml
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 (#) will need either XSLT or Javascript.
Re: Add id's to various elements in protocol.sgml
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.
Re: Add id's to various elements in protocol.sgml
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.
Insert
#
...
.variablelist a.anchor {
visibility: hidden;
}
.variablelist *:hover > a.anchor,
.variablelist a.anchor:focus {
visibility: visible;
}
Re: Add id's to various elements in protocol.sgml
On Thu, Feb 24, 2022, 16:52 Kyotaro Horiguchi wrote: > At Tue, 21 Dec 2021 08:47:27 +0100, Brar Piening 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.
Re: Add id's to various elements in protocol.sgml
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
Re: Add id's to various elements in protocol.sgml
At Tue, 21 Dec 2021 08:47:27 +0100, Brar Piening 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
Re: Add id's to various elements in protocol.sgml
On 24.02.2022 at 16:46, Alvaro Herrera wrote: On 2022-Feb-24, Dagfinn Ilmari Mannsåker wrote: Peter Eisentraut 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.
Re: Add id's to various elements in protocol.sgml
On 2022-Feb-24, Dagfinn Ilmari Mannsåker wrote: > Peter Eisentraut 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/
Re: Add id's to various elements in protocol.sgml
Peter Eisentraut 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
Re: Add id's to various elements in protocol.sgml
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?
Re: Add id's to various elements in protocol.sgml
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.
Re: Add id's to various elements in protocol.sgml
On Fri, Dec 17, 2021 at 6:54 PM 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. 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
Re: Add id's to various elements in protocol.sgml
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.
Re: Add id's to various elements in protocol.sgml
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?
Re: Add id's to various elements in protocol.sgml
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.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 34a7034282..0bca5831b1 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1810,7 +1810,7 @@ Replication commands are logged in the server log when
The commands accepted in replication mode are:
-
+
IDENTIFY_SYSTEM
IDENTIFY_SYSTEM
@@ -1875,7 +1875,7 @@ The commands accepted in replication mode are:
-
+
SHOW name
SHOW
@@ -1899,7 +1899,7 @@ The commands accepted in replication mode are:
-
+
TIMELINE_HISTORY tli
TIMELINE_HISTORY
@@ -2084,7 +2084,7 @@ The commands accepted in replication mode are:
-
+
CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] {
PHYSICAL [ RESERVE_WAL ] |
LOGICAL output_plugin [
EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT |
USE_SNAPSHOT | TWO_PHASE ] }
@@ -2095,7 +2095,7 @@ The commands accepted in replication mode are:
-
+
READ_REPLICATION_SLOT slot_name
READ_REPLICATION_SLOT
@@ -2143,7 +2143,7 @@ The commands accepted in replication mode are:
-
+
START_REPLICATION [ SLOT
slot_name ] [
PHYSICAL ] XXX/XXX [ TIMELINE
tli ]
START_REPLICATION
@@ -2201,7 +2201,7 @@ The commands accepted in replication mode are:
-
+
XLogData (B)
@@ -2270,7 +2270,7 @@ The commands accepted in replication mode are:
-
+
Primary keepalive message (B)
@@ -2334,7 +2334,7 @@ The commands accepted in replication mode are:
-
+
Standby status update (F)
@@ -2415,7 +2415,7 @@ The commands accepted in replication mode are:
-
+
Hot Standby feedback message (F)
@@ -2497,7 +2497,7 @@ The commands accepted in replication mode are:
-
+
START_REPLICATION SLOT
slot_name
LOGICAL XXX/XXX
[ ( option_name [
option_value ] [, ...] ) ]
@@ -2572,7 +2572,7 @@ The commands accepted in replication mode are:
-
+
DROP_REPLICATION_SLOT slot_name WAIT
DROP_REPLICATION_SLOT
@@ -2886,7 +2886,7 @@ The commands accepted in replication mode are:
-
+
BASE_BACKUP [ LABEL
'label' ] [ PROGRESS ] [
FAST ] [ WAL ] [
NOWAIT ] [ MAX_RATE
rate ] [ TABLESPACE_MAP ] [
NOVERIFY_CHECKSUMS ] [ MANIFEST
manifest_option ] [
MANIFEST_CHECKSUMS
checksum_algorithm ]
@@ -3138,7 +3138,7 @@ of any individual CopyData message cannot be
interpretable on their own.)
-
+
AuthenticationOk (B)
@@ -3183,7 +3183,7 @@ AuthenticationOk (B)
-
+
AuthenticationKerberosV5 (B)
@@ -3227,7 +3227,7 @@ AuthenticationKerberosV5 (B)
-
+
AuthenticationCleartextPassword (B)
@@ -3271,7 +3271,7 @@ AuthenticationCleartextPassword (B)
-
+
AuthenticationMD5Password (B)
@@ -3326,7 +3326,7 @@ AuthenticationMD5Password (B)
-
+
AuthenticationSCMCredential (B)
@@ -3371,7 +3371,7 @@ AuthenticationSCMCredential (B)
-
+
AuthenticationGSS (B)
@@ -3416,7 +3416,7 @@ AuthenticationGSS (B)
-
+
AuthenticationGSSContinue (B)
@@ -3471,7 +3471,7 @@ AuthenticationGSSContinue (B)
-
+
AuthenticationSSPI (B)
@@ -3516,7 +3516,7 @@ AuthenticationSSPI (B)
-
+
AuthenticationSASL (B)
@@ -3577,7 +3577,7 @@ following:
-
+
AuthenticationSASLContinue (B)
@@ -3632,7 +3632,7 @@ AuthenticationSASLContinue (B)
-
+
AuthenticationSASLFinal (B)
@@ -3688,7 +3688,7 @@ AuthenticationSASLFinal (B)
-
+
BackendKeyData (B)
@@ -3745,7 +3745,7 @@ BackendKeyData (B)
-
+
Bind (F)
@@ -3898,7 +3898,7 @@ Bind (F)
-
+
BindComplete (B)
@@ -3933,7 +3933,7 @@ BindComplete (B)
-
+
CancelRequest (F)
@@ -3991,7 +3991,7 @@ CancelRequest (F)
-
+
Close (F)
@@ -4048,7 +4048,7 @@ Close (F)
-
+
CloseComplete (B)
@@ -4083,7 +4083,7 @@ CloseComplete (B)
-
+
CommandComplete (B)
@@ -4182,7 +4182,7 @@ CommandComplete (B)
-
+
CopyData (F B)
@@ -4228,7 +4228,7 @@ CopyData (F B)
-
+
CopyDone (F B)
@@ -4263,7 +4263,7 @@ CopyDone (F B)
-
+
CopyFail (F)
@@ -4308,7 +4308,7 @@ CopyFail (F)
-
+
CopyInResponse (B)
@@ -4384,7 +4384,7 @@ CopyInResponse (B)
-
+
CopyOutResponse (B)
@@ -4457,7 +4457,7 @@ CopyOutResponse (B)
-
+
Re: Add id's to various elements in protocol.sgml
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-f37f9413e...@2ndquadrant.com > > Ok, thank you for the hint. > I added them because 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"
Re: Add id's to various elements in protocol.sgml
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-f37f9413e...@2ndquadrant.com Ok, thank you for the hint. I added them because 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?
Re: Add id's to various elements in protocol.sgml
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-f37f9413e...@2ndquadrant.com -- Álvaro Herrera Valdivia, Chile — https://www.EnterpriseDB.com/
Re: Add id's to various elements in protocol.sgml
On Sun, Dec 5, 2021 at 11:15 AM Daniel Gustafsson wrote: > > On 5 Dec 2021, at 16:51, Brar Piening 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.
Re: Add id's to various elements in protocol.sgml
> On 5 Dec 2021, at 16:51, Brar Piening 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
