Bourne shell short-circuit operators improperly documented

[Brett Glass]

Everyone:

I'm teaching some new employees UNIX basics, and just ran into the
following text on the sh(1) man page:

    Short-Circuit List Operators
      ``&&'' and ``||'' are AND-OR list operators.  ``&&'' executes the first
      command, and then executes the second command if the exit status of the
      first command is zero.  ``||'' is similar, but executes the second com-
      mand if the exit status of the first command is nonzero.  ``&&'' and
      ``||'' both have the same priority.

This is exactly backward.

&& is a "short circuit AND." It stops right away and doesn't
evaluate its second operand if its first operand is 0. Why? Because
if one operand of an AND operation is 0, we already know the
result: 0. It can't be otherwise.

Likewise, || is a "short circuit OR." It stops right away and
doesn't evaluate its second operand if the first operand is 1 (or
anything nonzero). Why? Because if one operand of an OR operation
is nonzero, the result can never be 0.

How could this error have persisted in the FreeBSD documentation for so long?

--Brett Glass

_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Adrian Wontroba]

On Fri, Jul 17, 2009 at 04:57:12PM -0600, Brett Glass wrote:
>    Short-Circuit List Operators
>      ``&&'' and ``||'' are AND-OR list operators.  ``&&'' executes the first
>      command, and then executes the second command if the exit status of the
>      first command is zero.  ``||'' is similar, but executes the second com-
>      mand if the exit status of the first command is nonzero.  ``&&'' and
>      ``||'' both have the same priority.
>
> This is exactly backward.

No it is succinctly correct but confusing (the UNIX way?). These
operators work on exit codes where 0 = success = true and and !0 =
failure = false.

[aw1@steerpike ~]$ sh
$ true && echo true
true
$ false || echo false
false
$ true; echo $?
0
$ false; echo $?
1
$ exit

--
Adrian Wontroba
Confused? You will be. Just watch ...
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Jeremy C. Reed]

The only problem to me is that it says "AND-OR" since they are not C-style
logical operators.

It should just say "conditional execution".
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Brett Glass]

At 06:01 PM 7/17/2009, Adrian Wontroba wrote:

>No it is succinctly correct but confusing (the UNIX way?). These
>operators work on exit codes where 0 = success = true and and !0 =
>failure = false.

As I understand it, when it comes to UNIX result codes, 0 doesn't
really mean "true" -- it means "no error." (In other words, it
means "false.") Whereas any nonzero value means there was an error
(and indicates what kind). In other words, it means that it's
"true" that there was an error.

So, the semantics of the operators are supposed to be that "false"
is "true?" Aaargh!

No wonder I don't use short circuit operators much. When zero
equals one, it gets rather confusing.

It's also confusing that they are called "AND" and "OR" operators
(and look like the short-circuit AND and OR operators in other
languages, which all do what you would expect).

--Brett

_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Adrian Wontroba]

On Fri, Jul 17, 2009 at 07:21:14PM -0600, Brett Glass wrote:

> At 06:01 PM 7/17/2009, Adrian Wontroba wrote:
> >No it is succinctly correct but confusing (the UNIX way?). These
> >operators work on exit codes where 0 = success = true and and !0 =
> >failure = false.
> As I understand it, when it comes to UNIX result codes, 0 doesn't
> really mean "true" -- it means "no error." (In other words, it
> means "false.") Whereas any nonzero value means there was an error
> (and indicates what kind). In other words, it means that it's
> "true" that there was an error.
> So, the semantics of the operators are supposed to be that "false"
> is "true?" Aaargh!

I think mentioning true and false confuses (even more). In this
context 0 is success, anything else is failure. That said, the sh man
page earlier refutes your 0 means false with:

Each command has an exit status that can influence the behavior of other
shell commands.  The paradigm is that a command exits with zero for nor-
mal or success, and non-zero for failure, error, or a false indication.
                    ^^^^^^^^                          ^^^^^

> No wonder I don't use short circuit operators much. When zero
> equals one, it gets rather confusing.

I agree that they can be confusing. Forget the 0 and 1, just think of
success and failure.

> It's also confusing that they are called "AND" and "OR" operators

I agree with that too. As Jeremy wrote, "conditional execution" would
have been a better description.

> (and look like the short-circuit AND and OR operators in other
> languages, which all do what you would expect).

Well, they are operators and there are only a limited number of special
characters available. Look at all the different uses of & and | in the
shell (8-(

Perhaps the syntax could have been " and " / " or " (as in Perl's
and / or statement qualifiers (something() or die "oops";), but it is
far too late to change sh syntax. We have to live with it or use a
different shell or language.

Far too often do I make the mistake of thinking that something can
easily be written using sh, getting deep into it and then wishing I'd
used perl instead. Yes, it is amazing what an expert can do with sh, but
developing and debugging a complex sh script can take far too long.

--
Adrian Wontroba
Nearly every complex solution to a programming problem that I
have looked at carefully has turned out to be wrong.
                -- Brent Welch
(First cookie out of the box, and almost appropriate.)
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Paul Schenkeveld-10]

On Sat, Jul 18, 2009 at 03:48:35AM +0100, Adrian Wontroba wrote:

> > No wonder I don't use short circuit operators much. When zero
> > equals one, it gets rather confusing.
>
> I agree that they can be confusing. Forget the 0 and 1, just think of
> success and failure.
>
> > It's also confusing that they are called "AND" and "OR" operators
>
> I agree with that too. As Jeremy wrote, "conditional execution" would
> have been a better description.

Their naming and meaning are completely in line with the semantics of
the if, while and until operators of sh.  For example:

    if newfs /dev/da0 && mount /dev/da0 /mnt && mkdir /mnt/some_dir
    then
        cp this_file /mnt/some_dir
        chown 123:456 /mnt/some_dir
        chmod u=rw,go=r /mnt/some_dir
        echo "Installed this_file in /mnt/some_dir"
    fi

Meaning: *IF* I can newfs my usb stick *AND* I can mount it on /mnt
*AND* making a subdirectory on it succeeds *THEN* copy this_file into
that directory and so on.

Remind that if, while and until, although often followed by the [
synonym of the test(1) command, the original intent of them is that
they can be followed by any command and operatoe on the success/failure
condition of that command.

Choosing 0 for true and non-zero for false is also a very natural
choice.  There is only one way the command can succeed and many ways
the command can fail.  So if you have to choose one value from the
range 0 through 255 to use for success I'd go for 42^W 0 of course!

> > (and look like the short-circuit AND and OR operators in other
> > languages, which all do what you would expect).
>
> Well, they are operators and there are only a limited number of special
> characters available. Look at all the different uses of & and | in the
> shell (8-(
>
> Perhaps the syntax could have been " and " / " or " (as in Perl's
> and / or statement qualifiers (something() or die "oops";), but it is
> far too late to change sh syntax. We have to live with it or use a
> different shell or language.

How would they then be distinguishable from file names on the same
command line?

> Far too often do I make the mistake of thinking that something can
> easily be written using sh, getting deep into it and then wishing I'd
> used perl instead. Yes, it is amazing what an expert can do with sh, but
> developing and debugging a complex sh script can take far too long.

That brings us back to the original cultural decision made in UNIX,
there is not one command language, compiler, text formatter or whatever
which is tied to the system (or built-in) but you can choose whichever
suits your needs best or you can write your own if you like none of
them.

I do occasionally use perl (once every few years) but I can fully
express myself using sh(1) and derived shells (ksh, bash, zsh).  Looking
at the footprint of the shells and perl and knowing that every UN*X-like
system I've used since 1983 has some shell which is sh(1) compatible (at
least for 95%) and perl comes in versions (porting from perl 4.036 to
perl 5 cost me a lot of time ten years ago), needs tons of modules (if
you pick perl scripts from the Internet) and is not part of the base
system of FreeBSD (and many other UN*X systems), for me sh(1) is the
natural choice but please choose your own favorite as that's what the
UN*X culture explicitely promotes.

My $.02

Paul Schenkeveld
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Oliver Fromme]

Actually I've never regarded "&&" and "||" (and also "|"
and "&") as operators, like real operators in a programming
language, but as command separators, much like ";", but
with special semantics.

Note that

   foo && bar && baz
   foo || bar || baz

is the same as

   if foo; then if bar; then baz; fi; fi
   if ! foo; then if ! bar; then baz; fi; fi

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

"If you aim the gun at your foot and pull the trigger, it's
UNIX's job to ensure reliable delivery of the bullet to
where you aimed the gun (in this case, Mr. Foot)."
        -- Terry Lambert, FreeBSD-hackers mailing list.
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Dag-Erling Smørgrav]

Adrian Wontroba <aw1@...> writes:
> Perhaps the syntax could have been " and " / " or " (as in Perl's
> and / or statement qualifiers (something() or die "oops";), but it is
> far too late to change sh syntax. We have to live with it or use a
> different shell or language.

Pop quiz: what are the semantics of the follwing command line after your
proposed change:

echo I need a box and cat litter for my new kittens.

There is absolutely nothing surprising or illogical about the && and ||
command separators.

There is absolutely nothing surprising about "zero means success, non-
zero means failure" either - that's how most Unix system calls and many
standard C library functions work.

I'm sure we all have better things to do than argue about this non-
issue.

DES
--
Dag-Erling Smørgrav - des@...
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Christian Weisgerber]

Brett Glass <brett@...> wrote:

> As I understand it, when it comes to UNIX result codes, 0 doesn't
> really mean "true" -- it means "no error." (In other words, it
> means "false.") Whereas any nonzero value means there was an error
> (and indicates what kind). In other words, it means that it's
> "true" that there was an error.

You are very confused.

$ true; echo $?
0
$ false; echo $?
1

--
Christian "naddy" Weisgerber                          naddy@...

_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[spellberg_robert]

howdy, y'all --

i've been off_line for almost two weeks,
   servicing certain non_maskable interrupts,
   so, i am, just now, catching_up on my in_box.

normally, i wouldn't comment on this.
however, by sheer happen_stance, this past weekend,
   i had copied the sources from "/usr/src/bin/sh/*" to a working_directory,
   for the purpose of editing them for increased human_readability
   [ see note a, below ].
as of last_night,
   i have done the man_page, the "tour" [ twenty years old, now ],
   three stand_alone headers [ machdep.h, init.h and shell.h, iirc ],
   "main.h" and "main.c".
i will limit my comments to these files.
i have not done a thorough analysis of the portion that i have edited,
   however, i --have-- had to do --some-- analysis, as part of the act of editing.

i am not going to address the specific concern of mr. glass,
   that has been well_covered;
   rather, i will treat his concern as an instance of a more_general concern,
   "the sh(1) documentation_set,
      including the source_code files,
      as an effort designed to enhance human_comprehension of its operation,
      are --significantly--_less_than_completely satisfying",
   to which more_general concern, i believe, he would subscribe.



my killer_app, -- a priori --, depends upon
   the use of a good general_purpose macro_processor [b].
i thought that i had found one in m4(1),
   however, for most of my target user_base,
   it has, shall_we_say, "characteristics", up with which they will not put.
it is, simply, --too-- different.

therefore, i re_evaluated the use of sh(1).
it will do almost everything that i want, excluding, specifically,
   a]  sub_stringing by character_count [c];
   b]  arithmetic on integers, of width 37_bits or so [ let's say, 40 ];
   c]  more_than_minimal string conditionals
         [ "test" is, understandably, file_oriented ].
it turns out that item [b], above, is a very common "deficiency" [ these days ],
   for widths greater than 31_bits.
i wanted to determine the difficulty of
   adding some "built_in" "function"s or "command"s [ tbd ],
   that would remedy these and, perhaps, other items,
   which led to my following the advice of obi_wan kenobi [d].
on the other hand, this may prove to be only an educational experience;
   it may eventuate that i throw_my_hands_up_in_disgust,
   write some dedicated c_programs and depend upon command_substitution.



first, the big one.
i do not expect a man_page to be a tutorial,
   although, examples of common_usage are appreciated by many.
when the man_page states, unequivocally, that it is not a complete reference [e],
   then, there --is-- a problem.
man_pages need to be, at least, "substantially_complete".

second, i can understand the "tour" being out_of_date somewhat,
   perhaps, even by a few years,
   but, --twenty-- years ?
a statement in the document that informs the reader that
   the document is --known-- to be
   out_of_date or, in places, --wrong-- is un_satisfactory.
this problem arises all_too_frequently in cases when
   source_code is revised and its associated comments are not revised.

third, while it is true that
   i have found only one instance of this type of situation,
   it is also true that i have only just begun my examination.
in "main.c", there is a completely un_necessary repetition of the statement,

   state = 3;

   only two or three lines down from its initial appearance.
it does not produce an "error", as such; it is, simply, extraneous.
this type of situation makes me nervous.
i wonder what else i will find.
imho, sh(1) is too critical to the operation of the system for
   the rabid bat of insufficient code_review to be permitted to rear its ugly head.
no, i do not want to hear about optimizing_compilers.
one should be in the habit of writing well in_the_first_place.

last, in one or two places in the documents,
   it is stated that sh(1) is in a state of "ongoing development".
this phrase suggests the existence of an "active" development_program.
yet, the time_stamps of the files pre_date the release_date by several years.
perhaps, newer versions had bugs,
   forcing the use of the most_recent "good" version.
none_the_less,
   i am concerned that sh(1) may be --such-- a mature computer_program that
   the "ongoing development" is, in reality, of a "back_burner" nature.
certainly, development was active at one time; perhaps, it remains so.
however, if not, then this phrase has outlived its usefulness.

when i was a bench_engineer, a long time ago in a galaxy far away,
   i was taught a rule regarding problems found during engineering development,
   "you findee, you fixee" [f].
perhaps, it will devolve to me to attend to such things for the benefit of others.
i know, for certain, that, in my own copies of the various documents,
   i will insert clarifications and, when errors are found, corrections;
   i have found this practice to be useful.



i could be wrong, but,
   i suspect that sh(1) doesn't change much from year to year.
perhaps, this situation is nothing more complicated than that
   folks are, well, "comfortable" with it.

rob



footnotes
---------

a]  my documentation_style subscribes to the commandment,
       "thou shalt not force
         [    thy code_reviewer
           or thy code_maintainer
           or thy student
           or other reader_of_thy_code
         ]
         to play the role of
         [    lexer
           or parser
         ]".

b]  i want to use, if possible, only standard utilities for the prototype,
       eventually converting to c for the benefit of large data_sets;
       sed(1) and awk(1) have proved to be particularly useful.

c]  well, not directly;
       i had to write a function that implemented a loop to
       remove, one_at_a_time, the un_desired characters [ ugh ! ].
     this experience was my motivation.

d]  i hear his voice in my head; he tells me to do things.

e]  speaking of which, from where does one obtain the posix spec ?
     do i buy a printed copy from the ieee or
       is there a downloadable "pdf", somewhere ?

f]  back then, it was still socially_acceptable to use a fake chinese accent.

eof

_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Oliver Fromme]

spellberg_robert <emailrob@...> wrote:
 > my killer_app, -- a priori --, depends upon
 >    the use of a good general_purpose macro_processor [b].
 > i thought that i had found one in m4(1),

Personally I think m4 is weird and error-prone.
Another possibility is to use cpp (the C preprocessor).
It's not perfect either, but maybe it's more suitable
for your purpose.

 > therefore, i re_evaluated the use of sh(1).
 > it will do almost everything that i want, excluding, specifically,
 >    a]  sub_stringing by character_count [c];

You can define a shell function that uses dd(1):

 $ substr() { echo "$1" | dd bs=1 skip=$2 count=$3 2>/dev/null; }
 $ foo=`substr "FreeBSD" 4 3`
 $ echo $foo
 BSD
 $

It's not terribly efficient, because dd(1) is an external
binary that has to be exec*()ed by the shell.  So it might
be slow if you use the substr function often.

It is possible to write this function using shell-builtin
commands only (no exec*() necessary), but it requires a
loop.  Whether this is faster or slower I can't tell, it
probably depends on the circumstances.  Shell loops that
use only builtin features are usually fast enough for
normal script, unless you try to abuse sh(1) and use it
like a programming language.  In that case you're advised
to use something better suited for the purpose, like
Python (my personal favourite), Ruby, Perl or similar.

 >    b]  arithmetic on integers, of width 37_bits or so [ let's say, 40 ];

This has been improved.  Recent versions of FreeBSD 7 and 8
use 64 bit arithmetic, like most other shells.

 >    c]  more_than_minimal string conditionals
 >          [ "test" is, understandably, file_oriented ].

There is also expr(1) and other tools.  Apart from that,
you should be able to implement what you need with shell
functions.  Is there anything in particular that you are
looking for?

 > i do not expect a man_page to be a tutorial,

Right.  Man pages are reference documentation.  They're
not typically used for tutorials, recipes or "how-to".
There are quite many books on the topic of bourne shell.
(I mean real books, i.e. paper ware.  There might be
online books, too, but I'm not aware of a good one right
now that I could recommend.)

 > man_pages need to be, at least, "substantially_complete".

I agree that the sh(1) manual page should be complete,
and I think it is indeed complete.  Do you think some
piece of reference information is missing?

 > second, i can understand the "tour" being out_of_date somewhat,
 >    perhaps, even by a few years,
 >    but, --twenty-- years ?

Probably it is kept only for historical purposes.  The
developers working on the sh(1) source certainly don't
need that "tour" file.

 > i could be wrong, but,
 >    i suspect that sh(1) doesn't change much from year to year.

Well, it depends on what you call "doesn't change much".
>From time to time it grows a new feature (like the 64bit
arithmetics last year) or a new builtin.  Sometimes a
builtin is even removed, like the printf command which
used to be builtin, but was removed in favour of the
external command.  And sometimes bugs are fixed, of
course.

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

"Unix gives you just enough rope to hang yourself --
and then a couple of more feet, just to be sure."
        -- Eric Allman
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[spellberg_robert]

dear mr. fromme ---

i thank you for your thoughts and the time you took to "pen" them.
my thesis was in regard to the documentation_set for sh(1).
what i said about my "killer_app"
   was an effort to describe my motivation for examining that set.
while it was not my intention to
   seek advice regarding the development of my prototype,
   i appreciate your efforts, on my behalf, and will respond to them,
   in addition to your thesis_related comments.



Oliver Fromme wrote:
> spellberg_robert <emailrob@...> wrote:
>  > my killer_app, -- a priori --, depends upon
>  >    the use of a good general_purpose macro_processor [b].
>  > i thought that i had found one in m4(1),
>
> Personally I think m4 is weird and error-prone.

hear !
hear !



> Another possibility is to use cpp (the C preprocessor).

oddly enough, i thought of this approach first [ great minds think alike ].
i rejected it because of the work involved to create work_arounds;
   its intended use is enough different from mine.

> It's not perfect either, but maybe it's more suitable
> for your purpose.
>
>  > therefore, i re_evaluated the use of sh(1).
>  > it will do almost everything that i want, excluding, specifically,
>  >    a]  sub_stringing by character_count [c];
>
> You can define a shell function that uses dd(1):
>
>  $ substr() { echo "$1" | dd bs=1 skip=$2 count=$3 2>/dev/null; }
>  $ foo=`substr "FreeBSD" 4 3`
>  $ echo $foo
>  BSD
>  $
>
> It's not terribly efficient, because dd(1) is an external
> binary that has to be exec*()ed by the shell.  So it might
> be slow if you use the substr function often.

i already did the filter thing:

         foo=`echo  FreeBSD   |   right_all_but_n  4   |   left_n  3`

   or

         foo=`echo  FreeBSD   |   right  3`

   where "left_n", "right_n", "left_all_but_n" and "right_all_but_n" are
   compiled, c_language filters, which take the character_count as an argument.
i may end_up using it, for now, because it works and it is "intuitively obvious".
long_term, however, i will reject it, because it forks a child.

additionally, the use of dd(1), especially for my target user_base,
   violates a corollary of my stated commandment,
   which i did not state originally, but, which i will state here:

         thou shalt not be clever.

some folks see commandments as "negative rights".
a "positive rights" variant would be:

         thou shalt be intuitively_obvious to even the most dis_interested reader;

   however, this is not as clear, so, it is not used, except informally.



>
> It is possible to write this function using shell-builtin
> commands only (no exec*() necessary), but it requires a
> loop.

see note [c].



   Whether this is faster or slower I can't tell, it
> probably depends on the circumstances.  Shell loops that
> use only builtin features are usually fast enough for
> normal script, unless you try to abuse sh(1) and use it
> like a programming language.

"abuse", to me, is a subjective term, because
   sh(1) "kinda is" and "kinda isn't" a programming language.
it has an intended purpose, but, it will do many other things, as well.



   In that case you're advised
> to use something better suited for the purpose, like
> Python (my personal favourite), Ruby, Perl or similar.

when i discovered python, about eight or nine years ago, i got really excited.
it would have been my first choice, for many reasons, but,
   i was forced to reject it because it violates another commandment:

         thou shalt not preclude the use of arbitrary white_space between tokens.

my writing_style violates python's indentation rules.

there exists a related rule:

         thou shalt formally specify the syntax of thy token_set.

this comes under the commandment:

         the operation of thy app shall
           produce the least amount of astonishment in thy user.

the syntax

         name=value

   can not have white_space around the equal_sign.
it is hard_to_read.
an sh(1)_newbie with programming_language experience will be, probably, taken_aback.
however,

         setvar   name   value

   can have arbitrary white_space.
betcha can't guess which one i like.

ruby forces me to be "oopsy".
fifty years ago, my late mommy taught me that it isn't good to be "oopsy".
the problem with "oops" is that, for my purposes,
   it is not "overkill", it is "too much overkill".
it is my understanding that it --does-- have a clear advantage in one case:
   the development of a so_called "windowing graphical_user_interface"
   [ if anyone knows of another, please advise ].
"oops" is like socialism:
   in the faculty_lounge, it seems like a really_great_idea
   [ "will you have another glass of chablis, professor_emeritus ?" ];
   in the real_world, it gets in the way of those who do real work.

i discovered perl in 2000, just before i discovered python.
perl is clever.
perl's numbers are floating_point; mine are integers
   [ i understand that an integral number_type has been added, but,
       this does not address the main problem
   ].



>
>  >    b]  arithmetic on integers, of width 37_bits or so [ let's say, 40 ];
>
> This has been improved.  Recent versions of FreeBSD 7 and 8
> use 64 bit arithmetic, like most other shells.

i am not up to seven, yet
   [ i have the cds from the mall; so many tasks, so few hours ].
eight is not out.
i can not expect my users to always have the "latest_and_greatest".
this is why, eventually, i will have to write most of this in c.



>
>  >    c]  more_than_minimal string conditionals
>  >          [ "test" is, understandably, file_oriented ].
>
> There is also expr(1) and other tools.  Apart from that,
> you should be able to implement what you need with shell
> functions.  Is there anything in particular that you are
> looking for?

not that i have not discussed.



>
>  > i do not expect a man_page to be a tutorial,
>
> Right.  Man pages are reference documentation.  They're
> not typically used for tutorials, recipes or "how-to".
> There are quite many books on the topic of bourne shell.
> (I mean real books, i.e. paper ware.  There might be
> online books, too, but I'm not aware of a good one right
> now that I could recommend.)

i have about twenty shelf_feet of books, just on computer_software topics.
i do not like "online" books, because i stare at my screen enough, as_it_is.
there is absolutely nothing like
   a good book,
   a comfortable chair,
   a high_wattage incandescent_lamp [ evenings ]
     [ to provide flicker_free even illumination that is easy_on_the_eyes ],
   a fine dominican cigar and
   artur schnabel, emil gilels or alfred brendel playing beethoven on the hi_fi.
oh, yes; i turn off the phone.



>
>  > man_pages need to be, at least, "substantially_complete".
>
> I agree that the sh(1) manual page should be complete,
> and I think it is indeed complete.  Do you think some
> piece of reference information is missing?

ah_ha, you have arrived at my thesis.

the man_page author states that it is not complete, in the first paragraph.



>
>  > second, i can understand the "tour" being out_of_date somewhat,
>  >    perhaps, even by a few years,
>  >    but, --twenty-- years ?
>
> Probably it is kept only for historical purposes.  The
> developers working on the sh(1) source certainly don't
> need that "tour" file.

i am not referring to any "developers".
a statement in the "tour" asserts that it remains as an introduction.
clearly, this document is intended to be a quasi_tutorial for
   a reader who is experienced in one_or_more other areas.
the information that it contains should be in the source_code,
   where it has a higher probability of being more recent,
   relative to the source being compiled
   [ as i said originally, this may be the case,
       for i have not, yet, reviewed all of the source
   ].



>
>  > i could be wrong, but,
>  >    i suspect that sh(1) doesn't change much from year to year.
>
> Well, it depends on what you call "doesn't change much".
>>From time to time it grows a new feature (like the 64bit
> arithmetics last year)

this does not qualify;
   converting from 32_bit to 64_bit occurs platform_wide,
   which is a task that will take a_while.

a change that applies to all shells also does not qualify.



  or a new builtin.  Sometimes a
> builtin is even removed, like the printf command which
> used to be builtin, but was removed in favour of the
> external command.

this qualifies, because it is sh(1)_specific.



   And sometimes bugs are fixed, of
> course.

sh(1) has bugs ?!?!?!

holy moses !!!

next thing, some_one will tell me that vi(1) has bugs.



>
> Best regards
>    Oliver

to you, sir, as well.
it has been a pleasure typing with you.

rob

_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Lowell Gilbert-10]

spellberg_robert <emailrob@...> writes:

> dear mr. fromme ---

>>  > man_pages need to be, at least, "substantially_complete".
>>
>> I agree that the sh(1) manual page should be complete,
>> and I think it is indeed complete.  Do you think some
>> piece of reference information is missing?
>
> ah_ha, you have arrived at my thesis.
>
> the man_page author states that it is not complete, in the first paragraph.

Not really.  What it says is that the man page is not a complete
*specification*.  That is not the same thing as being incomplete as a
user manual.  When appropriate information is noticed to be missing, it
does get added (as you can confirm from looking at the checkin log for
sh.1).
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Oliver Fromme]

Lowell Gilbert <freebsd-chat-local@...> wrote:
 > spellberg_robert <emailrob@...> writes:
 >
 > > dear mr. fromme ---
 >
 > > > > man_pages need to be, at least, "substantially_complete".
 > > >
 > > > I agree that the sh(1) manual page should be complete,
 > > > and I think it is indeed complete.  Do you think some
 > > > piece of reference information is missing?
 > >
 > > ah_ha, you have arrived at my thesis.
 > >
 > > the man_page author states that it is not complete, in the first paragraph.
 >
 > Not really.  What it says is that the man page is not a complete
 > *specification*.  That is not the same thing as being incomplete as a
 > user manual.  When appropriate information is noticed to be missing, it
 > does get added (as you can confirm from looking at the checkin log for
 > sh.1).

Right.  In particular, a complete specification should include
a formal grammar of the language accepted by the shell.  This
is missing from the manual page, but it isn't really necessary
for normal use of the shell.

On the other hand, I do have to agree with Robert that some
parts of the man page are very terse, sometimes up to the
point that you actually have to try things out (or examine
the source) in order to find out how something works.  For
example, the man page fails to mention which operators are
supported in arithmetic expressions, and how they evaluate
their arguments, exactly.  (I noticed this just today.)

Certainly, if someone writes up a paragraph for inclusion in
the manual page, it will be gratefully accepted and comitted
if appropriate.

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

"I started using PostgreSQL around a month ago, and the feeling is
similar to the switch from Linux to FreeBSD in '96 -- 'wow!'."
        -- Oddbjorn Steffensen
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[spellberg_robert]

Lowell Gilbert wrote:
 > spellberg_robert <emailrob@...> writes:
 >
 >
 >>dear mr. fromme ---
 >
 >
 >>> > man_pages need to be, at least, "substantially_complete".
 >>>
 >>>I agree that the sh(1) manual page should be complete,
 >>>and I think it is indeed complete.  Do you think some
 >>>piece of reference information is missing?
 >>
 >>ah_ha, you have arrived at my thesis.
 >>
 >>the man_page author states that it is not complete, in the first paragraph.
 >
 >
 > Not really.  What it says is that the man page is not a complete
 > *specification*.  That is not the same thing as being incomplete as a
 > user manual.  When appropriate information is noticed to be missing, it
 > does get added (as you can confirm from looking at the checkin log for
 > sh.1).



dear mr. gilbert ---

i thank you, sir.



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 ?



[ 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" ].
     with the option, however, a set of extensions is added.
     this set may include alternative behaviors.
     because one_or_more of the items in the set may conflict with posix,
       "complete" compliance may have to be sacrificed,
       however, "substantial" compliance would remain
       [ after all, we don't want to confuse people ].

   mostly, i am happy with the interactive operation
     [ i would add things to the prompt ].
   right now, my only other concern is to add sub_string operations.
   if i were to add other extensions,
     my focus would be on non_interactive use.
   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.
]



here's one.
put --all-- of the
   "built_in" commands, functions and whatnots
   into --one-- list.
do not say, else_where,
   obliquely [ was it somebody's after_thought ? ], that
   there exists a built_in version of test(1).
put "test" in the list, alphabetically, and say,
   "this is a built_in version of test(1);
   it behaves exactly in the same manner;
   the exit_status of [ thingy ] is
   a]  zero on 'success' or 'true' and
   b]  non_zero, other_wise".
if a built_in is described in another section,
   then put it in the list and say,
   this is described in section 'such_and_such'".
say if that section is "above" or "below".



here's another one.
the re_direction operators are poorly described
   [ i tried to deduce which descriptors had reads and which had writes, but,
       beyond changing reads from 0 and writes to 1 and 2,
       i will be more confident writing in c using stevens' "apue" as my guide;
       i do not do this every day, but, i ought to be able to figure it out
   ].
further, they are described in two places.
still further, the two lists of operators in those two places are different.
each concept should be defined in only one place.



oh, one other thing.
this one really sticks_in_my_craw.
in --my-- copies,
   i --am-- going to fix that whole "shell procedure" thing
   [ to para_phrase:
       "the term is mis_leading, but, we left it in anyway - GOTCHA !"
   ].

i recognize that somebody thought it sufficient to make a notation,
   rather than fix the problem.
better than nothing, certainly.
"easier", yes.
"sufficient", no.



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.

i have to keep telling myself that
   the people in this world who do the real work are governed by one rule,
   "too many tasks, too little time".



here is an exercise for the interested student.
fifty extra_credit points will be given.

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.

rob



ps ---

it strikes me that the following may explain a few things.

my first unix was something called "programmer's work_bench", on a pdp_11,
   way_back during "the before_time", circa 1983.
not too long after, this was replaced with bsd_4.2, on a vax_11_750, iirc
   [ they were all 780s, later ].
with a background in 6800, 6809 and 68000 assembly [ and a dollop of 8080 ],
   i fell in love with c
   [ as fermat is to theory, pascal is to celery ].
truly, this was the "cat's meow", although, imho, it could be more assembly_like
   [ send your flames to ... ].
i --think--     in   dec/motorola assembly_language.
i --translate-- into whatever i am using [ of course, i have the i386 manuals ].

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

as part of my "killer_app" project, i decided that
   i could not let it depend upon the availability of third_party software.
remember what i said about using standard utilities and, later, c ?
therefore, i decided to re_evaluate sh(1),
   in particular, because most of the fbsd system_scripts are written for it.
i observe that it is, now, more csh_like [ hmmm ... ].

i would describe myself as a sh(1) "re_newbie".

_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[Dag-Erling Smørgrav]

spellberg_robert <emailrob@...> writes:
> i began to write my scripts in csh.

http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/

DES
--
Dag-Erling Smørgrav - des@...
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."

[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
_______________________________________________
freebsd-chat@... mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "freebsd-chat-unsubscribe@..."