[PATCH 0/3] More stgit doc updates

[PATCH 0/3] More stgit doc updates

[Yann Dirson]

This set of patches fixes a couple of things and tries to improve the
doc.

-- 
Yann Dirson    <ydirson@altern.org> |
Debian-related: <dirson@debian.org> |   Support Debian GNU/Linux:
                                    |  Freedom, Power, Stability, Gratis
     http://ydirson.free.fr/        | Check <http://www.debian.org/>

[PATCH 1/3] Fix doc cross-refs.

[Yann Dirson]

Signed-off-by: Yann Dirson <ydirson@altern.org>
---

 Documentation/stg-branch.txt |    2 +-
 Documentation/stg-clone.txt  |    4 ++--
 Documentation/stg-init.txt   |    4 ++--
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/stg-branch.txt b/Documentation/stg-branch.txt
index 53f333b..28a9a28 100644
--- a/Documentation/stg-branch.txt
+++ b/Documentation/stg-branch.txt
@@ -56,7 +56,7 @@ no command, one argument::
 +
 StGIT will try to detect the branch off which the new stack is forked,
 as well as the remote repository from which that parent branch is
-taken (if any), so running stgdesc:pull[] will effectively pull new
+taken (if any), so running stglink:pull[] will effectively pull new
 commits from the correct branch.  It will warn if it cannot guess the
 parent branch (eg. if you do not specify a branch name as
 <commit-id>).
diff --git a/Documentation/stg-clone.txt b/Documentation/stg-clone.txt
index 73c0d92..126b0f2 100644
--- a/Documentation/stg-clone.txt
+++ b/Documentation/stg-clone.txt
@@ -20,8 +20,8 @@ a patch stack.
 
 This operation is for example suitable to start working using the
 "tracking branch" workflow (see gitlink:stg[1]).  Other means to setup
-an StGIT stack are stgdesc:init[] and the '--create' and '--clone'
-commands of stgdesc:branch[].
+an StGIT stack are stglink:init[] and the '--create' and '--clone'
+commands of stglink:branch[].
 
 The target directory named by <dir> will be created by this command,
 and must not exist beforehand.
diff --git a/Documentation/stg-init.txt b/Documentation/stg-init.txt
index 33fd387..e692a04 100644
--- a/Documentation/stg-init.txt
+++ b/Documentation/stg-init.txt
@@ -20,8 +20,8 @@ valid file in refs/heads/.
 
 This operation is for example suitable to start working using the
 "development branch" workflow (see gitlink:stg[1]).  Other means to setup
-an StGIT stack are stgdesc:clone[] and the '--create' and '--clone'
-commands of stgdesc:branch[].
+an StGIT stack are stglink:clone[] and the '--create' and '--clone'
+commands of stglink:branch[].
 
 OPTIONS
 -------

[PATCH 2/3] Make the documentation of options more consistent.

[Yann Dirson]

Signed-off-by: Yann Dirson <ydirson@altern.org>
---

 Documentation/COMMAND-TEMPLATE.txt |    3 +-
 Documentation/stg-branch.txt       |   51 +++++++++++++-----------------------
 Documentation/stg-clone.txt        |    8 +-----
 Documentation/stg-cp.txt           |    9 ++++--
 Documentation/stg-init.txt         |    8 +-----
 Documentation/stg-new.txt          |   11 ++++----
 Documentation/stg.txt              |    8 +++++-
 7 files changed, 43 insertions(+), 55 deletions(-)

diff --git a/Documentation/COMMAND-TEMPLATE.txt b/Documentation/COMMAND-TEMPLATE.txt
index e49a44d..7bc029a 100644
--- a/Documentation/COMMAND-TEMPLATE.txt
+++ b/Documentation/COMMAND-TEMPLATE.txt
@@ -9,7 +9,8 @@ stg-NAME - stgdesc:NAME[]
 
 SYNOPSIS
 --------
-stg NAME [OPTIONS] XXX
+[verse]
+'stg' NAME [OPTIONS] XXX
 
 DESCRIPTION
 -----------
diff --git a/Documentation/stg-branch.txt b/Documentation/stg-branch.txt
index 28a9a28..2efe7b1 100644
--- a/Documentation/stg-branch.txt
+++ b/Documentation/stg-branch.txt
@@ -9,25 +9,17 @@ stg-branch - stgdesc:branch[]
 
 SYNOPSIS
 --------
-stg branch
-
-stg branch <branch>
-
-stg branch --list
-
-stg branch --create <newstack> [<commit-id>]
-
-stg branch --clone [<newstack>]
-
-stg branch --rename <oldname> <newname>
-
-stg branch --protect [<branch>]
-
-stg branch --unprotect [<branch>]
-
-stg branch --delete [--force] <branch>
-
-stg branch --convert
+[verse]
+'stg' branch
+'stg' branch <branch>
+'stg' branch --list
+'stg' branch --create <newstack> [<commit-id>]
+'stg' branch --clone [<newstack>]
+'stg' branch --rename <oldname> <newname>
+'stg' branch --protect [<branch>]
+'stg' branch --unprotect [<branch>]
+'stg' branch --delete [--force] <branch>
+'stg' branch --convert
 
 DESCRIPTION
 -----------
@@ -40,16 +32,14 @@ no command, no argument::
 no command, one argument::
 	Switch to the named <branch>.
 
---list::
--l::
+'stg' branch [-l | --list]::
 	Display the list of branches in the current repository,
 	suffixed by the branch description if any, and optionally
 	prefixed by the letter flags 's' if the branch is an StGIT
 	stack, and 'p' if the StGIT stack is protected.  The current
 	branch is shown with a leading ">" character.
 
---create::
--c::
+'stg' branch [-c | --create]::
 	Create a new StGIT stack based at the specified commit, or at
 	the current HEAD if not specified.  The repository HEAD is
 	switched to the new stack.
@@ -61,7 +51,7 @@ commits from the correct branch.  It will warn if it cannot guess the
 parent branch (eg. if you do not specify a branch name as
 <commit-id>).
 
---clone::
+'stg' branch --clone::
 	Clone the current stack, under the name <newstack> if
 	specified, or using the current stack's name suffixed by a
 	timestamp.
@@ -73,20 +63,17 @@ the current stack.
 Cloning a GIT branch that is not an StGIT stack is similar to creating
 a new stack off the current branch.
 
---rename::
--r::
+'stg' branch [-r | --rename]::
 	Rename the stack named <oldname> to <newname>.
 
---protect::
--p::
+'stg' branch [-p | --protect]::
 	Protect the named stack or the current one, preventing
 	further StGIT operations from modifying this stack.
 
---unprotect::
--u::
+'stg' branch [-u | --unprotect]::
 	Remove a "protected" flag previously set with '--protect'.
 
---delete::
+'stg' branch --delete::
 	Delete the named <branch>.  If there are any patches left in
 	the series, StGIT will refuse to delete it, unless '--force'
 	is specified.
@@ -100,7 +87,7 @@ the "master" branch if it exists.
 Branch "master" is treated specially (see bug #8732), in that only the
 StGIT metadata are removed, the GIT branch itself is not destroyed.
 
---convert::
+'stg' branch --convert::
 	Switch current stack between old and new format.
 
 OPTIONS
diff --git a/Documentation/stg-clone.txt b/Documentation/stg-clone.txt
index 126b0f2..19a8b79 100644
--- a/Documentation/stg-clone.txt
+++ b/Documentation/stg-clone.txt
@@ -9,7 +9,8 @@ stg-clone - stgdesc:clone[]
 
 SYNOPSIS
 --------
-stg clone [OPTIONS] <repository> <dir>
+[verse]
+'stg' clone <repository> <dir>
 
 DESCRIPTION
 -----------
@@ -26,11 +27,6 @@ commands of stglink:branch[].
 The target directory named by <dir> will be created by this command,
 and must not exist beforehand.
 
-OPTIONS
--------
-
-No specific options.
-
 StGIT
 -----
 Part of the StGIT suite - see gitlink:stg[1].
diff --git a/Documentation/stg-cp.txt b/Documentation/stg-cp.txt
index d28c619..2314925 100644
--- a/Documentation/stg-cp.txt
+++ b/Documentation/stg-cp.txt
@@ -9,9 +9,9 @@ stg-cp - stgdesc:cp[]
 
 SYNOPSIS
 --------
-stg cp [OPTIONS] <file|dir> <newname>
-
-stg cp [OPTIONS] <files|dirs...> <dir>
+[verse]
+'stg' cp [OPTIONS] <file|dir> <newname>
+'stg' cp [OPTIONS] <files|dirs...> <dir>
 
 DESCRIPTION
 -----------
@@ -44,6 +44,9 @@ that directory would be overwritten.
 FUTURE OPTIONS
 --------------
 
+No options are supported yet.  The following options may be
+implemented in the future.
+
 --all::
 	Also copy files not known to Git when copying a directory.
 
diff --git a/Documentation/stg-init.txt b/Documentation/stg-init.txt
index e692a04..03877e0 100644
--- a/Documentation/stg-init.txt
+++ b/Documentation/stg-init.txt
@@ -9,7 +9,8 @@ stg-init - stgdesc:init[]
 
 SYNOPSIS
 --------
-stg init [OPTIONS]
+[verse]
+'stg' init
 
 DESCRIPTION
 -----------
@@ -23,11 +24,6 @@ This operation is for example suitable to start working using the
 an StGIT stack are stglink:clone[] and the '--create' and '--clone'
 commands of stglink:branch[].
 
-OPTIONS
--------
-
-No specific options.
-
 StGIT
 -----
 Part of the StGIT suite - see gitlink:stg[1].
diff --git a/Documentation/stg-new.txt b/Documentation/stg-new.txt
index 5775559..009659a 100644
--- a/Documentation/stg-new.txt
+++ b/Documentation/stg-new.txt
@@ -9,7 +9,8 @@ stg-new - stgdesc:new[]
 
 SYNOPSIS
 --------
-stg new [OPTIONS] <name>
+[verse]
+'stg' new [OPTIONS] <name>
 
 DESCRIPTION
 -----------
@@ -20,6 +21,9 @@ is made the new top of the stack.  The local changes in the working
 tree are not included in the patch. A stglink:refresh[] command is
 needed for this.
 
+The given <name> must be unique in the stack, and may only contain
+alphanumeric characters, dashes and underscores.
+
 An editor will be launched to edit the commit message to be used for
 the patch, unless the '--message' flag already specified one.  The
 'patchdescr.tmpl' template file is used if available to pre-fill the
@@ -57,11 +61,6 @@ described in gitlink:git-commit-tree[1].
 OPTIONS
 -------
 
-<name>::
-	The short name that will be used as to identify the patch in
-	other StGIT commands.  Must be unique in the stack.  May only
-	contain alphanumeric characters, dashes and underscores.
-
 --message=<message>::
 -m <message>::
 	Use <message> as the patch description.
diff --git a/Documentation/stg.txt b/Documentation/stg.txt
index 47934a5..a91b600 100644
--- a/Documentation/stg.txt
+++ b/Documentation/stg.txt
@@ -10,7 +10,9 @@ stg - manage stacks of patches using the GIT content tracker
 SYNOPSIS
 --------
 [verse]
-'stg' [--version] [--help] <command> [OPTIONS] [ARGS]
+'stg' [--version | --help]
+'stg' [--help <command> | <command> --help]
+'stg' <command> [COMMAND OPTIONS] [ARGS]
 
 DESCRIPTION
 -----------
@@ -52,6 +54,10 @@ patches; there may be regular GIT commits below your stack base.
 OPTIONS
 -------
 
+The following generic option flags are available.  Additional options
+are available per-command, and documented in the command-specific
+documentation.
+
 --version::
 	Prints the StGIT suite version that the 'stg' program came
 	from, as well as version of other components used, such as GIT

[PATCH 3/3] Stop advertising 'pull' as the only operation blocked on protected stacks.

[Yann Dirson]

Signed-off-by: Yann Dirson <ydirson@altern.org>
---

 stgit/commands/branch.py |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/stgit/commands/branch.py b/stgit/commands/branch.py
index eff0121..5f79f7e 100644
--- a/stgit/commands/branch.py
+++ b/stgit/commands/branch.py
@@ -58,13 +58,13 @@ options = [make_option('-c', '--create',
                        help = 'list branches contained in this repository',
                        action = 'store_true'),
            make_option('-p', '--protect',
-                       help = 'prevent "stg pull" from modifying this branch',
+                       help = 'prevent StGIT from modifying this branch',
                        action = 'store_true'),
            make_option('-r', '--rename',
                        help = 'rename an existing development branch',
                        action = 'store_true'),
            make_option('-u', '--unprotect',
-                       help = 'allow "stg pull" to modify this branch',
+                       help = 'allow StGIT to modify this branch',
                        action = 'store_true')]