Re: Add id's to various elements in protocol.sgml - Mailing list pgsql-hackers

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