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

Toggle useless messages

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

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).

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

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

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

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]

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

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'.

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

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'.

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

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 .

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

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'.

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

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?

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

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

Send a report that this bug log contains spam.