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

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