public inbox for git@vger.kernel.org 
 help / color / mirror / Atom feed

From: Jari Aalto <jari.aalto@cante•net>
To: git@vger•kernel.org
Subject: Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
Date: Fri, 01 Feb 2008 15:06:57 +0200	[thread overview]
Message-ID: <1w7w966m.fsf@blue.sea.net> (raw)
In-Reply-To: m37iho9b70.fsf@localhost.localdomain

* Fri 2008-02-01 Jakub Narebski <jnareb@gmail•com>
* Message-Id: m37iho9b70.fsf@localhost•localdomain
>
>
> 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)
> 'git-stash' [save [<message>...]]
>
> Angle brackets if I understand correctly are meant to denote part
> which you have to enter, the user supplied info (the reast ou have to
> enter literally).

Nowhere I have seen "(" parenheses to mean "required". The angle
brackets are commonly used to tell that the part is to be required:

    command <option> <file ...>

Reads:

    command -l file.txt

Whereas this has no known meaning:

    command (option) <file ...>

But this does:

    command [option] <file ...>

That's why I suggested to use:

    git stash <list | show [<stash>] | apply [<stash>] | clear>
    git stash [save [<message>...]]

The nesting of <'s is normal. The above reads:

    1st line: You have to select one command, one of the alternatives
    listed inside <...>: either "list", "show" ...

    2nd line: you can type 'git stash', 'git stash save' or supply
    additional message with the stash.

NOTE:

There exists curly braces notation that is sometimes used for
"required" part, but that not very common elsewhere other than
printed books from commercial vendors.

    command {one|two|three}

I would hesitate to select parentheses notation, which is relatively unknown
to mean "required" in the context of command syntax SYNOPSIS.

>> Welcome to FOSS revolution: we fix and modify until it shines
>
> Nice one. Can I add it to http://git.or.cz/gitwiki/FortuneCookies ?

Sure,
Jari

next prev parent reply	other threads:[~2008-02-01 13:08 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 [this message]
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
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=1w7w966m.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

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox