Debian Bug report logs - #411303
inconsistencies in manpage formatting practices

version graph

Packages: manpages, groff; Maintainer for manpages is Martin Schulze <joey@debian.org>; Source for manpages is src:manpages. Maintainer for groff is Colin Watson <cjwatson@debian.org>; Source for groff is src:groff.

Reported by: justinpryzby@users.sourceforge.net

Date: Sat, 17 Feb 2007 23:39:01 UTC

Severity: normal

Tags: fixed-upstream

Found in version 1.18.1.1-12

Done: Martin Schulze <joey@infodrom.org>

Bug is archived. No further changes may be made.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>:
Bug#411303; Package manpages,groff. Full text and rfc822 format available.

Acknowledgement sent to justinpryzby@users.sourceforge.net:
New Bug report received and forwarded. Copy sent to Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>. Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: justinpryzby@users.sourceforge.net
To: submit@bugs.debian.org
Subject: inconsistencies in manpage formatting practices
Date: Sun, 7 Jan 2007 12:28:35 -0500
Package: manpages,groff
Version: 1.18.1.1-12

I would like to resolve at least one inconsistency regarding preferred
manpage formatting practices.  Quoting .SH arguments; see Debian
#368996.  manpages man.7 and groff_man.7 have different advice about
whether .SH arguments with spaces should be quoted.  Colin indicates
that man(7) should probably change.

Also, where are \f[BRP] documented, anyway?  I hope there is something
more than the groff.7 paragraph "Fonts are identified..."....

On Thu, Jul 27, 2006 at 04:09:02PM +0100, Colin Watson wrote:
> On Thu, Jul 27, 2006 at 10:15:37AM -0400, Justin Pryzby wrote:
> > On Thu, Jul 27, 2006 at 08:39:42AM +0100, Colin Watson wrote:
> > > On Thu, Jul 27, 2006 at 08:20:39AM +0200, Martin Schulze wrote:
> > > > I'm writing you because of Bug#368996 in which the reporter
> > > > claims that when you use the .SH macro and the parameter
> > > > contains a space character it should be quoted.  Is this true?
> > > 
> > > To the best of my knowledge, this is not the case. See groff_man(7),
> > > which says:
> > > 
> > >        .SH [text for a heading]
> > >               Sets up an unnumbered section heading  sticking  out  to
> > >               the  left.   Prints  out all the text following SH up to
> > >               the end of the line (resp. the text in  the  next  input
> > >               line  if  there  is no argument to SH) in bold face, one
> > >               size larger than the base document size.   Additionally,
> > >               the  left  margin for the following text is reset to its
> > >               default value.
> > 
> > I'm reading man.7:
> > 
> >        If  the name  contains  spaces  and appears on the same line as .SH,
> >        then place the heading  in  double  quotes.
> 
> In my experience, man(7) frequently gives somewhat dubious advice, and
> is less authoritative than groff_man(7).



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>:
Bug#411303; Package manpages,groff. Full text and rfc822 format available.

Acknowledgement sent to Justin Pryzby <justinpryzby@users.sourceforge.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>. Full text and rfc822 format available.

Message #10 received at 411303@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: Michael Kerrisk <mtk-manpages@gmx.net>
Cc: 349388@bugs.debian.org, 411303@bugs.debian.org
Subject: Re: Bug#349388: argp.3
Date: Tue, 24 Apr 2007 10:25:05 -0400
On Tue, Apr 24, 2007 at 04:14:15PM +0200, Michael Kerrisk wrote:
> Hi Justin,
> 
> If you would like to get this pushed upstream, the following would help:
> 
> 1. Follow man-pages formatting conventions would help.  In particular, the
> use of lines containing just a "." (to force a blank line) should be
> avoided.  Just remove all of those lines.  (Most man-pages do not have the
> more than one blank line to separate sections.)
I'd actually like to see some resolution to #411303 before changing
everything back; nobody has commented on it yet.  After spending some
effort reading documentation, it's not inspiring to be told that the
documentation is wrong.

> 2. It would be helpful to know where you have gained the information from.
.\" References:
.\"   glibc manual and source

> 3. Can you find anyone to review this page for technical accuracy.  I am
> pressed for time.
That's why I've submitted it; I'm pressed for time too and don't see
the point of letting it stagnate on my disk and have someone else
write something from scratch.

> 4. A couple of demonstration programs might help this man page.  Once
> simple, the other more complex and general.  Initially, you forward the
> programs separately.
Sure, I'm still playing with this.  In particular interaction between
all the variables and special case function values should be
documented (and, well, tested).

Justin



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#411303; Package manpages,groff. Full text and rfc822 format available.

Acknowledgement sent to Colin Watson <cjwatson@debian.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #15 received at 411303@bugs.debian.org (full text, mbox):

From: Colin Watson <cjwatson@debian.org>
To: Justin Pryzby <justinpryzby@users.sourceforge.net>, 411303@bugs.debian.org
Cc: Michael Kerrisk <mtk-manpages@gmx.net>, 349388@bugs.debian.org
Subject: Re: Bug#411303: Bug#349388: argp.3
Date: Tue, 24 Apr 2007 16:38:45 +0100
On Tue, Apr 24, 2007 at 10:25:05AM -0400, Justin Pryzby wrote:
> On Tue, Apr 24, 2007 at 04:14:15PM +0200, Michael Kerrisk wrote:
> > If you would like to get this pushed upstream, the following would help:
> > 
> > 1. Follow man-pages formatting conventions would help.  In particular, the
> > use of lines containing just a "." (to force a blank line) should be
> > avoided.  Just remove all of those lines.  (Most man-pages do not have the
> > more than one blank line to separate sections.)

For the record, a line containing just a "." doesn't force a blank line;
rather, it does nothing. Compare:

  .TH FOO 1
  .SH NAME
  foo \- bar
  .SH DESCRIPTION
  foo
  .
  bar

... with:

  .TH FOO 1
  .SH NAME
  foo \- bar
  .SH DESCRIPTION
  foo
  
  bar

> I'd actually like to see some resolution to #411303 before changing
> everything back; nobody has commented on it yet.  After spending some
> effort reading documentation, it's not inspiring to be told that the
> documentation is wrong.

I didn't comment on #411303 because I was under the impression I
effectively already had. :-)

man(7) seems to have two purposes: first, it purports to document the
groff man macros; secondly, it acts as a man page style guide, at least
for those manual pages using the man macros. Perhaps it would help if it
dropped the first purpose and referred to groff_man instead, since
that's pretty small?

-- 
Colin Watson                                       [cjwatson@debian.org]



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>:
Bug#411303; Package manpages,groff. Full text and rfc822 format available.

Acknowledgement sent to Michael Kerrisk <mtk-manpages@gmx.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>. Full text and rfc822 format available.

Message #20 received at 411303@bugs.debian.org (full text, mbox):

From: Michael Kerrisk <mtk-manpages@gmx.net>
To: Justin Pryzby <justinpryzby@users.sourceforge.net>, 411303@bugs.debian.org
Cc: 349388@bugs.debian.org
Subject: Re: Bug#411303: Bug#349388: argp.3
Date: Tue, 24 Apr 2007 18:00:39 +0200
Hi Hustin,

>> If you would like to get this pushed upstream, the following would help:
>>
>> 1. Follow man-pages formatting conventions would help.  In particular, the
>> use of lines containing just a "." (to force a blank line) should be
>> avoided.  Just remove all of those lines.  (Most man-pages do not have the
>> more than one blank line to separate sections.)
> I'd actually like to see some resolution to #411303 before changing
> everything back; nobody has commented on it yet.  After spending some
> effort reading documentation, it's not inspiring to be told that the
> documentation is wrong.

Umm -that bug report is about quoting after .SH -- an unrelated issue.  Or
am I misunderstanding something?  My conclusion is that quoting is not
required not required.  I will fix man.7 to remove the mention of quotes
for .SH.

>> 2. It would be helpful to know where you have gained the information from.
> .\" References:
> .\"   glibc manual and source

Doh -- sorry!

>> 3. Can you find anyone to review this page for technical accuracy.  I am
>> pressed for time.
> That's why I've submitted it; I'm pressed for time too and don't see
> the point of letting it stagnate on my disk and have someone else
> write something from scratch.

Sounds good.  Hello any reviewer out there?

>> 4. A couple of demonstration programs might help this man page.  Once
>> simple, the other more complex and general.  Initially, you forward the
>> programs separately.
> Sure, I'm still playing with this.  In particular interaction between
> all the variables and special case function values should be
> documented (and, well, tested).

If you have a chance, could you append a couple of test programs to this
bug report.

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance?  Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>:
Bug#411303; Package manpages,groff. Full text and rfc822 format available.

Acknowledgement sent to Michael Kerrisk <mtk-manpages@gmx.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>. Full text and rfc822 format available.

Message #25 received at 411303@bugs.debian.org (full text, mbox):

From: Michael Kerrisk <mtk-manpages@gmx.net>
To: Colin Watson <cjwatson@debian.org>
Cc: Justin Pryzby <justinpryzby@users.sourceforge.net>, 411303@bugs.debian.org, 349388@bugs.debian.org
Subject: Re: Bug#411303: Bug#349388: argp.3
Date: Tue, 24 Apr 2007 18:24:26 +0200
Colin Watson wrote:
> On Tue, Apr 24, 2007 at 10:25:05AM -0400, Justin Pryzby wrote:
>> On Tue, Apr 24, 2007 at 04:14:15PM +0200, Michael Kerrisk wrote:
>>> If you would like to get this pushed upstream, the following would help:
>>>
>>> 1. Follow man-pages formatting conventions would help.  In particular, the
>>> use of lines containing just a "." (to force a blank line) should be
>>> avoided.  Just remove all of those lines.  (Most man-pages do not have the
>>> more than one blank line to separate sections.)
> 
> For the record, a line containing just a "." doesn't force a blank line;
> rather, it does nothing. Compare:

Cough!  Yes, thanks!

(Justin, do please eliminate those lines though.)

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance?  Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>:
Bug#411303; Package manpages,groff. Full text and rfc822 format available.

Acknowledgement sent to Justin Pryzby <justinpryzby@users.sourceforge.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>. Full text and rfc822 format available.

Message #30 received at 411303@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: Michael Kerrisk <mtk-manpages@gmx.net>
Cc: 411303@bugs.debian.org
Subject: Re: Bug#349388: Bug#411303: Bug#349388: argp.3
Date: Sat, 28 Apr 2007 16:34:37 -0400
Ccing bug #411303 not #349388

On Tue, Apr 24, 2007 at 06:00:39PM +0200, Michael Kerrisk wrote:
> Hi Hustin,
> 
> >> If you would like to get this pushed upstream, the following would help:
> >>
> >> 1. Follow man-pages formatting conventions would help.  In particular, the
> >> use of lines containing just a "." (to force a blank line) should be
> >> avoided.  Just remove all of those lines.  (Most man-pages do not have the
> >> more than one blank line to separate sections.)
> > I'd actually like to see some resolution to #411303 before changing
> > everything back; nobody has commented on it yet.  After spending some
> > effort reading documentation, it's not inspiring to be told that the
> > documentation is wrong.
> 
> Umm -that bug report is about quoting after .SH -- an unrelated issue.  Or
The no-empty-lines things is from roff.7 which documents historical
roff.  So I think you're right that this is a nonissue.

man.7
status values or  a  program
s/or/f&/

groff_man requires that arguments for some formatting macros (like
.BR) be on the same line, yet man.7 seems to say that they can be on
different lines.

Colin: groff.7: "afterwards the string to be defined"
I think just:         after ........................

"registers starting with a dot a read-only"
                              ^^^
                              are

       .di macro Divert to macro .
                           ^^^^^^^
There should be no space here, and the underlining is messed up;
.I macro .
.IR macro .



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>:
Bug#411303; Package manpages,groff. Full text and rfc822 format available.

Acknowledgement sent to Michael Kerrisk <mtk-manpages@gmx.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>. Full text and rfc822 format available.

Message #35 received at 411303@bugs.debian.org (full text, mbox):

From: Michael Kerrisk <mtk-manpages@gmx.net>
To: Justin Pryzby <justinpryzby@users.sourceforge.net>, 411303@bugs.debian.org
Subject: Re: Bug#411303: Bug#349388: Bug#411303: Bug#349388: argp.3
Date: Sun, 27 May 2007 10:24:12 +0200
> 
> man.7
> status values or  a  program
> s/or/f&/

Did I say already that that typod has been fixed now?

Thanks,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance?  Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>:
Bug#411303; Package manpages,groff. (Fri, 28 Nov 2008 14:21:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to mtk.manpages@gmail.com:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>, Colin Watson <cjwatson@debian.org>. (Fri, 28 Nov 2008 14:21:03 GMT) Full text and rfc822 format available.

Message #40 received at 411303@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk.manpages@googlemail.com>
To: 411303@bugs.debian.org
Cc: control@bugs.debian.org
Date: Fri, 28 Nov 2008 09:20:04 -0500
tags 411303 fixed-upstream
thanks


I long ago (April 2007, man-pgaes-2.48) fixed the problem that was the
source of Justsin's complaint for this bug.  Isn't it time to close
it?




Tags added: fixed-upstream Request was from "Michael Kerrisk" <mtk.manpages@googlemail.com> to control@bugs.debian.org. (Fri, 28 Nov 2008 14:21:06 GMT) Full text and rfc822 format available.

Reply sent to Martin Schulze <joey@infodrom.org>:
You have taken responsibility. (Fri, 28 Nov 2008 23:33:12 GMT) Full text and rfc822 format available.

Notification sent to justinpryzby@users.sourceforge.net:
Bug acknowledged by developer. (Fri, 28 Nov 2008 23:33:19 GMT) Full text and rfc822 format available.

Message #47 received at 411303-done@bugs.debian.org (full text, mbox):

From: Martin Schulze <joey@infodrom.org>
To: mtk.manpages@gmail.com, 411303-done@bugs.debian.org
Subject: Re: Bug#411303:
Date: Fri, 28 Nov 2008 20:00:17 +0100
Michael Kerrisk wrote:
> I long ago (April 2007, man-pgaes-2.48) fixed the problem that was the
> source of Justsin's complaint for this bug.  Isn't it time to close
> it?

Right.  Closing now.

Regards,

	Joey

-- 
If you come from outside of Finland, you live in wrong country.
	-- motd of irc.funet.fi




Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Sat, 27 Dec 2008 07:26:34 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Fri Apr 18 06:28:28 2014; Machine Name: beach.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.