Jari Aalto <jari.aalto@xxxxxxxxx> writes: > * Sat 2008-02-02 Jakub Narebski <jnareb@xxxxxxxxx> > * Message-Id: m3prvf7ku2.fsf@xxxxxxxxxxxxxxxxxxxxx >>>>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html >>> >>> 4. Frequently, names of parameters that _require_ substitution(...) >>> >>> <parameter name> >> >> Excuse me, but item is "required" if it is not marked (...) >> Angle brackets does not mean required parameters. Please read >> carefully; they denote parameters which _require substitution_ (note >> those _two_ words together), i.e. parameters that the user need to >> replace with appropriate input. > > We're talking about the same subject. You emphasize the "substitution" > aspect, which by nature of the context, is inherently present. If you > read your paragraph, you also conclude "required" -- which I emphasised > initially. No, I would not. The fact that the parameter _requires substitution_ (is placeholder) is orthogonal (independent) of the fact if the parameter is required or optional. Angle brackets (and italic or underline) means "placeholder", while lack of angle brackets (and bold) means "literal". Square brackets means "optional", while lack of brackets means "required" > SYNOPSIS syntax: > > command option > > Is inherently same as by spelling it more stronger: > > command <option> > > But different from > > command "option" I would say that in command option the 'option' string is literal, while in command <option> you have to substitute actual option in the place of '<option>'. I don't think that "option" for literals is used in SYNOPSIS in manpages, even if this notation is used elsewhere (BNF, RFC). >>>> Note that in the POSIX/SUSV below parentheses / curly braces are not >>>> mentioned. >>> >>> True. The precedence of curlies has however been set long ago in >>> software books and in other Unix manual pages. >> >> I have checked a bit of manual pages (in Linux), and only very few use >> this convention. Do you have any statistics? > > If you have ever skimmed Unix program book manuals, say before Linux, in > the Unix era, the industry quite frequently used angle curlies: > > command [<options>] {save|load} >From what I can see in Linux manuals usually this is dealt by either relying on generic placeholders, and describing optional parts in detailed description, e.g. tar <operation> [options] or by splitting synopsis into separate lines, each line dealing with alternate syntax, e.g. install [OPTION]... SOURCE DEST (1st format) install [OPTION]... SOURCE... DIRECTORY (2nd format) install -d [OPTION]... DIRECTORY... (3rd format) But in some cases using alternates which are not optional (i.e. not [ A | B | C ]) is a better solution. In some cases grouping is natural and does not need delimiters, for example "--opt=A|B", but in some cases delimiters are required, either "(-d | -D)" or "{-d | -D}" > Even today the braces are used to say "you must choose". E.g. in Oracle's > SQL manuals. This is quite self explanatory for the basic SQL: > > SELECT [DISTINCT] {*, column [AS ["<alias>"]], ...} > FROM <table> > ; I'm just more used to "(a | b)" from regular expressions, and AFAIK also BNFs, and "{a,b}", with comma ',' instead of vertical bar '|' to denote alternates (mutually exclusive parts), like in [some] shell globing, and in above documentation example. This will be last post from me in this sub-thread. I think we have exhausted this part of discussion... -- Jakub Narebski Poland ShadeHawk on #git - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
