From: Mark Walters <markwalters1009@gmail.com>
To: David Bremner <david@tethera.net>,
	Jameson Graef Rollins <jrollins@finestructure.net>,
	Jani Nikula <jani@nikula.org>, notmuch@notmuchmail.org
Subject: Re: [PATCH 0/6] notmuch cli config changes
In-Reply-To: <87pq05icse.fsf@convex-new.cs.unb.ca>
References: <cover.1359495450.git.jani@nikula.org>
	<871ucts54t.fsf@servo.finestructure.net>
	<87y5f0fhtd.fsf@zancas.localnet>
	<87fw12nf7w.fsf@servo.finestructure.net>
	<87k3qd92sw.fsf@zancas.localnet>
	<87a9r9o4ks.fsf@servo.finestructure.net>
	<87pq05icse.fsf@convex-new.cs.unb.ca>
User-Agent: Notmuch/0.14+255~gff3cc55 (http://notmuchmail.org) Emacs/23.4.1
	(x86_64-pc-linux-gnu)
Date: Wed, 13 Feb 2013 07:51:19 +0000
Message-ID: <87liaslki0.fsf@qmul.ac.uk>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Precedence: list


> Jameson Graef Rollins <jrollins@finestructure.net> writes:
>
>> But don't get me wrong, the CLI is one of the things that makes notmuch
>> so incredibly awesome.  It's an email swiss army knife that's there when
>> you need it.  But given that even I often need to look at the man page
>> during my occasional CLI usage, I just don't want to see it get to
>> overcrowded.
>
> Well, maybe this should be a discussion about how to organize the CLI
> documentation so that more commonly used options are easy to find. That
> would indeed be a side effect of making less commonly used options
> controlled by environment variables, and documenting the environment
> variables at the bottom of the man pages as per tradition. But I don't
> think this is the only way or even the best way to achieve good
> documentation.

I think one of the problems for documentation is that we have two
classes of "user" of the cli: one is actually people and one is front
ends (and yes scripting does blur the boundary). Would it be worth
splitting based on that. For example, the --format-version is really
only for front-end use. --format=text is for human use, whereas the
other options are mostly front-end (text0 might be an exception)

Best wishes

Mark