From: Tomi Ollila <tomi.ollila@iki.fi>
To: David Bremner <bremner@unb.ca>, Notmuch Mail <notmuch@notmuchmail.org>
Subject: Re: have "notmuch help" call man?
In-Reply-To: <87zkescxp5.fsf@zancas.localnet>
References: <87zkescxp5.fsf@zancas.localnet>
User-Agent: Notmuch/0.10.2+93~g631d290 (http://notmuchmail.org) Emacs/23.3.1
	(i686-pc-linux-gnu)
Date: Sat, 17 Dec 2011 11:56:57 +0200
Message-ID: <yf61us35xna.fsf@taco2.nixu.fi>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Precedence: list

On Fri, 16 Dec 2011 12:01:42 -0400, David Bremner <bremner@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-david@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