From: Jari Aalto <jari.aalto@cante•net>
To: git@vger•kernel.org
Subject: Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
Date: Sat, 02 Feb 2008 04:00:34 +0200 [thread overview]
Message-ID: <tzks5d8d.fsf@blue.sea.net> (raw)
In-Reply-To: m3y7a46vmf.fsf@localhost.localdomain
* Fri 2008-02-01 Jakub Narebski <jnareb@gmail•com>
* Message-Id: m3y7a46vmf.fsf@localhost•localdomain
> It seems that I was mistaken about that. Junio suggestion of following
> others example and using "{}" curly brackets for grouping alternate
> choices is IMHO a good solution.
That is another common syntax which I presented previously.
> The traditional manpages use /italics/ (usually rendered as
> _underlined_ text on terminals) to denote placeholders (user supplied
> input).
That does not matter. The text should stand out as it it in environment,
which do not render termcap or other terminal capabilities.
> From http://www.linux.com/articles/34212
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.
I think Git's manual pages should follow standard notation. E.g. the
use of parentheses should be replaced with curly braces.
Jari
-----------------------------------------------------------------------
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.
[...]
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.**
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...]
next prev parent reply other threads:[~2008-02-02 2:01 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 [this message]
2008-02-02 2:30 ` Jakub Narebski
2008-02-02 9:07 ` Jari Aalto
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=tzks5d8d.fsf@blue.sea.net \
--to=jari.aalto@cante$(echo .)net \
--cc=git@vger$(echo .)kernel.org \
/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