debianutils: sensible-editor(1) references BROWSER variable in environ(7), but no such reference

[Carthik Sharma]

Note: This bug report was originally sent to ubuntu-users using reportbug by Chris Pimlott bugs at chris.pimlott.net

The SEE ALSO section of sensible-editor(1) says:

       Documentation of the EDITOR, PAGER, and BROWSER variables in
environ(7)

However, there is no documentation on BROWSER in environ(7).

-- System Information:
Debian Release: testing/unstable
  APT prefers dapper-updates
  APT policy: (500, 'dapper-updates'), (500, 'dapper-security'), (500, 'dapper')
Architecture: i386 (i686)
Shell: /bin/sh linked to /bin/bash
Kernel: Linux 2.6.15-21-686
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)

Versions of packages debianutils depends on:
ii coreutils 5.93-5ubuntu4 The GNU core utilities
ii libc6 2.3.6-0ubuntu17 GNU C Library: Shared libraries an

debianutils recommends no packages.

-- no debconf information

[Justin Pryzby (justinpryzby-users)]

tag 123999 upstream
tag 147778 upstream
tag 171681 upstream
tag 182706 upstream
tag 215238 upstream
tag 235967 upstream
tag 268121 upstream
tag 95444 upstream
tag 156154 upstream
tag 182014 upstream
tag 186282 upstream
tag 186307 upstream
tag 202022 upstream
tag 205238 upstream
tag 207517 upstream
tag 216092 upstream
tag 225619 upstream
tag 236671 upstream
tag 255881 upstream
tag 295211 upstream
tag 306867 upstream
tag 309599 upstream
tag 337581 upstream
tag 341642 upstream
tag 342173 upstream
thanks

[Ryan C. Underwood (nemesis-icequake)]

Package: manpages
Version: 2.17-1
Followup-For: Bug #186282

It appears that the reference to BROWSER was simply removed from
environ(7) in later versions. This isn't an acceptable fix...

-- System Information:
Debian Release: testing/unstable
  APT prefers testing
  APT policy: (990, 'testing'), (500, 'unstable'), (1, 'experimental')
Architecture: i386 (i686)
Shell: /bin/sh linked to /bin/bash
Kernel: Linux 2.6.14
Locale: LANG=C, LC_CTYPE= (charmap=ANSI_X3.4-1968)

-- no debconf information

[Ryan C. Underwood (nemesis-icequake)]

Package: manpages
Version: 2.17-1
Followup-For: Bug #186282

The documentation for BROWSER should be moved from pts(1) in devscripts
to environ(7) in manpages, and then referred to from devscripts.

-- System Information:
Debian Release: testing/unstable
  APT prefers testing
  APT policy: (990, 'testing'), (500, 'unstable'), (1, 'experimental')
Architecture: i386 (i686)
Shell: /bin/sh linked to /bin/bash
Kernel: Linux 2.6.14
Locale: LANG=C, LC_CTYPE= (charmap=ANSI_X3.4-1968)

-- no debconf information

[Michael Kerrisk (mtk-manpages-gmx)]

> It appears that the reference to BROWSER was simply removed from
> environ(7) in later versions. This isn't an acceptable fix...

Not acceptable because?

Cheers,

Michael

PS I removed it from the page on the basis that this page
lists common environment variables. BROWSER seems to be far
from common. But if you can produce examples...

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

[Ryan C. Underwood (nemesis-icequake)]

On Mon, Feb 06, 2006 at 11:23:04AM +0100, Michael Kerrisk wrote:
> > It appears that the reference to BROWSER was simply removed from
> > environ(7) in later versions. This isn't an acceptable fix...
>
> Not acceptable because?

The information is duplicated in several other man pages. Some even
refer to environ(7) on the presumption that BROWSER would be documented
there.

> PS I removed it from the page on the basis that this page
> lists common environment variables. BROWSER seems to be far
> from common. But if you can produce examples...

zgrep -r BROWSER /usr/share/man
Even sensible-browser in debianutils uses it.

--
Ryan Underwood, <email address hidden>

[Michael Kerrisk (mtk-manpages-gmx)]

> On Mon, Feb 06, 2006 at 11:23:04AM +0100, Michael Kerrisk wrote:
> > > It appears that the reference to BROWSER was simply removed from
> > > environ(7) in later versions. This isn't an acceptable fix...
> >
> > Not acceptable because?
>
> The information is duplicated in several other man pages.

How is that a problem?

> Some even refer to environ(7) on the presumption that
> BROWSER would be documented there.

Which ones?

> > PS I removed it from the page on the basis that this page
> > lists common environment variables. BROWSER seems to be far
> > from common. But if you can produce examples...
>
> zgrep -r BROWSER /usr/share/man
> Even sensible-browser in debianutils uses it.

On the distribution I just checked (not Debian), grepping the
man pages produced exactly one other man page that mentions
BROWSER.

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.

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

[Ryan C. Underwood (nemesis-icequake)]

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), ...
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) seems to be the conventional place for documenting specific
environment variables. I don't see why BROWSER is an exception.

If this is simply an excuse for not having time to add the appropriate
documentation, here is a patch. Thanks.

--
Ryan Underwood, <email address hidden>

[Michael Kerrisk (mtk-manpages-gmx)]

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

[Ryan C. Underwood (nemesis-icequake)]

On Mon, Feb 06, 2006 at 11:31:35PM +0100, Michael Kerrisk wrote:
> >
> > 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.

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

> > 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. Nor am I going out of my way
to offend you... in any case I apologize if I have offended you.

Thanks,

--
Ryan Underwood, <email address hidden>

[Michael Kerrisk (mtk-manpages-gmx)]

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

[Ryan C. Underwood (nemesis-icequake)]

On Tue, Feb 07, 2006 at 05:36:29AM +0100, Michael Kerrisk wrote:
> > > > apt-listchanges(1), bts(1), dhelp(1), dwww(1), fontforge(1), man(1),
> > > > mensis(1), querybts(1), sensible-browser(1), urlview(1), ...
>
> 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.

Since out of 10 programs on my system that respect BROWSER, six are
Debian utilities, perhaps it is best left to the Debian maintainer to
decide whether to document the extended version. Out of the non-Debian
utilities, only man and urlview claim to support the extended version.

Still, with respect to the basic version, can you provide some
counterexample of a program that launches an external browser that does
_not_ respect a user's BROWSER variable? If counterexamples are hard to
come by, perhaps it is worth documenting at least the basic version.
That way, a user is aware that he has control over what browser is
launched - in the same manner he has control over what external editor
is launched.

And maybe the counterexamples should be considered usability bugs
anyway; who wants a hard-coded external browser?

--
Ryan Underwood, <email address hidden>

[Michael Kerrisk (mtk-manpages-gmx)]

> On Tue, Feb 07, 2006 at 05:36:29AM +0100, Michael Kerrisk wrote:
> > > > > apt-listchanges(1), bts(1), dhelp(1), dwww(1), fontforge(1),
> > > > > man(1),
> > > > > mensis(1), querybts(1), sensible-browser(1), urlview(1), ...
> >
> > 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.
>
> Since out of 10 programs on my system that respect BROWSER, six are
> Debian utilities, perhaps it is best left to the Debian maintainer to
> decide whether to document the extended version. Out of the non-Debian
> utilities, only man and urlview claim to support the extended version.
>
> Still, with respect to the basic version, can you provide some
> counterexample of a program that launches an external browser that does
> _not_ respect a user's BROWSER variable?

Offhand, I cannot. But my original point was: is BROWSER
common? it is not. (And is it consistent? it is not.)
That was why I removed it from the page.

> If counterexamples are hard to
> come by, perhaps it is worth documenting at least the basic version.

Yes, at this time each app that uses should note it (just as does
*any* application that relies on environment variables), and those
few that observe the % conventions should note that.

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

[Ryan C. Underwood (nemesis-icequake)]

On Tue, Feb 07, 2006 at 08:30:39PM +0100, Michael Kerrisk wrote:
> >
> > Still, with respect to the basic version, can you provide some
> > counterexample of a program that launches an external browser that does
> > _not_ respect a user's BROWSER variable?
>
> Offhand, I cannot. But my original point was: is BROWSER
> common? it is not. (And is it consistent? it is not.)
> That was why I removed it from the page.

Is is consistent?
Every one who supports BROWSER consistently supports the basic version.

Is it common?
What is the metric for being common enough for central reference?
Divide the number of packages that respect BROWSER by the number of
packages in the system? I believe that to be a poor metric. For
example, approximately 2-3 times the number of applications that respect
BROWSER respect EDITOR. This is still insignificant compared to the
number of packages in the system. Therefore, by that reasoning, EDITOR
is not common either. Same for VISUAL.

I believe this metric should have in its denominator the number of
packages _which perform the function that the environment variable in
question could potentially control_ - NOT the total number of packages
in the system.

> > If counterexamples are hard to
> > come by, perhaps it is worth documenting at least the basic version.
>
> Yes, at this time each app that uses should note it (just as does
> *any* application that relies on environment variables), and those
> few that observe the % conventions should note that.

You know what I meant - to document the basic version in environ(5) and
leave it up to the distributor to clutter the page further if his
distribution uses the extended version. Anyway, you have my opinion and
you obviously disagree for reasons unconvincing to me, so there's little
point in discussing this further.

--
Ryan Underwood, <email address hidden>

[Carthik Sharma (carthik)]

Note: This bug report was originally sent to ubuntu-users using reportbug.

The SEE ALSO section of sensible-editor(1) says:

       Documentation of the EDITOR, PAGER, and BROWSER variables in
environ(7)

However, there is no documentation on BROWSER in environ(7).

-- System Information:
Debian Release: testing/unstable
  APT prefers dapper-updates
  APT policy: (500, 'dapper-updates'), (500, 'dapper-security'), (500, 'dapper')
Architecture: i386 (i686)
Shell: /bin/sh linked to /bin/bash
Kernel: Linux 2.6.15-21-686
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)

Versions of packages debianutils depends on:
ii coreutils 5.93-5ubuntu4 The GNU core utilities
ii libc6 2.3.6-0ubuntu17 GNU C Library: Shared libraries an

debianutils recommends no packages.

-- no debconf information

[Simon Law (sfllaw)]

The manpages package is a bit out of date, compared to the
Debian version.

[Ryan C. Underwood (nemesis-icequake)]

reassign 445435 manpages
severity 186282 minor
merge 186282 445435
thanks

--
Ryan C. Underwood, <email address hidden>