[PATCH 0/4] doc: notmuch-show improvements

[PATCH 0/4] doc: notmuch-show improvements

[Austin Clements]

While I was poking at getting content-IDs to work better in the Emacs
UI, I found several things to be lacking in our notmuch-show
documentation.

[PATCH 1/4] doc: Clarify notmuch show --format=raw description

[Austin Clements]

In addition to being generally more precise, this is explicit that
there is no charset conversion.
---
 doc/man1/notmuch-show.rst | 36 ++++++++++++++++++++----------------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
index bad868b..2c0f64c 100644
--- a/doc/man1/notmuch-show.rst
+++ b/doc/man1/notmuch-show.rst
@@ -76,22 +76,26 @@ Supported options for **show** include
 
 	    http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 
-        **raw** (default for a single part, see --part)
-            For a message or an attached message part, the original, raw
-            content of the email message is output. Consumers of this
-            format should expect to implement MIME decoding and similar
-            functions.
-
-            For a single part (--part) the raw part content is output
-            after performing any necessary MIME decoding. Note that
-            messages with a simple body still have two parts: part 0 is
-            the whole message and part 1 is the body.
-
-            For a multipart part, the part headers and body (including
-            all child parts) is output.
-
-            The raw format must only be used with search terms matching
-            single message.
+        **raw** (default if --part is given)
+            Write the raw bytes of the given MIME part of a message to
+            standard out. For this format, it is an error to specify a
+            query that matches more than one message.
+
+            If the specified part is a leaf part, this outputs the
+            body of the part after performing content transfer
+            decoding (but no charset conversion). This is suitable for
+            saving attachments, for example.
+
+            For a multipart or message part, the output includes the
+            part headers as well as the body (including all child
+            parts). No decoding is performed because multipart and
+            message parts cannot have non-trivial content transfer
+            encoding. Consumers of this may need to implement MIME
+            decoding and similar functions.
+
+            Note that even a message with a simple body has two parts:
+            part 0 is the whole message and part 1 is the body of the
+            message.
 
     ``--format-version=N``
         Use the specified structured output format version. This is
-- 
1.9.1

[PATCH 2/4] doc: Fix minor formatting issues in notmuch-show.rst

[Austin Clements]

There were some extra line breaks and missing periods.
---
 doc/man1/notmuch-show.rst | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
index 2c0f64c..fdfb36d 100644
--- a/doc/man1/notmuch-show.rst
+++ b/doc/man1/notmuch-show.rst
@@ -50,9 +50,8 @@ Supported options for **show** include
             messages is reflected in nested JSON output. By default JSON
             output includes all messages in a matching thread; that is,
             by default,
-
-            ``--format=json`` sets ``--entire-thread`` The caller can
-            disable this behaviour by setting ``--entire-thread=false``
+            ``--format=json`` sets ``--entire-thread``. The caller can
+            disable this behaviour by setting ``--entire-thread=false``.
 
         **sexp**
             The output is formatted as an S-Expression (sexp). This
@@ -61,9 +60,8 @@ Supported options for **show** include
             is reflected in nested S-Expression output. By default,
             S-Expression output includes all messages in a matching
             thread; that is, by default,
-
-            ``--format=sexp`` sets ``--entire-thread`` The caller can
-            disable this behaviour by setting ``--entire-thread=false``
+            ``--format=sexp`` sets ``--entire-thread``. The caller can
+            disable this behaviour by setting ``--entire-thread=false``.
 
         **mbox**
             All matching messages are output in the traditional, Unix
-- 
1.9.1

[PATCH 3/4] doc: Clarify charset encoding of JSON output

[Austin Clements]

---
 doc/man1/notmuch-show.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
index fdfb36d..b8b10b9 100644
--- a/doc/man1/notmuch-show.rst
+++ b/doc/man1/notmuch-show.rst
@@ -52,6 +52,9 @@ Supported options for **show** include
             by default,
             ``--format=json`` sets ``--entire-thread``. The caller can
             disable this behaviour by setting ``--entire-thread=false``.
+            The JSON output is always encoded as UTF-8 and any message
+            content included in the output will be charset-converted to
+            UTF-8.
 
         **sexp**
             The output is formatted as an S-Expression (sexp). This
-- 
1.9.1

[PATCH 4/4] doc: Simplify and clarify notmuch show --format=sexp description

[Austin Clements]

Previously, this was a verbatim copy of the --format=json text.
Change it to instead reference the JSON text and actually describe how
the S-expression format works.
---
 doc/man1/notmuch-show.rst | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
index b8b10b9..586dbc5 100644
--- a/doc/man1/notmuch-show.rst
+++ b/doc/man1/notmuch-show.rst
@@ -57,14 +57,12 @@ Supported options for **show** include
             UTF-8.
 
         **sexp**
-            The output is formatted as an S-Expression (sexp). This
-            format is more robust than the text format for automated
-            processing. The nested structure of multipart MIME messages
-            is reflected in nested S-Expression output. By default,
-            S-Expression output includes all messages in a matching
-            thread; that is, by default,
-            ``--format=sexp`` sets ``--entire-thread``. The caller can
-            disable this behaviour by setting ``--entire-thread=false``.
+            The output is formatted as the Lisp s-expression (sexp)
+            equivalent of the JSON format above. Objects are formatted
+            as property lists whose keys are keywords (symbols preceded
+            by a colon). True is formatted as ``t`` and both false and
+            null are formatted as ``nil``. As for JSON, the s-expression
+            output is always encoded as UTF-8.
 
         **mbox**
             All matching messages are output in the traditional, Unix
-- 
1.9.1

Re: [PATCH 1/4] doc: Clarify notmuch show --format=raw description

[Mark Walters]

On Fri, 18 Apr 2014, Austin Clements <amdragon@MIT.EDU> wrote:
> In addition to being generally more precise, this is explicit that
> there is no charset conversion.
> ---
>  doc/man1/notmuch-show.rst | 36 ++++++++++++++++++++----------------
>  1 file changed, 20 insertions(+), 16 deletions(-)
>
> diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
> index bad868b..2c0f64c 100644
> --- a/doc/man1/notmuch-show.rst
> +++ b/doc/man1/notmuch-show.rst
> @@ -76,22 +76,26 @@ Supported options for **show** include
>  
>  	    http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
>  
> -        **raw** (default for a single part, see --part)
> -            For a message or an attached message part, the original, raw
> -            content of the email message is output. Consumers of this
> -            format should expect to implement MIME decoding and similar
> -            functions.
> -
> -            For a single part (--part) the raw part content is output
> -            after performing any necessary MIME decoding. Note that
> -            messages with a simple body still have two parts: part 0 is
> -            the whole message and part 1 is the body.
> -
> -            For a multipart part, the part headers and body (including
> -            all child parts) is output.
> -
> -            The raw format must only be used with search terms matching
> -            single message.
> +        **raw** (default if --part is given)
> +            Write the raw bytes of the given MIME part of a message to
> +            standard out. For this format, it is an error to specify a
> +            query that matches more than one message.
> +
> +            If the specified part is a leaf part, this outputs the
> +            body of the part after performing content transfer
> +            decoding (but no charset conversion). This is suitable for
> +            saving attachments, for example.
> +
> +            For a multipart or message part, the output includes the
> +            part headers as well as the body (including all child
> +            parts). No decoding is performed because multipart and
> +            message parts cannot have non-trivial content transfer
> +            encoding. Consumers of this may need to implement MIME
> +            decoding and similar functions.
> +
> +            Note that even a message with a simple body has two parts:
> +            part 0 is the whole message and part 1 is the body of the
> +            message.

Generally this looks good. I wonder whether the paragraph above could be
expanded slightly: my (quite possibly flawed) understanding is that
simple messages don't need to be MIME encoded (at least some messages
don't contain any mention of MIME). If this is correct then I think it
would be worth clarifying that this paragraph applies even to non-MIME
encoded messages.

Best wishes

Mark



>  
>      ``--format-version=N``
>          Use the specified structured output format version. This is
> -- 
> 1.9.1
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 1/4] doc: Clarify notmuch show --format=raw description

[Austin Clements]

Quoth Mark Walters on Apr 18 at  8:23 pm:
> 
> On Fri, 18 Apr 2014, Austin Clements <amdragon@MIT.EDU> wrote:
> > In addition to being generally more precise, this is explicit that
> > there is no charset conversion.
> > ---
> >  doc/man1/notmuch-show.rst | 36 ++++++++++++++++++++----------------
> >  1 file changed, 20 insertions(+), 16 deletions(-)
> >
> > diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
> > index bad868b..2c0f64c 100644
> > --- a/doc/man1/notmuch-show.rst
> > +++ b/doc/man1/notmuch-show.rst
> > @@ -76,22 +76,26 @@ Supported options for **show** include
> >  
> >  	    http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
> >  
> > -        **raw** (default for a single part, see --part)
> > -            For a message or an attached message part, the original, raw
> > -            content of the email message is output. Consumers of this
> > -            format should expect to implement MIME decoding and similar
> > -            functions.
> > -
> > -            For a single part (--part) the raw part content is output
> > -            after performing any necessary MIME decoding. Note that
> > -            messages with a simple body still have two parts: part 0 is
> > -            the whole message and part 1 is the body.
> > -
> > -            For a multipart part, the part headers and body (including
> > -            all child parts) is output.
> > -
> > -            The raw format must only be used with search terms matching
> > -            single message.
> > +        **raw** (default if --part is given)
> > +            Write the raw bytes of the given MIME part of a message to
> > +            standard out. For this format, it is an error to specify a
> > +            query that matches more than one message.
> > +
> > +            If the specified part is a leaf part, this outputs the
> > +            body of the part after performing content transfer
> > +            decoding (but no charset conversion). This is suitable for
> > +            saving attachments, for example.
> > +
> > +            For a multipart or message part, the output includes the
> > +            part headers as well as the body (including all child
> > +            parts). No decoding is performed because multipart and
> > +            message parts cannot have non-trivial content transfer
> > +            encoding. Consumers of this may need to implement MIME
> > +            decoding and similar functions.
> > +
> > +            Note that even a message with a simple body has two parts:
> > +            part 0 is the whole message and part 1 is the body of the
> > +            message.
> 
> Generally this looks good. I wonder whether the paragraph above could be
> expanded slightly: my (quite possibly flawed) understanding is that
> simple messages don't need to be MIME encoded (at least some messages
> don't contain any mention of MIME). If this is correct then I think it
> would be worth clarifying that this paragraph applies even to non-MIME
> encoded messages.

It's true that even "non-MIME" messages have two MIME parts.  Are you
thinking something like

Note that even a message with no MIME structure or a single body part
still has two MIME parts: part 0 is the whole message (headers and
body) and part 1 is just the body.

?

I wonder if this would be better in the documentation for --part.

> Best wishes
> 
> Mark

Re: [PATCH 1/4] doc: Clarify notmuch show --format=raw description

[Mark Walters]

On Fri, 18 Apr 2014, Austin Clements <amdragon@MIT.EDU> wrote:
> Quoth Mark Walters on Apr 18 at  8:23 pm:
>> 
>> On Fri, 18 Apr 2014, Austin Clements <amdragon@MIT.EDU> wrote:
>> > In addition to being generally more precise, this is explicit that
>> > there is no charset conversion.
>> > ---
>> >  doc/man1/notmuch-show.rst | 36 ++++++++++++++++++++----------------
>> >  1 file changed, 20 insertions(+), 16 deletions(-)
>> >
>> > diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
>> > index bad868b..2c0f64c 100644
>> > --- a/doc/man1/notmuch-show.rst
>> > +++ b/doc/man1/notmuch-show.rst
>> > @@ -76,22 +76,26 @@ Supported options for **show** include
>> >  
>> >  	    http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
>> >  
>> > -        **raw** (default for a single part, see --part)
>> > -            For a message or an attached message part, the original, raw
>> > -            content of the email message is output. Consumers of this
>> > -            format should expect to implement MIME decoding and similar
>> > -            functions.
>> > -
>> > -            For a single part (--part) the raw part content is output
>> > -            after performing any necessary MIME decoding. Note that
>> > -            messages with a simple body still have two parts: part 0 is
>> > -            the whole message and part 1 is the body.
>> > -
>> > -            For a multipart part, the part headers and body (including
>> > -            all child parts) is output.
>> > -
>> > -            The raw format must only be used with search terms matching
>> > -            single message.
>> > +        **raw** (default if --part is given)
>> > +            Write the raw bytes of the given MIME part of a message to
>> > +            standard out. For this format, it is an error to specify a
>> > +            query that matches more than one message.
>> > +
>> > +            If the specified part is a leaf part, this outputs the
>> > +            body of the part after performing content transfer
>> > +            decoding (but no charset conversion). This is suitable for
>> > +            saving attachments, for example.
>> > +
>> > +            For a multipart or message part, the output includes the
>> > +            part headers as well as the body (including all child
>> > +            parts). No decoding is performed because multipart and
>> > +            message parts cannot have non-trivial content transfer
>> > +            encoding. Consumers of this may need to implement MIME
>> > +            decoding and similar functions.
>> > +
>> > +            Note that even a message with a simple body has two parts:
>> > +            part 0 is the whole message and part 1 is the body of the
>> > +            message.
>> 
>> Generally this looks good. I wonder whether the paragraph above could be
>> expanded slightly: my (quite possibly flawed) understanding is that
>> simple messages don't need to be MIME encoded (at least some messages
>> don't contain any mention of MIME). If this is correct then I think it
>> would be worth clarifying that this paragraph applies even to non-MIME
>> encoded messages.
>
> It's true that even "non-MIME" messages have two MIME parts.  Are you
> thinking something like
>
> Note that even a message with no MIME structure or a single body part
> still has two MIME parts: part 0 is the whole message (headers and
> body) and part 1 is just the body.
>

That sounds great.

> ?
>
> I wonder if this would be better in the documentation for --part.

I think that would make sense.

Best wishes

Mark