[ fbsd_chat ] Re: sh(1) documentation_set

[Oliver Fromme]

spellberg_robert wrote:
 > this gets back to the question i asked originally [ see foot_note [e] ]:
 > 
 >      from where does one obtain the posix spec ?
 >      is it down_loadable ?

You can read it online or download it from the website
of The Open Group:

http://www.opengroup.org/onlinepubs/009695399/

Note that IEEE Std 1003.1 is what often is called "POSIX",
and there is also SUS (Single UNIX specification) which
used to be the same as POSIX, but AFAIK it wasn't updated
since 2001, so I think SUS is obsolete in this context.

 > [ as long as i am thinking about it, permit me to think "aloud".
 > 
 >    an idea that i had over the week_end was this:
 > 
 >      consider grep(1).
 >      there is "grep" and there is "grep -E".
 > 
 >      suppose sh(1) had an option.
 >      without the option, it defaults to being posix_compliant
 >        [ for an appropriate definition of "compliant" ].

If you need a feature-rich, configurable shell, I suggest
you install zsh (my favourite) or bash from the ports
collection.

In fact, zsh does support several emulation modes which
are enabled with the "emulate {zsh|sh|ksh|csh}" command,
and default to the name under which the shell was called.
The shell also support several options for finetuning the
level of POSIX-conformance vs. advanced features.

The bourne shell /bin/sh is a very important and critical
part of the operating system, therefore it is preferable
to keep it as simple as possible and not bloat it with
convenience features that are already handled by third-
party shells available from the ports collection.

 >    i would --not-- try to create the "be_all and end_all" scripting language.
 >    i --would-- have it do c_precedence integer arithmetic and bit_pattern operations.

Our /bin/sh already does that.  Admittedly, the documentation
is a little weak in this regard.

$ echo $(( 64 | 1 << 8 ))
320

 > here's one.
 > put --all-- of the
 >    "built_in" commands, functions and whatnots
 >    into --one-- list.

There's a builtin(1) manual page.  It just lists the commands
aphabetically and indicates which of them is available as
builtin in sh or csh, and/or as an external command.  For
a detailed description of the commands it refers to the
appropriate manual pages.  I think this is useful.

 > here's another one.
 > the re_direction operators are poorly described

FWIW, I think the description is terse, but complete.
If you're new to this, I agree that the description might
be _too_ terse, but again, the manual page is not intended
to be a tutorial.  In this case you should refer to third-
party material such as a good book on shell scripting.

 > further, they are described in two places.

There's only one section called "Redirections".  Of course,
they are mentioned in other sections, too, because they
affect other features, too.  For example, redirections
and pipes interact with each other, so they are mentioned
in the section about pipes, too.

 > still further, the two lists of operators in those two places are different.
 > each concept should be defined in only one place.

There is only one definition (section "Redirections").
The section "Lexical Structure" only lists the tokens that
are used for redirections, and specifically says that
"their meaning is discussed later".

 > oh, one other thing.
 > this one really sticks_in_my_craw.
 > in --my-- copies,
 >    i --am-- going to fix that whole "shell procedure" thing

The man page mentions this word only in one place, and that
place specifically says that this term is obsolete.
I think it's good to keep that remark, so people who come
from other shells and grep the manual page for this term
will find it.

 > in conclusion,
 >    i suspect that most of the readers of this post are --so-- accustomed to sh(1) that
 >    when they read the man_page,
 >    they see what they want to see, not what is, actually, written there.
 > because they have experience, they "read between the lines".
 > they "know" what the author "meant".
 > 
 > this is a human characteristic.

That's true.  It's also true that many developers (especially
in the open source / free software world) much prefer to
write code instead of good documentation.

But I can only repeat:  If you write up a diff or a new section
for the manual page, feel free to submit it (send-pr).
Improvements are always welcome.

 > read the man_pages for csh(1) and sh(1), in that order.
 > you tell me which is better organized.
 > you tell me which has clearer explanations.

Personally I feel that the csh(1) manual page is much too
long and contains too many things that do not belong into
a manual page.

 > my first shell was a flavor of bourne.
 > 
 > now, here's the rub.
 > almost immediately, i discovered csh(1).
 > in addition to its more__c_like__syntax, it had "alias" and "history".
 > at that time, bourne lacked these.
 > to this day, i have used csh(1) for interactive use.
 > i began to write my scripts in csh.
 > i like to think that i "understand" it [ of course, i --could-- be wrong ].

When I first started using UNIX, the default shell was csh
(tcsh to be exact), so I used that, and I even wrote a few
scripts in it.

I quickly discovered that csh syntax was awkward and not
really like C (at that time, I was a C programmer for several
years already).  So I switched over to bourne shell (/bin/sh)
for scripts.  I think that the bourne shell syntax is much
more consistent and less error-prone.  But I continued using
tcsh for interactive use.

Finally a coworker convinced me to give zsh a try.  It had
all the features of tcsh that I used, but the sane syntax
of a bourne shell.  The big advantage is that I can copy&paste
parts from shell scripts to the command line, try them out
interactively, modify them, try again, then paste them back
into the script.  The command line editor of zsh is very
advanced so you can easily edit multi-line constructs (and
I mean multi-line, not just long lines), unlike tcsh.  Also,
tab-completion works much better, the configuration of the
prompt is more flexible, and so on.  And last but not least,
it is easy to write your own extension modules.

It took me a very short time to get used to it, and I would
*never* go back to any shell that claims to have C-like
syntax.  I even put a statically linked zsh binary in /rescue
(my port update procedure does this automatically) because
it's so convenient.

Best regards
   Oliver

-- 
Oliver Fromme, secnetix GmbH & Co. KG, Marktplatz 29, 85567 Grafing b. M.
Handelsregister: Registergericht Muenchen, HRA 74606,  Geschäftsfuehrung:
secnetix Verwaltungsgesellsch. mbH, Handelsregister: Registergericht Mün-
chen, HRB 125758,  Geschäftsführer: Maik Bachmann, Olaf Erb, Ralf Gebhart

FreeBSD-Dienstleistungen, -Produkte und mehr:  http://www.secnetix.de/bsd

"We, the unwilling, led by the unknowing,
are doing the impossible for the ungrateful.
We have done so much, for so long, with so little,
we are now qualified to do anything with nothing."
        -- Mother Teresa