sh.1: wordsmith the section about getopts
ClosedPublic
Actions

bin/sh/sh.1
2358–2359	might even consider removing the "POSIX" part here completely.
2390	"unspecified" and "not specified" seem a bit vague to me; perhaps "not in .Va optstring" is better?

pstef added inline comments.Sat, Feb 22, 5:52 PM

bin/sh/sh.1
2390	I don't disagree and I'm open to suggestions, but FWIW, POSIX uses simiar wording: An option, specified or unspecified by optstring, was found. Although they do specify what it is that specifies. I'll wait and collect more suggestions, then try to make further improvements

imp added inline comments.Sat, Feb 22, 5:56 PM

bin/sh/sh.1
2390	this suggests "for an unknown option" to be easier to approach but jilles' is more correct and useful once you're past the basics.

getopts optstring var
        Parse command-line options and arguments.  The first argument
        optstring should be a series of letters, each possibly followed
        by a colon which indicates that the option takes an argument.
        The specified variable var is set to the parsed option.  The
        index of the next argument is placed into the shell variable
        OPTIND.  If an option takes an argument, it is placed into the
        shell variable OPTARG.

        If the found character is not specified by optstring or if it is
        missing a required argument, the option is considered invalid
        and:

              If the first character of optstring is not a colon then
              OPTARG is unset, var is set to ‘?’ and a diagnostic message
              is written to stderr.

              If the first character of optstring is a colon then OPTARG
              is set to the the option character found, var is set to ‘:’
              when a required argument is missing or to ‘?’ when the
              option was not specified by optstring, and no diagnostic
              message is written to stderr.

        getopts returns a false value (1) when it encounters the end of
        the options.  A new set of arguments may be parsed by assigning
        OPTIND=1.  The POSIX getopts command deprecates the older
        getopt(1) command.

ziaee added inline comments.Sun, Feb 23, 10:20 PM

bin/sh/sh.1
2388	stderr has a manual, you could optionally crossreference to that if you want.

ziaee added inline comments.Sun, Feb 23, 10:21 PM

bin/sh/sh.1
2383	These are environment variables? I think Ev is a special macro for environment variables.

pstef marked 3 inline comments as done.Tue, Feb 25, 4:34 PM

pstef added inline comments.

bin/sh/sh.1
2358–2359	I moved it to to the sentence about "POSIX getopts" obsoleting geptopt. I feel that was the intent of the original phrasing. I kept the two pieces of information, but moved it to the very end of this section. I don't think we need or want to remove it altogether.
2383	I think I can agree, I can change that before committing if I don't forget.
2388	I think it depends on what makes a term worth of cross-referencing. I think if someone is reading sh.1, they already know perfectly well what stderr is, so I wouldn't "fix what isn't broken". But if there is a good reason to cross-refer it and I just don't know it, I have no strong opinions either way.

ziaee added inline comments.Tue, Feb 25, 6:34 PM

bin/sh/sh.1
2388	I think if someone is reading sh.1, they already know perfectly well what stderr is. Please consider that this is unlikely today for the first time reader in the current climate. I am 29. I first installed FreeBSD on my parents old computer when I was 12. I learned what sh was long before stderr because informal learning is via "what's this?". The default MOTD, the only instruction the system gives a new user, does say "Introduction to manual pages:" at the bottom. On the discord we have a steady stream of such kids.