Possible formatting bug in ssh-agent.1 man page

[Ingo Schwarze]

Hi,

Glenn Golden 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++