[GUILT 0/5] doc: less guilt-foo invocations, minor Makefile fixes

guilt no longer supports running commands on the "guilt-add" form.
You need to use "guilt add" instead.

This patch series updates most of the documentation to use the
supported "guilt add" form.

There is one known instance where I did not change the style: in the
NAME section in Documentation/guilt-*.txt.  The reason is that if I
change it there, xmlto will create the man pages as e.g. guilt_add.1
instead of guilt-add.1, and I don't know how to fix that.  Also, the
git man pages (as of Git 2.1.0) still have "git-add" under the NAME
heading of git-add(1), so it might be wise to follow suite.

While working on this, I also found two minor issues with
Documentation/Makefile.

    /ceder

Per Cederqvist (5):
  Fix generation of Documentation/usage-%.txt.
  doc: guilt.xml depends on cmds.txt.
  doc: don't use guilt-foo invocations in examples.
  doc: don't use guilt-foo invocations in usage messages.
  doc: git doesn't use git-foo invocations.

 Documentation/.gitignore        | 3 +++
 Documentation/Makefile          | 6 ++++--
 Documentation/guilt-add.txt     | 4 ++--
 Documentation/guilt-delete.txt  | 2 +-
 Documentation/guilt-diff.txt    | 2 +-
 Documentation/guilt-help.txt    | 4 ++--
 Documentation/guilt-new.txt     | 6 +++---
 Documentation/guilt-refresh.txt | 2 +-
 Documentation/guilt-repair.txt  | 2 +-
 Documentation/guilt-rm.txt      | 2 +-
 Documentation/guilt-select.txt  | 4 ++--
 Documentation/usage.sh          | 8 +++-----
 12 files changed, 24 insertions(+), 21 deletions(-)

-- 
2.1.0

The old rule worked, most of the time, but had several issues:

 - It depended on the corresponding guilt-*.txt file, but the usage.sh
   script actually reads ../guilt-foo.

 - Actually, each usage-%.txt depended on all guilt-*.txt files, so
   make had to do more work than necessary if a single file was
   altered.

 - The construct broke parallel make, which would spawn several
   usage.sh at once.  This leads to unnecessary work, and could
   potentially result in broken usage files if the "echo some_string >
   some_file" construct used by usage.sh isn't atomic.

Fixed by letting the usage.sh script update a single file, and writing
a proper implicit make rule.  This makes parallel make work a lot
better.

There is a small downside, though, as usage.sh will now be run once
for each command (if everything is regenerated).  I think it is worth
to pay that price to get the correctness.  This command is still very
fast compared to the docbook processing.

Signed-off-by: Per Cederqvist <redacted>
---
 Documentation/Makefile | 4 ++--
 Documentation/usage.sh | 8 +++-----
 2 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b6c3285..ec3c9e8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -66,8 +66,8 @@ clean:
 	rm -f usage-*.txt
 	rm -f version.txt
 
-usage-%.txt: $(MAN1_TXT) usage.sh
-	sh ./usage.sh
+usage-guilt-%.txt: ../guilt-% usage.sh
+	sh ./usage.sh $<
 
 %.html : %.txt footer.txt version.txt
 	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<

diff --git a/Documentation/usage.sh b/Documentation/usage.sh
index 20fdca4..629f546 100644
--- a/Documentation/usage.sh
+++ b/Documentation/usage.sh

@@ -1,7 +1,5 @@
 #!/bin/sh
 
-for i in `ls ../guilt-*`; do
-	name=$(basename $i)
-	u=$(grep USAGE $i |  sed 's/USAGE="//' | sed 's/"$//') 
-	echo "'$name' $u"  > usage-$name.txt
-done
+name=$(basename $1)
+u=$(grep USAGE $1 |  sed 's/USAGE="//' | sed 's/"$//') 
+echo "'$name' $u"  > usage-$name.txt

-- 
2.1.0

Specify an explicit dependency, to stop make from trying to generate
guilt.xml if cmds.txt could not be created.  The asciidoc will fail
and produce an error message that might hide the original error
message.

The added dependency causes make to not remove the guilt.xml file.
Add *.xml to .gitignore.

Signed-off-by: Per Cederqvist <redacted>
---
 Documentation/.gitignore | 3 +++
 Documentation/Makefile   | 2 ++
 2 files changed, 5 insertions(+)

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index c4f0588..9b8d4da 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore

@@ -11,3 +11,6 @@ version.txt
 
 # Generated file dependency list
 doc.dep
+
+# Intermediate generated files
+*.xml

diff --git a/Documentation/Makefile b/Documentation/Makefile
index ec3c9e8..2574125 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -60,6 +60,8 @@ cmds.txt: cmd-list.sh $(MAN1_TXT)
 
 guilt.7 guilt.html: guilt.txt footer.txt version.txt
 
+guilt.xml: cmds.txt
+
 clean:
 	rm -f *.xml *.html *.1 *.7 doc.dep
 	rm -f cmds.txt

-- 
2.1.0

Note: there is one place where I replace guilt-repair with "guilt
repair" instead of "+guilt repair+".  At least the version of docbook
I'm using mishandles the "+" signs in that particular spot (even
though it works properly for "+guilt select+" in another file.  I know
too little docbook to be able to find the cause.

Signed-off-by: Per Cederqvist <redacted>
---
 Documentation/guilt-add.txt    | 2 +-
 Documentation/guilt-delete.txt | 2 +-
 Documentation/guilt-diff.txt   | 2 +-
 Documentation/guilt-help.txt   | 4 ++--
 Documentation/guilt-new.txt    | 6 +++---
 Documentation/guilt-repair.txt | 2 +-
 Documentation/guilt-select.txt | 4 ++--
 7 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/guilt-add.txt b/Documentation/guilt-add.txt
index 6d2785a..a276f09 100644
--- a/Documentation/guilt-add.txt
+++ b/Documentation/guilt-add.txt

@@ -24,7 +24,7 @@ EXAMPLES
 Create and add a new file example.c
 
 	$ touch example.c
-	$ guilt-add example.c
+	$ guilt add example.c
 
 Author
 ------

diff --git a/Documentation/guilt-delete.txt b/Documentation/guilt-delete.txt
index ef57dc6..4e8c28c 100644
--- a/Documentation/guilt-delete.txt
+++ b/Documentation/guilt-delete.txt

@@ -25,7 +25,7 @@ EXAMPLES
 --------
 Delete a patch called 'foobar':
 
-	$ guilt-delete foobar
+	$ guilt delete foobar
 
 Author
 ------

diff --git a/Documentation/guilt-diff.txt b/Documentation/guilt-diff.txt
index 986ceca..0ee062c 100644
--- a/Documentation/guilt-diff.txt
+++ b/Documentation/guilt-diff.txt

@@ -18,7 +18,7 @@ OPTIONS
 -------
 -z::
 	Output a interdiff against the top-most applied patch. This should
-	produce the same diff as "+guilt-new -f foo+".
+	produce the same diff as "+guilt new -f foo+".
 
 <path>...::
 	Restrict diff output to a given set of files.

diff --git a/Documentation/guilt-help.txt b/Documentation/guilt-help.txt
index ed6a5cf..df0e0fb 100644
--- a/Documentation/guilt-help.txt
+++ b/Documentation/guilt-help.txt

@@ -18,11 +18,11 @@ EXAMPLES
 
 Open the guilt-status man page 
 
-	$ guilt-help status
+	$ guilt help status
 
 Open the guilt man page 
 
-	$ guilt-help
+	$ guilt help
 
 Author
 ------

diff --git a/Documentation/guilt-new.txt b/Documentation/guilt-new.txt
index a2c8a4c..698dcb7 100644
--- a/Documentation/guilt-new.txt
+++ b/Documentation/guilt-new.txt

@@ -42,16 +42,16 @@ EXAMPLES
 
 Create a new patch called 'foobar':
 
-	$ guilt-new foobar
+	$ guilt new foobar
 
 Create a patch called 'foo' and supply a patch description interactively:
 
-	$ guilt-new -e foo
+	$ guilt new -e foo
 
 Create a patch called 'bar' with a provided patch description and sign off
 on the patch:
 
-	$ guilt-new -s -m patch-fu bar
+	$ guilt new -s -m patch-fu bar
 
 Author
 ------

diff --git a/Documentation/guilt-repair.txt b/Documentation/guilt-repair.txt
index 4aa472b..4faf113 100644
--- a/Documentation/guilt-repair.txt
+++ b/Documentation/guilt-repair.txt

@@ -22,7 +22,7 @@ Perform various repository repairs. You must specify one mode of repair:
 	WARNING: Running this command may result in commits and working
 	directory changes being lost. You may want to create a new reference
 	(e.g., branch, or reflog) to the original HEAD before using
-	guilt-repair.
+	"guilt repair".
 
 --status::
 	Upgrade the status file from old format to new.

diff --git a/Documentation/guilt-select.txt b/Documentation/guilt-select.txt
index f7fb5f7..dd5833e 100644
--- a/Documentation/guilt-select.txt
+++ b/Documentation/guilt-select.txt

@@ -19,10 +19,10 @@ the following way:
 * An unguarded patch is always applied.
 
 * A patch with a positive guard is applied *only* if the guard is
-selected with guilt-select.
+selected with "+guilt select+".
 
 * A patch with a negative guard is applied *unless* the guard is
-selected with guilt-select.
+selected with "+guilt select+".
 
 OPTIONS
 -------

-- 
2.1.0

Signed-off-by: Per Cederqvist <redacted>
---
 Documentation/usage.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/usage.sh b/Documentation/usage.sh
index 629f546..9cc49f7
--- a/Documentation/usage.sh
+++ b/Documentation/usage.sh

@@ -2,4 +2,4 @@
 
 name=$(basename $1)
 u=$(grep USAGE $1 |  sed 's/USAGE="//' | sed 's/"$//') 
-echo "'$name' $u"  > usage-$name.txt
+echo "'`echo $name|sed -e 's/^guilt-/guilt /'`' $u"  > usage-$name.txt

-- 
2.1.0

Make them into reference to the man pages instead.

Signed-off-by: Per Cederqvist <redacted>
---
 Documentation/guilt-add.txt     | 2 +-
 Documentation/guilt-refresh.txt | 2 +-
 Documentation/guilt-rm.txt      | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/guilt-add.txt b/Documentation/guilt-add.txt
index a276f09..067b6ca 100644
--- a/Documentation/guilt-add.txt
+++ b/Documentation/guilt-add.txt

@@ -11,7 +11,7 @@ include::usage-guilt-add.txt[]
 
 DESCRIPTION
 -----------
-Adds the files specified to git using git-add making it available to guilt.
+Adds the files specified to git using git-add(1) making it available to guilt.
 
 OPTIONS
 -------

diff --git a/Documentation/guilt-refresh.txt b/Documentation/guilt-refresh.txt
index 7757bdc..98076e3 100644
--- a/Documentation/guilt-refresh.txt
+++ b/Documentation/guilt-refresh.txt

@@ -23,7 +23,7 @@ OPTIONS
 Include a diffstat output in the patch file. Useful for cases where
 patches will be submitted with other tools.
 +
-If the command line option is omitted, the corresponding git-config
+If the command line option is omitted, the corresponding git-config(1)
 option "guilt.diffstat" will be queried. So this would enable diffstat
 output by default:
 

diff --git a/Documentation/guilt-rm.txt b/Documentation/guilt-rm.txt
index 71b49fe..cfe471e 100644
--- a/Documentation/guilt-rm.txt
+++ b/Documentation/guilt-rm.txt

@@ -11,7 +11,7 @@ include::usage-guilt-rm.txt[]
 
 DESCRIPTION
 -----------
-Removes the files specified from git using git-rm
+Removes the files specified from git using git-rm(1).
 
 OPTIONS
 -------

-- 
2.1.0

On Fri, Jan 23, 2015 at 02:24:55PM +0100, Per Cederqvist wrote:

The old rule worked, most of the time, but had several issues:

 - It depended on the corresponding guilt-*.txt file, but the usage.sh
   script actually reads ../guilt-foo.

 - Actually, each usage-%.txt depended on all guilt-*.txt files, so
   make had to do more work than necessary if a single file was
   altered.

 - The construct broke parallel make, which would spawn several
   usage.sh at once.  This leads to unnecessary work, and could
   potentially result in broken usage files if the "echo some_string >
   some_file" construct used by usage.sh isn't atomic.

Fixed by letting the usage.sh script update a single file, and writing
a proper implicit make rule.  This makes parallel make work a lot
better.

Nice!

There is a small downside, though, as usage.sh will now be run once
for each command (if everything is regenerated).  I think it is worth
to pay that price to get the correctness.  This command is still very
fast compared to the docbook processing.

Given how much simple usage.sh got, I'm thinking it might be worth it to
just remove it, and just shove the rule into the makefile itself.

Ok, I tried to write it.  I came up with the following.  (Note: I have *not*
tested it.)  It's not *that* ugly.

usage-guilt-%.txt: ../guilt-% usage.sh
	echo "'$(basename $<)' `sed -n -e '/^USAGE=/{s/USAGE="//; s/"$//; p; q}' $<`" > $@

What do you think?  Too opaque?  Your change looks good.

Jeff.

-- 
The reasonable man adapts himself to the world; the unreasonable one
persists in trying to adapt the world to himself. Therefore all progress
depends on the unreasonable man.
		- George Bernard Shaw

Signed-off-by: Josef 'Jeff' Sipek <redacted>

On Fri, Jan 23, 2015 at 02:24:56PM +0100, Per Cederqvist wrote:

-- 
The obvious mathematical breakthrough would be development of an easy way to
factor large prime numbers.
		- Bill Gates, The Road Ahead, pg. 265

On Fri, Jan 23, 2015 at 02:24:57PM +0100, Per Cederqvist wrote:

Note: there is one place where I replace guilt-repair with "guilt
repair" instead of "+guilt repair+".  At least the version of docbook
I'm using mishandles the "+" signs in that particular spot (even
though it works properly for "+guilt select+" in another file.  I know
too little docbook to be able to find the cause.

Yeah, a bit of a mystery to me too.  Regardless,

Signed-off-by: Josef 'Jeff' Sipek <redacted>

-- 
mainframe, n.:
  An obsolete device still used by thousands of obsolete companies serving
  billions of obsolete customers and making huge obsolete profits for their
  obsolete shareholders. And this year's run twice as fast as last year's.

Ah, I see you changed usage.sh here.  I guess that kinda invalidates my
comment for patch 1/5.

On Fri, Jan 23, 2015 at 02:24:58PM +0100, Per Cederqvist wrote:

Tiny nitpick: spaces around the |, otherwise looks good.

Signed-off-by: Josef 'Jeff' Sipek <redacted>

-- 
2.1.0

-- 
Si hoc legere scis nimium eruditionis habes.

Signed-off-by: Josef 'Jeff' Sipek <redacted>

On Fri, Jan 23, 2015 at 02:24:59PM +0100, Per Cederqvist wrote:

-- 
The obvious mathematical breakthrough would be development of an easy way to
factor large prime numbers.
		- Bill Gates, The Road Ahead, pg. 265

On Fri, Jan 23, 2015 at 3:21 PM, Jeff Sipek [off-list ref] wrote:

On Fri, Jan 23, 2015 at 02:24:55PM +0100, Per Cederqvist wrote:

quoted

The old rule worked, most of the time, but had several issues:

 - It depended on the corresponding guilt-*.txt file, but the usage.sh
   script actually reads ../guilt-foo.

 - Actually, each usage-%.txt depended on all guilt-*.txt files, so
   make had to do more work than necessary if a single file was
   altered.

 - The construct broke parallel make, which would spawn several
   usage.sh at once.  This leads to unnecessary work, and could
   potentially result in broken usage files if the "echo some_string >
   some_file" construct used by usage.sh isn't atomic.

Fixed by letting the usage.sh script update a single file, and writing
a proper implicit make rule.  This makes parallel make work a lot
better.

Nice!

quoted

There is a small downside, though, as usage.sh will now be run once
for each command (if everything is regenerated).  I think it is worth
to pay that price to get the correctness.  This command is still very
fast compared to the docbook processing.

Given how much simple usage.sh got, I'm thinking it might be worth it to
just remove it, and just shove the rule into the makefile itself.

Ok, I tried to write it.  I came up with the following.  (Note: I have *not*
tested it.)  It's not *that* ugly.

usage-guilt-%.txt: ../guilt-% usage.sh
        echo "'$(basename $<)' `sed -n -e '/^USAGE=/{s/USAGE="//; s/"$//; p; q}' $<`" > $@

What do you think?  Too opaque?  Your change looks good.

Too opaque, and not tested enough. It doesn't work, since make will
handle all $.  You need to write $$ instead of $ in at least one of the
places.  I would stick with usage.sh, as getting the quoting right when
you have make, shell, subshells, and sed all at the same time is just
too painful.

But it is of course up to you. You are the maintainer. :-)

    /ceder

Jeff.

quoted

Signed-off-by: Per Cederqvist <redacted>
---
 Documentation/Makefile | 4 ++--
 Documentation/usage.sh | 8 +++-----
 2 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b6c3285..ec3c9e8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -66,8 +66,8 @@ clean:
      rm -f usage-*.txt
      rm -f version.txt

-usage-%.txt: $(MAN1_TXT) usage.sh
-     sh ./usage.sh
+usage-guilt-%.txt: ../guilt-% usage.sh
+     sh ./usage.sh $<

 %.html : %.txt footer.txt version.txt
      $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<

diff --git a/Documentation/usage.sh b/Documentation/usage.sh
index 20fdca4..629f546 100644
--- a/Documentation/usage.sh
+++ b/Documentation/usage.sh

@@ -1,7 +1,5 @@
 #!/bin/sh

-for i in `ls ../guilt-*`; do
-     name=$(basename $i)
-     u=$(grep USAGE $i |  sed 's/USAGE="//' | sed 's/"$//')
-     echo "'$name' $u"  > usage-$name.txt
-done
+name=$(basename $1)
+u=$(grep USAGE $1 |  sed 's/USAGE="//' | sed 's/"$//')
+echo "'$name' $u"  > usage-$name.txt
--

2.1.0

--
The reasonable man adapts himself to the world; the unreasonable one
persists in trying to adapt the world to himself. Therefore all progress
depends on the unreasonable man.
                - George Bernard Shaw

On Fri, Jan 23, 2015 at 03:33:03PM +0100, Per Cederqvist wrote:

On Fri, Jan 23, 2015 at 3:21 PM, Jeff Sipek [off-list ref] wrote:

quoted

On Fri, Jan 23, 2015 at 02:24:55PM +0100, Per Cederqvist wrote:

quoted

The old rule worked, most of the time, but had several issues:

 - It depended on the corresponding guilt-*.txt file, but the usage.sh
   script actually reads ../guilt-foo.

 - Actually, each usage-%.txt depended on all guilt-*.txt files, so
   make had to do more work than necessary if a single file was
   altered.

 - The construct broke parallel make, which would spawn several
   usage.sh at once.  This leads to unnecessary work, and could
   potentially result in broken usage files if the "echo some_string >
   some_file" construct used by usage.sh isn't atomic.

Fixed by letting the usage.sh script update a single file, and writing
a proper implicit make rule.  This makes parallel make work a lot
better.

Nice!

quoted

There is a small downside, though, as usage.sh will now be run once
for each command (if everything is regenerated).  I think it is worth
to pay that price to get the correctness.  This command is still very
fast compared to the docbook processing.

Given how much simple usage.sh got, I'm thinking it might be worth it to
just remove it, and just shove the rule into the makefile itself.

Ok, I tried to write it.  I came up with the following.  (Note: I have *not*
tested it.)  It's not *that* ugly.

usage-guilt-%.txt: ../guilt-% usage.sh
        echo "'$(basename $<)' `sed -n -e '/^USAGE=/{s/USAGE="//; s/"$//; p; q}' $<`" > $@

What do you think?  Too opaque?  Your change looks good.

Too opaque,

Between that and the other patch in the series that modifies usage.sh, your
patch is good as is.

Signed-off-by: Josef 'Jeff' Sipek <redacted>

and not tested enough. It doesn't work, since make will
handle all $.  You need to write $$ instead of $ in at least one of the
places.  I would stick with usage.sh, as getting the quoting right when
you have make, shell, subshells, and sed all at the same time is just
too painful.

And this is comming from the person that rewrote cmd/shouldfail in a way
that the average shell user will go "whaaa??" :P  (To be fair, I don't know
of a simpler way to make cmd/shouldfail.)

But it is of course up to you. You are the maintainer. :-)

Heh.

Jeff.

-- 
Real Programmers consider "what you see is what you get" to be just as bad a
concept in Text Editors as it is in women. No, the Real Programmer wants a
"you asked for it, you got it" text editor -- complicated, cryptic,
powerful, unforgiving, dangerous.