Date: Tue, 28 Jul 2009 00:41:11 +0100 From: spellberg_robert <emailrob@emailrob.com> To: fbsd_chat <freebsd-chat@freebsd.org> Subject: [ fbsd_chat ] sh(1) docs [ was: Bourne shell short-circuit operators improperly documented ] Message-ID: <4A6E3B17.7030609@emailrob.com> References: <200907172257.QAA15292@lariat.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?4A6E3B17.7030609>