docs/85008: [patch] environ(7) manpage references builtin(1) but not printenv(1)
Gary W. Swearingen
garys at opusnet.com
Wed Aug 17 03:00:43 UTC 2005
The following reply was made to PR docs/85008; it has been noted by GNATS.
From: garys at opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida at freebsd.org>
Cc: bug-followup at freebsd.org
Subject: Re: docs/85008: [patch] environ(7) manpage references builtin(1)
but not printenv(1)
Date: Tue, 16 Aug 2005 19:52:21 -0700
Giorgos Keramidas <keramida at freebsd.org> writes:
>> Remove cd(1) and ex(1).
> No, please. The environ(7) manpage describes CDPATH (which affects the
> ``cd'' builtin of popular shells and is hard-linked as cd(1) to the
> builtin(1) manpage). This is why the references to cd(1) exist.
My 5.4-RELEASE environ(7) doesn't describe CDPATH and it's not used by
enough commands to deserve being described there, and even if it was I
don't see why it matters that it's a builtin when considering
references to other manpages. I can't even imagine why I'd want to
look at the builtin(1) (=cd(1)) manpage when I'm reading environ(7).
And there's a huge number of manpages for other commands that use the
> The ex(1) and vi(1) manpages are referenced within the text of the
> environ(7) manpage, at the description of EXINIT, so they can't go away
Sure they can. The references are located where they are needed, and
people looking at the "SEE ALSO" are looking for manpages related to
environ(7); they are not looking for a reference that they already
either already know about which has nothing to do with the subject of
environ(7) or won't care about for the same reason. People who are
reading about the envar EXINIT will find the references related to
that in it's description.
"Consistency is the hobgoblin of <something I forget>"
>> Add printenv(1).
> This is cool, but we have to find a good way to reference this manpage
> from the manpage text too. How about something like this?
> The current environment variables can be printed with set(1) or
> printenv(1) in sh(1) and printenv(1) or the ``printenv'' built-in
> command in csh(1).
That's almost fine with me, but I don't know why you say "we have to".
I'd think people interested in "environ" would probably check out the
likely-sounding "env" and "printenv" as SOP. But your para is helpful.
I say "almost", because "env" will also print the envars.
I guess I'll also admit to being miffed by gratuitous references to
"sh" and "csh" when so many users, especially those new to FreeBSD,
use bash or something else like ksh93 or pdksh (which I use).
>> Move csh(1) to make the grouping more consistent.
> Nope, this is wrong. The manpages in SEE ALSO sections are always
> sorted first by section number and then alphabetically.
OK, I'll try to remember that rule. My grouping was only a marginal
improvement anyway; I would order them all by decreasing likelyhood of
interest to a newbie, but I guess there would be too many
bikeshed-related changes like my proposed change, so the order less
helpful to users is more helpful to the FDP. A reasonable tactic, I
I'm happy to discuss this more, but there's no need; I'll not complain
about whatever you choose to do with this PR.
More information about the freebsd-doc