Thread: Add id's to various elements in protocol.sgml
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
Attachment
> 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 https://www.postgresql.org/message-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 > 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?
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"
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.
Attachment
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.
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.
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?
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.
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.
Attachment
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
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.
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.
Attachment
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
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.
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.
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?
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
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.
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
Attachment
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).