have "notmuch help" call man?

[Austin Clements]

Quoth David Bremner on Dec 26 at  8:35 pm:
> The following changes since commit d61cef374b3234c2f1327fa74b612b40c196a605:
> 
>   show: Rewrite show_message_body to use the MIME tree interface. (2011-12-25 
> 22:23:15 -0400)
> 
> are available in the git repository at:
>   git://pivot.cs.unb.ca/notmuch split-man
> 
> HEAD is at 8eaee754e48dc630d83e2f7369bdadde0f34af84

Some comments on "notmuch: replace built-in help with exec of man"

> @@ -534,38 +126,20 @@ notmuch_help_command (unused (void *ctx), int argc, 
> char *argv[])
>  for (i = 0; i < ARRAY_SIZE (commands); i++) {
>   command = [i];
>  
> - if (strcmp (argv[0], command->name) == 0) {
> - printf ("Help for \"notmuch %s\":\n\n", argv[0]);
> - if (command->arguments)
> - printf ("%s %s\n\n\t%s\n\n%s\n\n",
> - command->name, command->arguments,
> - command->summary, command->documentation);
> - else
> - printf ("%s\t%s\n\n%s\n\n", command->name,
> - command->summary, command->documentation);
> - return 0;
> + if (strncmp (argv[0], command->name, strlen (argv[0])) == 0) {

Shouldn't this be strcmp?

> + char *page = malloc (strlen (argv[0]) + strlen ("notmuch-") + 1);
> + strcpy (page, "notmuch-");
> + strcat (page, command->name);

This is fine, but could be cleaner with talloc:
  char *page = talloc_asprintf (ctx, "notmuch-%s", command->name);

> +
> + execlp ("man", "man", page, (char *) NULL);
> + /* NOTREACHED */

This certainly *can* be reached if the exec fails.  You should print a
helpful error message and exit, maybe something like
  fprintf (stderr, "failed to exec man: %s\n", strerror (errno));
  exit (1);

>   }
>  }
>  
> -if (strcmp (argv[0], "search-terms") == 0) {
> - printf ("Help for <%s>\n\n", argv[0]);
> - for (i = 0; i < ARRAY_SIZE (commands); i++) {
> - command = [i];
> -
> - if (command->arguments &&
> - strstr (command->arguments, "search-terms"))
> - {
> - printf ("\t%s\t%s\n",
> - command->name, command->arguments);
> - }
> - }
> - printf ("\n");
> - printf (search_terms_help);
> - return 0;
> -} else if (strcmp (argv[0], "hooks") == 0) {
> - printf ("Help for <%s>\n\n", argv[0]);
> - printf (hooks_help);
> - return 0;
> +if (strncmp (argv[0], "search-terms", strlen (argv[0])) == 0) {
> + execlp ("man", "man", "notmuch-search-terms", (char *) NULL);
> +} else if (strncmp (argv[0], "hooks", strlen (argv[0])) == 0) {
> + execlp ("man", "man", "notmuch-hooks", (char *) NULL);

Same comments about strncmp and exec failing for the above four lines.
It might make sense to merge all of the exec calls in to one to
centralize the error handling.

>  }
>  
>  fprintf (stderr,

Re: have notmuch help call man?

[Austin Clements]

Quoth David Bremner on Dec 26 at  8:35 pm:
 The following changes since commit d61cef374b3234c2f1327fa74b612b40c196a605:
 
   show: Rewrite show_message_body to use the MIME tree interface. (2011-12-25 
 22:23:15 -0400)
 
 are available in the git repository at:
   git://pivot.cs.unb.ca/notmuch split-man
 
 HEAD is at 8eaee754e48dc630d83e2f7369bdadde0f34af84

Some comments on notmuch: replace built-in help with exec of man

 @@ -534,38 +126,20 @@ notmuch_help_command (unused (void *ctx), int argc, 
 char *argv[])
  for (i = 0; i  ARRAY_SIZE (commands); i++) {
   command = commands[i];
  
 - if (strcmp (argv[0], command-name) == 0) {
 - printf (Help for \notmuch %s\:\n\n, argv[0]);
 - if (command-arguments)
 - printf (%s %s\n\n\t%s\n\n%s\n\n,
 - command-name, command-arguments,
 - command-summary, command-documentation);
 - else
 - printf (%s\t%s\n\n%s\n\n, command-name,
 - command-summary, command-documentation);
 - return 0;
 + if (strncmp (argv[0], command-name, strlen (argv[0])) == 0) {

Shouldn't this be strcmp?

 + char *page = malloc (strlen (argv[0]) + strlen (notmuch-) + 1);
 + strcpy (page, notmuch-);
 + strcat (page, command-name);

This is fine, but could be cleaner with talloc:
  char *page = talloc_asprintf (ctx, notmuch-%s, command-name);

 +
 + execlp (man, man, page, (char *) NULL);
 + /* NOTREACHED */

This certainly *can* be reached if the exec fails.  You should print a
helpful error message and exit, maybe something like
  fprintf (stderr, failed to exec man: %s\n, strerror (errno));
  exit (1);

   }
  }
  
 -if (strcmp (argv[0], search-terms) == 0) {
 - printf (Help for %s\n\n, argv[0]);
 - for (i = 0; i  ARRAY_SIZE (commands); i++) {
 - command = commands[i];
 -
 - if (command-arguments 
 - strstr (command-arguments, search-terms))
 - {
 - printf (\t%s\t%s\n,
 - command-name, command-arguments);
 - }
 - }
 - printf (\n);
 - printf (search_terms_help);
 - return 0;
 -} else if (strcmp (argv[0], hooks) == 0) {
 - printf (Help for %s\n\n, argv[0]);
 - printf (hooks_help);
 - return 0;
 +if (strncmp (argv[0], search-terms, strlen (argv[0])) == 0) {
 + execlp (man, man, notmuch-search-terms, (char *) NULL);
 +} else if (strncmp (argv[0], hooks, strlen (argv[0])) == 0) {
 + execlp (man, man, notmuch-hooks, (char *) NULL);

Same comments about strncmp and exec failing for the above four lines.
It might make sense to merge all of the exec calls in to one to
centralize the error handling.

  }
  
  fprintf (stderr,
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

have "notmuch help" call man?

[David Bremner]

On Wed, 21 Dec 2011 20:53:08 -0800, Jameson Graef Rollins  wrote:

> I think what you've done looks great.  A couple small issues:
> 
> * There are a couple of formatting issues (notmuch.1, notmuch-config.1,
>   notmuch-reply.1).

Hopefully I caught most of the formatting issues.

> 
> * The notmuch part command is completely deprecated, so I don't think
>   there's really any reason to include a man page for it.

removed.

> 
> * There's no man page for restore (notmuch-restore.1).
> 
There is a link in the source tree now (the link is recreated at install
time); notmuch dump and restore will share options, so I think it makes
sense to be in the same page.

The following changes since commit d61cef374b3234c2f1327fa74b612b40c196a605:

  show: Rewrite show_message_body to use the MIME tree interface. (2011-12-25 
22:23:15 -0400)

are available in the git repository at:
  git://pivot.cs.unb.ca/notmuch split-man

HEAD is at 8eaee754e48dc630d83e2f7369bdadde0f34af84

David Bremner (10):
  initial splitting of notmuch.1
  remove notmuch-part from documentation.
  man: add symlinks for notmuch-restore.1 and notmuch-setup.1
  man/*: formatting cleanup
  notmuch.1: smooth wording.
  notmuch-config.1: fix typo
  man/*: fixup page references
  build-system: update for split man pages
  debian: install split man pages.
  notmuch: replace built-in help with exec of man

 Makefile|2 +-
 Makefile.local  |   22 +-
 debian/notmuch.install  |2 +-
 man/Makefile|5 +
 man/Makefile.local  |   61 +++
 man/man1/notmuch-config.1   |   54 +++
 man/man1/notmuch-count.1|   50 +++
 man/man1/notmuch-dump.1 |   62 +++
 man/man1/notmuch-new.1  |   65 
 man/man1/notmuch-reply.1|   65 
 man/man1/notmuch-restore.1  |1 +
 man/man1/notmuch-search.1   |  121 ++
 man/man1/notmuch-setup.1|1 +
 man/man1/notmuch-show.1 |  145 
 man/man1/notmuch-tag.1  |   32 ++
 man/man1/notmuch.1  |  148 
 man/man5/notmuch-hooks.5|   48 +++
 man/man7/notmuch-search-terms.7 |  141 +++
 notmuch.1   |  776 ---
 notmuch.c   |  472 ++--
 20 files changed, 1028 insertions(+), 1245 deletions(-)
 create mode 100644 man/Makefile
 create mode 100644 man/Makefile.local
 create mode 100644 man/man1/notmuch-config.1
 create mode 100644 man/man1/notmuch-count.1
 create mode 100644 man/man1/notmuch-dump.1
 create mode 100644 man/man1/notmuch-new.1
 create mode 100644 man/man1/notmuch-reply.1
 create mode 12 man/man1/notmuch-restore.1
 create mode 100644 man/man1/notmuch-search.1
 create mode 12 man/man1/notmuch-setup.1
 create mode 100644 man/man1/notmuch-show.1
 create mode 100644 man/man1/notmuch-tag.1
 create mode 100644 man/man1/notmuch.1
 create mode 100644 man/man5/notmuch-hooks.5
 create mode 100644 man/man7/notmuch-search-terms.7
 delete mode 100644 notmuch.1

-- next part --
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 315 bytes
Desc: not available
URL: 

Re: have notmuch help call man?

[David Bremner]

On Wed, 21 Dec 2011 20:53:08 -0800, Jameson Graef Rollins 
jroll...@finestructure.net wrote:

 I think what you've done looks great.  A couple small issues:
 
 * There are a couple of formatting issues (notmuch.1, notmuch-config.1,
   notmuch-reply.1).

Hopefully I caught most of the formatting issues.

 
 * The notmuch part command is completely deprecated, so I don't think
   there's really any reason to include a man page for it.

removed.

 
 * There's no man page for restore (notmuch-restore.1).
 
There is a link in the source tree now (the link is recreated at install
time); notmuch dump and restore will share options, so I think it makes
sense to be in the same page.

The following changes since commit d61cef374b3234c2f1327fa74b612b40c196a605:

  show: Rewrite show_message_body to use the MIME tree interface. (2011-12-25 
22:23:15 -0400)

are available in the git repository at:
  git://pivot.cs.unb.ca/notmuch split-man

HEAD is at 8eaee754e48dc630d83e2f7369bdadde0f34af84

David Bremner (10):
  initial splitting of notmuch.1
  remove notmuch-part from documentation.
  man: add symlinks for notmuch-restore.1 and notmuch-setup.1
  man/*: formatting cleanup
  notmuch.1: smooth wording.
  notmuch-config.1: fix typo
  man/*: fixup page references
  build-system: update for split man pages
  debian: install split man pages.
  notmuch: replace built-in help with exec of man

 Makefile|2 +-
 Makefile.local  |   22 +-
 debian/notmuch.install  |2 +-
 man/Makefile|5 +
 man/Makefile.local  |   61 +++
 man/man1/notmuch-config.1   |   54 +++
 man/man1/notmuch-count.1|   50 +++
 man/man1/notmuch-dump.1 |   62 +++
 man/man1/notmuch-new.1  |   65 
 man/man1/notmuch-reply.1|   65 
 man/man1/notmuch-restore.1  |1 +
 man/man1/notmuch-search.1   |  121 ++
 man/man1/notmuch-setup.1|1 +
 man/man1/notmuch-show.1 |  145 
 man/man1/notmuch-tag.1  |   32 ++
 man/man1/notmuch.1  |  148 
 man/man5/notmuch-hooks.5|   48 +++
 man/man7/notmuch-search-terms.7 |  141 +++
 notmuch.1   |  776 ---
 notmuch.c   |  472 ++--
 20 files changed, 1028 insertions(+), 1245 deletions(-)
 create mode 100644 man/Makefile
 create mode 100644 man/Makefile.local
 create mode 100644 man/man1/notmuch-config.1
 create mode 100644 man/man1/notmuch-count.1
 create mode 100644 man/man1/notmuch-dump.1
 create mode 100644 man/man1/notmuch-new.1
 create mode 100644 man/man1/notmuch-reply.1
 create mode 12 man/man1/notmuch-restore.1
 create mode 100644 man/man1/notmuch-search.1
 create mode 12 man/man1/notmuch-setup.1
 create mode 100644 man/man1/notmuch-show.1
 create mode 100644 man/man1/notmuch-tag.1
 create mode 100644 man/man1/notmuch.1
 create mode 100644 man/man5/notmuch-hooks.5
 create mode 100644 man/man7/notmuch-search-terms.7
 delete mode 100644 notmuch.1



pgpUjASb62xSU.pgp
Description: PGP signature
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

have "notmuch help" call man?

[David Bremner]

On Wed, 21 Dec 2011 20:53:08 -0800, Jameson Graef Rollins  wrote:

> * There are a couple of formatting issues (notmuch.1, notmuch-config.1,
>   notmuch-reply.1).

I'm sure there are. Can you be more specific? I suspect I might fix a
different set of problems than you found ;).

> * The notmuch part command is completely deprecated, so I don't think
>   there's really any reason to include a man page for it.

I'm not sure if removing that would be "doing too many things at once";
it is in the current man page. But maybe that was an oversight?

> * There's no man page for restore (notmuch-restore.1).

Currently the symlink to notmuch-dump.1.gz is installed at runtime. I
agree this is a bit inconvenient for testing; I think it should work to
have symlinks in the source just for the convenience of testers.

> It also occurs to me while looking through this: do we really need a
> separate "setup" command?  

I guess notmuch-setup is a UI convenience mainly for people who want to
re-run setup.  It doesn't feel as natural to me to run notmuch without
arguments in this case. I couldn't really justify that, though.

Thanks for the review,

David

Re: have notmuch help call man?

[David Bremner]

On Wed, 21 Dec 2011 20:53:08 -0800, Jameson Graef Rollins 
jroll...@finestructure.net wrote:

 * There are a couple of formatting issues (notmuch.1, notmuch-config.1,
   notmuch-reply.1).

I'm sure there are. Can you be more specific? I suspect I might fix a
different set of problems than you found ;).

 * The notmuch part command is completely deprecated, so I don't think
   there's really any reason to include a man page for it.

I'm not sure if removing that would be doing too many things at once;
it is in the current man page. But maybe that was an oversight?

 * There's no man page for restore (notmuch-restore.1).

Currently the symlink to notmuch-dump.1.gz is installed at runtime. I
agree this is a bit inconvenient for testing; I think it should work to
have symlinks in the source just for the convenience of testers.

 It also occurs to me while looking through this: do we really need a
 separate setup command?  

I guess notmuch-setup is a UI convenience mainly for people who want to
re-run setup.  It doesn't feel as natural to me to run notmuch without
arguments in this case. I couldn't really justify that, though.

Thanks for the review,

David
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

have "notmuch help" call man?

[David Bremner]

On Tue, 20 Dec 2011 00:16:47 -0400, David Bremner  wrote:

> You can also look at the patches in git://pivot.cs.unb.ca/notmuch 
> branch split-man

I made some progress.

The man pages are now installed, a notmuch help (built from this branch)
uses them.

The hacks we added to update and check the versions in the man page need
to be re-done or maybe re-thought; perhaps some simple preprocessing
with m4 or equivalent is in order to embed version numbers.

All going well, I'd like to push these relatively soon after we freeze
0.11, so that future documentation changes can take advantage of doing
it in one place.

I'm not sure if posting the patches make sense; it's up to 74k of diffs,
even using "git format-patch -D".  I'm open to suggestions, as always.

d

have "notmuch help" call man?

[Jameson Graef Rollins]

On Wed, 21 Dec 2011 23:43:09 -0400, David Bremner  wrote:
> The man pages are now installed, a notmuch help (built from this branch)
> uses them.

Hey, David this is really great.  Thank you so much for working on this.
This will make things much easier to maintain down the line.

I think what you've done looks great.  A couple small issues:

* There are a couple of formatting issues (notmuch.1, notmuch-config.1,
  notmuch-reply.1).

* The notmuch part command is completely deprecated, so I don't think
  there's really any reason to include a man page for it.

* There's no man page for restore (notmuch-restore.1).

It also occurs to me while looking through this: do we really need a
separate "setup" command?  Does that ever really get run?  Doesn't
notmuch new run the setup if it doesn't detect a config?  If there's
really reason to run it again at a later point, why don't we just have a
--setup option to notmuch new instead?  It would also make notmuch.1
cleaner if we removed it.

> I'm not sure if posting the patches make sense; it's up to 74k of diffs,
> even using "git format-patch -D".  I'm open to suggestions, as always.

While in general I think it's nice to have patches to the list, but I'm
not sure how much benefit there is in this case.  I would be fine to
just see the patch merged directly from your branch.

Again, thanks for the work on this, David.  This 

jamie.
-- next part --
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 835 bytes
Desc: not available
URL: 

Re: have notmuch help call man?

[David Bremner]

On Tue, 20 Dec 2011 00:16:47 -0400, David Bremner da...@tethera.net wrote:

 You can also look at the patches in git://pivot.cs.unb.ca/notmuch 
 branch split-man

I made some progress.

The man pages are now installed, a notmuch help (built from this branch)
uses them.

The hacks we added to update and check the versions in the man page need
to be re-done or maybe re-thought; perhaps some simple preprocessing
with m4 or equivalent is in order to embed version numbers.

All going well, I'd like to push these relatively soon after we freeze
0.11, so that future documentation changes can take advantage of doing
it in one place.

I'm not sure if posting the patches make sense; it's up to 74k of diffs,
even using git format-patch -D.  I'm open to suggestions, as always.

d


___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

Re: have notmuch help call man?

[Jameson Graef Rollins]

On Wed, 21 Dec 2011 23:43:09 -0400, David Bremner da...@tethera.net wrote:
 The man pages are now installed, a notmuch help (built from this branch)
 uses them.

Hey, David this is really great.  Thank you so much for working on this.
This will make things much easier to maintain down the line.

I think what you've done looks great.  A couple small issues:

* There are a couple of formatting issues (notmuch.1, notmuch-config.1,
  notmuch-reply.1).

* The notmuch part command is completely deprecated, so I don't think
  there's really any reason to include a man page for it.

* There's no man page for restore (notmuch-restore.1).

It also occurs to me while looking through this: do we really need a
separate setup command?  Does that ever really get run?  Doesn't
notmuch new run the setup if it doesn't detect a config?  If there's
really reason to run it again at a later point, why don't we just have a
--setup option to notmuch new instead?  It would also make notmuch.1
cleaner if we removed it.

 I'm not sure if posting the patches make sense; it's up to 74k of diffs,
 even using git format-patch -D.  I'm open to suggestions, as always.

While in general I think it's nice to have patches to the list, but I'm
not sure how much benefit there is in this case.  I would be fine to
just see the patch merged directly from your branch.

Again, thanks for the work on this, David.  This 

jamie.


pgpimNh5XrVkz.pgp
Description: PGP signature
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

have "notmuch help" call man?

[David Bremner]

On Fri, 16 Dec 2011 12:01:42 -0400, David Bremner  wrote:

> What do you think about having "notmuch help foo" invoke "man
> notmuch-foo" and create appropriate man pages (or links).

I started on this man page splitting. So far I have just been editing
the documents, which I attach.

The patches are a bit unwieldy, so I'm being a bad person and attaching
a tarball (about 20% of the size) for initial review.

You can also look at the patches in git://pivot.cs.unb.ca/notmuch 
branch split-man

-- next part --
A non-text attachment was scrubbed...
Name: man.tgz
Type: application/x-gtar-compressed
Size: 9160 bytes
Desc: not available
URL: 

Re: have notmuch help call man?

[David Bremner]

On Fri, 16 Dec 2011 12:01:42 -0400, David Bremner brem...@unb.ca wrote:

 What do you think about having notmuch help foo invoke man
 notmuch-foo and create appropriate man pages (or links).

I started on this man page splitting. So far I have just been editing
the documents, which I attach.

The patches are a bit unwieldy, so I'm being a bad person and attaching
a tarball (about 20% of the size) for initial review.

You can also look at the patches in git://pivot.cs.unb.ca/notmuch 
branch split-man



man.tgz
Description: application/gtar-compressed
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

have "notmuch help" call man?

[Tomi Ollila]

On Fri, 16 Dec 2011 12:01:42 -0400, David Bremner  wrote:
> 
> Hi All;
> 
> Currently help strings are compiled into the notmuch binary. This is a
> bit a of pain, since we have the same help text in two places.
> What do you think about having "notmuch help foo" invoke "man
> notmuch-foo" and create appropriate man pages (or links).

+1

> There are other ways around the maintenance dilemma, including
> generating man pages and online help from some common source (e.g. in
> the style of id:"1288804736-5173-3-git-send-email-david at tethera.net").

In that case we dilemma is what would be the most suitable source format
(pod, mdwn, rst, nroff, ...)...

> For downsides, it might complicate things slightly for people who
> install notmuch in "odd" places. On the other hand, it is no worse than
> setting LD_LIBRARY_PATH. Also, there is the question of common text like
> search-terms, which could be included in every page, or maybe contained
> in man notmuch.

Those people who install notmuch in "odd" places (I'm one of those) can
also define MANPATH...

Nroff provides the .so "request" which includes other nroff source.

for example /usr/share/man/man1/zshall.1.gz includes all other zsh
namual pages.

... however it is common to have SEE ALSO at the end of each manual page

SEE ALSO
notmuch(1), notmuch-search-terms(7)

> 
> David

Tomi

Re: have notmuch help call man?

[Tomi Ollila]

On Fri, 16 Dec 2011 12:01:42 -0400, David Bremner brem...@unb.ca wrote:
 
 Hi All;
 
 Currently help strings are compiled into the notmuch binary. This is a
 bit a of pain, since we have the same help text in two places.
 What do you think about having notmuch help foo invoke man
 notmuch-foo and create appropriate man pages (or links).

+1

 There are other ways around the maintenance dilemma, including
 generating man pages and online help from some common source (e.g. in
 the style of id:1288804736-5173-3-git-send-email-da...@tethera.net).

In that case we dilemma is what would be the most suitable source format
(pod, mdwn, rst, nroff, ...)...

 For downsides, it might complicate things slightly for people who
 install notmuch in odd places. On the other hand, it is no worse than
 setting LD_LIBRARY_PATH. Also, there is the question of common text like
 search-terms, which could be included in every page, or maybe contained
 in man notmuch.

Those people who install notmuch in odd places (I'm one of those) can
also define MANPATH...

Nroff provides the .so request which includes other nroff source.

for example /usr/share/man/man1/zshall.1.gz includes all other zsh
namual pages.

... however it is common to have SEE ALSO at the end of each manual page

SEE ALSO
notmuch(1), notmuch-search-terms(7)

 
 David

Tomi
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

have "notmuch help" call man?

[Kazuo Teramoto]

On 2011-12-16T14:01:42, David Bremner wrote:
>Also, there is the question of common text like search-terms, which
>could be included in every page, or maybe contained in man notmuch.
>

What about continuing the git-foo analogy and creating a notmuch search
terms page. Like how git-log page reference gitrevisions(7) for a
complete description of giving references.

And leave the notmuch page as a table of contents for the others
commands and definitions.

have "notmuch help" call man?

[Jameson Graef Rollins]

On Fri, 16 Dec 2011 12:01:42 -0400, David Bremner  wrote:
> Currently help strings are compiled into the notmuch binary. This is a
> bit a of pain, since we have the same help text in two places.
> What do you think about having "notmuch help foo" invoke "man
> notmuch-foo" and create appropriate man pages (or links).

Hey, David.  I am absolutely in favor of this idea.  I'm a fan of the
git help interface, so the more we can emulate that, and make it so we
only have to maintain documentation in one place, then that's a huge win
in my mind.

jamie.
-- next part --
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 835 bytes
Desc: not available
URL: 

have "notmuch help" call man?

[David Bremner]

Hi All;

Currently help strings are compiled into the notmuch binary. This is a
bit a of pain, since we have the same help text in two places.
What do you think about having "notmuch help foo" invoke "man
notmuch-foo" and create appropriate man pages (or links).

There are other ways around the maintenance dilemma, including
generating man pages and online help from some common source (e.g. in
the style of id:"1288804736-5173-3-git-send-email-david at tethera.net").

For downsides, it might complicate things slightly for people who
install notmuch in "odd" places. On the other hand, it is no worse than
setting LD_LIBRARY_PATH. Also, there is the question of common text like
search-terms, which could be included in every page, or maybe contained
in man notmuch.

David

have "notmuch help" call man?

[Adam Wolfe Gordon]

On Fri, Dec 16, 2011 at 09:01, David Bremner  wrote:
> Currently help strings are compiled into the notmuch binary. This is a
> bit a of pain, since we have the same help text in two places.
> What do you think about having "notmuch help foo" invoke "man
> notmuch-foo" and create appropriate man pages (or links).

I really like this git-style idea.  An additional plus is that long
help (e.g. notmuch help show) would be automatically paged, avoiding a
lot of !!|less.

-- 
Adam Wolfe Gordon

have notmuch help call man?

[David Bremner]

Hi All;

Currently help strings are compiled into the notmuch binary. This is a
bit a of pain, since we have the same help text in two places.
What do you think about having notmuch help foo invoke man
notmuch-foo and create appropriate man pages (or links).

There are other ways around the maintenance dilemma, including
generating man pages and online help from some common source (e.g. in
the style of id:1288804736-5173-3-git-send-email-da...@tethera.net).

For downsides, it might complicate things slightly for people who
install notmuch in odd places. On the other hand, it is no worse than
setting LD_LIBRARY_PATH. Also, there is the question of common text like
search-terms, which could be included in every page, or maybe contained
in man notmuch.

David
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

Re: have notmuch help call man?

[Kazuo Teramoto]

On 2011-12-16T14:01:42, David Bremner wrote:
Also, there is the question of common text like search-terms, which
could be included in every page, or maybe contained in man notmuch.


What about continuing the git-foo analogy and creating a notmuch search
terms page. Like how git-log page reference gitrevisions(7) for a
complete description of giving references.

And leave the notmuch page as a table of contents for the others
commands and definitions.

___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

Re: have notmuch help call man?

[Jameson Graef Rollins]

On Fri, 16 Dec 2011 12:01:42 -0400, David Bremner brem...@unb.ca wrote:
 Currently help strings are compiled into the notmuch binary. This is a
 bit a of pain, since we have the same help text in two places.
 What do you think about having notmuch help foo invoke man
 notmuch-foo and create appropriate man pages (or links).

Hey, David.  I am absolutely in favor of this idea.  I'm a fan of the
git help interface, so the more we can emulate that, and make it so we
only have to maintain documentation in one place, then that's a huge win
in my mind.

jamie.


pgpdYD9w7eIkh.pgp
Description: PGP signature
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch