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 From owner-freebsd-chat@FreeBSD.ORG Tue Jul 28 13:52:55 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 35DD410656C0 for ; Tue, 28 Jul 2009 13:52:55 +0000 (UTC) (envelope-from olli@lurza.secnetix.de) Received: from lurza.secnetix.de (lurza.secnetix.de [IPv6:2a01:170:102f::2]) by mx1.freebsd.org (Postfix) with ESMTP id 941168FC08 for ; Tue, 28 Jul 2009 13:52:54 +0000 (UTC) (envelope-from olli@lurza.secnetix.de) Received: from lurza.secnetix.de (localhost [127.0.0.1]) by lurza.secnetix.de (8.14.3/8.14.3) with ESMTP id n6SDqYBZ017296; Tue, 28 Jul 2009 15:52:49 +0200 (CEST) (envelope-from oliver.fromme@secnetix.de) Received: (from olli@localhost) by lurza.secnetix.de (8.14.3/8.14.3/Submit) id n6SDqXur017295; Tue, 28 Jul 2009 15:52:33 +0200 (CEST) (envelope-from olli) Date: Tue, 28 Jul 2009 15:52:33 +0200 (CEST) Message-Id: <200907281352.n6SDqXur017295@lurza.secnetix.de> From: Oliver Fromme To: freebsd-chat@FreeBSD.ORG, emailrob@emailrob.com In-Reply-To: <4A6E3B17.7030609@emailrob.com> X-Newsgroups: list.freebsd-chat User-Agent: tin/1.8.3-20070201 ("Scotasay") (UNIX) (FreeBSD/6.4-PRERELEASE-20080904 (i386)) MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-2.1.2 (lurza.secnetix.de [127.0.0.1]); Tue, 28 Jul 2009 15:52:49 +0200 (CEST) Cc: Subject: Re: [ 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 Reply-To: freebsd-chat@FreeBSD.ORG, emailrob@emailrob.com 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 13:52:55 -0000 spellberg_robert 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 From owner-freebsd-chat@FreeBSD.ORG Tue Jul 28 21:14:29 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 CD24E106566C for ; Tue, 28 Jul 2009 21:14:29 +0000 (UTC) (envelope-from emailrob@emailrob.com) Received: from mx01.dls.net (mx01.dls.net [216.145.245.197]) by mx1.freebsd.org (Postfix) with ESMTP id 9B4BF8FC14 for ; Tue, 28 Jul 2009 21:14:29 +0000 (UTC) (envelope-from emailrob@emailrob.com) Received: from [216.145.235.162] (helo=emailrob.com) by mx01.dls.net with esmtp (Exim 4.69) (envelope-from ) id 1MVu08-0006Ro-KH; Tue, 28 Jul 2009 16:14:27 -0500 Message-ID: <4A6F5C31.2000502@emailrob.com> Date: Tue, 28 Jul 2009 21:14:41 +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 , Oliver Fromme References: <200907281352.n6SDqXur017295@lurza.secnetix.de> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Cc: Subject: [ fbsd_chat ] Re: sh(1) documentation_set 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 21:14:30 -0000 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 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 From owner-freebsd-chat@FreeBSD.ORG Wed Jul 29 14:15:32 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 193811065690 for ; Wed, 29 Jul 2009 14:15:32 +0000 (UTC) (envelope-from freebsd-chat-local@be-well.ilk.org) Received: from mail7.sea5.speakeasy.net (mail7.sea5.speakeasy.net [69.17.117.9]) by mx1.freebsd.org (Postfix) with ESMTP id E5B5F8FC20 for ; Wed, 29 Jul 2009 14:15:31 +0000 (UTC) (envelope-from freebsd-chat-local@be-well.ilk.org) Received: (qmail 9279 invoked from network); 29 Jul 2009 13:48:51 -0000 Received: from dsl092-078-145.bos1.dsl.speakeasy.net (HELO be-well.ilk.org) ([66.92.78.145]) (envelope-sender ) by mail7.sea5.speakeasy.net (qmail-ldap-1.03) with SMTP for ; 29 Jul 2009 13:48:51 -0000 Received: by be-well.ilk.org (Postfix, from userid 1147) id 5D67E5083C; Wed, 29 Jul 2009 09:48:50 -0400 (EDT) To: spellberg_robert References: <200907281352.n6SDqXur017295@lurza.secnetix.de> <4A6F5C31.2000502@emailrob.com> From: Lowell Gilbert Date: Wed, 29 Jul 2009 09:48:50 -0400 In-Reply-To: <4A6F5C31.2000502@emailrob.com> (spellberg robert's message of "Tue\, 28 Jul 2009 21\:14\:41 +0100") Message-ID: <444osvbnwd.fsf@be-well.ilk.org> User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.3 (berkeley-unix) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Cc: fbsd_chat Subject: Re: [ fbsd_chat ] Re: sh(1) documentation_set X-BeenThere: freebsd-chat@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: fbsd_chat List-Id: Non technical items related to the community List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 29 Jul 2009 14:15:32 -0000 spellberg_robert 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). From owner-freebsd-chat@FreeBSD.ORG Wed Jul 29 14:41:52 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 D7934106564A for ; Wed, 29 Jul 2009 14:41:52 +0000 (UTC) (envelope-from olli@lurza.secnetix.de) Received: from lurza.secnetix.de (lurza.secnetix.de [IPv6:2a01:170:102f::2]) by mx1.freebsd.org (Postfix) with ESMTP id 59C6A8FC08 for ; Wed, 29 Jul 2009 14:41:52 +0000 (UTC) (envelope-from olli@lurza.secnetix.de) Received: from lurza.secnetix.de (localhost [127.0.0.1]) by lurza.secnetix.de (8.14.3/8.14.3) with ESMTP id n6TEfU5g082559; Wed, 29 Jul 2009 16:41:46 +0200 (CEST) (envelope-from oliver.fromme@secnetix.de) Received: (from olli@localhost) by lurza.secnetix.de (8.14.3/8.14.3/Submit) id n6TEfUhD082558; Wed, 29 Jul 2009 16:41:30 +0200 (CEST) (envelope-from olli) Date: Wed, 29 Jul 2009 16:41:30 +0200 (CEST) Message-Id: <200907291441.n6TEfUhD082558@lurza.secnetix.de> From: Oliver Fromme To: freebsd-chat@FreeBSD.ORG, freebsd-chat-local@be-well.ilk.org In-Reply-To: <444osvbnwd.fsf@be-well.ilk.org> X-Newsgroups: list.freebsd-chat User-Agent: tin/1.8.3-20070201 ("Scotasay") (UNIX) (FreeBSD/6.4-PRERELEASE-20080904 (i386)) MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-2.1.2 (lurza.secnetix.de [127.0.0.1]); Wed, 29 Jul 2009 16:41:46 +0200 (CEST) Cc: Subject: Re: [ fbsd_chat ] Re: sh(1) documentation_set X-BeenThere: freebsd-chat@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: freebsd-chat@FreeBSD.ORG, freebsd-chat-local@be-well.ilk.org List-Id: Non technical items related to the community List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 29 Jul 2009 14:41:53 -0000 Lowell Gilbert wrote: > spellberg_robert 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 From owner-freebsd-chat@FreeBSD.ORG Wed Jul 29 21:21:26 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 21FE2106566B for ; Wed, 29 Jul 2009 21:21:26 +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 E3CF08FC08 for ; Wed, 29 Jul 2009 21:21:25 +0000 (UTC) (envelope-from emailrob@emailrob.com) Received: from [216.145.235.2] (helo=emailrob.com) by mx04.dls.net with esmtp (Exim 4.69) (envelope-from ) id 1MWGaR-00078y-Aq; Wed, 29 Jul 2009 16:21:24 -0500 Message-ID: <4A70AF55.3060104@emailrob.com> Date: Wed, 29 Jul 2009 21:21:41 +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 , Lowell Gilbert References: <200907281352.n6SDqXur017295@lurza.secnetix.de> <4A6F5C31.2000502@emailrob.com> <444osvbnwd.fsf@be-well.ilk.org> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Cc: Subject: Re: [ fbsd_chat ] Re: sh(1) documentation_set 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: Wed, 29 Jul 2009 21:21:26 -0000 Lowell Gilbert wrote: > spellberg_robert 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". From owner-freebsd-chat@FreeBSD.ORG Thu Jul 30 08:28:48 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 1068A106566B for ; Thu, 30 Jul 2009 08:28:48 +0000 (UTC) (envelope-from des@des.no) Received: from tim.des.no (tim.des.no [194.63.250.121]) by mx1.freebsd.org (Postfix) with ESMTP id C55DD8FC14 for ; Thu, 30 Jul 2009 08:28:47 +0000 (UTC) (envelope-from des@des.no) Received: from ds4.des.no (des.no [84.49.246.2]) by smtp.des.no (Postfix) with ESMTP id 8C1406D418; Thu, 30 Jul 2009 08:12:50 +0000 (UTC) Received: by ds4.des.no (Postfix, from userid 1001) id 608AF844DC; Thu, 30 Jul 2009 10:12:50 +0200 (CEST) From: =?utf-8?Q?Dag-Erling_Sm=C3=B8rgrav?= To: spellberg_robert References: <200907281352.n6SDqXur017295@lurza.secnetix.de> <4A6F5C31.2000502@emailrob.com> <444osvbnwd.fsf@be-well.ilk.org> <4A70AF55.3060104@emailrob.com> Date: Thu, 30 Jul 2009 10:12:50 +0200 In-Reply-To: <4A70AF55.3060104@emailrob.com> (spellberg robert's message of "Wed, 29 Jul 2009 21:21:41 +0100") Message-ID: <86k51qwpvh.fsf@ds4.des.no> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.0.92 (berkeley-unix) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Cc: Lowell Gilbert , fbsd_chat Subject: Re: [ fbsd_chat ] Re: sh(1) documentation_set 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: Thu, 30 Jul 2009 08:28:48 -0000 spellberg_robert writes: > i began to write my scripts in csh. http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/ DES --=20 Dag-Erling Sm=C3=B8rgrav - des@des.no From owner-freebsd-chat@FreeBSD.ORG Thu Jul 30 10:33:00 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 1F4E51065680 for ; Thu, 30 Jul 2009 10:33:00 +0000 (UTC) (envelope-from olli@lurza.secnetix.de) Received: from lurza.secnetix.de (lurza.secnetix.de [IPv6:2a01:170:102f::2]) by mx1.freebsd.org (Postfix) with ESMTP id 3737B8FC1B for ; Thu, 30 Jul 2009 10:32:59 +0000 (UTC) (envelope-from olli@lurza.secnetix.de) Received: from lurza.secnetix.de (localhost [127.0.0.1]) by lurza.secnetix.de (8.14.3/8.14.3) with ESMTP id n6UAWdVo030885; Thu, 30 Jul 2009 12:32:54 +0200 (CEST) (envelope-from oliver.fromme@secnetix.de) Received: (from olli@localhost) by lurza.secnetix.de (8.14.3/8.14.3/Submit) id n6UAWdFG030884; Thu, 30 Jul 2009 12:32:39 +0200 (CEST) (envelope-from olli) Date: Thu, 30 Jul 2009 12:32:39 +0200 (CEST) Message-Id: <200907301032.n6UAWdFG030884@lurza.secnetix.de> From: Oliver Fromme To: freebsd-chat@FreeBSD.ORG, emailrob@emailrob.com In-Reply-To: <4A70AF55.3060104@emailrob.com> X-Newsgroups: list.freebsd-chat User-Agent: tin/1.8.3-20070201 ("Scotasay") (UNIX) (FreeBSD/6.4-PRERELEASE-20080904 (i386)) MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-2.1.2 (lurza.secnetix.de [127.0.0.1]); Thu, 30 Jul 2009 12:32:55 +0200 (CEST) Cc: Subject: Re: [ fbsd_chat ] Re: sh(1) documentation_set X-BeenThere: freebsd-chat@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: freebsd-chat@FreeBSD.ORG, emailrob@emailrob.com List-Id: Non technical items related to the community List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 30 Jul 2009 10:33:00 -0000 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