Re: Fwd: Small fixes for ssh.1 and ssh_config.5, OpenSSH_7.2p2

[Ingo Schwarze <schwarze@usta.de>]

Hi Steffen,

Steffen Nurpmeso wrote on Tue, Mar 29, 2016 at 09:25:36PM +0200:

> i've just recognized a syntax error in some OpenSSH manuals,

That's not a syntax error.  It cannot be one.  The esacape sequence
"\&" can be used at any place where any other character can be used.
At the worst, it could be a semantic error, but it is not even that.

> and that mandoc falsely does the correct thing, if that is possible.

Mandoc correctly does the correct thing.

> I.e., it renders correctly instead of printing the "Ns" as text,

Doing that would be a rather severe bug.  Whether a macro argument
is treated as text or called as a submacro must not depend on the
text content of previous arguments.

> which i *think* it should; i think since groff does so,

I cannot reproduce.  At least, groff-1.22.3 on OpenBSD-current
does not, and i cannot remember ever having seen such a bug in
groff.  It's hard to imagine how that could even happen, given
how the groff implementation of mdoc(7) works internally...

> i however wonder why the zero-width extends beyond the space,
> hm, because it is a separator?

A zero-width space doesn't extend at all.  In fact, no roff characters
ever extend beyond any other characters.  In groff, there is no
concept of "separators" that would include "\&".  The only similar
concept here is "mdoc delimiters", and that applies to "!", but not
to "\&".

The blank after "\&" is indeed a roff(7) macro argument separator,
but it isn't escaped.  To escape blanks with respect to macro
argument separation, you need to prepend a backslash (forming the
"\ " escape sequence, in which case they are regarded as a different
input characters by roff, no longer as blanks) or to enclose both
arguments including the blank in between in double quotes (in which
case that's still a normal blank character, but now inside a macro
argument).

I'm also appending my response to your patch.

Yours,
  Ingo


> -------- Original Message --------
> Date: Tue, 29 Mar 2016 21:21:07 +0200
> From: Steffen Nurpmeso <steffen@sdaoden.eu>
> To: openssh-unix-dev@mindrot.org
> Subject: Small fixes for ssh.1 and ssh_config.5, OpenSSH_7.2p2
> 
> Hello,
> 
> the fix says it all.  sftp.1 uses correct syntax already.
> Ciao,
> 
> --- ssh.1.orig  2016-03-29 21:15:31.616819859 +0200
> +++ ssh.1       2016-03-29 21:15:52.996820743 +0200
> @@ -1049,7 +1049,7 @@ for remote and
>  .Fl KD Oo Ar bind_address : Oc Ar port
>  .Sm on
>  for dynamic port-forwardings.
> -.Ic !\& Ns Ar command
> +.Ic \&! Ns Ar command
>  allows the user to execute a local command if the
>  .Ic PermitLocalCommand
>  option is enabled in
> --- ssh_config.5.orig   2016-03-29 20:43:23.853406023 +0200
> +++ ssh_config.5        2016-03-29 20:42:21.703403428 +0200
> @@ -1220,7 +1220,7 @@ The default is
>  Allow local command execution via the
>  .Ic LocalCommand
>  option or using the
> -.Ic !\& Ns Ar command
> +.Ic \&! Ns Ar command
>  escape sequence in
>  .Xr ssh 1 .
>  The argument must be

This patch is bogus.  Both versions are completely correct.

The purpose of escaping in this context is to prevent mdoc(7)
from treating the exclamation mark as a delimiter, which can
influence spacing and end of sentence detection.

The mdoc(7) language treats the argument of an mdoc macro
as a delimiter if both of the following conditions hold:

 1. The macro argument consists of exactly one input character.
 2. That character is anyone from the following set:
     - opening delimiters:  ([
     - middle delimiters:   |
     - closing delimiters:  .,:;)]?!

The usual way to escape an argument such that it isn't taken as
a delimiter is to add a zero-width space "\&" such that condition 1
no longer holds.  See the mdoc(7) manual, subsection "Delimiters",
for a full discussion.

I admit that i usually put the "\&" in front of the character rather
than after it, and so do the examples in the mdoc(7) manual.  But
some people find it more intuitive to put the "\&" afterwards to
express that the character is not ending a sentence (i.e. is not a
delimiter).

I don't see the point in enforcing either style, it seems like
useless churn and wasted time.
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv