From: Jari Aalto <jari.aalto@cante•net>
To: git@vger•kernel.org
Cc: srackham@methods•co.nz
Subject: Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
Date: Sat, 02 Feb 2008 11:07:36 +0200 [thread overview]
Message-ID: <ejbv6813.fsf@blue.sea.net> (raw)
In-Reply-To: m3tzks6qfm.fsf@localhost.localdomain
* Fri 2008-02-01 Jakub Narebski <jnareb@gmail•com>
* Message-Id: m3tzks6qfm.fsf@localhost•localdomain
>> he text should stand out as it it in environment,
>> which do not render termcap or other terminal capabilities.
>
> Nevertheless it would be nice if our AsciiDoc configuration generated
> italics or underline ...for manpage, and italics for HTML output for
> placeholders, *in addition* to using angle parentheses (angle braces)
> as delimites for placeholder parameters.
Sure, let's notify the asciidoc maintainer know about the wishes (CC'd)
>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
>>
>> Here are the POSIX/Susv guidelines for the manual pages, I've marked the
>> relevant points with **....**. We were both right: Angles mean required
>> and grouping.
>
> Errr... as far as I understand angles means placeholders, i.e. user
> supplied input. You can use "[<file>...]" for optional placeholder;
> everything which is not inside brackets is required.
If you choose to use the "optional", then you are _required_ to fill in
the mentioned item. The "[....]" is applied in your example as well. The
angles always keep it's nature, which is a requirement:
4. Frequently, names of parameters that _require_ substitution(...)
<parameter name>
> It is used quite frequently in git manpages. Using parentheses to
> delimit required alternate parts seems quite sensible.
>
> 'git-branch' (-m | -M) [<oldbranch>] <newbranch>
The change is small, but important. People look at the manual paged any
will get the wrong impression on "the standard notation"
git-branch {-m | -M} [<oldbranch>] <newbranch>
= =
Change to use curlies
> 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 manaul pages.
>> -----------------------------------------------------------------------
>> http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11
>>
>> 12.1 Utility Argument Syntax
>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01
>>
>> [...]
>>
>> 4. Frequently, names of parameters that **require** substitution by
>> actual values are shown with embedded underscores. Alternatively,
>> parameters are shown as follows:
>>
>> <parameter name>
>>
>> The angle brackets are used for the symbolic grouping of a phrase
>> representing a single parameter and conforming applications shall
>> not include them in data submitted to the utility.
>
> This means that <param> denotes placeholder: parameter that requires
> **subsititution** (this part should be emphasized!). Such parameter
> might have multi-word name. Such parameter might be required, but
> might be optional.
It's never optional. For optionality, there is specific notation.
Everybody knows how to read these; what is required and what is not:
command <arg> <arg>
command <arg> [<message>]
command <arg> [-lbc]
The <message> here is symbolic and not to be taken literally, whereas
text that is not eclosed inside angles, "-lbc", is to be taken
literally and interpreted by the rules of "set of options".
>> [...]
>> 7. Arguments or option-arguments enclosed in the '[' and ']'
>> notation are **optional** and can be omitted. Conforming applications
>> shall not include the '[' and ']' symbols in data submitted to the
>> utility.
>>
>> 8. Arguments separated by the '|' vertical bar notation are
>> **mutually-exclusive.**
>
> Note that is natural that '[' and ']' also are limits of mutualy
> exclusive parameters: "cmd [ A | B ]" means "cmd" or "cmd A" or "cmd B".
> It is not specified explicitely, but IMHO is quite natural. And it is
> what is used in different manpages, see examples I have provided in my
> previous post in this subthread.
We are in all agreement on this one.
>> 9. Ellipses ( "..." ) are used to denote that one or **more**
>> occurrences of an option or operand are allowed. When an option or
>> an operand followed by ellipses is enclosed in brackets, **zero** or
>> more options or operands can be specified.
>>
>> utility_name [-g option_argument]...[operand...]
>
> Note that one is not followed strictly, and one should take note of
> that. For example to make sure that everybody knows that it is zero or
> more one would use [<param>...], and to make use that it is one or
> more one would use "<param> [<param>...]", just to be sure.
That's what it says. Outside of "[]" the ellipses mean (1+), indiside
"[]", by rules of the brackets, it means (0+). I forgot to paste the
two examples. Here:
utility_name -f option_argument...[operand...]
utility_name [-g option_argument]...[operand...]
Jari
--
Welcome to FOSS revolution: we fix and modify until it shines
next prev parent reply other threads:[~2008-02-02 9:09 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-02-01 10:04 [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes Jari Aalto
2008-02-01 11:19 ` Jakub Narebski
2008-02-01 13:06 ` Jari Aalto
2008-02-01 13:35 ` Jakub Narebski
2008-02-01 22:37 ` Jari Aalto
2008-02-01 23:26 ` Junio C Hamano
2008-02-02 1:43 ` Jari Aalto
2008-02-02 2:17 ` Jari Aalto
2008-02-02 0:38 ` Jakub Narebski
2008-02-02 2:00 ` Jari Aalto
2008-02-02 2:30 ` Jakub Narebski
2008-02-02 9:07 ` Jari Aalto [this message]
2008-02-02 9:45 ` Jakub Narebski
2008-02-02 14:32 ` Jari Aalto
2008-02-02 15:25 ` Jakub Narebski
2008-02-02 2:22 ` [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntax Jari Aalto
2008-02-02 2:47 ` Junio C Hamano
2008-02-02 10:23 ` Jakub Narebski
2008-02-02 14:03 ` [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntax (2) Jari Aalto
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ejbv6813.fsf@blue.sea.net \
--to=jari.aalto@cante$(echo .)net \
--cc=git@vger$(echo .)kernel.org \
--cc=srackham@methods$(echo .)co.nz \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox