Bug 85008

Comment 1 Giorgos Keramidas 2005-08-16 23:05:26 UTC

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.

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.

Comment 3 Giorgos Keramidas 2005-08-17 14:13:18 UTC

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

Comment 4 Giorgos Keramidas 2005-08-17 14:40:17 UTC

State Changed
From-To: open->patched

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! 

Comment 5 Giorgos Keramidas 2005-08-17 14:40:17 UTC

Responsible Changed
From-To: freebsd-doc->keramida

Comment 6 Giorgos Keramidas 2006-07-12 12:31:08 UTC

State Changed
From-To: patched->closed

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;