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
