Comment 8 for bug 46480

> On Mon, Feb 06, 2006 at 07:57:13PM +0100, Michael Kerrisk wrote:
> > >
> > > The information is duplicated in several other man pages.
> >
> > How is that a problem?
>
> Usually we maintain information in one place and provide pointers to it,
> to lessen the maintenance cost in avoiding inconsistent and/or
> contradictory copies.
>
> > > Some even refer to environ(7) on the presumption that
> > > BROWSER would be documented there.
> >
> > Which ones?
>
> At a glance, sensible-browser and urlview. This is just on one system.
>
> > On the distribution I just checked (not Debian), grepping the
> > man pages produced exactly one other man page that mentions
> > BROWSER.
>
> apt-listchanges(1), bts(1), dhelp(1), dwww(1), fontforge(1), man(1),
> mensis(1), querybts(1), sensible-browser(1), urlview(1), ...

Are you saying that all of these tools observe the '%' specifiers
that are documented in your proposed patch? Certainly some of the
manual pages do not indicate that is so.

(Interestingly, the man(1) is the only one of these
that is present and documentes BROWSER on the SUSE 10 and
RH ES 4.0 systems I just checked; RH has urlview(1), but the page
there does not document BROWSER. I am guessing that many of the
above pages are Debian-specific.)

> And that doesn't even include the various non-English translations of
> these man pages, which also must maintain copies of that information.
>
> > Any apps that need BROWSER should of course be documenting
> > its use in their own man pages -- they do not/should not
> > be relying on environ(7) to be documenting specific
> > environment variables.
>
> environ(7)

Actually environ(5) in upstream -- Debian has changed this for
some reason unknown to me.

> seems to be the conventional place for documenting specific
> environment variables.

*some* environment variables. To repeat, I looked at the
brief list of environment variables that were said to be *common*
in environ(5), and BROWSER is clearly not common.

> I don't see why BROWSER is an exception.

It is not; see above.

> If this is simply an excuse for not having time to add the appropriate
> documentation,

You begin by stating that a change to the manual pages is
"unacceptable", now you are making presumptions about my
motivations. Neither of things has warmed me up to
your argument.

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
ftp://ftp.win.tue.nl/pub/linux-local/manpages/,
read the HOWTOHELP file and grep the source
files for 'FIXME'.