.Li in mdoc(7), was: `\c`, mdoc(7), and man(7) extension macros

[Ingo Schwarze]

Hi James and Alexis,

Alexis wrote on Mon, Nov 06, 2023 at 11:28:55AM +1100:
> "James K. Lowden" <jklowden@schemamania.org> writes:

>> .Sh SYNOPSIS
>> .Nm 

Since you are asking about style, here is a tiny detail:
In the SYNOPSIS, i recommend not leaving out the .Nm argument,
mostly for the benefit of human readers of the source code,
even though there is no syntactic, semantic, or portability
problem with leaving it out.

See, for example,

  https://mandoc.bsd.lv/mdoc/intro/synopsis_util.html#EXAMPLES

>> .Op Fl D Ns Ar name Ns Oo Li = Ns Ar value Oc
>>
>> The = is not an argument.

That is true.  "Ar name Ns Oo Ar = Ns Ar value Oc"
would be wrong for semantic reasons.

>> It's a literal;

There is mnemonic confusion here.  The term "literal" sounds as if
you intended it to convey semantics, but .Li is a purely presentational
macro and has no semantic value whatsoever.  The macro .Li
means "request a typewriter font":

  https://man.openbsd.org/mdoc.7#Li

When you want a semantic macro that expresses the idea of "literal"
or "this string has to be provided verbatim by the user", use a macro
like .Cm, .Fl, .Ic, or .Fn, or if none of semantic macros fits and
you still want to express "literal, verbatim", use .Sy:

  https://man.openbsd.org/mdoc.7#Sy

In contrast to .Li, .Sy *does* provide some (limited) semantic value.

So being (excessively) strict, one could write

  .Op Fl D Ar name Ns Op Sy = Ns Ar value

because the user has to type the equal sign verbatim, just like the -D.

However, i do not recommend .Sy here.  The usual way is to regard
the equal sign as punctuation and not mark it up at all.

>> that is, it stands for itself.  It separates two arguments.  
>>
>> What is the nondeprecated preferred alternative? 

> i'm certainly interested in Ingo's answer here, but in that 
> specific case, i'd simply leave 'Li' out, as it's not required.

I fully agree.  The standard way to write this is:

  .Op Fl D Ar name Ns Op = Ns Ar value

> (i presume because the 'Oo' has effectively "opened a new formatting 
> context" in which text is literal until a new macro is invoked, 
> but i'd be happy to be corrected.)

Even though i never heard the term "formatting context", i think
you intend to say the right thing here.  Using proper terminology,
i would express your idea as follows:

  .Ar is an in-line macro.  Consequently, its scope only extends
  to the next macro on the same input line or to the end of the
  input line, whichever comes earlier.  That means the font
  inside the inner .Op macro is the same as the font at the
  beginning of the input line, before the .Fl, i.e. the default
  roman font.

Yours,
  Ingo