Hi Simon, Simon Branch wrote on Sat, Nov 20, 2021 at 03:10:22PM -0800:
> Here's a diff that adds explicit .Tg macros to vi(1), We don't want that: $ man -O tag=Tg mdoc [...] In most cases, adding a Tg macro would be redundant because mandoc(1) is able to automatically tag most definitions. This macro is intended for cases where automatic tagging of a term is unsatisfactory, for example if a definition is not tagged automatically (false negative) or if places are tagged that do not define the term (false positives). [...] This is a typical example of a .Tg macro that should not be added because it is redundant: > +.Tg c > .It Fl c Ar cmd The command $ man -O tag=c vi already works without your patch. I do not think .Tg should be used to enforce ambiguous tags (like "c" pointing to both the command line option and the vi(1) "change" command). On the one hand, adding multiple explicit .Tg macros for the same name is very noisy. On the other hand, it is much less useful than having an unambiguous tag because both "-O tag=c" for terminal output and the fragment identifier "#c" in HTML output only target the first copy. Consequently, the cost-to-benefit ratio is bad for ambiguous manual tagging. In general, if the same term is defined at multiple places, or if - like in this case - multiple different terms represented by the same word are defined in the same file, tagging does not work very well yet. The basic concept isn't fully worked out for such complicated cases, and i'm not even convinced designing a solution for that task that is simple enough to be worth implementing is possible. As long as the basic design is an unsolved problem, trying to handle individual cases by using the .Tg macro is a bad idea. > so that you can jump to vi or ex commands using -Otag or :t. > This patch *should* include every command, but I couldn't figure out > how to tag the '!' and ':!' commands; none of these worked: > > .Tg > .Tg ! > .Tg !\& > .Tg "!" man(1) already writes the "!" tag even without your patch: $ grep ^! /tmp/man.* /tmp/man.JF8ZO3DibX:! /tmp/man.sZVbqIr51P 729 which alreday targets this paragraph: ! argument(s) [range] ! argument(s) Execute a shell command, or filter lines through a shell command. But less(1) does not support that, see /usr/src/usr.bin/less/tags.c line 217: /* * Search the tags file for the desired tag. */ while (fgets(tline, sizeof (tline), f) != NULL) { if (tline[0] == '!') /* Skip header of extended format. */ continue; The ctags(1) format is not perfect. Some strings exist that it cannot tag, and strings starting with an exclamation mark are an example of such strings. Strings containing space characters are another. > This patch doesn't tag special keys either (word erase, literal next, > etc.), because tag names can't contain whitespace and I'd prefer > consistency with the manpage. One solution would be to say WERASE and > LNEXT instead, which is what ksh(1) does, and this also makes it easier > to lookup what 'word erase' and 'literal next' really are. > > $ man -k Dv=WERASE Dv=LNEXT > stty(1) - set the options for a terminal device interface > termios(4) - general terminal line discipline > > $ man 4 termios -Otag=WERASE > WERASE Special character on input and is recognized if the ICANON > flag is set. Erases the last word ... Maybe; but one thing at a time. We really should not discuss text changes in a thread about tagging. > If a line is explicitly tagged with the .Tg macro, mandoc removes any > other automatically-created tags with the same name. So this patch also > explicitly tags the 'print', 'number', and 'list' options and the > [-ceFRrSstvw] flags. > > Comments? OK? Not OK. This is excessive. The .Tg macro is intended to be used sparingly, not to be smeared all over the place. I do not object to marking unambiguos targets that cannot be recognized automatically. But you cannot reasonably aim for completeness in this respect. Yours, Ingo