"notmuch help" outputs to stderr?

"notmuch help" outputs to stderr?

[Lars Kellogg-Stedman]

[-- Attachment #1.1: Type: text/plain, Size: 542 bytes --]

I'm just noticing that 'notmuch help ...' outputs to stderr, which
isn't terribly intuitive.  For example, the obvious invocation:

  notmuch help | less

...isn't terribly helpful.

I've attached a patch that lets usage() take a FILE * argument so that
you can output to stderr in response to usage errors, and stdout in
response to an explicit request.

-- 
Lars Kellogg-Stedman <lars@seas.harvard.edu>
Senior Technologist, Computing and Information Technology
Harvard University School of Engineering and Applied Sciences


[-- Attachment #1.2: notmuch-help.patch --]
[-- Type: text/plain, Size: 1386 bytes --]

diff --git a/notmuch.c b/notmuch.c
index c47e640..a35cb99 100644
--- a/notmuch.c
+++ b/notmuch.c
@@ -157,23 +157,23 @@ command_t commands[] = {
 };
 
 static void
-usage (void)
+usage (FILE *out)
 {
     command_t *command;
     unsigned int i;
 
-    fprintf (stderr, "Usage: notmuch <command> [args...]\n");
-    fprintf (stderr, "\n");
-    fprintf (stderr, "Where <command> and [args...] are as follows:\n");
-    fprintf (stderr, "\n");
+    fprintf (out, "Usage: notmuch <command> [args...]\n");
+    fprintf (out, "\n");
+    fprintf (out, "Where <command> and [args...] are as follows:\n");
+    fprintf (out, "\n");
 
     for (i = 0; i < ARRAY_SIZE (commands); i++) {
 	command = &commands[i];
 
-	fprintf (stderr, "\t%s\t%s\n\n", command->name, command->summary);
+	fprintf (out, "\t%s\t%s\n\n", command->name, command->summary);
     }
 
-    fprintf (stderr, "Use \"notmuch help <command>\" for more details on each command.\n\n");
+    fprintf (out, "Use \"notmuch help <command>\" for more details on each command.\n\n");
 }
 
 static int
@@ -183,8 +183,8 @@ notmuch_help_command (unused (void *ctx), int argc, char *argv[])
     unsigned int i;
 
     if (argc == 0) {
-	fprintf (stderr, "The notmuch mail system.\n\n");
-	usage ();
+	fprintf (stdout, "The notmuch mail system.\n\n");
+	usage (stdout);
 	return 0;
     }
 

[-- Attachment #2: Type: application/pgp-signature, Size: 489 bytes --]

Re: "notmuch help" outputs to stderr?

[Lars Kellogg-Stedman]

[-- Attachment #1.1: Type: text/plain, Size: 437 bytes --]

> I've attached a patch that lets usage() take a FILE * argument so that
> you can output to stderr in response to usage errors, and stdout in
> response to an explicit request.

Whoops, missed a couple of stderr's in that last patch.  New one
attached.

-- 
Lars Kellogg-Stedman <lars@seas.harvard.edu>
Senior Technologist, Computing and Information Technology
Harvard University School of Engineering and Applied Sciences


[-- Attachment #1.2: notmuch-help.patch --]
[-- Type: text/plain, Size: 1878 bytes --]

diff --git a/notmuch.c b/notmuch.c
index c47e640..446c810 100644
--- a/notmuch.c
+++ b/notmuch.c
@@ -157,23 +157,23 @@ command_t commands[] = {
 };
 
 static void
-usage (void)
+usage (FILE *out)
 {
     command_t *command;
     unsigned int i;
 
-    fprintf (stderr, "Usage: notmuch <command> [args...]\n");
-    fprintf (stderr, "\n");
-    fprintf (stderr, "Where <command> and [args...] are as follows:\n");
-    fprintf (stderr, "\n");
+    fprintf (out, "Usage: notmuch <command> [args...]\n");
+    fprintf (out, "\n");
+    fprintf (out, "Where <command> and [args...] are as follows:\n");
+    fprintf (out, "\n");
 
     for (i = 0; i < ARRAY_SIZE (commands); i++) {
 	command = &commands[i];
 
-	fprintf (stderr, "\t%s\t%s\n\n", command->name, command->summary);
+	fprintf (out, "\t%s\t%s\n\n", command->name, command->summary);
     }
 
-    fprintf (stderr, "Use \"notmuch help <command>\" for more details on each command.\n\n");
+    fprintf (out, "Use \"notmuch help <command>\" for more details on each command.\n\n");
 }
 
 static int
@@ -183,8 +183,8 @@ notmuch_help_command (unused (void *ctx), int argc, char *argv[])
     unsigned int i;
 
     if (argc == 0) {
-	fprintf (stderr, "The notmuch mail system.\n\n");
-	usage ();
+	fprintf (stdout, "The notmuch mail system.\n\n");
+	usage (stdout);
 	return 0;
     }
 
@@ -192,8 +192,8 @@ notmuch_help_command (unused (void *ctx), int argc, char *argv[])
 	command = &commands[i];
 
 	if (strcmp (argv[0], command->name) == 0) {
-	    fprintf (stderr, "Help for \"notmuch %s\":\n\n", argv[0]);
-	    fprintf (stderr, "\t%s\t%s\n\n%s\n\n", command->name,
+	    fprintf (stdout, "Help for \"notmuch %s\":\n\n", argv[0]);
+	    fprintf (stdout, "\t%s\t%s\n\n%s\n\n", command->name,
 		     command->summary, command->documentation);
 	    return 0;
 	}

[-- Attachment #2: Type: application/pgp-signature, Size: 489 bytes --]

Re: "notmuch help" outputs to stderr?

[Carl Worth]

On Tue, 17 Nov 2009 20:01:16 -0500, Lars Kellogg-Stedman <lars@seas.harvard.edu> wrote:
> > I've attached a patch that lets usage() take a FILE * argument so that
> > you can output to stderr in response to usage errors, and stdout in
> > response to an explicit request.
> 
> Whoops, missed a couple of stderr's in that last patch.  New one
> attached.
> 
> -- 
> Lars Kellogg-Stedman <lars@seas.harvard.edu>
> Senior Technologist, Computing and Information Technology
> Harvard University School of Engineering and Applied Sciences

Thanks Lars!

That was obviously a bug, so I really appreciate both your report and
your fix.

BTW, for future patches, it would be easier for me, (and hopefully not
too much harder for you), if you could format your mails so that "git
am" will find a good commit message in them. There are a few different
ways you can do that:

Option (1) takes more work upfront to get comfortable with it and to
make sure it works, but it's probably less work (particuarly 1.b with
"git send-email) once you get into the flow of it. Option (2) is
probably the least different from what you're currently doing.

1. Make a commit locally with the commit message. Then run "git
   format-patch", (with "git format-patch HEAD~N" where N is the number
   of commits you want to generate), to generate formatted email
   messages, (or even an entire mbox).

   a. Suck those messages up into an email program. Add any commentary
      (to not be part of the commit message) after the --- separator and
      send.

   b. Use "git send-email" to fire the messages off.

2. Just attach the "git diff" output like you did, but then carefully
   word the subject and body of the email message to look like a commit
   message. You can again use a --- separator for commentary that's not
   part of the patch.

For example, option (2) would have looked like the below to generate the
commit message I ended up using for your commit.

Anyway, thanks again,

-Carl

Subject: [Patch] notmuch help: Print to stdout, not to stderr.

Let usage() take a FILE * argument so that you can output to stderr in
response to usage errors, and stdout in response to an explicit request.

---

Whoops, missed a couple of stderr's in that last patch.  New one
attached.

-- 
Lars Kellogg-Stedman <lars@seas.harvard.edu>
Senior Technologist, Computing and Information Technology
Harvard University School of Engineering and Applied Sciences