From owner-freebsd-chat@FreeBSD.ORG Tue Jul 28 02:30:09 2009 Return-Path: Delivered-To: freebsd-chat@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 7814C106564A for ; Tue, 28 Jul 2009 02:30:09 +0000 (UTC) (envelope-from emailrob@emailrob.com) Received: from mx04.dls.net (mx04.dls.net [216.145.245.200]) by mx1.freebsd.org (Postfix) with ESMTP id 462498FC1A for ; Tue, 28 Jul 2009 02:30:08 +0000 (UTC) (envelope-from emailrob@emailrob.com) Received: from [216.145.235.48] (helo=emailrob.com) by mx04.dls.net with esmtp (Exim 4.69) (envelope-from ) id 1MVakR-0000ni-KF; Mon, 27 Jul 2009 19:40:57 -0500 Message-ID: <4A6E3B17.7030609@emailrob.com> Date: Tue, 28 Jul 2009 00:41:11 +0100 From: spellberg_robert User-Agent: Mozilla/5.0 (Windows; U; Win98; en-US; rv:1.0.2) Gecko/20030208 Netscape/7.02 X-Accept-Language: en-us, en MIME-Version: 1.0 To: fbsd_chat References: <200907172257.QAA15292@lariat.net> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Subject: [ fbsd_chat ] sh(1) docs [ was: Bourne shell short-circuit operators improperly documented ] X-BeenThere: freebsd-chat@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Non technical items related to the community List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 28 Jul 2009 02:30:09 -0000 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