* [PATCH 0/4] doc: notmuch-show improvements
@ 2014-04-18 15:18 Austin Clements
2014-04-18 15:18 ` [PATCH 1/4] doc: Clarify notmuch show --format=raw description Austin Clements
` (3 more replies)
0 siblings, 4 replies; 8+ messages in thread
From: Austin Clements @ 2014-04-18 15:18 UTC (permalink / raw)
To: notmuch
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.
^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH 1/4] doc: Clarify notmuch show --format=raw description
2014-04-18 15:18 [PATCH 0/4] doc: notmuch-show improvements Austin Clements
@ 2014-04-18 15:18 ` Austin Clements
2014-04-18 19:23 ` Mark Walters
2014-04-18 15:18 ` [PATCH 2/4] doc: Fix minor formatting issues in notmuch-show.rst Austin Clements
` (2 subsequent siblings)
3 siblings, 1 reply; 8+ messages in thread
From: Austin Clements @ 2014-04-18 15:18 UTC (permalink / raw)
To: notmuch
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
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 2/4] doc: Fix minor formatting issues in notmuch-show.rst
2014-04-18 15:18 [PATCH 0/4] doc: notmuch-show improvements Austin Clements
2014-04-18 15:18 ` [PATCH 1/4] doc: Clarify notmuch show --format=raw description Austin Clements
@ 2014-04-18 15:18 ` Austin Clements
2014-04-18 15:18 ` [PATCH 3/4] doc: Clarify charset encoding of JSON output Austin Clements
2014-04-18 15:18 ` [PATCH 4/4] doc: Simplify and clarify notmuch show --format=sexp description Austin Clements
3 siblings, 0 replies; 8+ messages in thread
From: Austin Clements @ 2014-04-18 15:18 UTC (permalink / raw)
To: notmuch
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
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 3/4] doc: Clarify charset encoding of JSON output
2014-04-18 15:18 [PATCH 0/4] doc: notmuch-show improvements Austin Clements
2014-04-18 15:18 ` [PATCH 1/4] doc: Clarify notmuch show --format=raw description Austin Clements
2014-04-18 15:18 ` [PATCH 2/4] doc: Fix minor formatting issues in notmuch-show.rst Austin Clements
@ 2014-04-18 15:18 ` Austin Clements
2014-04-18 15:18 ` [PATCH 4/4] doc: Simplify and clarify notmuch show --format=sexp description Austin Clements
3 siblings, 0 replies; 8+ messages in thread
From: Austin Clements @ 2014-04-18 15:18 UTC (permalink / raw)
To: notmuch
---
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
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 4/4] doc: Simplify and clarify notmuch show --format=sexp description
2014-04-18 15:18 [PATCH 0/4] doc: notmuch-show improvements Austin Clements
` (2 preceding siblings ...)
2014-04-18 15:18 ` [PATCH 3/4] doc: Clarify charset encoding of JSON output Austin Clements
@ 2014-04-18 15:18 ` Austin Clements
3 siblings, 0 replies; 8+ messages in thread
From: Austin Clements @ 2014-04-18 15:18 UTC (permalink / raw)
To: notmuch
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
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH 1/4] doc: Clarify notmuch show --format=raw description
2014-04-18 15:18 ` [PATCH 1/4] doc: Clarify notmuch show --format=raw description Austin Clements
@ 2014-04-18 19:23 ` Mark Walters
2014-04-18 19:33 ` Austin Clements
0 siblings, 1 reply; 8+ messages in thread
From: Mark Walters @ 2014-04-18 19:23 UTC (permalink / raw)
To: Austin Clements, notmuch
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH 1/4] doc: Clarify notmuch show --format=raw description
2014-04-18 19:23 ` Mark Walters
@ 2014-04-18 19:33 ` Austin Clements
2014-04-18 19:37 ` Mark Walters
0 siblings, 1 reply; 8+ messages in thread
From: Austin Clements @ 2014-04-18 19:33 UTC (permalink / raw)
To: Mark Walters; +Cc: notmuch
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH 1/4] doc: Clarify notmuch show --format=raw description
2014-04-18 19:33 ` Austin Clements
@ 2014-04-18 19:37 ` Mark Walters
0 siblings, 0 replies; 8+ messages in thread
From: Mark Walters @ 2014-04-18 19:37 UTC (permalink / raw)
To: Austin Clements; +Cc: notmuch
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
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2014-04-18 19:37 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-04-18 15:18 [PATCH 0/4] doc: notmuch-show improvements Austin Clements
2014-04-18 15:18 ` [PATCH 1/4] doc: Clarify notmuch show --format=raw description Austin Clements
2014-04-18 19:23 ` Mark Walters
2014-04-18 19:33 ` Austin Clements
2014-04-18 19:37 ` Mark Walters
2014-04-18 15:18 ` [PATCH 2/4] doc: Fix minor formatting issues in notmuch-show.rst Austin Clements
2014-04-18 15:18 ` [PATCH 3/4] doc: Clarify charset encoding of JSON output Austin Clements
2014-04-18 15:18 ` [PATCH 4/4] doc: Simplify and clarify notmuch show --format=sexp description Austin Clements
Code repositories for project(s) associated with this public inbox
https://yhetil.org/notmuch.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).