[ fbsd_chat ] sh(1) docs [ was: Bourne shell short-circuit operators improperly documented ]

[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