To: Carl Worth <cworth@cworth.org>, notmuch <notmuch@notmuchmail.org>
In-Reply-To: <87bpe2j2vu.fsf@yoom.home.cworth.org>
References: <87oci344n4.fsf@ut.hh.sledj.net>
	<87bpe2j2vu.fsf@yoom.home.cworth.org>
From: David Edmondson <dme@dme.org>
Date: Fri, 02 Apr 2010 09:53:04 +0100
Message-ID: <87oci2xmkv.fsf@ut.hh.sledj.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Subject: Re: [notmuch] pull request
Precedence: list

On Thu, 01 Apr 2010 14:09:57 -0700, Carl Worth <cworth@cworth.org> wrote:
> On Thu, 01 Apr 2010 15:41:03 +0100, David Edmondson <dme@dme.org> wrote:
> > Carl, a couple of patches that I'd like you to consider. They are the
> > first two on the `dme' branch of git://github.com/dme/notmuch.git.

The updated changes are on the 'dme-for-cworth' branch now.

> > http://github.com/dme/notmuch/commit/f86254e4509ed02731aa3eaa8541df1f2d11e400
> > > notmuch-show: Add unix and pretty dates to the JSON output
> > > 
> > > Include a 'date_unix' and 'date_pretty' field in the JSON output for
> > > each message. 'date_pretty' can be used by a UI implementation,
> > > whereas 'date_unix' is useful when scripting.
> 
> With "date_unix" it's easy enough to guess what the value is. But
> "date_pretty" is much more ambiguous. I assumed that this would be an
> RFC 822 date string, (but then found that it's the relative date that
> "notmuch show" is using currently).
> 
> I think I'd rather see that named "date_relative", (or dropped with the
> expectation that callers can decide how to format dates on their own).

I renamed it to 'date_relative'.

Keeping the creation of the relative date strings in one place struck me
as a good idea - there will consistency between the two places it is
used (search mode and show mode) and if the `notmuch' command is
localised the Emacs UI will immediately benefit.

> > > The search terms should match only a single message
> > > (e.g. id:foo@bar.com). The part number specified refers to the part
> > > identifiers output by `notmuch show'. The content of the part is written
> > > the stdout with no formatting or identification marks. It is not JSON
> > > formatted.
> 
> The above documentation isn't quite complete to me. Is MIME decoding
> handled by this or not? Also, the documentation says the search terms
> "should match" only one message, but what does the implementation do if
> more than one message is matched? It would be good to document that as
> well.
> 
> More significantly, this level of documentation needs to be put into the
> "notmuch help" output (instead of the placeholder that's there in the
> current patch). It also needs to be added to the man page in
> notmuch.1.

The documentation is updated. Sorry for being lazy.

> > The second of these (part) has been the topic of some
> > discussion. There's a suggestion that a 'cat' subcommand or
> > '--format=raw' option to the 'show' subcommand would be better. I'm not
> > particular preference - I just wanted the functionality to use in the
> > Emacs UI.
> 
> One other approach that I imagined with the json output would be to
> simply include all of the MIME parts of all messages directly in the
> json-format output from "notmuch show". Does json have any particular
> way of encodign a binary blob? If not, should we just have one single
> encoding here? (Such as BASE64 within a json string?)

I'm sure that JSON could express the blob. There were two reasons that I
decided not to include the full message in the JSON output:

        - some of the parts can be very large, causing Emacs to spend
          considerably time loading the part (and consume a bunch of
          memory). This would be particularly noticeable in a thread
          where many of the messages include large parts - the UI will
          load all of the parts, even if you've already seen the
          message.

        - there are some parts that the UI will probably never display
          inline usefully (OpenOffice?). For those parts it's quite
          wasteful to have the UI pull them in.

There's obviously a compromise to be had. If we agreed to include
text/html parts in the JSON output it would make sense to me - maybe all
text/* parts should be there. There are probably others that would be
useful.

The later 'display all parts' version of notmuch-show is able to use
either inline or external content to display parts (it uses that
included in the JSON output if present).

dme.
-- 
David Edmondson, http://dme.org