Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.1 6/24/83; site udenva.UUCP
Path: utzoo!linus!decvax!ittvax!dcdwest!sdcsvax!sdcrdcf!hplabs!hao!
denelcor!udenva!jkcohen
From: jkco...@udenva.UUCP
Newsgroups: net.general
Subject: Pointer to Critiques of 4.2 documentation
Message-ID: <254@udenva.UUCP>
Date: Tue, 21-Aug-84 20:03:28 EDT
Article-I.D.: udenva.254
Posted: Tue Aug 21 20:03:28 1984
Date-Received: Thu, 30-Aug-84 09:47:18 EDT
Organization: U of Denver
Lines: 7

I have placed "crit1" and "crit2" in net.sources.  The first is
a critique of the 4.2BSD Programmer's Manual, Vol. I, the latter a
critique of the first 2 sections of Vol. IIc.  The first file is
an update of a previous version.
-- 
Jack Cohen
{nbires|denelcor|hao}!udenva!jkcohen

Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.1 6/24/83; site udenva.UUCP
Path: utzoo!linus!decvax!ittvax!dcdwest!sdcsvax!sdcrdcf!hplabs!hao!
denelcor!udenva!jkcohen
From: jkco...@udenva.UUCP
Newsgroups: net.sources
Subject: Critique of 4.2BSD Doc, Vol I
Message-ID: <253@udenva.UUCP>
Date: Tue, 21-Aug-84 19:28:10 EDT
Article-I.D.: udenva.253
Posted: Tue Aug 21 19:28:10 1984
Date-Received: Thu, 30-Aug-84 09:46:44 EDT
Organization: U of Denver
Lines: 1719





















                                 CRITIQUE

                                  of the

                BERKELEY 4.2 UNIX DOCUMENTATION - Volume I



                                    by



                              Jack K. Cohen






                             August 21, 1984



                     Copyright 1984 by Jack K. Cohen


       Permission to copy all or part of this material  is  granted
       provided  that  the  copies  are not made or distributed for
       direct commercial advantage, the author's  copyright  notice
       and the title of the article and its date appear, and notice
       is given that copying is by permission of  the  author.   To
       copy  otherwise,  or  to  republish,  requires  a fee and/or
       specific permission.

















       4.2BSD                                                   -1-


       Introduction

            This Critique emphasizes documentation problems  rather
       than  4.2BSD  software problems.  However, suggestions about
       possible improvements to the latter are jabbed in  here  and
       there.  Critiques of various parts of Volume IIc will appear
       separately.

            My purpose is not to denigrate the work of  the  people
       at  Berkeley  or  at  Bell (though I am not above teasing at
       times).  In fact, I hope the text shows my great  admiration
       for  the  marvelous  applications  engine  provided by them.
       Suffice it to say that I have used other  operating  systems
       and read other documention!

            Since I can report on only what I experience, be  aware
       that  the  effects  recorded  herein are descriptions of the
       local University of Denver  implementation  of  BSD4.2.   In
       cases  where  I  know  our  implementation to be specialized
       (e.g. effects caused by the local  choices  for  Mailrc),  I
       will make that clear.  I can only hope that my local readers
       have  caught  any   remaining   instances   of   erroneously
       attributing    'mis-documentation'    instead    of   'local
       variation.'

            For maximum enjoyment, I recommend having a  hard  copy
       manual  near  at  hand  while reading these notes.  You will
       notice that there is lots of good stuff there in addition to
       the nits picked by this Critique.

            Being  of  impulsive  cast,  no  doubt  I  have   amply
       displayed my ignorance below.  I have never been troubled by
       being wrong; life is too short  to  stand  on  ceremony.   I
       await your blunt refutations and explanations.

            For several years, my first source of technical  UNIX/C
       information  has been Andrew Burt, a graduate student at the
       University of Denver.  He has been kind enough  to  continue
       tracking  down  puzzling  items  which cropped up during the
       writing of these notes.  I have also gotten  valuable  ideas
       from  several  other  students: Craig Ruff, Brian Sumner and
       Matt Taylor.  Also among the contributors to and critics  of
       these  notes  are  various  present  and past members of the
       University of Denver Computing Services including the 'Three
       Bobs'   (Shafer,   Stocker   and   Ware),  Carol  Ward,  and
       especially, my first UNIX teacher, Howard  Lasus.   However,
       none  of  my  consultants are to be blamed for the remaining
       errors in these notes; they rest (light-heartedly) with me.

            I am now also in debt to those readers of the 'net' who
       have  provided  corrections  to  an  earlier edition of this
       Critique.   In  many  cases,  I  have   acknowledged   their
       contributions  below.   In  some  cases, their comments have


                                                        J. K. Cohen







       4.2BSD                                                   -2-


       caused me to delete entries altogether, thus  also  removing
       the opportunity to thank them in the text!





















































                                                        J. K. Cohen







       4.2BSD                                                   -3-


       Programmer's Manual: Section 1

       adb  On  page  1  the  last  word  -  ADDRESSES  -  in   the
            DESCRIPTION should be enlarged to: "For further details
            of address mapping see ADDRESSES." (The reference is to
            a later section on page 5 of "man adb").

            On page 4, the parenthetical in the description of $c -
            (broken on the VAX) - is either opaque or incomplete.

            What has  happened  to  the  adb  tutorial?   The  only
            remaining hint of its existence is in /usr/doc/run.

       basename
            Calling the shell example, 'base' and evoking  it  with
            the   suggested  argument,  'base  /usr/src/bin/cat.c',
            produced:

                0: No source file /usr/src/bin/cat.c
                mv: cannot access a.out

            Since /usr/src is a 'Permission  denied'  directory,  I
            could  not  investigate  further.  Since source code is
            unlikely to be available to the vast majority  of  UNIX
            users, a different example argument should be given.

       cal  See  Kernighan  and  Pike's   "The   UNIX   Programming
            Environment" for a shell providing a friendly interface
            to this utility.

       calendar
            Calendar service is erratic locally.  If  you  want  to
            get  daily  reminders, you might start an infinite loop
            of your own.  Prepare a file, 'earlyam':

       #! /bin/sh
       # From K & P
       # To start this infinite loop: earlyam
       # To stop this process: edit the /usr/spool/at file, to cause an abort

       file=/usr/tmp/cal.$$
       /usr/bin/calendar >$file
       if /bin/test -s $file
       then
               /usr/ucb/mail jkcohen <$file
       fi
       /bin/rm $file
       /bin/echo earlyam | at 5am


            and issue the command:




                                                        J. K. Cohen







       4.2BSD                                                   -4-


           % earlyam


            to launch your service.  The first time it comes  right
            back, but thereafter, the service sends you mail once a
            day at 5 am.  Remember, you have to prepare a 'calendar
            file' as described on the manual page.

       cat  The command line "cat a b >a" mentioned in the BUG  now
            evokes  the error message: "cat: input is output." But,
            of course, the shell gets there first  and  file  a  is
            still wiped out.  Similarly for "cat a b >b".  Even the
            dreaded "cat * >>x" now does no harm to the system.

            Cat with  no  arguments  does  not  echo  back  to  the
            terminal  at  each  newline.  The manual says that when
            the standard output is a terminal, the output  is  line
            buffered.   I  take  that to mean that each line input,
            should be echoed after the  NEWLINE.   Since  'cat  -u'
            does  echo  back to the terminal, the problem is likely
            that some undocumented buffering is going on.

            Perhaps usages such as 'cat -vt  file  ...'  should  be
            acceptable  as per Kernighan and Ritchie, page 112-113.
            In fact, this flexible  acceptance  of  flag  arguments
            should   be   uniformly  extended  to  all  appropriate
            commands.

       cb   It seems inconsistent with the vast  majority  of  UNIX
            software that this command does not accept command line
            arguments.

       cc   I don't understand why some of the options accepted  on
            the  command line by 'cc' are not discussed on the 'cc'
            manual page, but instead are deferred to the 'ld' page.
            In particular the -s option should be mentioned.  There
            may well be some distinction apparent  to  the  expert,
            but  I  vote for all the items which may be on the 'cc'
            command line being discussed on the 'cc' manual page.

       chfn Should be made more universally applicable.

       compact
            Compact  violates  the  UNIX  rule  about   not   being
            "chatty." This seems like a case of the author being so
            proud of the algorithm's  effectiveness  that  he  must
            brag   each   and   every  time  about  the  degree  of
            compaction.  Seems harmless?   Well, suppose the system
            is overloaded, so just before logout you go:

                nohup compact file1 file2 file2 &

            and log out.  Next login, you find the files:


                                                        J. K. Cohen







       4.2BSD                                                   -5-


                file1 file1.C file2 file3

            In addition to the "strange" failure of file2 and file3
            to  get  compacted,  the file1.C which looks like it is
            the compaction of file1, really will not be  recognized
            by  'uncompact' as a compacted file!  Thus if the naive
            user  deletes  file1  before  checking,  he's  in  real
            trouble.

            Even online the messages can be a nuisance.  If you go:

                compact file1 file2 &

            when file1 finishes compacting, the action stops  until
            you  bring  it  into foreground to deliver its message.
            Then the second compaction launches off in  foreground,
            so  you  have  to stop it and stick it in background so
            you can continue with your real foreground job.  If you
            still remember what that was.

            The  "RESTRICTION"  of  keeping  files  less  than   13
            characters,  so  as  to have room for the .C is quaint.
            In BSD4.2, less than 254 characters would be more  like
            it.    Thus,   I  think  we  could  safely  delete  the
            RESTRICTION section.

            Uncompact and ccat should be forgiving when you fail to
            type the final .C.

            In the previous release, I said:

                Also, "compact" is a lot to type, why not some-
                thing like "pack"?

            But Lew Mullen points out that  changing  the  name  of
            established  commands  is  a  poor  idea.   Well, it is
            impossible to argue with  that,  so  I'll  retrench  to
            suggesting  a link to a shorter name (as 'f' serves for
            'finger' in 4.2BSD).  (Lew also suggests that  I  learn
            to  type  faster.   This  shows  an all too penetrating
            insight into my plight, my backspace key is  worn  down
            to half the height of the other keys.)

       csh

            The header line:

                #! /bin/csh

            unambiguously specifies that a shell program is  to  be
            executed  in  C  shell.  It also serves as an important
            comment to the same effect.  See execve(2).



                                                        J. K. Cohen







       4.2BSD                                                   -6-


            On page 14, "then" is omitted from the list  of  built-
            ins.

            On page 17, "term" and "user" are omitted from the list
            of pre-defined and environmental variables.

            The discussion of the "prompt" variable seems wrong  to
            me.   If  you  want  just the event number as a prompt,
            then as per the discussion:

                set prompt=!

            does the job.  But

                set prompt=\!

            also gives the same prompt, whereas the manual  implies
            that  you  will  not get the event number in this case.
            Similarly, the command

                set prompt='\!: '

            gives a  prompt  consisting  of  event  number,  colon,
            space.  Moreover, in the immortal phrasing from Bell:

                set prompt='!: '

            'does not have the effect intended.' One  subtle  point
            in  all  this is that if ! is followed by a blank, tab,
            newline, equal sign or left parenthesis then  it  loses
            its history connotation.  So, for example,

                set prompt='! '

            works just fine.

            In  the  BUGS  subsection,  the   alias   facility   is
            deprecated  vs.  the  use  of Shell files.  The user is
            left uncertain whether something like 'alias del rm -i'
            is  a  good  or  bad way to proceed.  It's time someone
            wrote an  essay  on  what  aliases  and  such  cost  in
            response time (and yours truly just might throw caution
            to the winds and attempt it).  For now,  a  small  tip:
            things  you  use only in your login shell, should go in
            .login instead of .cshrc.  Even if (like aliases)  they
            "logically" seem associated with C shell.

            Request: provide some  way  of  turning  off  history's
            echoing  of  the interpreted command.  My personal need
            for this concerns sending my  serial  printer  a  local
            escape  sequence to toggle it on.  I send that sequence
            after the command line, but before hitting the carriage
            return.   If I forget and use a history abbreviation in


                                                        J. K. Cohen







       4.2BSD                                                   -7-


            the command, then the first line of my hard copy  shows
            the  interpreted  command.   I am sure others will have
            other reasons why they'd like to suppress the echoing.

            Request: Provide some version of 'set' which shows  the
            value  of  the  variable.   Maybe 'set var?' would be a
            good choice.  Of course, 'echo $var'  works,  but  this
            seems unnatural in this context.

            Request: Extend 'repeat'  to  compound  commands.   The
            shell   program   shown   in   the   critique   of  the
            "Introduction to the  C  Shell"  below  gives  such  an
            extension.

       checknr
            This command should be extended to cover -mm too.   And
            also to include the 'checkeq' command's duties.

       chsh Neither /bin/oldcsh nor /usr/new/csh exist, so I  doubt
            that they can be useful as possible second arguments to
            'chsh.'

       crypt
            No command line arguments.

       deroff
            The macro package -me throws deroff into a tizzy.  It's
            fun   to   watch  deroff  on  a  file  headed  by  '.so
            /usr/lib/tmac/tmac.e'.  For example, on the file:

            .so /usr/lib/tmac/tmac.e

            deroff gives:


           You are using the wrong version of NROFF/TROFF!!
           This macro package works only on the version seven
           release of NROFF and TROFF.




            which is not likely to provide the user  with  a  clear
            idea of what's going on.  More fun is the input file:

            .so /usr/lib/tmac/tmac.e
            speling erroers
            It is fun to run 'deroff' and 'spell'
            on this file.
            The effects are discussed in my
            documentation critique.

            which yields:


                                                        J. K. Cohen







       4.2BSD                                                   -8-







               Produced for your edification and enjoyment by:
                       Eric Allman
                       Electronics Research Laboratory
                        Berkeley.

               VERSION         First Release:  Sept
               See file   for revision history

               Documentation  available.




        This version has had comments stripped;  unstripped version  available.
           You are using the wrong version  NROFF/TROFF!!
           This macro package works only  the version seven
           release  NROFF and TROFF.




            which is not more illuminating, but gives, in  addition
            to   the  above  text,  a  nifty  cursor  display  (not
            reproduced here).

            The inability of deroff to cope with such  files  means
            that utilities such as 'spell' and 'diction' which rely
            on deroff, cannot be used on this type of file  (unless
            it   is  nroffed  first  or  unless  the  .so  line  is
            temporarily removed).  At the least, this defect should
            be noted as a deroff BUG.

       diction
            It is time that the BUG was removed.  That is,  diction
            should  'grok'  -me  (or  a  phasing  out of -me should
            begin).  It is not nice to  suck  users  into  a  macro
            package  for  which  tools  like  'spell' and 'diction'
            can't be used.

       ed   There are an incredible number of documentation  errors
            (see  the  note  below for an explanation).  The manual
            describes an 'ex' like editor, but all we seem to  have
            is a barebones Bell 'ed' from the year one.  A sampling
            of the discrepencies follow.

            The manual says that '%' abbreviates '1,$', but

                %p


                                                        J. K. Cohen







       4.2BSD                                                   -9-


            produces  an  error  message.   Likewise,  despite  the
            manual  page, trailing delimiters are needed on the 's'
            command.  Especially serious is the  false  claim  that
            there  is  an  'u' undo command.  The described command
            'wq' is absent.

            The manual description of q is incomplete:  'ed'  flags
            as  an  error  a  'q'  if  a 'w' has not been done on a
            changed file.  Alas, the  error  message  is  just  the
            usual  '?', which is likely to be too subtle to prevent
            the user from issuing an immediate repeat of 'q' which,
            as  per  standard  Bell, is accepted.  Good old 'silent
            ed.'

            There's not much point  in  going  on.   In  case,  the
            documentation  is  later changed, I should note that my
            manual page  is labeled '3rd Berkeley  Distribution  14
            September  1979.' Interestingly enough, the manual page
            I had from the 4.1BSD distribution had  the  same  date
            (3rd  Berkeley  Distribution  9/14/79).   However,  the
            pages  are  not  identical!   The  earlier   page   had
            documented  a  -p  option which provided a * prompt for
            'ed' at the command level.  Of course, that didn't work
            either  and  the  current distribution has 'fixed' that
            bug by removing the option from the documentation.

            In general, the only safe course is to  expect  nothing
            more than what is described in the Kernighan tutorials.

            It would be nice if 'ed' were jazzed up a bit along the
            lines  described  in  the  documentation.   Even though
            'vi/ex' largely supercede 'ed', there are  times  on  a
            busy  system when one does not want to wait for 'vi' to
            start up.

       Note on ed manual page
            Mark Horton has been kind enough  to  explain  how  the
            wrong  manual  page got released.  It seems that before
            the 3rd distribution, he spent some time  at  Bell  and
            wrote the jazzed up 'ed' (including the prompt option).
            Expecting Bell to permit this code to  be  distributed,
            the   manual   page  was  written  for  the  new  'ed.'
            Unfortunately,  just  before  distribution  time,  Bell
            decided  against allowing the upgrade.  The documentors
            have never caught up with this sad fact of life.

       error
            This  is  a  marvelous  command  for   the   reasonably
            sophisticated  user.   A word of advice about using the
            -v option: be sure to redirect  standard  output  to  a
            file,  because  if  vi starts up fast, the errors which
            are written to standard output will vanish too  quickly
            to  read  before the screen clears.  Note that even the


                                                        J. K. Cohen







       4.2BSD                                                  -10-


            'floodgate' effect noted under BUGS  is  not  all  that
            serious  a drawback: the inserts made by 'error' are so
            distinctive that they can be  eradicated  by  a  single
            global editor command.

       ex   Appending to a line and inserting at the beginning of a
            line  are  such  common  operations  that vi's 'A', 'I'
            should be added to the 'ex' command set (one  does  get
            trapped on a teletype terminal once in awhile).

            The BUG entry concerning the inability to scan ignoring
            case should be deleted, since the ex option 'ic' solves
            that problem.

       explain
            This page is a repeat of the 'diction' page.  But I  am
            not  complaining.   It's  really frustrating to look up
            'checkeq' and not find it, etc.

       expr The last example is a little tough on the eyes.  But  I
            tried  it  and got the error messages 'Variable syntax'
            (csh)  and  'syntax  error'  (sh).   Maybe  I   screwed
            something up.  My 'csh' attempt was:

            set x=/a/b/c
            expr $x: '.*/\(.*\)' '|' $x

            while my 'sh' attempt was:

            x=/a/b/c
            expr $x: '.*/\(.*\)' '|' $x

            Someday someone should write  a  supplement  explaining
            these  convoluted  examples concocted by the 'Boys from
            Bell.'

       eyacc
            The  word  'old'  in  the  first  sentence   seems   to
            contradict the same word in the last sentence.  If this
            version is an  improvement  over  yacc,  it  should  be
            called   'yacc'.   Otherwise,  clearer  guidelines  are
            needed as to when to use which.

       f77  The subheading -o is missing.

       find The bug cited is an understatement.  It took me a month
            to  figure  out  how  to find and print the files in my
            subdirectories which matched a regular expression.   To
            alleviate  the  pain,  why not give half a dozen simple
            examples?

       finger
            The initial letter, 'f', is a valid abbreviation.


                                                        J. K. Cohen







       4.2BSD                                                  -11-


       gprof
            Doesn't work locally  because  this  program  needs  to
            access /dev/kmem which has been made private to protect
            the  password  buffer!   We  now  know  that  a  better
            solution  is  to change /dev/mem, /dev/kmem, /dev/kUmem
            and dev/drum to mode 0640,  owned  by  'root',  with  a
            special  group  such  as  'bin'.  Then change the group
            owner of the programs  (gprof,  iostat,  sysline,  ...)
            that access these special devices to the special group.
            Finally, make those programs  setgid  (mode  2755),  so
            they  will  read  from the kernel.  (Thank you to Chris
            Torek and Jon Biggar for describing this  'fix'.   Also
            thanks  to  Mike  Kupfer  for pointing out that 'gprof'
            needs to access kmem.)

       grep The  command  'grep  \\   filename'   does   not   fail
            gracefully.    At   least  that's  what  the  Bell  Lab
            documenters would say.  In the interest of the  system,
            I'll be explicit about what it does:

                RE botch
                RE botch
                RE botch
                RE botch
                RE botch
                RE botch
                RE botch
                RE botch
                RE botch
                RE botch
                RE botch
                RE botch
                RE botch
                ^C

            However, egrep handles this error in fine style and, of
            course, it is not an error for fgrep.

            Is there a way to get  fgrep  to  search  for  multiple
            strings without using the -f file option?

       indent
            What is the relation of this program to 'cb'?

       iostat
            Fails locally because of the  /dev/kmem  problem  here,
            see above discussion of 'gprof'.

       learn
            Attention: 'learn vi' is available  locally.   If  it's
            any good this should be one of the most valuable things
            on the system.



                                                        J. K. Cohen







       4.2BSD                                                  -12-


       ln   Compacting or uncompacting breaks links (quasi-bug).

       lock Not available locally.

       look My first reaction was: "Do we need  this,  if  we  have
            'grep'?"  On  second glance, I noticed that the default
            file was the spelling dictionary!  This command  allows
            one  to  get correct spellings by searching through the
            dictionary's list of words which begin with the desired
            initial  string.   Why not spend a moment on this short
            manual page, to explain this use of 'look'?  Note  that
            homespun shells like:

            #! /bin/sh
            # lookup - check spelling dictionary for pattern
            # Usage: lookup 'pattern'

            /usr/bin/egrep $1 /usr/dict/words

            while more  general,  do  not  take  advantage  of  the
            sorted, one word to a line, structure of the dictionary
            (after "lookup '^aa'", there is a long pause while  the
            entire  dictionary  is  searched,  "look aa" terminates
            promptly when the "aa's" end).

       ls   The option -A is not explained.  It means the  same  as
            -a,  but omits the always present . and .. directories.
            (Thank you to Percy Irani for this one.)

            The  discussion  of  permissions  for  directories   is
            inadequate.   Instead  of  the  vague  word 'search' in
            connection with the x permission for  directories,  why
            not say:

                r gives permission to 'ls' the directory;
                w gives permission to create files in the directory;
                x gives permission to 'cd' to the directory and to use
                  (e.g., 'cat' or execute) files whose names we know in
                  the directory.


            Comment: Despite the claims  of  an  over-abundance  of
            options,  this version is inflexible.  For example, one
            cannot view the protections without seeing all the info
            in -l.  This has annoyed me enough to write a shell:

       #! /bin/sh
       # lsp - list files with protections
       # Usage: lsp

       /bin/ls -l | /bin/sed 's/  *.* / /' | exec /u/nosupport/p




                                                        J. K. Cohen







       4.2BSD                                                  -13-


       mail The local /usr/lib/Mail.rc is (5/6/84):

                set append dot save

            these three options mean:

       (1)  new mail is appended (the default is first in last out)

       (2)  a line consisting of just a '.' signals that  you  wish
            to launch your completed message (the default is ^D; if
            you like dot, you might also like 'ignoreeof').

       (3)  letters killed by two breaks are saved in ~/dead.letter



            The ~b escape is not documented (it  gives  a  'bcc'  -
            'blind carbon copy').

            The option 'quiet' has the undocumented effect of  also
            suppressing the current message number (unfortunately).

            On the last line of page 5, 'the' is misspelled.

            A possible BUG entry: ex/vi  cannot  be  aimed  at  the
            headers of a message you are typing.  Given the content
            of the first BUG entry, the option,  'debug'  with  its
            confusing reference could be deleted.

            Mail's help file still talks about  /usr/mail  (instead
            of /usr/spool/mail) and .sendrc (instead of .mailrc).

            A helpful usage hint.  You can make mail customized  by
            putting mail commands in a login directory file, called
            .mailrc.  For an subject prompt and a cc prompt,  enter
            the lines:

                set ask
                set askcc


            To suppress all those machine-generated  mail  headers,
            put the following line in your .mailrc:

                ignore Received Date From Message-Id Status

            Since if you have 'vi',  you  have  'ex'  via  the  'Q'
            command,  you  might  consider  specifying 'ed' as your
            line editor within mail.  Recall that  'vi'  starts  up
            very  slowly  on  a  busy system and even the primitive
            'ed' supplied by 4.2BSD (see above under 'ed') is often
            adequate for mail messages.  To obtain 'ed' when you ~e
            and 'vi' when you ~v, place the following lines in your


                                                        J. K. Cohen







       4.2BSD                                                  -14-


            .mailrc file:

                set EDITOR=/bin/ed
                set VISUAL=/usr/ucb/vi


       man  The related commands 'apropos' and 'whatis'  should  be
            mentioned.

            Possible BUG.  Is there a way to get the new subsection
            introductions, such as intro(3S)?

       mkdir
            In the online  manual,  the  default  protection  level
            cited as 777 is actually (at least locally) 755.

            The command:

                mkdir

            evokes the error message:

                mkdir: arg count

            The user who does not program in C will not  find  this
            useful.    Either   a  "Usage:"  error  message  or  an
            interactive prompt for  the  directory  name  would  be
            preferable.

       more This command needs an option  to  suppress  its  prompt
            message.   Yes,  even  on a CRT.  Much local effort has
            been expended in writing shells and C programs to avoid
            having  this  prompt  mess  up hardcopy being output on
            slaved serial printers.

            The  underlining  done  by  "more"  is  often  erratic.
            Sometimes  it  extends  to  the end of the line when it
            should not.

            When using "more"  and  advancing  to  a  new  page  by
            hitting  the  space  bar,  the  visual attribute of the
            terminal you are using will change.   In  mail  if  you
            type ~v it will do the same thing.

       msgs Is currently off-limits locally (Permission denied).

       pr   It would be helpful to have options to set left  margin
            and  the  top  margin.   Also it would be useful to get
            paginated output without a heading.

       prof Sometimes 'mon.out' is not produced.  I have hard  copy
            examples  of  a  'cc  -p file.c' command, followed by a
            'prof' which yielded:


                                                        J. K. Cohen







       4.2BSD                                                  -15-


                mon.out: No such file or directory

            whereas some  time  later  the  same  command  sequence
            worked  fine.   In both cases, 'a.out' was produced and
            functioned normally.   This  certainly  smells  like  a
            local  or  a  personal problem, but I report it in case
            others have had the same experience.

            The 'SEE ALSO' should reference 'gprof.'

       ps   Needs an option to suppress the header line.

       ratfor
            Should reference 'RATFOR  A Preprocessor for a Rational
            Fortran' by Brian W. Kernighan (in /usr/doc).

       refer
            In the description  of  -a,  the  letter  following  -a
            should be 'n' instead of 'r.'

            In the description of -f I think the intent is  to  set
            the initial footnote number, but this is not clear from
            the text.

            Hooray!  This revision gives an example.  It is a  good
            example.  It's contents belong in 'SEE ALSO.'

            I suspect -me will drive "refer" as insane as "deroff",
            "style", etc.

       rev  Give some examples of when this command would  serve  a
            useful purpose.

       rmdir
            Again this is a duplicate of another manual  page  (rm)
            and again this is not a complaint.

       script
            If you  try  "script",  you  get  the  following  error
            message:

                 %script
                  out of pty's
                  terminated


       sed  Should reference the manual in /usr/doc.  Possibly  (in
            the future), also Kernighan and Pike for a tutorial.

       sh   The 'new' comment symbol, '#', is not mentioned.  I  am
            not  familiar  enough  with the history of Bourne shell
            development to be able to tell what  else  is  missing.
            If  you are, be warned that the documentation is not up


                                                        J. K. Cohen







       4.2BSD                                                  -16-


            to the minute.

            The header line:

                #! /bin/sh

            unambiguously specifies that a shell program is  to  be
            executed  in  Bourne  shell.   It  also  serves  as  an
            important comment to the same effect.  See execve(2).

            Should  reference  the  tutorial  in   /usr/doc.    And
            definitely  (in  the  future) Kernighan and Pike as the
            place to learn Bourne Shell programming.

       spell
            Here we are, back at Murray Hill, trying to get  laughs
            from  cute examples.  The little terminal sequence near
            the bottom of the page  creates  56  blocks  of  hashed
            dictionary in the user's directory.  Most systems can't
            tolerate every novice maintaining their  own  56  block
            dictionary.   Besides,  following the method shown, you
            wipe out out 'myhist' each time you  add  a  new  word.
            Thus  your 56 block dictionary would perpetually differ
            from the system's by only one word.  Finally, while the
            association  of 'hookey' with the filename, 'huckfinn',
            may be obvious when one is composedly  reading  through
            the  manual,  it  may  be  totally  opaque  when one is
            harried.  Below, I shall show a first cut  at  a  shell
            program  (following  an  example  in Bourne's 'The UNIX
            System') which employs an auxiliary  personal  spelling
            list   whose   entries   are   not  to  be  flagged  as
            misspellings.

            The discussion of -d, -s, -h, will have to  be  greatly
            expanded  before this reader will understand it.  For a
            moment, I thought that  -d  provided  an  easy  way  to
            maintain an exception list.  But

                spellin <myhist >myhist.hash

            seems to create an alternate hashed spelling  list  (56
            blocks,  of  course),  not  an auxiliary list.  What is
            needed is an option to specify a small  extra  list  of
            exceptions  (hashed or not) which are NOT to be flagged
            as spelling errors.  If we demand that the list be in a
            sorted,  one  word  per line file, then the following C
            shell program accomplishes this:

       #! /bin/sh
       # Usage: sp [-eexceptionlist] [-spelloptions] filename ...
       # spell command with exception list
       # NOTE:  The exception list is assumed to be sorted:
       #        sort -o exclist exclist


                                                        J. K. Cohen







       4.2BSD                                                  -17-


       # NOTE to other users:  Change the defaultlist below (yours might
       #                       contain the names of you and yours, etc.)
       # Caveat: Revise to ccat a compacted exception list if it's large.

       cmd=`/usr/bin/basename $0`
       typos=/usr/tmp/$$.dict

       case $# in
       0) echo Usage: $cmd [-eexclist] [-spelloptions] files 1>&2; exit 1
       esac

       defaultlist=/u/mathf/jkcohen/Wds/words  # CHANGE THIS!
       for i
       do
               case $i in
               -e*)    # User supplied exception list.
                       exceptions=`/bin/echo $i | /bin/sed 's/^-e//'`
               ;;
               -*)     # Collect user-supplied spell options
                       option="$option $i"
               ;;
               *)      # Collect filenames
                       files="$files $i"
               ;;
               esac
       done

       exceptions=${exceptions-$defaultlist}

       trap '/bin/rm $typos' 0 1 2 15
       /usr/bin/spell $option $files >$typos

       # spell sorts with -f option; but comm demands ASCII collating sequence!
       /usr/bin/sort -o $typos $typos
       /usr/bin/comm -23 $typos $exceptions
       exit 0


            The   inclusion   of   .so   lines   such    as    '.so
            /usr/lib/tmac/tmac.s'  in  your  text  utterly  defeats
            'spell.' Here is the story for our  two  most  commonly
            used nroff macro systems.  For 'tmac.e', you do not get
            the  spelling  errors.   For  'tmac.s',  you  get   the
            spelling errors, but also get 107 two letter nroff-type
            commands:










                                                        J. K. Cohen







       4.2BSD                                                  -18-


                AB
                AE
                AI
                AJ
                AU
                BD
                BG
                bp
                br
                BT
                .
                .
                .


            The 'SEE ALSO' for 'spell' should reference 'look.'

       struct
            When I go:

                struct prog.f

            or

                struct <prog.f

            I get:

                trap: Command not found

            I looked, and 'struct' is a shell file  from  Berkeley.
            My  favorite  guru  points  out that UCB added a header
            saying that UCB wrote it.  The header line is a comment
            line.   You  can tell because it begins with a #. Alas,
            there is an archaic convention that if the  first  line
            of  a shell file begins with a # line, then the file is
            handed over to the C shell interpreter.  The problem is
            that  the  shell  is  actually  a  Bourne  script!  The
            solution is either to delete the header line or use the
            modern  convention  of  first  line  beginning with '#!
            /bin/sh.'  (The system is smart enough to look past the
            initial  '#'  to see if '!' is the next character; thus
            both the archaic and  the  modern  convention  live  on
            together.)

       stty Section 39 in Volume  IIc,  'Bug  Fixes  and  changes',
            gives  different defaults for erase, kill and interrupt
            characters.

       style
            The BUG should be removed to the extent of dealing with
            -me.  Alternatively, -me should be withdrawn.



                                                        J. K. Cohen







       4.2BSD                                                  -19-


       sysline
            This command fails locally because it needs  /dev/kmem,
            see discussion of 'gprof' above.

       su   Section 39 in Volume  IIc,  'Bug  Fixes  and  changes',
            gives   a  new  option,  -f,  which  is  omitted  here.
            Similarly,  the  extra  arguments  extension   is   not
            discussed here.

       tabs The BUG should be explained  in  greater  detail:  Why?
            How?

       talk Talk doesn't work here.  According to a  local  expert:
            'undoubtedly something to do with /etc/hosts not having
            udenva listed in it.' ('udenva' is our system name.)

       tbl  There is an nroff mistake in the 'tbl' page!  It causes
            a  missing line in the description and is due to a . at
            the beginning of the line which was  not  protected  by
            the  \& escape.  The cute thing is that 'checknr' would
            have found this error, because the line begins with .TS
            and  had  no  .TE to match it.  Now you and I forget to
            run 'spell' and 'checknr', but not the pros.  Not much.
            Recently,  I  was  looking at a 'brand X' derivative of
            4.2BSD and the ms(7) manual page similarly left  out  a
            raft  of  \&'s  and  most  of the first manual page was
            omitted after nroffing.   Your  online  manual  may  be
            fixed, but in case not, here is the correct description
            (underlining omitted):

                Tbl is a preprocessor for formatting tables for
                nroff  or troff(1).  The input files are copied
                to  the  standard  output,  except  for   lines
                between  .TS  and  .TE command lines, which are
                assumed to describe tables and are reformatted.
                Details are given in the tbl(1) reference manu-
                al.


       tee  Here is this big empty space (on the manual  page).   I
            have an idea: let's use some of it to give examples.

       time You may think  that  /bin/time  is  anachronistic,  but
            think  about  how  you  would  get  the  effect  of the
            following shell using the  C  shell's  built-in  'time'
            command.









                                                        J. K. Cohen







       4.2BSD                                                  -20-


       #! /bin/sh
       # cpu - put timing data into the file "timedata" (and throw output away).
       # Usage: cpu command

       file=timedata
       /bin/echo -n $*: >>$file
       /bin/time $* 1>/dev/null 2>>$file


       tip  The next to the last word on the last  page  should  be
            'pared' not 'paired.'

            This is generally an excellent manual page about a very
            difficult  subject,  but a local user of 'tip' suggests
            inclusion of  additional  information  on  how  to  get
            auto-dialers to work with it.

       tr   On one occasion, I found  the  BUG  to  actually  be  a
            useful  feature.   Once,  after  transferring a file, I
            wound up with a file loaded with  NULs.   The  command,
            'tr  <file  >nicefile', was very useful (the version of
            'vi' I had then simply did not like  files  with  NULs;
            probably the current version doesn't either).

       tset The alias given on page 2 proved deadly when I inserted
            it  into  my .cshrc (unless you are a UNIX adept, don't
            play around with this - if you can't  resist,  remember
            to  make a backup copy of your '.cshrc', so you can get
            this file restored without use of 'vi').

            The   option   '-s'   (still   used   in   our    local
            /usr/skel/.login) is not documented.

            Locally, you get  reasonable  terminal  characteristics
            without  using  'tset.'  (As  an experiment, I moved my
            .login to another name and logged  in  on  a  CRT.   My
            backspace key worked fine.)

       ul   The sentence describing  the  -i  option  contains  the
            mystifying phrase: 'underlining onto ...'

       uucp Is  there  a  relation  between  'tip'  and  the   'uu'
            commands?

       users
            The initial letter, 'u', is a valid abbreviation.

       wall Should document effect of 'mesg' on this command.

       write
            The concept of 'write back' should be elucidated  (i.e.
            describe how you do that).



                                                        J. K. Cohen







       4.2BSD                                                  -21-


       yacc SEE ALSO should reference 'eyacc'.

       yes  The manual page should squeeze in an example or two.




















































                                                        J. K. Cohen







       4.2BSD                                                  -22-


       Programmer's Manual: Section 2

       intro
            Should tell us where to find the values  of  {PROC_MAX}
            etc.

            Again under 'File Access Permissions' we  have  only  a
            vague hint of what x permission for a directory implies
            (see above ls(1) discussion).  In the last paragraph on
            page  6,  the 'and' at the end of the first line should
            be 'but' as in the next paragraph.  However, both these
            paragraphs   could  be  simplified  by  removing  their
            opening clauses.

       creat
            Last word in NOTES is misspelled.

       execve
            Near the top of page 2, argv is described as an  array,
            but  envp as a pointer to an array.  Their descriptions
            should  be  identical,  since  their  declarations  are
            identical.

       fcntl
            Last item under F_DUPFD should  refer  to  execve,  not
            exec (or section 3, not section 2).

            There's an extra blank line before FAPPEND.

       gethostid
            RETURN VALUE and ERRORS sections are missing.

            The hostid is not set on Eos.

       gethostname
            The hostname on Eos is 'udenva.'

       getpriority
            The file <sys/time.h> must also  be  included,  without
            it, the include file, <sys/resource.h>, evokes:

                "/usr/include/sys/resource.h", line 21: unknown size
                "/usr/include/sys/resource.h", line 22: unknown size
                "/usr/include/sys/resource.h", line 39: unknown size
                "/usr/include/sys/resource.h", line 39: unknown size


            The defines shown are already in resource.h and  should
            not be given here.






                                                        J. K. Cohen







       4.2BSD                                                  -23-


       Programmer's Manual: Section 3

       A request for a missing utility from a local  C  whiz:  "Put
       itoa()  back  in.  Sprintf is a bit much for just converting
       one integer."

       bstring
            The BUGS are respectively non-existent and inexcusable.
            Bcmp   cannot  take  its  parameters  'backwards'  from
            strcmp, because bcmp is  symmetric  in  its  first  two
            arguments.   Unlike strcmp, bcmp does not return <0 and
            >0 when the strings  differ.   Bcmp  only  promises  to
            return  'non-zero'  when  the  strings  differ.  On the
            basis of a very small sample, bcmp seems to return  the
            length of the strings when they differ.

            On the other hand, having bcopy take its parameters  in
            the opposite order from strcpy is the pits.

       ctime
            The function, time(2), referred to in  the  DESCRIPTION
            is non-existent.  There is a gettimeofday(2).

            The function, time(3), referred to in  the  DESCRIPTION
            is non-existent.  There is an obsolescent time(3c).

            Page 2 has lots of room for usage examples.

       ctype
            In the definition of isprint,  I  think  the  '(8)'  is
            superfluous.

       directory
            The include  file,  <sys/types.h>,  should  be  in  the
            synopsis.

            Give  the  returns  from  'seekdir',  'rewinddir'   and
            'closedir'  or,  if  none, state that the functions are
            void.

            The  quantities,  d_namlen,  d_name  mentioned  in  the
            example,  as  well as others in 'struct direct' need to
            be defined.   Probably,  the  include  file  should  be
            cited.

       execl
            If the second sentence of  the  description  is  saying
            that  the  details  of  execl,  execv  are given on the
            manual page for execve(2), it lies.

            I think the FILES entry would be clearer as:  '/bin/sh,
            or  whatever  shell  is  invoked when a command file is
            found by execlp or execvp'


                                                        J. K. Cohen







       4.2BSD                                                  -24-


       getlogin
            The description says the correct  procedure  to  get  a
            login  name  involves  a  call  to  'getpw.'   However,
            'getpw' is deemed  'obsolescent.'  A  call  to  such  a
            function doesn't sound 'correct' to me.

            And 'getpw(3C)' is cited as having two  arguments,  not
            one, as indicated here.

            In the SEE ALSO, 'getpw(3)' is cited, but doesn't exist
            (the correct reference is 'getpw(3C).'

       malloc
            In the last phrase on the page omit the apostrophe.

       random
            The SEE  ALSO  should  refer  to  rand(3C)  instead  of
            rand(3).

       qsort(3F)
            The NAME says 'quick sort' instead of  'quicker  sort.'
            Is  this intentional, i.e., is this algorithm different
            than qsort(3)?

       syslog(3F)
            The header line should have (3F) instead of (3).

       getfsent(3X)
            Why gratuitously make things  harder  by  omitting  the
            comments in the copy of 'struct fstab'?

       printf(3S)
            In the second paragraph of the description, the phrase,
            'the  first  argument',  should  be  replaced  by, 'the
            format argument.'

            In the bullet item about field width, discuss effect of
            insufficient or missing field width (i.e. move the next
            to the last sentence of the description here).

            In fourth bullet item, omit the first comma.

            The X conversion is not defined.

            In the paragraph on 's' conversion, put a  comma  after
            the word, 'missing.'









                                                        J. K. Cohen







       4.2BSD                                                  -25-


       Programmer's Manual: Sections 4-7

       Not a chance your roving reporter  can  understand  much  of
       this.  I am even incompetent at the games!

       intro(4)
            The first entry in the SEE ALSO  sets  up  an  infinite
            loop.

       General comment on section 5:  this would be the right place
       to have a complete set of documented #include files.

       disktab(5)
            In the first sentence, 'date' should be 'data.'

       termcap(5)
            Last sentence of next to last paragraph  doesn't  parse
            well.

       aardvark(6)
            Won't run on this release (see volume 2c, section 39).

       boggle(6)
            Attempts to invoke produce  the  message:  'can't  open
            /usr/games/bogdict.'    This    is   truly   a   shame.
            /usr/games/bogdict exists (mode 600)  and  is  of  very
            healthy  size,  256  blocks.   Even /usr/dict/hlista is
            only 56 blocks.

       chase(6)
            Won't run on this release (see volume 2c, section 39).

       doctor(6)
            When invoked, pauses for a long  time  and  then  says:
            'Can't open file ./doctor' and dies.

       me(7)
            None of the writer aids that  depend  on  deroff  (like
            'spell')     work,    if    you    include    a    '.so
            /usr/lib/tmac/tmac.e' line in your file.

            Nroffing with -me causes variable  length  pages.   One
            cure  is  to  specify  the -Tlpr option.  Another is to
            filter the output through 'col.' Both  of  these  fixes
            nullify the advanced capabilities of the printer.










                                                        J. K. Cohen



-- 
Jack Cohen
{nbires|denelcor|hao}!udenva!jkcohen

Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.1 6/24/83; site udenva.UUCP
Path: utzoo!linus!decvax!ittvax!dcdwest!sdcsvax!sdcrdcf!hplabs!hao!
denelcor!udenva!jkcohen
From: jkco...@udenva.UUCP
Newsgroups: net.sources
Subject: Critique of 4.2BSD Doc, sec 39,40
Message-ID: <252@udenva.UUCP>
Date: Tue, 21-Aug-84 19:26:42 EDT
Article-I.D.: udenva.252
Posted: Tue Aug 21 19:26:42 1984
Date-Received: Thu, 30-Aug-84 09:43:53 EDT
Organization: U of Denver
Lines: 465





















                                 CRITIQUE

                                  of the

               BERKELEY 4.2 UNIX DOCUMENTATION - Volume IIc
                              Sections 39-40



                                    by



                              Jack K. Cohen






                             August 21, 1984



                     Copyright 1984 by Jack K. Cohen


       Permission to copy all or part of this material  is  granted
       provided  that  the  copies  are not made or distributed for
       direct commercial advantage, the author's  copyright  notice
       and the title of the article and its date appear, and notice
       is given that copying is by permission of  the  author.   To
       copy  otherwise,  or  to  republish,  requires  a fee and/or
       specific permission.
















       4.2BSD                                                   -1-


       Introduction

            I am hoping to issue a set  of  mini-critiques  of  the
       Programmer's Manual Volume IIc to supplement the Critique of
       Volume  I  which  was  recently  distributed.   This   first
       installement  covers  the  first two sections of Volume IIc.
       There are many sections  totally  beyond  my  interests  and
       abilities,  but  in addition to sections 39 and 40 presented
       here, I anticipate eventually covering at least sections 41,
       43, 45, 53, 54, and 56.













































                                                        J. K. Cohen







       4.2BSD                                                   -2-


       Bug Fixes and changes in 4.2BSD, section 39

       csh  In the third line, add the word, 'be', after the  word,
            'to.'

       script
            Last phrase should probably be 'at a terminal.'

       sdb  We are told that "it still lives on in/usr/src/old  for
            those  with  a personal attachment." However, if anyone
            does have  such  an  attachment,  they  are  doomed  to
            unrequited love since /usr/src is a private directory.

       stty The defaults mentioned here disagree with  those  given
            on the manual page.

       su   Changes noted do not appear on manual  page.   I  could
            not get the extra argument business to work:

                su myfriend 'ls /u/gsis/myfriend'

            evoked:

                ls /u/gsis/myfriend: File or directory not found


       tail Need something after the word, 'similar.'




























                                                        J. K. Cohen







       4.2BSD                                                   -3-


       An Introduction to the C Shell, section 40

       p2.  The mail example shows a visible EOT signal being  sent
            to  the  terminal,  and the text claims the characters,
            'EOT', are echoed by the mail program.  However,  these
            characters do not really appear at the terminal.

            It is stated that the uparrow character will be used to
            represent  the  control key.  This conflicts with other
            documents in this volume and  conflicts  with  internal
            usage  in  this  document.  For on pages 14-16, we find
            uparrow being used in  the  discussion  of  history  to
            represent the hat character.

            Locally, you get  reasonable  terminal  characteristics
            without  using  'tset'.   In particular, the default is
            that the backspace key works fine.

       p3.  The command 'ls  -s'  gives  file  sizes  in  terms  of
            kilobytes  (1024  characters)  instead  of  in terms of
            blocks of 512 characters.

       p4.  Again, 'ls -s' is said  to  use  512  character  blocks
            instead of the actual 1024.

       p7.  The first complete sentence on this page ('There exists
            ...'), is confusing because the list at the end of this
            lengthy beast uses ',' instead of 'or' as the delimiter
            between  cases.   Making a list of cases would be yet a
            better solution.

            The local interrupt signal is 'break'  (control-c)  not
            'del.'

       p8.  The example may mislead the novice into believing  that
            people  can  put  files into his/her directories.  Rest
            easy,  dear  novice,  your  directories   are   default
            protected  against  such intrusions both on this system
            and on any  professionally  administered  UNIX  system.
            Except  for the system administrator (aka 'super user',
            aka 'support'),  no  one  can  write  in  any  of  your
            directories  unless  you  take  special action (see the
            'chmod' command) to allow  them  to  do  so.   Again  a
            visible EOT is shown.

       p9.  Again, a claim is made for the appearance of a  visible
            EOT.

            Third sentence of  second  paragraph  gives  the  shell
            human  attributes (it can be 'provoked', but apparently
            only sometimes).




                                                        J. K. Cohen







       4.2BSD                                                   -4-


            After the example of using the command,  'more',  as  a
            filter, we find the awkward phrase, 'more simple more'.

       p11. The example of a typical  .login  could  be  made  more
            useful   if   here,   or  elsewhere,  a  more  complete
            explanation was given.

            The   method   shown   of    setting    the    terminal
            characteristics  is  archaic  (e.g. the option -s is no
            longer even documented in TSET(1)).

            The 'msgs' command does not currently function here.

            The if-then-endif structure shown at  the  end  of  the
            .login fails if one (see CSH(1), page 16) puts:

                set mail=(300 /usr/spool/mail/username)

            or the like.

            It is stated that the default 'mail check' interval  is
            5  minutes;  it  seems  to  be  10 minutes as stated in
            CSH(1), page 16.

       p14-15.
            The commands 'num' and 'ssp' do not exist.

       p14-16.
            As noted above, uparrow (defined  as  control  key)  is
            used when the hat character is meant.

       p15. To make the alias examples intelligible, it  should  be
            explained  that  !*  is  the  history  notation for all
            arguments of the previous (i.e. unaliased) command  and
            similarly  that  !^ means the first argument (and while
            we are at it that !$ means the last argument).

       p17. In the first sentence of the last paragraph,  the  word
            'background' is misspelled.

       p19. Before first example, 'background' is misspelled again.

            Why does the 'ls'  command  produce  only  one  process
            number  (cf.  same  command  and explanation thereof on
            page 18)?

       p23. This is scary, but despite the explicit note about  the
            \  inside  the  quotes,  I found that I got exactly the
            prompt whether or not I used the \.  (cf.  my  comments
            about  the  same  issue  under  'csh' in part I of this
            Critique).




                                                        J. K. Cohen







       4.2BSD                                                   -5-


            The reference to the repeat command (which has  limited
            usefulness  since  it  iterates  only a simple command)
            might well be supplemented  with  a  scaled  down  (and
            improved!) version of the following shell program:

            #! /bin/csh
            # Usage: loop ntimes cmd ...
            # Repeat group of commands n times
            # Note: The built-in, 'repeat' works only on simple cmds.
            # Note: Quote cmds with args, eg., loop 2 "sleep 10" who
            set c=$0
            set c=$c:t
            set N=$#argv

            if ($N < 2) then
                    echo Usage $c ntimes cmd ...
                    exit(1)
            endif
            @ x = $1
            shift
            @ N--
            while ($x)
                    @ i = 1
                    while ($i <= $N)
                            $argv[$i]
                            @ i++
                    end
                    @ x--
            end


            The discussion of setenv needs to be supplemented  with
            some discussion of what an 'environment' is.

       p25ff.
            There should be far more examples of shell programs  to
            illustrate  the many items mentioned all too fleetingly
            in this part of the tutorial.

       p25. In 4.2BSD, it would be better to start csh files with

                #! /bin/csh

            instead of just an arbitrary comment line.  In fact, if
            the first line of the file is

                #! /bin/sh

            then despite the fact that the file  begins  with  a  #
            line,   it   will   be  handled  by  the  Bourne  shell
            interpreter.




                                                        J. K. Cohen







       4.2BSD                                                   -6-


       p26. Near the bottom of the page the wrong form of 'echo' is
            cited, it should be:

                echo -n 'yes or no? '


       p27. At midpage the 'd' is omitted from 'replaced.'

       p29. I had trouble using set n=$0:t in shell  scripts.   (so
            the  program would be able to 'know' its name for error
            messages).  I found that  set  n=$0,  followed  by  set
            n=$n:t worked, but I have no idea why!

       p30. I advocate illustrating the structures shown;  this  is
            supposed to be a tutorial.

       p31. A  comment  should  be  added,  explaining   what   the
            'oldstring'  is  in the ed 's' command.  Note that here
            the uparrow is again  used  in  the  non-  control  key
            sense.

            Section 3.10 is too terse to be of any use.   And  then
            one-third  of  it re-explains the archaic usage of # to
            distinguish Bourne from C shells.

       p37. In the last paragraph, 'messages' is misspelled.





























                                                        J. K. Cohen



-- 
Jack Cohen
{nbires|denelcor|hao}!udenva!jkcohen