Improve git issue help output

.travis.yml

@@ -1,2 +1,2 @@
 language: bash
-script: ./test.sh
+script: make test

Makefile

@@ -17,11 +17,14 @@ install:
 sync-docs:
 	./sync-docs.sh
 
+test:
+	./test.sh
+
 uninstall:
 	rm -f $(DESTDIR)$(BINPREFIX)/git-issue
 	rm -f $(DESTDIR)$(MANPREFIX)/git-issue.
 	rm -f $(DESTDIR)$(SYSCONFDIR)/bash_completion.d/git-issue
 
 clean:
 
-.PHONY: default clean install uninstall sync-docs
+.PHONY: default clean install uninstall sync-docs test

README.md

@@ -69,27 +69,31 @@ its operation, and (please) update this file.
 ## Use
 You use _git issue_ with the following sub-commands.
 
+### start an issue repository
+* `git issue clone`: Clone the specified remote repository.
 * `git issue init`: Create a new issues repository in the current directory.
   The `-e` option uses an existing Git project repository.
-* `git issue clone`: Clone the specified remote repository.
-* `git issue new`: Create a new open issue with the specified summary.
-* `git issue list`: List the issues with the specified tag.
-  By default this lists issues that are tagged as `open`.
+### work with an issue
+* `git issue new`: Create a new open issue (with optional `-s` summary).
 * `git issue show`: Show specified issue (and its comments with `-c`).
 * `git issue comment`: Add an issue comment.
+* `git issue edit`: Edit the specified issue's summary (not yet implemented)
 * `git issue tag`: Add (or remove with `-r`) a tag.
 * `git issue assign`: Assign (or reassign) an issue to a person.
   The person is specified with his/her email address.
   The form `@name` or `name@` can be used as a shortcut, provided it
   uniquely identifies an existing assignee or committer.
 * `git issue attach`: Attach (or remove with `-r`) a file to an issue.
 * `git issue watcher`: Add (or remove with `-r`) an issue watcher.
-* `git issue close`: Remove the `open` tag from the issue, marking it as closed.
-* `git issue edit`: Edit the specified issue's summary or comment.
-* `git issue help`: Display help information about git issue.
-* `git issue log`: Output a log of changes made
+* `git issue close`: Remove the `open` tag, add the closed tag
+### show multiple issues
+* `git issue list`: List open issues (or all with `-a`); supports tags
+### synchronize with remote repository
 * `git issue push`: Update remote repository with local changes.
 * `git issue pull`: Update local repository with remote changes.
+### help and debug
+* `git issue help`: Display help information about git issue.
+* `git issue log`: Output a log of changes made
 * `git issue git`: Run the specified Git command on the issues repository.
 
 Issues and comments are specified through the SHA hash associated with the

git-issue.1

@@ -38,28 +38,22 @@ a solid audit trail regarding any changes.
 .\" Auto-generated content from README.md; do not edit this section
 You use \fIgit issue\fP with the following sub-commands.
 
-.RE
-.PP
-\fBgit issue init\fP
-.RS 4
-Create a new issues repository in the current directory.
-  The \fC-e\fP option uses an existing Git project repository.
 .RE
 .PP
 \fBgit issue clone\fP
 .RS 4
 Clone the specified remote repository.
 .RE
 .PP
-\fBgit issue new\fP
+\fBgit issue init\fP
 .RS 4
-Create a new open issue with the specified summary.
+Create a new issues repository in the current directory.
+  The \fC-e\fP option uses an existing Git project repository.
 .RE
 .PP
-\fBgit issue list\fP
+\fBgit issue new\fP
 .RS 4
-List the issues with the specified tag.
-  By default this lists issues that are tagged as \fCopen\fP.
+Create a new open issue (with optional \fC-s\fP summary).
 .RE
 .PP
 \fBgit issue show\fP
@@ -72,6 +66,11 @@ Show specified issue (and its comments with \fC-c\fP).
 Add an issue comment.
 .RE
 .PP
+\fBgit issue edit\fP
+.RS 4
+Edit the specified issue's summary (not yet implemented)
+.RE
+.PP
 \fBgit issue tag\fP
 .RS 4
 Add (or remove with \fC-r\fP) a tag.
@@ -97,32 +96,32 @@ Add (or remove with \fC-r\fP) an issue watcher.
 .PP
 \fBgit issue close\fP
 .RS 4
-Remove the \fCopen\fP tag from the issue, marking it as closed.
+Remove the \fCopen\fP tag, add the closed tag
 .RE
 .PP
-\fBgit issue edit\fP
+\fBgit issue list\fP
 .RS 4
-Edit the specified issue's summary or comment.
+List open issues (or all with \fC-a\fP); supports tags
 .RE
 .PP
-\fBgit issue help\fP
+\fBgit issue push\fP
 .RS 4
-Display help information about git issue.
+Update remote repository with local changes.
 .RE
 .PP
-\fBgit issue log\fP
+\fBgit issue pull\fP
 .RS 4
-Output a log of changes made
+Update local repository with remote changes.
 .RE
 .PP
-\fBgit issue push\fP
+\fBgit issue help\fP
 .RS 4
-Update remote repository with local changes.
+Display help information about git issue.
 .RE
 .PP
-\fBgit issue pull\fP
+\fBgit issue log\fP
 .RS 4
-Update local repository with remote changes.
+Output a log of changes made
 .RE
 .PP
 \fBgit issue git\fP
@@ -140,8 +139,9 @@ to use to display long lists of results.
 
 .SH FILES
 .\" Auto-generated content from README.md; do not edit this section
-All data are stored under \fC.issues\fP. The directory contains the
-following elements.
+All data are stored under \fC.issues\fP, which should be placed under \fC.gitignore\fP,
+if it will coexist with another Git-based project.
+The directory contains the following elements.
 .IP "" 4
 A \fC.git\fP directory contains the Git data associated with the issues.
 .IP "" 4

git-issue.sh

@@ -577,24 +577,35 @@ sub_help()
   #
   cat <<\USAGE_EOF
 usage: git issue <command> [<args>]
-The following commands are available
-git issue init: Create a new issues repository in the current directory.
-git issue clone: Clone the specified remote repository.
-git issue new: Create a new open issue with the specified summary.
-git issue list: List the issues with the specified tag.
-git issue show: Show specified issue (and its comments with -c).
-git issue comment: Add an issue comment.
-git issue tag: Add (or remove with -r) a tag.
-git issue assign: Assign (or reassign) an issue to a person.
-git issue attach: Attach (or remove with -r) a file to an issue.
-git issue watcher: Add (or remove with -r) an issue watcher.
-git issue close: Remove the open tag from the issue, marking it as closed.
-git issue edit: Edit the specified issue's summary or comment.
-git issue help: Display help information about git issue.
-git issue log: Output a log of changes made
-git issue push: Update remote repository with local changes.
-git issue pull: Update local repository with remote changes.
-git issue git: Run the specified Git command on the issues repository.
+
+The following commands are available:
+
+start an issue repository
+   clone      Clone the specified remote repository
+   init       Create a new issues repository in the current directory
+
+work with an issue
+   new        Create a new open issue (with optional -s summary)
+   show       Show specified issue (and its comments with -c)
+   comment    Add an issue comment
+   edit       Edit the specified issue's summary (not yet implemented)
+   tag        Add (or remove with -r) a tag
+   assign     Assign (or reassign) an issue to a person
+   attach     Attach (or remove with -r) a file to an issue
+   watcher    Add (or remove with -r) an issue watcher
+   close      Remove the open tag, add the closed tag
+
+show multiple issues
+   list       List open issues (or all with -a); supports tags
+
+synchronize with remote repository
+   push       Update remote repository with local changes
+   pull       Update local repository with remote changes
+
+help and debug
+   help       Display help information about git issue
+   log        Output a log of changes made
+   git        Run the specified Git command on the issues repository
 USAGE_EOF
 }
 

sync-docs.sh

@@ -25,11 +25,26 @@ MAN_PAGE=git-issue.1
 
 # Update usage information in the script based on README.md
 {
-  sed -n '1,/^The following commands are available/p' $SCRIPT_NAME
-  sed -n '/^\* `git issue init`/,/^\* `git issue git`/ {
-    /^\* /!d
+  sed -n '1,/^The following commands are available:/p' $SCRIPT_NAME
+  # Keep lines from `### start ` to `git issue git`
+  sed -n '/^### start/,/^\* `git issue git`/ {
+    # Only keep listed commands or subheaders
+    /^\* \|^### /!d
+    # Format headers by eliminating all preceding space
+    s/^### \(.*\)/\n\1/g
+    # Remove repetitive git issue
+    s/git issue //g
+    # Remove code markup
     s/`//g
-    s/^\* //
+    # Remove fullstops
+    s/\.//g
+    # Format commands, depending on length
+    s/^\* \([^:]\{3\}\): /   \1        /g
+    s/^\* \([^:]\{4\}\): /   \1       /g
+    s/^\* \([^:]\{5\}\): /   \1      /g
+    s/^\* \([^:]\{6\}\): /   \1     /g
+    s/^\* \([^:]\{7\}\): /   \1    /g
+
     p
   }' README.md
   sed -n '/^USAGE_EOF/,$p' $SCRIPT_NAME
@@ -55,6 +70,7 @@ replace_section()
       $command"'
       # Remove section titles
       /^## /d
+      /^###/d
       # Set code text with Courier (twice per line)
       s/`/\\fC/;s/`/\\fP/
       s/`/\\fC/;s/`/\\fP/

test.sh

@@ -111,6 +111,18 @@ ntest=0
 gi=../git-issue.sh
 gi_re=$(echo $gi | sed 's/[^0-9A-Za-z]/\\&/g')
 rm -rf testdir
+
+start
+GenFiles="git-issue.sh git-issue.1"
+make sync-docs
+Status=$(git status --porcelain -- $GenFiles)
+if [ -z "$Status" ]; then
+    ok "make sync-docs left $GenFiles as committed"
+else
+    fail "make sync-docs changed $GenFiles"
+    git checkout -- $GenFiles
+fi
+
 mkdir testdir
 cd testdir