Date: Wed, 29 Jul 2009 21:21:41 +0100 From: spellberg_robert <emailrob@emailrob.com> To: fbsd_chat <freebsd-chat@freebsd.org>, Lowell Gilbert <freebsd-chat-local@be-well.ilk.org> Subject: Re: [ fbsd_chat ] Re: sh(1) documentation_set Message-ID: <4A70AF55.3060104@emailrob.com> References: <200907281352.n6SDqXur017295@lurza.secnetix.de> <4A6F5C31.2000502@emailrob.com> <444osvbnwd.fsf@be-well.ilk.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Lowell Gilbert wrote:
> spellberg_robert <emailrob@emailrob.com> 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".
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?4A70AF55.3060104>