Date: Tue, 27 Sep 2016 23:10:35 +0200
From: Ingo Schwarze 
To: xxxxxxx@openbsd.org
Cc: openssh-unix-dev@mindrot.org, Glenn <xxxx@xxx.xxx>
Subject: Re: Possible formatting bug in ssh-agent.1 man page

Hi,

Glenn wrote on Mon, Sep 26, 2016 at 02:55:08PM -0600:
>
> Version info: OpenSSH_7.3p1, OpenSSL 1.0.2i  22 Sep 2016, Arch linux
> 
> The ssh-agent.1 man page seems to have an indentation oddity, at least, as
> formatted with recent Arch linux manpage toolset. Here's what appears in
> the formatted output just after the description of the the "-t" option:
> 
>      ---------- Begin formatted output -------------------------------------
>        -t life
>               Set a default value for the maximum lifetime of identities added
>               to  the agent.  The lifetime may be specified in seconds or in a
>               time format specified in sshd_config(5).  A  lifetime  specified
>               for  an  identity with ssh-add(1) overrides this value.  Without
>               this option the default maximum lifetime is forever.
> 
>               If a command line is given, this is executed as a subprocess  of
>               the agent.  When the command dies, so does the agent.
> 
>               The  idea  is that the agent is run in the user's local PC, lap
>                       .
>                       .
>                       .
>      ------------ End formatted output -------------------------------------
> 
> Seems to me like all the paragraphs after the one immediately
> below "-t life" (starting with "If a command line..." and thereafter)
> are meant to be outdented to the main indentation level so that they
> do not appear be associated with the description of the -t option.

Glenn sent some additional information to me in private.

It turned out the problem is caused by a bug in the script mdoc2man.awk.
The bug is not platform-specific.  With the information Glenn
provided, i can easily reproduce the problem from git master on
OpenBSD-current if i use

  $ ./configure --with-mantype=man

The problem is that the awk script neglects terminating top level
lists, resulting in bogus indentation unless the indentation gets
cancelled for some other reason like .SH.


The following patch fixes the problem.

It improves the following manuals when using --with-mantype=man:

 sftp-server(8) after -u umask
 ssh-add(1)     after FILES ~/.ssh/id_rsa
 ssh-agent(1)   after -t life
 ssh_config(5)  after 3. system-wide configuration file (.../ssh_config)
 sshd(8)        after X11-forwarding

The patch also inserts a few needless .PP before .SH, but that does
no harm.  mdoc2man.awk is a terrible hack and not a proper parser
in the first place, so we shouldn't expect beauty in its output.
If the output is correct and portable, that's good enough.  At some
point, we should replace mdoc2man.awk with mandoc -Tman anyway.
The last time i tried, there was still some work to do, so that
won't be instantaneous.

So, for now, i think the following patch should be committed to
git master.

Yours,
  Ingo


diff --git a/mdoc2man.awk b/mdoc2man.awk
index 80e8d5f..cf210ba 100644
--- a/mdoc2man.awk
+++ b/mdoc2man.awk
@@ -321,6 +321,8 @@ function add(str) {
       w=nwords
     } else if(match(words[w],"^El$")) {
       optlist=oldoptlist
+      if(!optlist)
+	add(".PP")
     } else if(match(words[w],"^Bk$")) {
       if(match(words[w+1],"-words")) {
 	w++


===========================================================================
Date: Tue, 27 Sep 2016 23:24:28 +0200
From: Ingo Schwarze <xxx@xx.xx>
To: Glenn <xx@xxx.xxxx>
Subject: Re: Possible formatting bug in ssh-agent.1 man page


There is still one thing i wonder about:  Why is Arch using the
equivalent of

 $ ./configure --with-mantype=man

 ?

 That makes no sense to me, given that the latest and greatest groff
 is in use, which certainly supports mdoc(7), better even than man(7).

 Do you care looking at the build system of the packaging for Arch?
 If you do that, you may be able to improve the package build on Arch,
 resulting in better documentation for all Arch users.  OpenSSH is
 probably important enough to make that worthwhile.

 Usually, the Arch build scripts are reasonably easy to understand.
 Look for any suspicious environment variables, look for how and
 with which arguments ./configure gets called in particular, and
 look at the output of ./configure.

 If you can't figure out why the stuff decides to install man(7)
 rather than mdoc(7) manuals, feel free to send me a copy of the
 main build script and a build log - it must include the output
 that configure produces on stdout.  Nota bene, from a real package
 build, *not* from a ./configure that you called by hand.

 Thanks for reporting,
   Ingo