From garys@opusnet.com  Tue Aug 16 20:22:44 2005
Return-Path: <garys@opusnet.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 072FD16A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 16 Aug 2005 20:22:44 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from opusnet.com (mail.opusnet.com [209.210.200.6])
	by mx1.FreeBSD.org (Postfix) with ESMTP id B395943D46
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 16 Aug 2005 20:22:43 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id AB12FDFB0030; Tue, 16 Aug 2005 13:22:42 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j7GKNW4G052895
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 16 Aug 2005 13:23:32 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j7GKNRLZ052894;
	Tue, 16 Aug 2005 13:23:27 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <8tek8tws00.k8t@mail.opusnet.com>
Date: Tue, 16 Aug 2005 13:23:27 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: [patch] environ(7) manpage references builtin(1) but not
 printenv(1)
X-GNATS-Notify:

>Number:         85008
>Category:       docs
>Synopsis:       [patch] environ(7) manpage references builtin(1) but not
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    keramida
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Aug 16 20:30:15 GMT 2005
>Closed-Date:    Wed Jul 12 11:32:12 GMT 2006
>Last-Modified:  Wed Jul 12 11:32:12 GMT 2006
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:

environ(7) manpage references builtin(1) (as cd(1)) and ex(1)
for no apparent reason, but not printenv(1).

(It also references system(3), but I'm less sure about the
irrelevance of that, so I don't propose removing it.)

>How-To-Repeat:
n/a

>Fix:
Remove cd(1) and ex(1).
Add printenv(1).
Move csh(1) to make the grouping more consistent.


--- environ..orig.7	Mon Aug  8 16:42:46 2005
+++ environ.7	Mon Aug  8 17:20:13 2005
@@ -234,11 +234,10 @@
 .Ev IFS ,
 unless you know what you are doing.
 .Sh SEE ALSO
-.Xr cd 1 ,
-.Xr csh 1 ,
 .Xr env 1 ,
-.Xr ex 1 ,
+.Xr printenv 1 ,
 .Xr login 1 ,
+.Xr csh 1 ,
 .Xr sh 1 ,
 .Xr execve 2 ,
 .Xr execle 3 ,

>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@freebsd.org>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/85008: [patch] environ(7) manpage references builtin(1) but not printenv(1)
Date: Wed, 17 Aug 2005 01:05:26 +0300

 On 2005-08-16 13:23, "Gary W. Swearingen" <garys@opusnet.com> wrote:
 > environ(7) manpage references builtin(1) (as cd(1)) and ex(1)
 > for no apparent reason, but not printenv(1).
 >
 > (It also references system(3), but I'm less sure about the
 > irrelevance of that, so I don't propose removing it.)
 
 > >Fix:
 >  .Sh SEE ALSO
 > -.Xr cd 1 ,
 > -.Xr csh 1 ,
 >  .Xr env 1 ,
 > -.Xr ex 1 ,
 > +.Xr printenv 1 ,
 >  .Xr login 1 ,
 > +.Xr csh 1 ,
 >  .Xr sh 1 ,
 >  .Xr execve 2 ,
 >  .Xr execle 3 ,
 
 See below for comments for each change...
 
 > 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.
 
 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.
 
 > 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).
 
 > 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.
 

From: garys@opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@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@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.
State-Changed-From-To: open->patched 
State-Changed-By: keramida 
State-Changed-When: Wed Aug 17 13:40:17 GMT 2005 
State-Changed-Why:  
The printenv(1) reference was added with the text that describes 
how environment variables can be displayed.  I'll merge to 6.X 
once I get approval and to 5.X shortly after. 

Thanks! 


Responsible-Changed-From-To: freebsd-doc->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Wed Aug 17 13:40:17 GMT 2005 
Responsible-Changed-Why:  

http://www.freebsd.org/cgi/query-pr.cgi?pr=85008 

From: Giorgos Keramidas <keramida@freebsd.org>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/85008: [patch] environ(7) manpage references builtin(1) but not printenv(1)
Date: Wed, 17 Aug 2005 16:13:18 +0300

 On 2005-08-16 19:52, "Gary W. Swearingen" <garys@opusnet.com> wrote:
 >Giorgos Keramidas <keramida@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
 
 5.4-RELEASE is too old.  The manpage has no difference from HEAD in the
 RELENG_5 revision.
 
 > 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.
 
 I see.  Then cd(1) can go, I guess.
 
 >> 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>"
 
 ``FreeBSD''? :P
 
 I think the reason the references for all the xxx(n) inline references
 are collected in the SEE ALSO section, even if they only appear once and
 they refer to marginally related topics, really is to have all the
 references in a neat collection at a well known place.
 
 You are probably thinking that this is not a good way to present related
 ``topics'', in which case I agree, but unfortunately the SEE ALSO
 section is an admittedly poor way of presenting related topics.
 Personally, I'd prefer something more index-like.  For instance, the
 pthreads_xxx() manpages could end with:
 
 	SEE ALSO
 
 	     Other manual pages describing functions related to the
 	     POSIX threads include:
 
 		 pthread_create(3), pthread_attr_init(3),
 		 pthread_attr_destroy(3), ...
 
 	     Manual pages linked from this document are:
 
 	         cd(1), ex(1), vi(1), hosts.allow(5)
 
 but this is, I'm afraid quite impossible and contrary to the way SEE
 ALSO sections have traditionally been used.
 
 >>> 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.
 
 Thanks.
 
 > 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).
 
 These are not part of the standard, base system.  We can't add
 references to them, because people who don't install the relevant ports
 will have tons of broken manpage links.
 
 > 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.
 
 I've added a paragraph that describes how to display the current
 environment variables and a reference to printenv(1).  Thanks for
 putting up with my (probably annoying at times) comments.
 
 - Giorgos
 
State-Changed-From-To: patched->closed 
State-Changed-By: keramida 
State-Changed-When: Wed Jul 12 11:31:08 UTC 2006 
State-Changed-Why:  
This has been MFC'ed to: 

RELENG_5 with revision 1.23.2.1 @ 2005/08/26 10:27:02; 
RELENG_6 with revision 1.23.8.1 @ 2005/08/26 10:25:44; 


http://www.freebsd.org/cgi/query-pr.cgi?pr=85008 
>Unformatted:
  printenv(1)
