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.
On 09/26/2016 10:55 PM, Glenn Golden wrote:> 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.The Fedora gets it correctly, both from 7.3p1 tarball and from upstream git. Tested with man-db-2.7.5-3.fc24.x86_64 (not sure what other tools might involved in formatting). -- Jakub Jelen Associate Software Engineer Security Technologies Red Hat
Hi Glenn, 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.To debug this, we have to decide whether the problem is in the manual page sources used (for example due to bogus patches), in the build system, in the man(1) command on Arch, or in the formatter (likely groff) on Arch. As a first step, can you provide the file that gets installed on Arch? You can probably find the name and path of that file with $ man -w ssh-agent More is likely required after that, but what is needed depends on the contents of that file. You should also say up front which man(1) implementation you are using, which roff formatter you are using, whether you have enabled any caching of preformatted manuals, whether you have any man.conf or manpath.config files in use, and what they contain. This is likely to be some simple user oder packager error; yet again, it could also be a yet unknown mdoc(7) or man(7) compat issue, which is why i'm interested. Yours, Ingo
Hi Ingo, Inline below describes what I found, per your queries: Ingo Schwarze <schwarze at usta.de> [2016-09-27 18:52:52 +0200]:> Hi Glenn, > > 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. > > To debug this, we have to decide whether the problem is in the manual > page sources used (for example due to bogus patches), in the build > system, in the man(1) command on Arch, or in the formatter (likely > groff) on Arch. > > As a first step, can you provide the file that gets installed on > Arch? You can probably find the name and path of that file with > > $ man -w ssh-agent > > More is likely required after that, but what is needed depends on > the contents of that file. >The target file is /usr/share/man/man1/ssh-agent.1.gz. The first few lines are .TH SSH-AGENT 1 "November 15 2015 " "" .SH NAME \fBssh-agent\fP \- authentication agent .SH SYNOPSIS The md5sums are $ md5sum /usr/share/man/man1/ssh-agent.1.gz 30f21b3dc30d5c081dda5482c28bee40 /usr/share/man/man1/ssh-agent.1.gz $ zcat /usr/share/man/man1/ssh-agent.1.gz | md5sum 3bcf66fe367ed5df9c5d209b291b09cb (Didn't want to attach the actual ssh-agent.1.gz file, figuring it would probably get kicked out by the list handler, but it you want it, just let me know, will send it directly to you.)> > You should also say up front which man(1) implementation you are > using, which roff formatter you are using, >$ man --version man 2.7.5 $ groff --version GNU groff version 1.22.3 called subprograms: GNU grops (groff) version 1.22.3 GNU troff (groff) version 1.22.3> > whether you have enabled any caching of preformatted manuals, >Not that I am aware of. But in any case, "man -w -W" reports only the roff source page (the one mentioned above) but does not report any "cat" version: $ man -w -W ssh-agent /usr/share/man/man1/ssh-agent.1.gz So I think that implies that the page that gets rendered when I do "man ssh-agent" really is from that .gz file, processed at that time by man(1), not a cached version. I also did this: $ cd /tmp $ cp /usr/share/man/man1/ssh-agent.1.gz foo.gz $ man ./foo.gz and the rendered result is identical to "man ssh-agent" (i.e. the indentation oddity is present.)> > whether you have any man.conf or manpath.config files in use, and what > they contain. >My entire fileystem contains no file of either of those names, as verified using slocate(1).> > This is likely to be some simple user oder packager error; yet again, > it could also be a yet unknown mdoc(7) or man(7) compat issue, which > is why i'm interested. >Hope the above helps. Let me know if there's anything else you need. Glenn
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++
On Tue, 27 Sep 2016, Ingo Schwarze wrote:> 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.Done - thanks!
On 2016-09-28 00:10, Ingo Schwarze wrote:> 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.At least on Linux systems, wouldn't using man/groff's built-in mdoc support also be good enough? -- Mantas Mikul?nas <grawity at gmail.com>