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

Reply via email to