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
this bug!

Hi, Greg.

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
systems.  ;-)

> @@ -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
> problems)

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)

NAME
     sh - command interpreter (shell)

SYNOPSIS
     sh [-/+aCefnuvxIimqsVEbc] [-o longname] [target ...]

DESCRIPTION
     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)

NAME
       gcc, g++ - GNU project C and C++ Compiler (gcc-2.95)

SYNOPSIS
       gcc [ option | filename ]...
       g++ [ option | filename ]...

WARNING
       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)

NAME
       xterm - terminal emulator for X

SYNOPSIS
       xterm [-toolkitoption ...] [-option ...]

DESCRIPTION
       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.

Cheers,
Igor.

-- 
Igor Sobrado, UK34436 - sobrado@acm.org