Subject: Re: misc/23278: fixes for sh(1) - wrong sections and man pages referred
To: NetBSD GNATS submissions and followups <firstname.lastname@example.org>
From: Igor Sobrado <email@example.com>
Date: 10/27/2003 13:34:02
In message <m1ADoIA-0002TNC@proven.weird.com>, you wrote:
> I've just done the following in my copy (even though I've removed all
> traces and remnants of csh from my system and so could have an sh/ksh
> compatible copy of alias(1) :-)
Thanks a lot, Greg and Wiz for the feedback on sh(1) and fixing
Wow... it looks to me that you do not like csh(1) a lot. How curious,
sh(1) was originally written by Stephen Bourne (the former ACM president)
and used in AT&T Unix. csh(1) was developed for the BSD operating
> @@ -301,10 +301,10 @@
> Their meaning is discussed later.
> .Ss Aliases
> An alias is a name and corresponding value set using the
> -.Xr alias 1
> -builtin command. Whenever a reserved word may occur (see above),
> +.Ic alias
> +built-in command. Whenever a reserved word may occur (see above),
> and after checking for reserved words, the shell
> -checks the word to see if it matches an alias. If it does,
> +checks the word to see if it matches an alias. If it does,
> it replaces it in the input stream with its value. For example,
> if there is an alias called
> .Dq lf
> I think the description of the alias built-in command that follows
> further down in the manual page is sufficient.
Indeed, but it does not provide examples about how using the alias
built-in command. Instead of that, it refers to the alias(1)
man page which is a link to csh(1)... sh's aliases do not work
in the same way as csh ones. :-)
> (the sh(1) manual page really needs a good going over by someone who is
> a very experienced technical documentation editor, and then by someone
> very familiar with *BSD manual page markup -- there are many other
I agree with you, but sh(1) is not so bad. ;-)
About the system manual markup, I believe that most pages need
a revision. I like the general layout of BSD systems man pages,
an example is sh(1):
SH(1) NetBSD Reference Manual SH(1)
sh - command interpreter (shell)
sh [-/+aCefnuvxIimqsVEbc] [-o longname] [target ...]
Sh is the standard command interpreter for the system. The current ver-
sion of sh is in the process of being changed to conform with the POSIX
1003.2 and 1003.2a specifications for the shell. This version has many
features which make it appear similar in some respects to the Korn shell,
but it is not a Korn shell clone (see ksh(1)). Only features designated
by POSIX, plus a few Berkeley extensions, are being incorporated into
this shell. We expect POSIX conformance by the time 4.4 BSD is released.
This man page is not intended to be a tutorial or a complete specifica-
tion of the shell.
But others have an ugly layout (perhaps because those pages were
written for GNU/Linux systems). I like left aligned man pages,
at least when displayed in non-proportional fonts character devices.
Man pages in the base system should have the same layout as the previous man
page, and not the next one:
GCC(1) GNU Tools GCC(1)
gcc, g++ - GNU project C and C++ Compiler (gcc-2.95)
gcc [ option | filename ]...
g++ [ option | filename ]...
The information in this man page is an extract from the
full documentation of the GNU C compiler, and is limited
to the meaning of the options.
This man page is not kept up to date except when volun-
teers want to maintain it. If you find a discrepancy
between the man page and the software, please check the
Info file, which is the authoritative documentation.
(well... at least this page is readable, others are not.) For
example, xterm(1) replaces the hyphens (-) with spaces (as other
XFree86 related man pages):
XTERM(1) XFree86 XTERM(1)
xterm - terminal emulator for X
xterm [-toolkitoption ...] [-option ...]
The xterm program is a terminal emulator for the X Window
System. It provides DEC VT102/VT220 (VTxxx) and Tektronix
4014 compatible terminals for programs that can't use the
window system directly. If the underlying operating sys
tem supports terminal resizing capabilities (for example,
the SIGWINCH signal in systems derived from 4.3bsd), xterm
will use the facilities to notify programs running in the
window whenever it is resized.
I believe that sh(1) follows the conventions in "The Unix
Programming Environment" from Brian W. Kernighan and
Rob Pike. That is all I want for the layout of a man page...
ok, and being left-aligned too.
Igor Sobrado, UK34436 - firstname.lastname@example.org