From: Jason McIntyre <jmc@kerhand.co.uk>
Subject: Re: Zap useless bare .Xo/Xc in manuals
To: tech@openbsd.org
Date: Wed, 25 Sep 2024 07:20:55 +0100

On Tue, Sep 24, 2024 at 04:20:52PM -0700, Evan Silberman wrote:
> .Xo/.Xc outside an .It header or a block-partial-implicit macro body seems to
> be a no-op on present mandoc and is not a documented use-case. ascii and
> html output are identical before and after.
> 
> If I'm wrong about the above in some way I will appreciate correction,
> as I am working on an mdoc(7) parser in another setting, and naturally
> mandoc(1) is my reference implementation and the OpenBSD manuals are my
> reference corpus.
> 
> E
> 

hi. you're pretty much correct, though i'm sure ingo will give us the
details of the matter.

i've just committed the diff, though it had two errors in dig.1, which
i'll note inline:

> diff /usr/src
> commit - 208893442c38e0767db1293632337acc2532616c
> path + /usr/src
> blob - d60769e2763926cb4fc4d431eea79e0bd0d5da94
> file + bin/ksh/ksh.1
> --- bin/ksh/ksh.1
> +++ bin/ksh/ksh.1
> @@ -1800,10 +1800,8 @@ command may be used to list, change, and add to this c
>  Brace expressions take the following form:
>  .Bd -unfilled -offset indent
>  .Sm off
> -.Xo
>  .Ar prefix No { Ar str1 No ,...,
>  .Ar strN No } Ar suffix
> -.Xc
>  .Sm on
>  .Ed
>  .Pp
> blob - 86145e812e7e26fc4e324a5733d0e376704d9b2e
> file + usr.bin/dig/dig.1
> --- usr.bin/dig/dig.1
> +++ usr.bin/dig/dig.1
> @@ -307,11 +307,9 @@ The query options are:
>  .Cm aaflag
>  .Xc
>  A synonym for
> -.Xo
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm aaonly .
> -.Xc
>  .It Xo
>  .Cm + Ns
>  .Op Cm no Ns
> @@ -413,11 +411,9 @@ is automatically set when
>  is in use, to better emulate the default queries from a name server.
>  .Pp
>  This option was formerly called
> -.Xo
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm sit
> -.Xc
>  (Server Identity Token).
>  In BIND 9.10.0 through BIND 9.10.2,
>  it sent the experimental option code 65001.
> @@ -425,17 +421,13 @@ This was changed to option code 10 in BIND 9.10.3 when
>  COOKIE option was allocated.
>  .Pp
>  The
> -.Xo
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm sit
> -.Xc
>  option is now deprecated, but has been retained as a synonym for
> -.Xo
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm cookie
> -.Xc
>  for backward compatibility within the BIND 9.10 branch.
>  .It Xo
>  .Cm + Ns
> @@ -453,7 +445,6 @@ the key id is displayed as the replacement, e.g. "[ ke
>  .Cm defname
>  .Xc
>  Deprecated, treated as a synonym for
> -.Xo
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm search

i had to alter this to

	.Cm search .

then remove

	.Xc

on the following line.

> @@ -462,7 +453,6 @@ Deprecated, treated as a synonym for
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm dnssec
> -.Xc
>  Request DNSSEC records be sent by setting the DNSSEC OK bit (DO) in the OPT
>  record in the additional section of the query (off by default).
>  .It Cm +domain Ns = Ns Ar name
> @@ -650,7 +640,6 @@ is returned (on by default).
>  .Cm rdflag
>  .Xc
>  A synonym for
> -.Xo
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm recurse

same again:

	.Cm recurse .

then zap the following ".Xc" line.

i think you maybe zapped the wrong Xc in your diff, but i'm not sure.
maybe you sent diff(1) mad.

jmc

> @@ -659,7 +648,6 @@ A synonym for
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm recurse
> -.Xc
>  Set the RD (recursion desired) bit in the query (on by default).
>  Recursion is automatically disabled when the
>  .Cm +nssearch
> @@ -817,11 +805,9 @@ Display the TTL when printing the record (on by defaul
>  .Xc
>  Use TCP when querying name servers.
>  This alternate syntax to
> -.Xo
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm tcp
> -.Xc
>  is provided for backwards compatibility.
>  The "vc" stands for "virtual circuit".
>  .El
> @@ -848,11 +834,9 @@ also be supplied.
>  These global query options must precede the first tuple of name, class, type,
>  options, flags, and query options supplied on the command line.
>  Any global query options (except the
> -.Xo
>  .Cm + Ns
>  .Op Cm no Ns
>  .Cm cmd
> -.Xc
>  option) can be overridden by a query-specific set of query options.
>  For example:
>  .Bd -literal -offset indent
> blob - f3fef23abb446ef5d840bfe20fb24d29db14a566
> file + usr.bin/ssh/ssh_config.5
> --- usr.bin/ssh/ssh_config.5
> +++ usr.bin/ssh/ssh_config.5
> @@ -1585,14 +1585,12 @@ ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 
>  .Ed
>  .It Cm ProxyJump
>  Specifies one or more jump proxies as either
> -.Xo
>  .Sm off
>  .Op Ar user No @
>  .Ar host
>  .Op : Ns Ar port
>  .Sm on
> -or an ssh URI
> -.Xc .
> +or an ssh URI.
>  Multiple proxies may be separated by comma characters and will be visited
>  sequentially.
>  Setting this option will cause
> blob - 2b382bf50de01a76991cb559c4d8fa966ad91285
> file + usr.bin/systat/systat.1
> --- usr.bin/systat/systat.1
> +++ usr.bin/systat/systat.1
> @@ -265,10 +265,8 @@ The
>  .Dq State
>  column has the format
>  .Sm off
> -.Xo
>  .Cm up | dn
>  .Bq : Cm U | D .
> -.Xc
>  .Sm on
>  .Sq up
>  and
>