doc: convert git-stash.adoc to synopis style

- Switch the synopsis to a synopsis block which will automatically
  format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use `backticks` for keywords and more complex option
descriptions. The new rendering engine will apply synopsis rules to
these spans.

Also do not refer to the man page in the description of settings when this
description is already in the man page.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config/stash.adoc b/Documentation/config/stash.adoc
index e556105a15bd46c6489717b0aee663d461f98de1..7fc32027f70cd4315f31355e495fc454dd15d156 100644 (file)
--- a/Documentation/config/stash.adoc
+++ b/Documentation/config/stash.adoc
@@ -1,19 +1,28 @@
-stash.index::
+ifndef::git-stash[]
+:see-show: See the description of the 'show' command in linkgit:git-stash[1].
+endif::git-stash[]
+
+ifdef::git-stash[]
+:see-show:
+endif::git-stash[]
+
+`stash.index`::
        If this is set to true, `git stash apply` and `git stash pop` will
-       behave as if `--index` was supplied. Defaults to false. See the
-       descriptions in linkgit:git-stash[1].
+       behave as if `--index` was supplied. Defaults to false.
+ifndef::git-stash[]
+See the descriptions in linkgit:git-stash[1].
+endif::git-stash[]
 
-stash.showIncludeUntracked::
+`stash.showIncludeUntracked`::
        If this is set to true, the `git stash show` command will show
-       the untracked files of a stash entry.  Defaults to false. See
-       the description of the 'show' command in linkgit:git-stash[1].
+       the untracked files of a stash entry. Defaults to false. {see-show}
 
-stash.showPatch::
+`stash.showPatch`::
        If this is set to true, the `git stash show` command without an
        option will show the stash entry in patch form.  Defaults to false.
-       See the description of the 'show' command in linkgit:git-stash[1].
+       {see-show}
 
-stash.showStat::
+`stash.showStat`::
        If this is set to true, the `git stash show` command without an
        option will show a diffstat of the stash entry.  Defaults to true.
-       See the description of the 'show' command in linkgit:git-stash[1].
+       {see-show}

diff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc
index e2300a19a2c0a34870e965ce9d14eb72491f246c..235d57ddd8f5d107552fadba02c99180e69da2e0 100644 (file)
--- a/Documentation/git-stash.adoc
+++ b/Documentation/git-stash.adoc
@@ -7,24 +7,24 @@ git-stash - Stash the changes in a dirty working directory away
 
 SYNOPSIS
 --------
-[verse]
-'git stash' list [<log-options>]
-'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
-'git stash' drop [-q | --quiet] [<stash>]
-'git stash' pop [--index] [-q | --quiet] [<stash>]
-'git stash' apply [--index] [-q | --quiet] [<stash>]
-'git stash' branch <branchname> [<stash>]
-'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+[synopsis]
+git stash list [<log-options>]
+git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
+git stash drop [-q | --quiet] [<stash>]
+git stash pop [--index] [-q | --quiet] [<stash>]
+git stash apply [--index] [-q | --quiet] [<stash>]
+git stash branch <branchname> [<stash>]
+git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
             [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
             [--pathspec-from-file=<file> [--pathspec-file-nul]]
             [--] [<pathspec>...]]
-'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
-            [-u | --include-untracked] [-a | --all] [<message>]
-'git stash' clear
-'git stash' create [<message>]
-'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
-'git stash' export (--print | --to-ref <ref>) [<stash>...]
-'git stash' import <commit>
+git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+           [-u | --include-untracked] [-a | --all] [<message>]
+git stash clear
+git stash create [<message>]
+git stash store [(-m | --message) <message>] [-q | --quiet] <commit>
+git stash export (--print | --to-ref <ref>) [<stash>...]
+git stash import <commit>
 
 DESCRIPTION
 -----------
@@ -38,7 +38,7 @@ The modifications stashed away by this command can be listed with
 `git stash list`, inspected with `git stash show`, and restored
 (potentially on top of a different commit) with `git stash apply`.
 Calling `git stash` without any arguments is equivalent to `git stash push`.
-A stash is by default listed as "WIP on 'branchname' ...", but
+A stash is by default listed as "WIP on '<branchname>' ...", but
 you can give a more descriptive message on the command line when
 you create one.
 
@@ -47,16 +47,16 @@ stashes are found in the reflog of this reference and can be named using
 the usual reflog syntax (e.g. `stash@{0}` is the most recently
 created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}`
 is also possible). Stashes may also be referenced by specifying just the
-stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
+stash index (e.g. the integer `<n>` is equivalent to `stash@{<n>}`).
 
 COMMANDS
 --------
 
-push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
+`push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [ -a | --all] [-q | --quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]`::
 
        Save your local modifications to a new 'stash entry' and roll them
-       back to HEAD (in the working tree and in the index).
-       The <message> part is optional and gives
+       back to `HEAD` (in the working tree and in the index).
+       The _<message>_ part is optional and gives
        the description along with the stashed state.
 +
 For quickly making a snapshot, you can omit "push".  In this mode,
@@ -65,14 +65,14 @@ subcommand from making an unwanted stash entry.  The two exceptions to this
 are `stash -p` which acts as alias for `stash push -p` and pathspec elements,
 which are allowed after a double hyphen `--` for disambiguation.
 
-save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
+`save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [-a | --all] [-q | --quiet] [<message>]`::
 
        This option is deprecated in favour of 'git stash push'.  It
        differs from "stash push" in that it cannot take pathspec.
        Instead, all non-option arguments are concatenated to form the stash
        message.
 
-list [<log-options>]::
+`list [<log-options>]`::
 
        List the stash entries that you currently have.  Each 'stash entry' is
        listed with its name (e.g. `stash@{0}` is the latest entry, `stash@{1}` is
@@ -88,7 +88,7 @@ stash@{1}: On master: 9cc0589... Add git-stash
 The command takes options applicable to the 'git log'
 command to control what is shown and how. See linkgit:git-log[1].
 
-show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]::
+`show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]`::
 
        Show the changes recorded in the stash entry as a diff between the
        stashed contents and the commit back when the stash entry was first
@@ -96,12 +96,12 @@ show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]::
        By default, the command shows the diffstat, but it will accept any
        format known to 'git diff' (e.g., `git stash show -p stash@{1}`
        to view the second most recent entry in patch form).
-       If no `<diff-option>` is provided, the default behavior will be given
+       If no _<diff-option>_ is provided, the default behavior will be given
        by the `stash.showStat`, and `stash.showPatch` config variables. You
        can also use `stash.showIncludeUntracked` to set whether
        `--include-untracked` is enabled by default.
 
-pop [--index] [-q|--quiet] [<stash>]::
+`pop [--index] [-q | --quiet] [<stash>]`::
 
        Remove a single stashed state from the stash list and apply it
        on top of the current working tree state, i.e., do the inverse
@@ -112,19 +112,19 @@ Applying the state can fail with conflicts; in this case, it is not
 removed from the stash list. You need to resolve the conflicts by hand
 and call `git stash drop` manually afterwards.
 
-apply [--index] [-q|--quiet] [<stash>]::
+`apply [--index] [-q | --quiet] [<stash>]`::
 
        Like `pop`, but do not remove the state from the stash list. Unlike `pop`,
        `<stash>` may be any commit that looks like a commit created by
        `stash push` or `stash create`.
 
-branch <branchname> [<stash>]::
+`branch <branchname> [<stash>]`::
 
-       Creates and checks out a new branch named `<branchname>` starting from
-       the commit at which the `<stash>` was originally created, applies the
-       changes recorded in `<stash>` to the new working tree and index.
-       If that succeeds, and `<stash>` is a reference of the form
-       `stash@{<revision>}`, it then drops the `<stash>`.
+       Creates and checks out a new branch named _<branchname>_ starting from
+       the commit at which the _<stash>_ was originally created, applies the
+       changes recorded in _<stash>_ to the new working tree and index.
+       If that succeeds, and _<stash>_ is a reference of the form
+       `stash@{<revision>}`, it then drops the _<stash>_.
 +
 This is useful if the branch on which you ran `git stash push` has
 changed enough that `git stash apply` fails due to conflicts. Since
@@ -132,54 +132,51 @@ the stash entry is applied on top of the commit that was HEAD at the
 time `git stash` was run, it restores the originally stashed state
 with no conflicts.
 
-clear::
+`clear`::
        Remove all the stash entries. Note that those entries will then
        be subject to pruning, and may be impossible to recover (see
-       'Examples' below for a possible strategy).
-
-drop [-q|--quiet] [<stash>]::
+       'EXAMPLES' below for a possible strategy).
 
+`drop [-q | --quiet] [<stash>]`::
        Remove a single stash entry from the list of stash entries.
 
-create::
-
+`create`::
        Create a stash entry (which is a regular commit object) and
        return its object name, without storing it anywhere in the ref
        namespace.
        This is intended to be useful for scripts.  It is probably not
        the command you want to use; see "push" above.
 
-store::
+`store`::
 
        Store a given stash created via 'git stash create' (which is a
        dangling merge commit) in the stash ref, updating the stash
        reflog.  This is intended to be useful for scripts.  It is
        probably not the command you want to use; see "push" above.
 
-export ( --print | --to-ref <ref> ) [<stash>...]::
+`export ( --print | --to-ref <ref> ) [<stash>...]`::
 
        Export the specified stashes, or all of them if none are specified, to
        a chain of commits which can be transferred using the normal fetch and
        push mechanisms, then imported using the `import` subcommand.
 
-import <commit>::
-
+`import <commit>`::
        Import the specified stashes from the specified commit, which must have been
        created by `export`, and add them to the list of stashes.  To replace the
        existing stashes, use `clear` first.
 
 OPTIONS
 -------
--a::
---all::
+`-a`::
+`--all`::
        This option is only valid for `push` and `save` commands.
 +
 All ignored and untracked files are also stashed and then cleaned
 up with `git clean`.
 
--u::
---include-untracked::
---no-include-untracked::
+`-u`::
+`--include-untracked`::
+`--no-include-untracked`::
        When used with the `push` and `save` commands,
        all untracked files are also stashed and then cleaned up with
        `git clean`.
@@ -187,12 +184,12 @@ up with `git clean`.
 When used with the `show` command, show the untracked files in the stash
 entry as part of the diff.
 
---only-untracked::
+`--only-untracked`::
        This option is only valid for the `show` command.
 +
 Show only the untracked files in the stash entry as part of the diff.
 
---index::
+`--index`::
        This option is only valid for `pop` and `apply` commands.
 +
 Tries to reinstate not only the working tree's changes, but also
@@ -200,15 +197,15 @@ the index's ones. However, this can fail, when you have conflicts
 (which are stored in the index, where you therefore can no longer
 apply the changes as they were originally).
 
--k::
---keep-index::
---no-keep-index::
+`-k`::
+`--keep-index`::
+`--no-keep-index`::
        This option is only valid for `push` and `save` commands.
 +
 All changes already added to the index are left intact.
 
--p::
---patch::
+`-p`::
+`--patch`::
        This option is only valid for `push` and `save` commands.
 +
 Interactively select hunks from the diff between HEAD and the
@@ -224,8 +221,8 @@ The `--patch` option implies `--keep-index`.  You can use
 
 include::diff-context-options.adoc[]
 
--S::
---staged::
+`-S`::
+`--staged`::
        This option is only valid for `push` and `save` commands.
 +
 Stash only the changes that are currently staged. This is similar to
@@ -234,49 +231,49 @@ of current branch.
 +
 The `--patch` option has priority over this one.
 
---pathspec-from-file=<file>::
+`--pathspec-from-file=<file>`::
        This option is only valid for `push` command.
 +
-Pathspec is passed in `<file>` instead of commandline args. If
-`<file>` is exactly `-` then standard input is used. Pathspec
+Pathspec is passed in _<file>_ instead of commandline args. If
+_<file>_ is exactly `-` then standard input is used. Pathspec
 elements are separated by LF or CR/LF. Pathspec elements can be
 quoted as explained for the configuration variable `core.quotePath`
 (see linkgit:git-config[1]). See also `--pathspec-file-nul` and
 global `--literal-pathspecs`.
 
---pathspec-file-nul::
+`--pathspec-file-nul`::
        This option is only valid for `push` command.
 +
 Only meaningful with `--pathspec-from-file`. Pathspec elements are
 separated with NUL character and all other characters are taken
 literally (including newlines and quotes).
 
--q::
---quiet::
+`-q`::
+`--quiet`::
        This option is only valid for `apply`, `drop`, `pop`, `push`,
        `save`, `store` commands.
 +
 Quiet, suppress feedback messages.
 
---print::
+`--print`::
        This option is only valid for the `export` command.
 +
 Create the chain of commits representing the exported stashes without
 storing it anywhere in the ref namespace and print the object ID to
 standard output.  This is designed for scripts.
 
---to-ref::
+`--to-ref`::
        This option is only valid for the `export` command.
 +
 Create the chain of commits representing the exported stashes and store
 it to the specified ref.
 
-\--::
+`--`::
        This option is only valid for `push` command.
 +
 Separates pathspec from options for disambiguation purposes.
 
-<pathspec>...::
+`<pathspec>...`::
        This option is only valid for `push` command.
 +
 The new stash entry records the modified states only for the files
@@ -286,11 +283,11 @@ too, leaving files that do not match the pathspec intact.
 +
 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
 
-<stash>::
+_<stash>_::
        This option is only valid for `apply`, `branch`, `drop`, `pop`,
        `show`, and `export` commands.
 +
-A reference of the form `stash@{<revision>}`. When no `<stash>` is
+A reference of the form `stash@{<revision>}`. When no _<stash>_ is
 given, the latest stash is assumed (that is, `stash@{0}`).
 
 DISCUSSION
@@ -419,6 +416,7 @@ CONFIGURATION
 
 include::includes/cmd-config-section-all.adoc[]
 
+:git-stash: 1
 include::config/stash.adoc[]