[ On Monday, October 27, 2003 at 13:34:02 (+0100), Igor Sobrado wrote: ]
> Subject: Re: misc/23278: fixes for sh(1) - wrong sections and man pages referred
>
> Wow... it looks to me that you do not like csh(1) a lot. 

Indeed.  I do not like it 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.  ;-)

Well, actually the history of csh is a little more complicated than that.

IIUC, and IIRC, csh was an off-shoot of a much earlier shell, the Sixth
Edition Unix "sh".  It is a 898-line little command interpreter written
in rather plain C, and csh is indeed a remakable improvement on it.

Bourne independently wrote a new shell for the Seventh Edition, and it's
the root of all things "sh" in modern systems, though of course the
implementation we use in NetBSD is not based on any more than the syntax
implemented by Bourne's interpreter.

Besides, "sh" is a POSIX thing; and "csh" is a nothing.  :-)

Also, I'm not really a fan of any BSD technology per se (I am a great
fan of BSD politics), though I do very much acknowledge some of the
important contributions the CSRG folks made to unix, such as sockets for
network programming, filesystem enhancements, virtual memory, etc.

> Indeed, but it does not provide examples about how using the alias
> built-in command.

A miriade of examples are not usually needed or wanted in a reference
manual page -- they often just get in the way of the important details
that a reference should make clear.

Examples, and guides to how to use commands, belong in a "User's Guide",
though unfortunately there is not yet any equivalent in NetBSD
documentation to the old "An Introduction to the UNIX Shell" paper by
Bourne that was included in the original V7 manual volume 2.

> But others have an ugly layout (perhaps because those pages were
> written for GNU/Linux systems).

Well there are still two separate Troff macro packages in use for NetBSD
manual pages -- one compatible with UNIX(tm) man macros, and the other
is based on the new (and much better) BSD mdoc macros.

(True GNU documentation is always in "texinfo" format :-)

> (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):

The hyphens appearing as spaces problem is caused by a bug in the way
the X11 manual pages are generated.

The xterm.0 file, which is what you're actually viewing when you type
"man xter" is generated by the following filters:

	neqn -Tlatin1 | tbl | nroff -Tlatin1 -man | col

Nroff, with '-Tlatin1' is using a special ISO-8859-1 character as the
hyphen (oxAD), and that character is not available on all terminals
(though thankfully it is available on "xterm" itself by default :-).

However 'col', being a good old-fashioned unix command is stripping the
high-bit characters, including the ISO-8859-1 hyphen (0xAD) out.

Since most people use "less" as their pager now, and since NetBSD's
"more" is a variant of "less" (i.e. it's not the old-fashioned and
original BSD "more"), we should probably simply not use "col" in the
pipeline used to generate manual pages (or at minimum use "col -p").
(Personally I've just set ColCmd to "cat" :-)

However it is still a bit tricky to get "less" to work properly in the
default environment (i.e. to pass through high-bit characters without
using '-r').  Setting LESSCHARSET=iso8859 in your environment works for
the X11 manual pages generated without "col", but may not be appropriate
for everyone's environment.

What was done in previous releases in the old /usr/xsrc/xc, was to use
"-Tascii" instead of "-Tlatin1", and then normal ASCII '-' characters
were used as hyphens and all was well.  Perhaps we should just revert to
using ASCII for the default English manual pages since that's the lowest
common denominator between all the ISO-8859-* character sets and forcing
non-Latin-1 users to explicitly use Latin-1 when viewing manual pages is
perhaps a bit much to expect.

-- 
						Greg A. Woods

+1 416 218-0098                  VE3TCP            RoboHack <woods@robohack.ca>
Planix, Inc. <woods@planix.com>          Secrets of the Weird <woods@weird.com>