docs/85008: [patch] environ(7) manpage references builtin(1) but not printenv(1)

[Gary W. Swearingen]

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
 described envars.
 
 > 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
 > either.
 
 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
 suppose.
 
 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.