NetBSD Problem Report #35460

From www@NetBSD.org  Sun Jan 21 19:19:25 2007
Return-Path: <www@NetBSD.org>
Received: by narn.NetBSD.org (Postfix, from userid 31301)
	id 53CBA63B9EE; Sun, 21 Jan 2007 19:19:25 +0000 (UTC)
Message-Id: <20070121191925.53CBA63B9EE@narn.NetBSD.org>
Date: Sun, 21 Jan 2007 19:19:25 +0000 (UTC)
From: uwe@NetBSD.org
Reply-To: uwe@NetBSD.org
To: gnats-bugs@NetBSD.org
Subject: man(1) and catman(1) don't honour '\" first line comment
X-Send-Pr-Version: www-1.0

>Number:         35460
>Category:       bin
>Synopsis:       man(1) and catman(1) don't honour '\" first line comment
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          sw-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Jan 21 19:20:00 +0000 2007
>Last-Modified:  Sat May 21 11:50:00 +0000 2016
>Originator:     Valery Ushakov
>Release:        current
>Organization:
>Environment:
NetBSD bigmac 4.99.1 NetBSD 4.99.1 (BIGMAC) #2: Sat Sep 16 03:57:52 MSD 2006  uwe@bigmac:/export/netbsd/cvs/src/sys/arch/macppc/compile/BIGMAC macppc
>Description:
It is a traditional practice to specify required preprocessors in
the first line comment of the manual page.  Groff info has this to say:

4.1.6 Preprocessors in `man' pages
----------------------------------

If a preprocessor like `gtbl' or `geqn' is needed, it has become common
usage to make the first line of the man page look like this:


     '\" WORD

Note the single space character after the double quote.  WORD consists
of letters for the needed preprocessors: `e' for `geqn', `r' for
`grefer', `t' for `gtbl'.  Modern implementations of the `man' program
read this first line and automatically call the right preprocessor(s).


Our man(1) and catman(1) don't honour this comment.

For system man pages this is hidden by the fact that we ship cat pages
and when pre-formmatting cat pages, we realy on the program Makefile
to specify USETBL= make variable.


>How-To-Repeat:
        $ mkdir -p /tmp/man/man1
        $ cp /usr/share/man/man1/ksh.1 /tmp/man/man1
        $ MANPATH=/tmp/man man ksh | less +/'Compound commands'

and compare with

        $ man ksh | less +/'Compound commands'

You can also see this with system x11 pages, e.g.:

        $ man XCreateWindow | less +/'Window attribute value'

b/c makefile doesn't suuply USETBL= and so preformatted cat page
is not preprocessed correctly.

>Fix:

>Audit-Trail:
From: Abhinav Upadhyay <er.abhinav.upadhyay@gmail.com>
To: NetBSD GNATS <gnats-bugs@netbsd.org>
Cc: 
Subject: Re: bin/35460
Date: Sat, 21 May 2016 16:38:02 +0530

 I think this is not valid anymore now that we use mandoc for formatting
 the man page? :)

 -
 Abhinav

From: Valery Ushakov <uwe@stderr.spb.ru>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: bin/35460 - man(1) and catman(1) don't honour '\" first line
 comment
Date: Sat, 21 May 2016 14:46:37 +0300

 On Sat, May 21, 2016 at 11:10:01 +0000, Abhinav Upadhyay wrote:

 >  I think this is not valid anymore now that we use mandoc for
 >  formatting the man page? :)

 We use mandoc only because man.conf specifies mandoc as the man page
 formatter.  Nothing prevents users from switching back to nroff and
 I'd prefer we keep it that way.  Now, there's a problem that
 traditional magic handling of the first line assumes nroff and will
 break mandoc if performed unconditionally.  So what our switch to
 mandoc implies is not that this bug can be closed, but that the
 handling of the first line must be controlled by a man.conf option.

 -uwe

Home	PR Database Search