Comment 10 for bug 46480

> > > 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.
>
> The patch says 'most' observe the extended format, while informing the
> user contextually that some do not. Change it to 'many' if you disagree
> on the proportion.
>
> > (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.)
>
> Yes, many of them are. I filed a Debian bug after all. If you're
> upstream, I'm not sure why this bug reached you because I didn't send it
> to you.

Because Debian makes it possible (thank folks!), and a short time
browsing the Debian BTS for man-pages/man-pages-dev would illustrate
the benefits that result.

I responded to this particular report because it was my upstream action
that changed the page.

> > > environ(7)
> >
> > Actually environ(5) in upstream -- Debian has changed this for
> > some reason unknown to me.
>
> (5) is for documenting file formats according to FHS. A strict reading
> of FHS would exclude it from (5), but I'm not sure anyone really cares
> about that.

The logic is reasonable. environ(5) made its way there before
my time; (7) does seem more logical -- but the question is whether
to break existing culture by moving such misplaced pages.
Another day...

> > > 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.
>
> How many applications must respect it in order to be considered
> 'common'? Very few applications launch an external browser, but of
> those that do, most of them seem to respect BROWSER. Because many
> applications do not launch external browsers, BROWSER is thus uncommon?
>
> > > 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.
>
> I'm a busy person myself and I would prefer to present opposition to
> work that I don't consider necessary, and that someone seems capable of
> doing themselves, than to spent time doing that work. That is all I
> meant. And I perceived that was the case because the original BROWSER
> documentation was simply commented out rather than fixed according to
> the user request.
>
> Anyway, I'm not trying to 'warm you up' to convince you, because I
> believe only facts are truly convincing.

Facts are in short supply though. Here is a fact. Before I
decided about commenting out that text, I grepped the entire
source tree of one Linux distribution to see how many applications
were using BROWSER. There were no more than a handful. (I do not
remember how many exactly, but the number was very small.) I did
not check how many of those observed the % conventions described
in your patch, but obviously it would have been an even smaller
number.

Debian is of course free to patch their own version of the pages.
But before doing so, it may be worthwhile to check out how
many applications actually use BROWSER and whether they actually
observe the % conventions. If I see some convincing information,
I would consider patching upstream.

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