Here's a couple of other things from my wish list. The Unix manuals
need to be *completely* rewritten by somebody who knows how to write
technical documentation. Unix documentation rivals Interlisp documentation
(guess what two systems I've been using a lot lately?) in its generally
poor quality and disorganization. The indices are next to useless.
As an example, here were two questions I had recently. First, I wanted
to know how to find out what the Unix system thought was terminal type and
its parameters were (the TOPS-20 INFORMATION TERMINAL command). I knew that
the magic "setenv TERM terminal_type" would set it, but I couldn't find a
corresponding getenv command or any help under keywords "setenv", "term",
"stty", etc. etc. I still don't know how to do this. Second, I wanted to
know how to set the width and height of my terminal. My terminal type may
be "VT100", but it's a terminal emulator on a Lisp machine and the window
I draw is 62x116. Another reason for setting the width is that we use the
same terminals on TOPS-20 and Unix. On TOPS-20, software will output an
automatic newline at the end of the line so you do *not* want to set auto
newlines in the terminal hardware. I wanted to get software newlines on
Unix as well. My local guru said "it can't be done"...(another wish list
prints the entire current environment (UNIX System V; use
"printenv" in Cshells).
Terminal descriptions are contained in /etc/termcap or the
terminfo equivalent (SVR2 only). This database is indexed
by the value of TERM; if you claim to be using a "vt100",
then the description for a DEC VT-100 is used. By gum, a
DEC VT-100 does NOT have 62x116 character positions. To
get the 62x116 terminal described, have an entry with a
new name added to /etc/termcap, e.g.
xx|crispin|Crispin's magic terminal:\
Another approach, if your system supports it, is to set
the window size information into the kernel data structure
associated with the terminal, via TIOCSWINSZ or equivalent.
This overrides the screen size info from /etc/termcap and
is (0,0) until specifically set. Windowing systems should
update this information for each pseudo-terminal automatically.
Your system administrator really should know all this and
be able to set up your login state appropriately.
On the other hand, I'm sure that if I attempted to use TOPS-20
with UNIX experience as a guide and didn't read the explanatory
material first, I would get just as annoyed with it as you seem
to be with UNIX. (In fact, in my few brief encounters with
TOPS-20, it was pretty puzzling. If I had to use it for serious
work, though, you can bet I'd read the documentation first.)
There's room for both TOPS-20 and UNIX, but I wouldn't
advertise either as having an ideal general-user interface.
Remember that a major feature of the UNIX documentation has always
been that it is designed to be kept entirely on-line, this requires
some compromises in organization (which I personally think aren't
too bad.) I have seen a few vendors try to 'fix' the documentation
in various ways and every one of them first forsook (?!) on-line
documentation which I promptly called them and screamed my little
head off about.
Something I did not understand from your note is: do you want more
indexing in the on-line set or the printed set? Which were you having
trouble with? (not that I have anything to do with this, just asking.)
People have INFO-ized the UNIX manual (I did it once, quite a chore but
it worked), would this help or maybe what you really need is a good
KWIC index? At any rate, I don't see anything particularly wonderful
in the TOPS-20 documentation that solves any of this, for example,
except perhaps the operations manual which is quite well done.
My question is basically do you need better on-line programs to
search the docs (write one! that's all we ever do and submit it
to the world for acceptance), or actually different dead-tree style.
Speaking of TOPS-20, I think you are unfair to accuse UNIX of
honesty. I think UNIX has stolen shamelessly over and over again
and is proud of it, I pluck your beard sirrah!
What is your reaction to the TIOCSTI call (emphasis on STI)? How
about the tcsh with command completion? The inheritance of groups
through directories? The standardization of TCP (I know, low blow,
but let's face it, that was w/in the domain of TOPS-20, I seem
to specifically remember a memo going around back in the early
80's or maybe late 70's that specifically was debating whether to
move from TOPS-20 to UCB/VAX/UNIX for standard DARPA implementation,
the memo I believe originated from somewhere in DARPA.) My point
is only that their historical growth has been close and there has
been no particular lack of cross-semination, albeit with keeping
to their own particular styles.
(hmm, how about the ability to suspend shells and the apology
you get if you try to suspend [read: detach] your login shell?)
-Barry Shein, Boston University
The online documentation needs a good KWIC index, and the
hardcopy documentation needs a real index, e.g.:
hung terminals, fixing 844
reading parameters 111, 143(fn), 432
setting parameters 113-116, 124, 322
using terminals as a device 53-55
Basically, *every time* some technique is described, it
should get an index marker. I have no idea if troff or nroff or
whatever is in vogue can do this; if not dump it and use a real
document formatter such as Scribe.
Look in any well-organized reference manual index or even
better, look at any history book with indices and footnotes.
Such things can be done; it just takes a person with more than a
6th grade education in writing skills and the English language.
Yes, many hackers are functionally illiterate, but I know that
isn't the universal case.
There really isn't much of a comparision between the
TOPS-20 documentation and Unix. There's too much TOPS-20
documentation (it needs 5 strong men to carry all of it), and
very little of it is available online. Most TOPS-20 programs are
intrinsically self-documenting, which helps. And, equally
important, most TOPS-20 manuals have a REAL index! Since the
Unix documentation is so small, it should be possible to index
the entire documentation set.
-- Mark --
Uh, sorry, Mark, but which of env/printenv/echo works depends on what
command line interpreter you're using, as well as what Unix you're
using. Just ask how to find the terminal type on a v6 system :-).
The ability to use your favorite CLI is a win. You have to expect that
things that change/print/otherwise-diddle the internal data structures
of the CLI will change as you change CLIs. For the most part, they
stay constant across different flavors of Unix if you stay with the
same CLI. Now, what you shouldn't ask is how the terminal type
information got imbedded into the CLI on Unix.
"Unix is rapidly replacing obsolete 10 to 15 year old OS's."