Re: shell manpage tweaks wrt getopt
Christian Weisgerber wrote: > Marc Espie: > > > I would also actually be fairly happy if we changed drastically the way > > sh(1) and ksh(1) look. To me, sh(1) should be the (more or less) standard > > shell documentation, AND ksh(1) should contain the differences/extensions. > > I think that is a terrible idea. Historically the tcsh(1) man page > was like this: only document the extensions to csh, point to csh(1) > for the rest. > > This only makes sense for people who already fully know the base > man page. If you don't, you now have to go back and forth between > two man pages to figure out things. > > Eventually, the tcsh man page was overhauled and now describes the > whole shell, which was a huge improvement in my book. I agree with that. Solving the problem by changing "I have to look at 2 pages" into "I have to look at 2 pages, but interpret the results differently" is not great. Seperate coherent explanations are the best outcome, if it can be done.
Re: shell manpage tweaks wrt getopt
Marc Espie: > I would also actually be fairly happy if we changed drastically the way > sh(1) and ksh(1) look. To me, sh(1) should be the (more or less) standard > shell documentation, AND ksh(1) should contain the differences/extensions. I think that is a terrible idea. Historically the tcsh(1) man page was like this: only document the extensions to csh, point to csh(1) for the rest. This only makes sense for people who already fully know the base man page. If you don't, you now have to go back and forth between two man pages to figure out things. Eventually, the tcsh man page was overhauled and now describes the whole shell, which was a huge improvement in my book. -- Christian "naddy" Weisgerber na...@mips.inka.de
Re: shell manpage tweaks wrt getopt
On Sat, May 01, 2021 at 04:33:08PM +0200, Christian Weisgerber wrote: > Jason McIntyre: > > > - i'm ok with the getopt.1 and ksh.1 parts > > - i'm not ok with the addition to sh.1 > > > > no one has really given a good reason why they think it should go into > > sh.1. i've given a few why i think it should not. > > My understanding is that sh.1 is a subset of ksh.1, describing the > POSIX-standardized functionality. Am I wrong? > that's correct. > ksh.1 has very little in the way of examples, but I think figuring > out the correct getopts idiom is difficult enough to warrant an > example. > > The problem is that if I'm trying to write a portable shell script, > I will refer to sh.1. I will not check ksh.1 for examples. > > But since you are the principal author of sh.1, I'm certainly > deferring to your judgment. > ok, your point is a good one too. i had been trying to keep sh(1) trim. i think the general idea is if you need more of an explanation, it's in ksh(1). but on balance i guess i'm ok with the addition to sh.1 too. jmc
Re: shell manpage tweaks wrt getopt
Jason McIntyre: > - i'm ok with the getopt.1 and ksh.1 parts > - i'm not ok with the addition to sh.1 > > no one has really given a good reason why they think it should go into > sh.1. i've given a few why i think it should not. My understanding is that sh.1 is a subset of ksh.1, describing the POSIX-standardized functionality. Am I wrong? ksh.1 has very little in the way of examples, but I think figuring out the correct getopts idiom is difficult enough to warrant an example. The problem is that if I'm trying to write a portable shell script, I will refer to sh.1. I will not check ksh.1 for examples. But since you are the principal author of sh.1, I'm certainly deferring to your judgment. -- Christian "naddy" Weisgerber na...@mips.inka.de
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 04:42:12PM +0200, Marc Espie wrote: > On Fri, Apr 30, 2021 at 03:28:42PM +0100, Jason McIntyre wrote: > > my argument boils down to: sh(1) is small and has no examples. adding > > them changes the (deliberate) nature of the page. ksh(1) is what you > > read when you can;t get to sleep. > > > > why is it wrong to add your example to ksh(1)? why would that leave the > > reader disadvantaged? > > I would also actually be fairly happy if we changed drastically the way > sh(1) and ksh(1) look. To me, sh(1) should be the (more or less) standard > shell documentation, AND ksh(1) should contain the differences/extensions. > > Occasionally useful when you want to write scripts that are usable outside > of OpenBSD with /bin/sh as a tagline. > > Not very likely to happen. > hi. there's a few possibilities with what to do with sh.1 and ksh.1, but i guess none of them are fully satisfactory. i suspect if we picked out the parts in ksh.1 already covered by sh.1 it would leave a not very helpful page. and it would take a lot of picking... jmc
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 04:54:57PM +0200, Christian Weisgerber wrote: > Marc Espie: > > > Until a patch from naddy, I wasn't even aware of getopts in sh(1) > > Let's start the discussion with this instead. > > This puts the deprecation notice in getopt.1 in a prominent place, > and uses the same snippet in sh.1 and ksh.1. > morning. - i'm ok with the getopt.1 and ksh.1 parts - i'm not ok with the addition to sh.1 no one has really given a good reason why they think it should go into sh.1. i've given a few why i think it should not. jmc > Index: bin/ksh/ksh.1 > === > RCS file: /cvs/src/bin/ksh/ksh.1,v > retrieving revision 1.214 > diff -u -p -r1.214 ksh.1 > --- bin/ksh/ksh.1 11 Mar 2021 07:04:12 - 1.214 > +++ bin/ksh/ksh.1 30 Apr 2021 14:40:52 - > @@ -3219,6 +3219,25 @@ resetting > .Ev OPTIND , > may lead to unexpected results. > .Pp > +The following code fragment shows how one might process the arguments > +for a command that can take the option > +.Fl a > +and the option > +.Fl o , > +which requires an argument. > +.Bd -literal -offset indent > +while getopts ao: name > +do > + case $name in > + a) flag=1 ;; > + o) oarg=$OPTARG ;; > + ?) echo "Usage: ..."; exit 2 ;; > + esac > +done > +shift $(($OPTIND - 1)) > +echo "Non-option arguments: " "$@" > +.Ed > +.Pp > .It Xo > .Ic hash > .Op Fl r > Index: bin/ksh/sh.1 > === > RCS file: /cvs/src/bin/ksh/sh.1,v > retrieving revision 1.152 > diff -u -p -r1.152 sh.1 > --- bin/ksh/sh.1 22 May 2019 15:23:23 - 1.152 > +++ bin/ksh/sh.1 30 Apr 2021 14:45:22 - > @@ -508,6 +508,25 @@ is a colon, > .Ev OPTARG > is set to the unsupported option, > otherwise an error message is displayed. > +.Pp > +The following code fragment shows how one might process the arguments > +for a command that can take the option > +.Fl a > +and the option > +.Fl o , > +which requires an argument. > +.Bd -literal -offset indent > +while getopts ao: name > +do > + case $name in > + a) flag=1 ;; > + o) oarg=$OPTARG ;; > + ?) echo "Usage: ..."; exit 2 ;; > + esac > +done > +shift $(($OPTIND - 1)) > +echo "Non-option arguments: " "$@" > +.Ed > .It Ic hash Op Fl r | Ar utility > Add > .Ar utility > Index: usr.bin/getopt/getopt.1 > === > RCS file: /cvs/src/usr.bin/getopt/getopt.1,v > retrieving revision 1.19 > diff -u -p -r1.19 getopt.1 > --- usr.bin/getopt/getopt.1 16 Mar 2018 16:58:26 - 1.19 > +++ usr.bin/getopt/getopt.1 30 Apr 2021 14:25:17 - > @@ -14,6 +14,13 @@ > .Ar optstring > .Va $* > .Sh DESCRIPTION > +The > +.Nm > +utility cannot handle option arguments containing whitespace; > +consider using the standard > +.Ic getopts > +shell built-in instead. > +.Pp > .Nm > is used to break up options in command lines for easy parsing by > shell procedures, and to check for legal options. > > -- > Christian "naddy" Weisgerber na...@mips.inka.de >
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 04:54:57PM +0200, Christian Weisgerber wrote: > Marc Espie: > > > Until a patch from naddy, I wasn't even aware of getopts in sh(1) > > Let's start the discussion with this instead. > > This puts the deprecation notice in getopt.1 in a prominent place, > and uses the same snippet in sh.1 and ksh.1. > > Index: bin/ksh/ksh.1 > === > RCS file: /cvs/src/bin/ksh/ksh.1,v > retrieving revision 1.214 > diff -u -p -r1.214 ksh.1 > --- bin/ksh/ksh.1 11 Mar 2021 07:04:12 - 1.214 > +++ bin/ksh/ksh.1 30 Apr 2021 14:40:52 - > @@ -3219,6 +3219,25 @@ resetting > .Ev OPTIND , > may lead to unexpected results. > .Pp > +The following code fragment shows how one might process the arguments > +for a command that can take the option > +.Fl a > +and the option > +.Fl o , > +which requires an argument. > +.Bd -literal -offset indent > +while getopts ao: name > +do > + case $name in > + a) flag=1 ;; > + o) oarg=$OPTARG ;; > + ?) echo "Usage: ..."; exit 2 ;; > + esac > +done > +shift $(($OPTIND - 1)) > +echo "Non-option arguments: " "$@" > +.Ed > +.Pp > .It Xo > .Ic hash > .Op Fl r > Index: bin/ksh/sh.1 > === > RCS file: /cvs/src/bin/ksh/sh.1,v > retrieving revision 1.152 > diff -u -p -r1.152 sh.1 > --- bin/ksh/sh.1 22 May 2019 15:23:23 - 1.152 > +++ bin/ksh/sh.1 30 Apr 2021 14:45:22 - > @@ -508,6 +508,25 @@ is a colon, > .Ev OPTARG > is set to the unsupported option, > otherwise an error message is displayed. > +.Pp > +The following code fragment shows how one might process the arguments > +for a command that can take the option > +.Fl a > +and the option > +.Fl o , > +which requires an argument. > +.Bd -literal -offset indent > +while getopts ao: name > +do > + case $name in > + a) flag=1 ;; > + o) oarg=$OPTARG ;; > + ?) echo "Usage: ..."; exit 2 ;; > + esac > +done > +shift $(($OPTIND - 1)) > +echo "Non-option arguments: " "$@" > +.Ed > .It Ic hash Op Fl r | Ar utility > Add > .Ar utility > Index: usr.bin/getopt/getopt.1 > === > RCS file: /cvs/src/usr.bin/getopt/getopt.1,v > retrieving revision 1.19 > diff -u -p -r1.19 getopt.1 > --- usr.bin/getopt/getopt.1 16 Mar 2018 16:58:26 - 1.19 > +++ usr.bin/getopt/getopt.1 30 Apr 2021 14:25:17 - > @@ -14,6 +14,13 @@ > .Ar optstring > .Va $* > .Sh DESCRIPTION > +The > +.Nm > +utility cannot handle option arguments containing whitespace; > +consider using the standard > +.Ic getopts > +shell built-in instead. > +.Pp > .Nm > is used to break up options in command lines for easy parsing by > shell procedures, and to check for legal options. > Sure, works for me.
Re: shell manpage tweaks wrt getopt
Marc Espie: > Until a patch from naddy, I wasn't even aware of getopts in sh(1) Let's start the discussion with this instead. This puts the deprecation notice in getopt.1 in a prominent place, and uses the same snippet in sh.1 and ksh.1. Index: bin/ksh/ksh.1 === RCS file: /cvs/src/bin/ksh/ksh.1,v retrieving revision 1.214 diff -u -p -r1.214 ksh.1 --- bin/ksh/ksh.1 11 Mar 2021 07:04:12 - 1.214 +++ bin/ksh/ksh.1 30 Apr 2021 14:40:52 - @@ -3219,6 +3219,25 @@ resetting .Ev OPTIND , may lead to unexpected results. .Pp +The following code fragment shows how one might process the arguments +for a command that can take the option +.Fl a +and the option +.Fl o , +which requires an argument. +.Bd -literal -offset indent +while getopts ao: name +do + case $name in + a) flag=1 ;; + o) oarg=$OPTARG ;; + ?) echo "Usage: ..."; exit 2 ;; + esac +done +shift $(($OPTIND - 1)) +echo "Non-option arguments: " "$@" +.Ed +.Pp .It Xo .Ic hash .Op Fl r Index: bin/ksh/sh.1 === RCS file: /cvs/src/bin/ksh/sh.1,v retrieving revision 1.152 diff -u -p -r1.152 sh.1 --- bin/ksh/sh.122 May 2019 15:23:23 - 1.152 +++ bin/ksh/sh.130 Apr 2021 14:45:22 - @@ -508,6 +508,25 @@ is a colon, .Ev OPTARG is set to the unsupported option, otherwise an error message is displayed. +.Pp +The following code fragment shows how one might process the arguments +for a command that can take the option +.Fl a +and the option +.Fl o , +which requires an argument. +.Bd -literal -offset indent +while getopts ao: name +do + case $name in + a) flag=1 ;; + o) oarg=$OPTARG ;; + ?) echo "Usage: ..."; exit 2 ;; + esac +done +shift $(($OPTIND - 1)) +echo "Non-option arguments: " "$@" +.Ed .It Ic hash Op Fl r | Ar utility Add .Ar utility Index: usr.bin/getopt/getopt.1 === RCS file: /cvs/src/usr.bin/getopt/getopt.1,v retrieving revision 1.19 diff -u -p -r1.19 getopt.1 --- usr.bin/getopt/getopt.1 16 Mar 2018 16:58:26 - 1.19 +++ usr.bin/getopt/getopt.1 30 Apr 2021 14:25:17 - @@ -14,6 +14,13 @@ .Ar optstring .Va $* .Sh DESCRIPTION +The +.Nm +utility cannot handle option arguments containing whitespace; +consider using the standard +.Ic getopts +shell built-in instead. +.Pp .Nm is used to break up options in command lines for easy parsing by shell procedures, and to check for legal options. -- Christian "naddy" Weisgerber na...@mips.inka.de
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 03:28:42PM +0100, Jason McIntyre wrote: > my argument boils down to: sh(1) is small and has no examples. adding > them changes the (deliberate) nature of the page. ksh(1) is what you > read when you can;t get to sleep. > > why is it wrong to add your example to ksh(1)? why would that leave the > reader disadvantaged? I would also actually be fairly happy if we changed drastically the way sh(1) and ksh(1) look. To me, sh(1) should be the (more or less) standard shell documentation, AND ksh(1) should contain the differences/extensions. Occasionally useful when you want to write scripts that are usable outside of OpenBSD with /bin/sh as a tagline. Not very likely to happen.
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 03:28:42PM +0100, Jason McIntyre wrote: > On Fri, Apr 30, 2021 at 04:07:55PM +0200, Marc Espie wrote: > > On Fri, Apr 30, 2021 at 02:44:01PM +0100, Jason McIntyre wrote: > > > On Fri, Apr 30, 2021 at 11:54:16AM +0200, Marc Espie wrote: > > > > Until a patch from naddy, I wasn't even aware of getopts in sh(1) > > > > > > > > Unless I made some mistakes, this translates the example in getopt(1) > > > > manpage. > > > > > > > > It's likely some stronger wording might be adequate, I suspect some > > > > of the BUGS section in getopt(1) does not apply to the sh(1) built-in. > > > > > > > > > > hi marc. > > > > > > is there a reason why you wanted the example in sh(1) and not ksh(1)? > > > > > > i think the overall structure is that ksh(1) is the full monty, whereas > > > sh(1) is really a simplified reference to which bits you can use if you > > > want to keep things portable. to that end there aren;t really any > > > examples in sh(1). i felt that having a short page was more beneficial > > > in the long run (especially since we already have a full on ksh(1) > > > page). > > > > > > having said that, getopts is one of those things that you really won;t > > > get from reading descriptive text. an example is definitely helpful. so > > > i'd not be dead against it in sh(1) if there's a good reason. > > > > > > there's also the possibility that it may be more helpful to show it in > > > getopts(1) itself? i guess there are pros and cons there too. > > > > > > jmc > > > > getopts(1) is not a separate command. Having built-ins in their separate > > manpage would be a definitive departure from what we've always done. > > > > i'm not advocating that. ah i think i see the misunderstanding - when i > said it could "show it in getopts(1) itself" i meant getopt(1) of > course. i was not proposing we create a getopts(1) page! sorry about > that! > > > Some linux distributions do have some of the built-ins in their own > > man pages so that they're easier to find, which makes all kind of sense > > to me, even though it's pedantically incorrect. I think it would help, > > but you are going to ruffle all kinds of feathers. > > > > where a standalone command and sh builtin co-exist (like kill) we > tend to note in STANDARDS for that command that a shell version > exists. in this case though, getopt(1) just references sh(1): we > couldn;t add a pointer to STANDARDS (since it doesn't have one) so > i think we just nudged SEE ALSO. it could be that we should be more > upfront in getopt(1) about the shell built-in getopts. > > > > > Also, getopts is POSIX. Documenting it in ksh would send the wrong signal > > in my opinion (but if I replace getopt with getopts, am I still writing > > a standard shell script). > > > > well, getopts is already documented in ksh(1). along with all the other > builtins mandated by posix. so i can;t see how it would "send the wrong > signal". > > my argument boils down to: sh(1) is small and has no examples. adding > them changes the (deliberate) nature of the page. ksh(1) is what you > read when you can;t get to sleep. > > why is it wrong to add your example to ksh(1)? why would that leave the > reader disadvantaged? > > > That said, we can easily lift the exact same paragraph in both manpages. > > > > i don;t like that idea. these pages are already big enough, and duplicate text > always, at some point, goes out of sync. > > jmc > > My diff includes a nudge from getopt(1) towards getopts. Now, it needs to be 100% explicit that getopts is now POSIX standard, and thus a perfectly good (somewhat portable) replacement.
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 04:07:55PM +0200, Marc Espie wrote: > On Fri, Apr 30, 2021 at 02:44:01PM +0100, Jason McIntyre wrote: > > On Fri, Apr 30, 2021 at 11:54:16AM +0200, Marc Espie wrote: > > > Until a patch from naddy, I wasn't even aware of getopts in sh(1) > > > > > > Unless I made some mistakes, this translates the example in getopt(1) > > > manpage. > > > > > > It's likely some stronger wording might be adequate, I suspect some > > > of the BUGS section in getopt(1) does not apply to the sh(1) built-in. > > > > > > > hi marc. > > > > is there a reason why you wanted the example in sh(1) and not ksh(1)? > > > > i think the overall structure is that ksh(1) is the full monty, whereas > > sh(1) is really a simplified reference to which bits you can use if you > > want to keep things portable. to that end there aren;t really any > > examples in sh(1). i felt that having a short page was more beneficial > > in the long run (especially since we already have a full on ksh(1) > > page). > > > > having said that, getopts is one of those things that you really won;t > > get from reading descriptive text. an example is definitely helpful. so > > i'd not be dead against it in sh(1) if there's a good reason. > > > > there's also the possibility that it may be more helpful to show it in > > getopts(1) itself? i guess there are pros and cons there too. > > > > jmc > > getopts(1) is not a separate command. Having built-ins in their separate > manpage would be a definitive departure from what we've always done. > i'm not advocating that. ah i think i see the misunderstanding - when i said it could "show it in getopts(1) itself" i meant getopt(1) of course. i was not proposing we create a getopts(1) page! sorry about that! > Some linux distributions do have some of the built-ins in their own > man pages so that they're easier to find, which makes all kind of sense > to me, even though it's pedantically incorrect. I think it would help, > but you are going to ruffle all kinds of feathers. > where a standalone command and sh builtin co-exist (like kill) we tend to note in STANDARDS for that command that a shell version exists. in this case though, getopt(1) just references sh(1): we couldn;t add a pointer to STANDARDS (since it doesn't have one) so i think we just nudged SEE ALSO. it could be that we should be more upfront in getopt(1) about the shell built-in getopts. > > Also, getopts is POSIX. Documenting it in ksh would send the wrong signal > in my opinion (but if I replace getopt with getopts, am I still writing > a standard shell script). > well, getopts is already documented in ksh(1). along with all the other builtins mandated by posix. so i can;t see how it would "send the wrong signal". my argument boils down to: sh(1) is small and has no examples. adding them changes the (deliberate) nature of the page. ksh(1) is what you read when you can;t get to sleep. why is it wrong to add your example to ksh(1)? why would that leave the reader disadvantaged? > That said, we can easily lift the exact same paragraph in both manpages. > i don;t like that idea. these pages are already big enough, and duplicate text always, at some point, goes out of sync. jmc
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 02:44:01PM +0100, Jason McIntyre wrote: > On Fri, Apr 30, 2021 at 11:54:16AM +0200, Marc Espie wrote: > > Until a patch from naddy, I wasn't even aware of getopts in sh(1) > > > > Unless I made some mistakes, this translates the example in getopt(1) > > manpage. > > > > It's likely some stronger wording might be adequate, I suspect some > > of the BUGS section in getopt(1) does not apply to the sh(1) built-in. > > > > hi marc. > > is there a reason why you wanted the example in sh(1) and not ksh(1)? > > i think the overall structure is that ksh(1) is the full monty, whereas > sh(1) is really a simplified reference to which bits you can use if you > want to keep things portable. to that end there aren;t really any > examples in sh(1). i felt that having a short page was more beneficial > in the long run (especially since we already have a full on ksh(1) > page). > > having said that, getopts is one of those things that you really won;t > get from reading descriptive text. an example is definitely helpful. so > i'd not be dead against it in sh(1) if there's a good reason. > > there's also the possibility that it may be more helpful to show it in > getopts(1) itself? i guess there are pros and cons there too. > > jmc getopts(1) is not a separate command. Having built-ins in their separate manpage would be a definitive departure from what we've always done. Some linux distributions do have some of the built-ins in their own man pages so that they're easier to find, which makes all kind of sense to me, even though it's pedantically incorrect. I think it would help, but you are going to ruffle all kinds of feathers. Also, getopts is POSIX. Documenting it in ksh would send the wrong signal in my opinion (but if I replace getopt with getopts, am I still writing a standard shell script). That said, we can easily lift the exact same paragraph in both manpages.
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 11:54:16AM +0200, Marc Espie wrote: > Until a patch from naddy, I wasn't even aware of getopts in sh(1) > > Unless I made some mistakes, this translates the example in getopt(1) > manpage. > > It's likely some stronger wording might be adequate, I suspect some > of the BUGS section in getopt(1) does not apply to the sh(1) built-in. > hi marc. is there a reason why you wanted the example in sh(1) and not ksh(1)? i think the overall structure is that ksh(1) is the full monty, whereas sh(1) is really a simplified reference to which bits you can use if you want to keep things portable. to that end there aren;t really any examples in sh(1). i felt that having a short page was more beneficial in the long run (especially since we already have a full on ksh(1) page). having said that, getopts is one of those things that you really won;t get from reading descriptive text. an example is definitely helpful. so i'd not be dead against it in sh(1) if there's a good reason. there's also the possibility that it may be more helpful to show it in getopts(1) itself? i guess there are pros and cons there too. jmc > Index: bin/ksh/sh.1 > === > RCS file: /cvs/src/bin/ksh/sh.1,v > retrieving revision 1.152 > diff -u -p -r1.152 sh.1 > --- bin/ksh/sh.1 22 May 2019 15:23:23 - 1.152 > +++ bin/ksh/sh.1 30 Apr 2021 09:51:42 - > @@ -508,6 +508,26 @@ is a colon, > .Ev OPTARG > is set to the unsupported option, > otherwise an error message is displayed. > +.Pp > +The following example has identical functionality to the > +example in > +.Xr getopt 1 . > +.Bd -literal -offset indent > +while getopts abo: name > +do > + case "$name" > + in > + a|b) > + flag="-$name";; > + o) > + oarg="$OPTARG";; > + ?) > + echo "Usage: ..." > + exit 2 > + ;; > + esac > +done > +.Ed > .It Ic hash Op Fl r | Ar utility > Add > .Ar utility > Index: usr.bin/getopt/getopt.1 > === > RCS file: /cvs/src/usr.bin/getopt/getopt.1,v > retrieving revision 1.19 > diff -u -p -r1.19 getopt.1 > --- usr.bin/getopt/getopt.1 16 Mar 2018 16:58:26 - 1.19 > +++ usr.bin/getopt/getopt.1 30 Apr 2021 09:51:42 - > @@ -54,7 +54,7 @@ which requires an argument. > args=`getopt abo: $*` > if [ $? -ne 0 ] > then > - echo 'Usage: ...' > + echo "Usage: ..." > exit 2 > fi > set -- $args > @@ -79,6 +79,11 @@ cmd -a -o arg file file > cmd -oarg -a file file > cmd -a -oarg -- file file > .Ed > +Note that > +.Xr sh 1 > +offers the > +.Ic getopts > +built-in with a simpler usage. > .Sh DIAGNOSTICS > .Nm > prints an error message on the standard error output when it >
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 12:14:26PM BST, Marc Espie wrote: > On Fri, Apr 30, 2021 at 12:03:00PM +0100, Raf Czlonka wrote: > > Hi Mark, > > > > You and me both ;^) > > > > Until recently, I thought that getopt(1) was POSIX, whereas it is > > in fact getopts(1), and it is not a shell built-in there, but a > > utility[0]. > > Nope, it is a shell built-in... the "wording" of posix is a bit strange, > but you can't possibly set variables inside the shell from an outside > command. > > It has the same status as read. You're obviously right - the "utility" got me confused :^P R.
Re: shell manpage tweaks wrt getopt
On Fri, Apr 30, 2021 at 12:03:00PM +0100, Raf Czlonka wrote: > Hi Mark, > > You and me both ;^) > > Until recently, I thought that getopt(1) was POSIX, whereas it is > in fact getopts(1), and it is not a shell built-in there, but a > utility[0]. Nope, it is a shell built-in... the "wording" of posix is a bit strange, but you can't possibly set variables inside the shell from an outside command. It has the same status as read. and I haven't looked too closely, but I would assume most of the BUG in getopt(1) do not apply to getopts
Re: shell manpage tweaks wrt getopt
Hi Mark, You and me both ;^) Until recently, I thought that getopt(1) was POSIX, whereas it is in fact getopts(1), and it is not a shell built-in there, but a utility[0]. [0] https://pubs.opengroup.org/onlinepubs/9699919799/utilities/getopts.html Cheers, Raf On Fri, Apr 30, 2021 at 10:54:16AM BST, Marc Espie wrote: > Until a patch from naddy, I wasn't even aware of getopts in sh(1) > > Unless I made some mistakes, this translates the example in getopt(1) > manpage. > > It's likely some stronger wording might be adequate, I suspect some > of the BUGS section in getopt(1) does not apply to the sh(1) built-in. > > Index: bin/ksh/sh.1 > === > RCS file: /cvs/src/bin/ksh/sh.1,v > retrieving revision 1.152 > diff -u -p -r1.152 sh.1 > --- bin/ksh/sh.1 22 May 2019 15:23:23 - 1.152 > +++ bin/ksh/sh.1 30 Apr 2021 09:51:42 - > @@ -508,6 +508,26 @@ is a colon, > .Ev OPTARG > is set to the unsupported option, > otherwise an error message is displayed. > +.Pp > +The following example has identical functionality to the > +example in > +.Xr getopt 1 . > +.Bd -literal -offset indent > +while getopts abo: name > +do > + case "$name" > + in > + a|b) > + flag="-$name";; > + o) > + oarg="$OPTARG";; > + ?) > + echo "Usage: ..." > + exit 2 > + ;; > + esac > +done > +.Ed > .It Ic hash Op Fl r | Ar utility > Add > .Ar utility > Index: usr.bin/getopt/getopt.1 > === > RCS file: /cvs/src/usr.bin/getopt/getopt.1,v > retrieving revision 1.19 > diff -u -p -r1.19 getopt.1 > --- usr.bin/getopt/getopt.1 16 Mar 2018 16:58:26 - 1.19 > +++ usr.bin/getopt/getopt.1 30 Apr 2021 09:51:42 - > @@ -54,7 +54,7 @@ which requires an argument. > args=`getopt abo: $*` > if [ $? -ne 0 ] > then > - echo 'Usage: ...' > + echo "Usage: ..." > exit 2 > fi > set -- $args > @@ -79,6 +79,11 @@ cmd -a -o arg file file > cmd -oarg -a file file > cmd -a -oarg -- file file > .Ed > +Note that > +.Xr sh 1 > +offers the > +.Ic getopts > +built-in with a simpler usage. > .Sh DIAGNOSTICS > .Nm > prints an error message on the standard error output when it >
shell manpage tweaks wrt getopt
Until a patch from naddy, I wasn't even aware of getopts in sh(1) Unless I made some mistakes, this translates the example in getopt(1) manpage. It's likely some stronger wording might be adequate, I suspect some of the BUGS section in getopt(1) does not apply to the sh(1) built-in. Index: bin/ksh/sh.1 === RCS file: /cvs/src/bin/ksh/sh.1,v retrieving revision 1.152 diff -u -p -r1.152 sh.1 --- bin/ksh/sh.122 May 2019 15:23:23 - 1.152 +++ bin/ksh/sh.130 Apr 2021 09:51:42 - @@ -508,6 +508,26 @@ is a colon, .Ev OPTARG is set to the unsupported option, otherwise an error message is displayed. +.Pp +The following example has identical functionality to the +example in +.Xr getopt 1 . +.Bd -literal -offset indent +while getopts abo: name +do + case "$name" + in + a|b) + flag="-$name";; + o) + oarg="$OPTARG";; + ?) + echo "Usage: ..." + exit 2 + ;; + esac +done +.Ed .It Ic hash Op Fl r | Ar utility Add .Ar utility Index: usr.bin/getopt/getopt.1 === RCS file: /cvs/src/usr.bin/getopt/getopt.1,v retrieving revision 1.19 diff -u -p -r1.19 getopt.1 --- usr.bin/getopt/getopt.1 16 Mar 2018 16:58:26 - 1.19 +++ usr.bin/getopt/getopt.1 30 Apr 2021 09:51:42 - @@ -54,7 +54,7 @@ which requires an argument. args=`getopt abo: $*` if [ $? -ne 0 ] then - echo 'Usage: ...' + echo "Usage: ..." exit 2 fi set -- $args @@ -79,6 +79,11 @@ cmd -a -o arg file file cmd -oarg -a file file cmd -a -oarg -- file file .Ed +Note that +.Xr sh 1 +offers the +.Ic getopts +built-in with a simpler usage. .Sh DIAGNOSTICS .Nm prints an error message on the standard error output when it
