Re: Question about the return value of 'local'
On Fri, Dec 14, 2012 at 08:37:02AM +0100, Francis Moreau wrote: Then maybe an option should be added to 'local' to display the full description that one can get from the manual, or maybe change the behaviour of '-m' switch ? Almost every builtin command has a shorter and less informative description in the shell's 'help' than it does in the manual. The 'help' output is supposed to be a brief reminder of the syntax (e.g. which option letter was that...), not a repetition of the entire manual. I do sympathize with the difficulty of finding the relevant information in the manual sometimes, though, especially for builtins that are common words like 'set'.
Re: Question about the return value of 'local'
On Fri, Dec 14, 2012 at 2:21 PM, Greg Wooledge wool...@eeg.ccf.org wrote: On Fri, Dec 14, 2012 at 08:37:02AM +0100, Francis Moreau wrote: Then maybe an option should be added to 'local' to display the full description that one can get from the manual, or maybe change the behaviour of '-m' switch ? Almost every builtin command has a shorter and less informative description in the shell's 'help' than it does in the manual. The 'help' output is supposed to be a brief reminder of the syntax (e.g. which option letter was that...), not a repetition of the entire manual. Well, I actually use help(1) more than a shortcut to access quickly the relevant part of the manual than anything else. I regularly find that sailing across the manual is quite slow and annoying, but it's probably just me being lazy. -- Francis
Re: Question about the return value of 'local'
On 12/14/12 2:37 AM, Francis Moreau wrote: `help' is a quick reference -- a handy shortcut. The authoritative documentation is still the manual page and texinfo document. Then maybe an option should be added to 'local' to display the full description that one can get from the manual, or maybe change the behaviour of '-m' switch ? It was never a goal to duplicate the entire 70+-page manual inside bash. Why would I add options to each builtin to do that? The -m option to help was intended to display in a more familiar format. It's not a manual replacement, either. We already have the man page and the info file. -- ``The lyf so short, the craft so long to lerne.'' - Chaucer ``Ars longa, vita brevis'' - Hippocrates Chet Ramey, ITS, CWRUc...@case.eduhttp://cnswww.cns.cwru.edu/~chet/
Re: Question about the return value of 'local'
On 12/14/12 8:21 AM, Greg Wooledge wrote: I do sympathize with the difficulty of finding the relevant information in the manual sometimes, though, especially for builtins that are common words like 'set'. That's where the superior indexing and structure of the info file format demonstrate their advantages. Chet -- ``The lyf so short, the craft so long to lerne.'' - Chaucer ``Ars longa, vita brevis'' - Hippocrates Chet Ramey, ITS, CWRUc...@case.eduhttp://cnswww.cns.cwru.edu/~chet/
Re: Question about the return value of 'local'
On Friday, December 14, 2012 08:37:02 AM Francis Moreau wrote: On Thu, Dec 13, 2012 at 3:19 PM, Chet Ramey chet.ra...@case.edu wrote: On 12/13/12 3:56 AM, Francis Moreau wrote: I see thanks. Somehow I thought that help(1) would have given nothing more nothing less than what was described in the manual. `help' is a quick reference -- a handy shortcut. The authoritative documentation is still the manual page and texinfo document. Then maybe an option should be added to 'local' to display the full description that one can get from the manual, or maybe change the behaviour of '-m' switch ? Thanks. The best you could do (realistically) is manually keep the man document in sync with the help text for every individual builtin. Generating help output automatically would require completely changing the way builtin options are processed, because there aren't just arrays of options that could be mapped to descriptions. Bash loops over a condition for all available options for each argument. There are also a couple intentionally undocumented options (like declare -c), and some which can vary by how bash was built (like echo). Also the man document has all the formatting in it and can't be automatically generated from individual builtin help text easily, or vice versa. Zsh is way bigger than Bash and has no help system at all (unless I missed it in the dozen or so manpages...). Ksh has an unbelievably stupid way of accessing the help, though it tends to be even more comprehensive than the manpage. The options are automatically generated and the descriptions hardcoded to a central builtins.c file. (user-defined types are self- documenting). Most shell manuals follow about the same overall format and obviously borrow from one another. Some paragraphs are word-for-word identical between Bash and multiple other manuals. Best bet is to learn to navigate it quickly. -- Dan Douglas
Re: Question about the return value of 'local'
I'm not trying to start a war, but ... Has anyone entertained the idea of getting rid of the man pages and the info system? Those are relics of the tty era. We have graphical interfaces today with capabilities that could enhance providing and then finding better information. Wouldn't a browser based html page be more helpful? Anyone on a non GUI could use lynx to read the pages, or make man pull up lynx to keep the command structure the same. The basic page could be what man is now, more or less, and the ability to drill down would provide more and more information the deeper you drill. Code snippets could highlight idiosyncratic behavior at boundary conditions while other examples demonstrate the main emphasis. A WIKI set up could allow people to augment the docs with some authority then editing the content to keep it up to some standard. Greg's site is excellent, as are several others, and that's the issue. There is no one authoritative place to go to get the OFFICIAL docs in a modern form. Who wants to learn how to write and submit man or info docs when the future is clearly html, especially when neither man nor info has the rendering capability html has? If the Linux community as a whole missed one technical release cycle to instead concentrate on properly documenting what already exists, the effort would pay off in spades for all future releases. On Fri, Dec 14, 2012 at 10:15 AM, Dan Douglas orm...@gmail.com wrote: On Friday, December 14, 2012 08:37:02 AM Francis Moreau wrote: On Thu, Dec 13, 2012 at 3:19 PM, Chet Ramey chet.ra...@case.edu wrote: On 12/13/12 3:56 AM, Francis Moreau wrote: I see thanks. Somehow I thought that help(1) would have given nothing more nothing less than what was described in the manual. `help' is a quick reference -- a handy shortcut. The authoritative documentation is still the manual page and texinfo document. Then maybe an option should be added to 'local' to display the full description that one can get from the manual, or maybe change the behaviour of '-m' switch ? Thanks. The best you could do (realistically) is manually keep the man document in sync with the help text for every individual builtin. Generating help output automatically would require completely changing the way builtin options are processed, because there aren't just arrays of options that could be mapped to descriptions. Bash loops over a condition for all available options for each argument. There are also a couple intentionally undocumented options (like declare -c), and some which can vary by how bash was built (like echo). Also the man document has all the formatting in it and can't be automatically generated from individual builtin help text easily, or vice versa. Zsh is way bigger than Bash and has no help system at all (unless I missed it in the dozen or so manpages...). Ksh has an unbelievably stupid way of accessing the help, though it tends to be even more comprehensive than the manpage. The options are automatically generated and the descriptions hardcoded to a central builtins.c file. (user-defined types are self- documenting). Most shell manuals follow about the same overall format and obviously borrow from one another. Some paragraphs are word-for-word identical between Bash and multiple other manuals. Best bet is to learn to navigate it quickly. -- Dan Douglas -- Bill Gradwohl
Re: Question about the return value of 'local'
On 12/14/2012 12:07 PM, Bill Gradwohl wrote: I'm not trying to start a war, but ... Has anyone entertained the idea of getting rid of the man pages and the info system? Those are relics of the tty era. We have graphical interfaces today with capabilities that could enhance providing and then finding better information. Wouldn't a browser based html page be more helpful? Anyone on a non GUI could use lynx to read the pages, or make man pull up lynx to keep the command structure the same. The basic page could be what man is now, more or less, and the ability to drill down would provide more and more information the deeper you drill. Code snippets could highlight idiosyncratic behavior at boundary conditions while other examples demonstrate the main emphasis. A WIKI set up could allow people to augment the docs with some authority then editing the content to keep it up to some standard. Greg's site is excellent, as are several others, and that's the issue. There is no one authoritative place to go to get the OFFICIAL docs in a modern form. Who wants to learn how to write and submit man or info docs when the future is clearly html, especially when neither man nor info has the rendering capability html has? If the Linux community as a whole missed one technical release cycle to instead concentrate on properly documenting what already exists, the effort would pay off in spades for all future releases. Die Infidel! ;-) You will find no problem viewing man or info pages in html. They are all over the web for a reason. TeXInfo was designed to produce either info files or DVI. From the DVI, you can do anything you want, including convert to html. I'm not wild about software (or associated docs) that's maintained in a wiki. It kinda violates the notion of a stable picture of what's in a release. Steve Orr
Re: Question about the return value of 'local'
On 12/14/2012 06:07 PM, Bill Gradwohl wrote: I'm not trying to start a war, but ... Has anyone entertained the idea of getting rid of the man pages and the info system? Those are relics of the tty era. Don't make the error of confusing the texinfo system with just the info format. I, for one, *never* read pages in the info format. However, I never had any problem reading the official documentation of GNU packages -- I just read the HTML version that is generated by exactly the same texinfo sources used to generate the info pages (as well as the PDF manuals for printing are). [SNIP] A WIKI set up could allow people to augment the docs with some authority then editing the content to keep it up to some standard. Greg's site is excellent, as are several others, and that's the issue. There is no one authoritative place to go to get the OFFICIAL docs in a modern form. What's wrong with http://www.gnu.org/software/bash/manual/bashref.html? Or, if you want a local version, just install the 'bash-doc' package on Debian (or the equivalent package that surely comes with other distros). Who wants to learn how to write and submit man or info docs when the future is clearly html, especially when neither man nor info has the rendering capability html has? Nobody writes info directly; one writes Texinfo, and that can be automatically translated to info, html, PDF (and PostScript and DVI too, not that it matters today). And I must say that I find the HTML generated from texinfo sources of high quality (nor perfect, granted, but definitely good enough). Writing something directly in HTML seems absurd today, IMHO. We want higher-level languages, and Texinfo is an excellent example of such a language, at least for most technical manuals. If the Linux community as a whole missed one technical release cycle to instead concentrate on properly documenting what already exists, the effort would pay off in spades for all future releases. I don't see how HTML-only documentation would be an improvement; it would be a huge step back, actually. Regards, Stefano
Re: Question about the return value of 'local'
On 12/14/2012 06:58 PM, Bill Gradwohl wrote: My point was to DESIGN for html and the rich environment it offers, not to try to convert a Model T into a Mercedes. I'm not wild about a wiki either, if its a free for all. If on the other hand, it is a submission platform that gets reviewed and edited by the developers then it's possibly of benefit, especially for examples. The best technical document I ever encountered was the DOS C compiler from Microsoft over 20 years ago. At about 1.5 thick, the book that came with it was excellent. I kept the book long after I ditched the compiler. Every item listed in the index had sample code associated with it that not only showed how to use the item, but also provided examples for the boundary conditions that reinforced what the documentation said. AFAICS, there's nothing in Texinfo preventing a developer from writing such an excellent documentation; what prevents it is typically the fact that writing good documentation is hard, subtly complex, time consuming, and tiring. No silver bullet for that; a tool or a format can only remove the non-essential, mundane difficulties, not the intrinsic ones. Absolutely excellent documentation. It used the KR style but applied it to the entire subroutine library. Regards, Stefano
Question about the return value of 'local'
Hello, I found that the return value of 'local' keyword is counter intuitive when the value of the assignment is an expression returning false. In that case the return value of local is still true. For example: local foo=$(echo bar; false) returns true whereas: foo=$(echo bar; false) returns false, that is removing the 'local' keyword has the opposite behaviour. The help of 'local' is rather obscure about the description on its return value: Returns success unless an invalid option is supplied, an error occurs, or the shell is not executing a function. an error occurs is rather meaningless IMHO. Could anybody explain me why 'local' returns true in this case ? Also I tried to find in the documentation, where the specification of the return value of an asignment is but have failed. Could anybody point me out the location ? Thanks -- Francis
Re: Question about the return value of 'local'
Francis Moreau wrote: I found that the return value of 'local' keyword is counter intuitive when the value of the assignment is an expression returning false. In that case the return value of local is still true. For example: local foo=$(echo bar; false) returns true Yes. The creation of the local variable foo was successful. whereas: foo=$(echo bar; false) returns false, that is removing the 'local' keyword has the opposite behaviour. The local function itself is either there or it isn't. If it is there then the return value is the return from local. If it isn't there then it isn't there and the return value is of whatever you are checking. If the local value is there then you may use it to assign multiple values. How does your thinking change when thinking about having multiple values to local? local v1=true v2=false v3=green v4=42 If the entire operation is successful then it returns 0. If any of the operands fail then it returns non-zero. The help of 'local' is rather obscure about the description on its return value: Returns success unless an invalid option is supplied, an error occurs, or the shell is not executing a function. an error occurs is rather meaningless IMHO. Could anybody explain me why 'local' returns true in this case ? It returns 0 because the local variable was successfully created. Also I tried to find in the documentation, where the specification of the return value of an asignment is but have failed. Could anybody point me out the location ? The bash manual contains this: local [option] [name[=value] ...] For each argument, a local variable named name is created, and assigned value. The option can be any of the options accepted by declare. When local is used within a function, it causes the variable name to have a visible scope restricted to that function and its children. With no operands, local writes a list of local variables to the standard output. It is an error to use local when not within a function. The return status is 0 unless local is used outside a function, an invalid name is supplied, or name is a readonly variable. See also 'export'. Compare and contrast. export [-fn] [name[=word]] ... export -p The supplied names are marked for automatic export to the environment of subsequently executed commands. If the -f option is given, the names refer to functions. If no names are given, or if the -p option is supplied, a list of all names that are exported in this shell is printed. The -n option causes the export property to be removed from each name. If a variable name is followed by =word, the value of the variable is set to word. export returns an exit status of 0 unless an invalid option is encountered, one of the names is not a valid shell variable name, or -f is supplied with a name that is not a function. Bob
Re: Question about the return value of 'local'
Francis Moreau francis.m...@gmail.com writes: The help of 'local' is rather obscure about the description on its return value: Returns success unless an invalid option is supplied, an error occurs, or the shell is not executing a function. an error occurs is rather meaningless IMHO. See the manual for an alternative description: The return status is zero unless `local' is used outside a function, an invalid NAME is supplied, or NAME is a readonly variable. Andreas. -- Andreas Schwab, sch...@linux-m68k.org GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 And now for something completely different.
Re: Question about the return value of 'local'
On Thu, Dec 13, 2012 at 9:44 AM, Bob Proulx b...@proulx.com wrote: Francis Moreau wrote: I found that the return value of 'local' keyword is counter intuitive when the value of the assignment is an expression returning false. In that case the return value of local is still true. For example: local foo=$(echo bar; false) returns true Yes. The creation of the local variable foo was successful. whereas: foo=$(echo bar; false) returns false, that is removing the 'local' keyword has the opposite behaviour. The local function itself is either there or it isn't. If it is there then the return value is the return from local. If it isn't there then it isn't there and the return value is of whatever you are checking. If the local value is there then you may use it to assign multiple values. How does your thinking change when thinking about having multiple values to local? local v1=true v2=false v3=green v4=42 If the entire operation is successful then it returns 0. If any of the operands fail then it returns non-zero. Ok I see, thanks. The help of 'local' is rather obscure about the description on its return value: Returns success unless an invalid option is supplied, an error occurs, or the shell is not executing a function. an error occurs is rather meaningless IMHO. Could anybody explain me why 'local' returns true in this case ? It returns 0 because the local variable was successfully created. Also I tried to find in the documentation, where the specification of the return value of an asignment is but have failed. Could anybody point me out the location ? The bash manual contains this: local [option] [name[=value] ...] Actually I was asking for the case when 'local' is not used: foo=$(echo bar; false) this assignment expression returns false, and I'm wondering where that's documented. Thanks. -- Francis
Re: Question about the return value of 'local'
On Thu, Dec 13, 2012 at 9:44 AM, Andreas Schwab sch...@linux-m68k.org wrote: Francis Moreau francis.m...@gmail.com writes: The help of 'local' is rather obscure about the description on its return value: Returns success unless an invalid option is supplied, an error occurs, or the shell is not executing a function. an error occurs is rather meaningless IMHO. See the manual for an alternative description: The return status is zero unless `local' is used outside a function, an invalid NAME is supplied, or NAME is a readonly variable. I see thanks. Somehow I thought that help(1) would have given nothing more nothing less than what was described in the manual. -- Francis
Re: Question about the return value of 'local'
On 12/13/12 3:56 AM, Francis Moreau wrote: I see thanks. Somehow I thought that help(1) would have given nothing more nothing less than what was described in the manual. `help' is a quick reference -- a handy shortcut. The authoritative documentation is still the manual page and texinfo document. I'll add something to the effect that `error' means `variable assignment error'. Chet -- ``The lyf so short, the craft so long to lerne.'' - Chaucer ``Ars longa, vita brevis'' - Hippocrates Chet Ramey, ITS, CWRUc...@case.eduhttp://cnswww.cns.cwru.edu/~chet/
Re: Question about the return value of 'local'
Actually I was asking for the case when 'local' is not used: foo=$(echo bar; false) this assignment expression returns false, and I'm wondering where that's documented. Look in the SIMPLE COMMAND EXPANSION section of the man page: If there is a command name left after expansion, execution proceeds as described below. Otherwise, the command exits. If one of the expan- sions contained a command substitution, the exit status of the command is the exit status of the last command substitution performed. If there were no command substitutions, the command exits with a status of zero. It's the final paragraph. Chet -- ``The lyf so short, the craft so long to lerne.'' - Chaucer ``Ars longa, vita brevis'' - Hippocrates Chet Ramey, ITS, CWRUc...@case.eduhttp://cnswww.cns.cwru.edu/~chet/
Re: Question about the return value of 'local'
On Thu, Dec 13, 2012 at 3:25 PM, Chet Ramey chet.ra...@case.edu wrote: Actually I was asking for the case when 'local' is not used: foo=$(echo bar; false) this assignment expression returns false, and I'm wondering where that's documented. Look in the SIMPLE COMMAND EXPANSION section of the man page: If there is a command name left after expansion, execution proceeds as described below. Otherwise, the command exits. If one of the expan- sions contained a command substitution, the exit status of the command is the exit status of the last command substitution performed. If there were no command substitutions, the command exits with a status of zero. It's the final paragraph. Thanks you. -- Francis
Re: Question about the return value of 'local'
On Thu, Dec 13, 2012 at 3:19 PM, Chet Ramey chet.ra...@case.edu wrote: On 12/13/12 3:56 AM, Francis Moreau wrote: I see thanks. Somehow I thought that help(1) would have given nothing more nothing less than what was described in the manual. `help' is a quick reference -- a handy shortcut. The authoritative documentation is still the manual page and texinfo document. Then maybe an option should be added to 'local' to display the full description that one can get from the manual, or maybe change the behaviour of '-m' switch ? Thanks.
