From d51b7842149dcaedd02c4e5b6ba74a5bccd926a9 Mon Sep 17 00:00:00 2001 From: David Bremner Date: Tue, 17 Jan 2012 08:47:51 -0400 Subject: Start devel directory for developer tools and documentation. We had a lot of back and forth about the name of this directory, but nothing very conclusive. In the end, I just chose "devel" just to move on. --- devel/RELEASING | 113 ++++++++++++++++++++++ devel/TODO | 285 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 398 insertions(+) create mode 100644 devel/RELEASING create mode 100644 devel/TODO (limited to 'devel') diff --git a/devel/RELEASING b/devel/RELEASING new file mode 100644 index 0000000..88dab04 --- /dev/null +++ b/devel/RELEASING @@ -0,0 +1,113 @@ +Here are the steps to follow to create a new notmuch release. + +These steps assume that a process (not described here) has already +been followed to determine the features and bug fixes to be included +in a release, and that adequate testing by the community has already +been performed. The little bit of testing performed here is a safety +check, and not a substitute for wider testing. + +OK, so the code to be released is present and committed to your git +repository. From here, there are just a few steps to release: + +1) Verify that the NEWS file is up to date. + + Read through the entry at the top of the NEWS file and see if + you are aware of any major features recently added that are + not mentioned there. If so, please add them, (and ask the + authors of the commits to update NEWS in the future). + +2) Verify that the library version in lib/Makefile.local is correct + + See the instructions there for how to increment it. + + The version should have been updated with any commits that + added API _in a non-upwardly compatible_ way, but do check + that that is the case. The command below can be useful for + inspecting header-file changes since the last release X.Y: + + git diff X.Y..HEAD -- lib/notmuch.h + + Commit this change, if any. + +3) Update the debian/libnotmuchX.symbols file + + If the library version changed at all (step 2) it probably + means that symbols have changed/been added, in which case the + debian symbols file also needs to be updated: + + dpkg-buildpackage -uc -us + dpkg-gensymbols -plibnotmuchX | patch -p0 + + Carefully review the changes to debian/libnotmuch1.symbols to + make sure there are no unexpected changes. Remove any debian + versions from symbols. + + Commit this change, if any. + +4) Upgrade the version in the file "version" + + The scheme for the release number is as follows: + + A major milestone in usability causes an increase in the major + number, yielding a two-component version with a minor number + of 0, (such as "1.0" or "2.0"). + + Otherwise, releases with changes in features cause an increase + in the minor number, yielding a two-component version, (such + as "1.1" or "1.2"). + + Finally, releases that do not change "features" but are merely + bug fixes either increase the micro number or add it (starting + at ".1" if not present). So a bug-fix release from "1.0" would + be "1.0.1" and a subsequent bug-fix release would be "1.0.2" + etc. + + When you are happy with the file 'version', run + + make update-versions + + to propagate the version to the other places needed. + + Commit these changes. + +5) Create an entry for the new release in debian/changelog + + The syntax of this file is tightly restricted, but the + available emacs mode (see the dpkg-dev-el package) helps. + The entries here will be the Debian-relevant single-line + description of changes from the NEWS entry. And the version + must match the version in the next step. + + Commit this change. + + XXX: It would be great if this step were automated as part of + release, (taking entries from NEWS and the version from the + version file, and creating a new commit, etc.) + +6) Run "make release" which will perform the following steps. + + Note: in order to really upload anything, set the make variable + REALLY_UPLOAD=yes + + * Ensure that the version consists only of digits and periods + * Ensure that version and debian/changelog have the same version + * Verify that the source tree is clean + * Compile the current notmuch code (aborting release if it fails) + * Run the notmuch test suite (aborting release if it fails) + * Check that no release exists with the current version + * Make a signed tag + * Generate a tar file from this tag + * Generate a .sha1 sum file for the tar file and GPG sign it. + * Commit a (delta for a) copy of the tar file using pristine-tar + * Tag for the debian version + * if REALLY_UPLOAD=yes + - push the signed tag to the origin + XXX FIXME push debian tag + - scp tarball to web site + * Provide some text for the release announcement (see below). + +7) Send a message to notmuch@notmuchmail.org to announce the release. + + Use the text provided from "make release" above, (if for some + reason you lose this message, "make release-message" prints + it again for you. diff --git a/devel/TODO b/devel/TODO new file mode 100644 index 0000000..4dda6f4 --- /dev/null +++ b/devel/TODO @@ -0,0 +1,285 @@ +Fix the things that are causing the most pain to new users +---------------------------------------------------------- +1. A new import is tagging all messages as "inbox" -- total pain + +Emacs interface (notmuch.el) +---------------------------- +Add notmuch-bcc and notmuch-cc for setting default Bcc and Cc values, +(should affect the message-setup-hook). + +Switch the notmuch-search view to use "notmuch search --format=json" +to fix large classes of bugs regarding poorly-escaped output and lame +regular expressions. (The most recently found, unfixed example is the +sender's name containing ';' which causes emacs to drop a search +result.) This may require removing the outer array from the current +"notmuch search --format=json" results. + +Fix '*' to work by simply calling '+' or '-' on a region consisting of +the entire buffer, (this would avoid one race condition---while still +leaving other race conditions---but could also potentially make '*' a +very expensive operation). + +Add a global keybinding table for notmuch, and then view-specific +tables that add to it. + +Add a '|' binding from the search view. + +Add support for choosing from one of the user's configured email +addresses for the From line. + +Make 'notmuch-show-pipe-message have a private history. + +Add support for a delete keybinding that adds a "deleted" tag to the +current message/thread and make searches not return deleted messages +by default, (unless the user asks explicitly for deleted messages in +the search query). + +Add keybindings for next/previous thread. + +Add support to "mute" a thread (add a "muted" tag and then don't +display threads in searches by default where any message of the thread +has the "muted" tag). + +Make '=' count from the end rather than from the beginning if more +than half-way through the buffer. + +Fix to automatically wrap long headers (for RFC compliance) before +sending. This should probably just be fixed in message-mode itself, +(but perhaps we can have a notmuch-message-mode that layers this on +top). + +Stop hiding the headers so much in the thread-view mode. + +Allow opening a message in thread-view mode by clicking on either +line. + +Automatically open a message when navigating to it with N or P. + +Change 'a' command in thread-view mode to only archive open messages. + +Add a binding to open all closed messages. + +Change the 'a'rchive command in the thread view to only archive open +messages. + +Completion +---------- +Fix bash completion to complete multiple search options (both --first +and *then* --max-threads), and also complete value for --sort= +(oldest-first or newest-first). + +notmuch command-line tool +------------------------- +Add support to "notmuch search" and "notmuch show" to allow for +listing of duplicate messages, (distinct filenames with the same +Message-ID). I'm not sure what the option should be named. Perhaps +--with-duplicates ? + +Add a -0 option to "notmuch search" so that one can safely deal with +any filename with: + + notmuch search --output=files -0 | xargs -0 + +"notmuch setup" should use realpath() before replacing the +configuration file. The ensures that the final target file of any +intermediate symbolic links is what is actually replaced, (rather than +any symbolic link). + +Replace "notmuch reply" with "notmuch compose --reply ". +This would enable a plain "notmuch compose" to be used to construct an +initial message, (which would then have the properly configured name +and email address in the From: line. We could also then easily support +"notmuch compose --from " to support getting at alternate +email addresses. + +Fix the --format=json option to not imply --entire-thread. + +Implement "notmuch search --exclude-threads=" to allow +for excluding muted threads, (and any other negative, thread-based +filtering that the user wants to do). + +Fix "notmuch show" so that the UI doesn't fail to show a thread that +is visible in a search buffer, but happens to no longer match the +current search. (Perhaps add a --matching= +option (or similar) to "notmuch show".) For now, this is being worked +around in the emacs interface by noticing that "notmuch show" returns +nothing and re-rerunning the command without the extra arguments. + +Add a "--format" option to "notmuch search", (something printf-like +for selecting what gets printed). + +Give "notmuch restore" some progress indicator. + +Fix "notmuch restore" to operate in a single pass much like "notmuch +dump" does, rather than doing N searches into the database, each +matching 1/N messages. + +Add a "-f " option to select an alternate configuration +file. + +Allow configuration for filename patterns that should be ignored when +indexing. + +Replace the "notmuch part --part=id" command with "notmuch show +--part=id", (David Edmondson wants to rewrite some of "notmuch show" to +provide more MIME-structure information in its output first). + +Replace the "notmuch search-tags" command with "notmuch search +--output=tags". + +Fix to avoid this ugly message: + + (process:17197): gmime-CRITICAL **: g_mime_message_get_mime_part: assertion `GMIME_IS_MESSAGE (message)' failed + Warning: Not indexing empty mime part. + + This probably means adding a test case to generate that message, + filing an upstream bug against GMime, and then silencing the + notmuch-generated portion of the warning (so that once GMime is + fixed, this is all silent). + +Simplify notmuch-reply to simply print the headers (we have the +original values) rather than calling GMime (which encodes) and adding +the confusing gmime-filter-headers.c code (which decodes). + +notmuch library +--------------- +Add support for custom flag<->tag mappings. In the notmuch +configuration file this could be + + [maildir] + synchronize_flags = R:replied; D*:deleted; S:~unread; + +In the library interface this could be implemented with an array of +structures to define the mapping (flag character, tag name, +inverse-sense bit (~ above), and tag-when-any-file-flagged +vs. tag-when-all-files-flagged (* above)). + +Add an interface to accept a "key" and a byte stream, rather than a +filename. + +Provide a sane syntax for date ranges. First, we don't want to require +both endpoints to be specified. For example it would be nice to be +able to say things like "since:2009-01-1" or "until:2009-01-1" and +have the other endpoint be implicit. Second we'd like to support +relative specifications of time such as "since:'2 months ago'". To do +any of this we're probably going to need to break down an write our +own parser for the query string rather than using Xapian's QueryParser +class. + +Make failure to read a file (such as a permissions problem) a warning +rather than an error (should be similar to the existing warning for a +non-mail file). + +Fix to use the *last* Message-ID header if multiple such headers are +encountered, (I noticed this is one thing that kept me from seeing the +same message-ID values as sup). + +Add support for configuring "virtual tags" which are a tuple of +(tag-name, search-specification). The database is responsible for +ensuring that the virtual tag is always consistent. + +Indicate to the user if two files with the same message ID have +content that is actually different in some interesting way. Perhaps +notmuch initially sees all changes as interesting, and quickly learns +from the user which changes are not interesting (such as the very +common mailing-list footer). + +Fix notmuch_query_count_messages to share code with +notmuch_query_search_messages rather than duplicating code. (And +consider renaming it as well.) + +Provide a mechanism for doing automatic address completion based on +notmuch searches. Here was one proposal made in IRC: + + I guess all it would really have to be would be a way + to configure a series of searches to try in turn, + (presenting ambiguities at a given single level, and + advancing to the next level only if one level + returned no matches). + So then I might have a series that looks like this: + notmuch search --output=address_from tag:address_book_alias + notmuch search --output=address_to tag:sent + notmuch search --output=address_from + I think I might like that quite a bit. + And then we have a story for an address book for + non-emacs users. + +Provide a ~me Xapian synonym for all of the user's configured email +addresses. + +Add symbol hiding so that we don't risk leaking any private symbols +into the shared-library interface. + +Audit all libnotmuch entry points to ensure that all Xapian calls are +wrapped in a try/catch block. + +Fix the "count" functionality to be exact as Olly explained in IRC: + + ojwb> cworth: if you set the check_at_least parameter to the + database size, get_matches_estimated() will be exact + +Fix the threading of a message that has a References: header but no +In-Reply-To: header (see id:"87lixxnxpb.fsf@yoom.home.cworth.org"). + +Search syntax +------------- +Implement support for "tag:*" to expand to all tags. + +Fix "notmuch search to:" to be less confusing. Many users expect this +to search for all messages with a To: header, but it instead searches +for all messages with the word "to". If we don't provide the first +behavior, perhaps we should exit on an error when a configured prefix +is provided with no value? + +Support "*" in all cases and not just as a special case. That is, "* " +should also work, as well as "* and tag:inbox". + +Implement a syntax for requesting set-theoertic operations on results +of multiple searches. For example, I would like to do: + + "tag:inbox" SET-SUBTRACT "tag:muted" + + as well as: + + "tag:notmuch and " SET-INTERSECT + "tag:notmuch and not (tag:merged or tag:postponed)" + + See id:3wdpr282yz2.fsf@testarossa.amd.com for more details on the + use cases of the above. + +Database changes +---------------- +Store a reference term for every message-id that appears in +References. We just started doing this for newly-added documents, but +at the next convenient database-schema upgrade, we should go back and +fix old messages to be consistent. + +Start indexing the List-Id header, (and re-index this header for +existing messages at the next database upgrade). + +Add support for the user to specify custom headers to be indexed (and +re-index these for existing messages at the next database upgrade). + +Save filenames for files detected as "not an email file" in the +database. This would allow for two things: 1. Optimizing "notmuch new" +to not have to look at these files again (since they are potentially +large so the detection could be potentially slow). 2. A "notmuch +search" syntax could be added to allow the user to find these files, +(and perhaps delete them or move them away as appropriate). + +Fix filesystem/notmuch-new race condition by not updating database +mtime for a directory if it is the same as the current mtime. + +Test suite +---------- +Achieve 100% test coverage with the test suite. + +General +------- +Audit everything for dealing with out-of-memory (and drop xutil.c). + +Investigate why the notmuch database is slightly larger than the sup +database for the same corpus of email. + +Makefile should print message teaching user about LD_LIBRARY_PATH (or +similar) if libdir is not set to a directory examined by ldconfig. -- cgit v1.2.3 From 871fc32837d1e734895bef5f89040b5b874ae473 Mon Sep 17 00:00:00 2001 From: David Bremner Date: Tue, 10 Jan 2012 08:07:07 -0400 Subject: uncrustify.cfg: initial support for notmuch coding style Uncrustify is a free (as in GPL2+) tool that indents and beautifies C/C++ code. It is similar to GNU indent in functionality although probably more configurable (in fairness, indent has better documentation). Uncrustify does not have the indent mis-feature of needing to have every typedef'ed type defined in the configuration (even standard types like size_t). This configuration starts with the linux-kernel style from the uncrustify config, disables aggressive re-indenting of structs, and fine tunes the handling 'else' and braces. In an ideal situation, running uncrustify on notmuch code would be NOP; currently this is not true for all files because 1) the configuration is not perfect 2) the coding style of notmuch is not completely consistent; in particular the treatment of braces after e.g. for (_) is not consistent. Some fine tuning by Tomi Olilla. --- devel/uncrustify.cfg | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 devel/uncrustify.cfg (limited to 'devel') diff --git a/devel/uncrustify.cfg b/devel/uncrustify.cfg new file mode 100644 index 0000000..1dbc5e4 --- /dev/null +++ b/devel/uncrustify.cfg @@ -0,0 +1,105 @@ +# +# uncrustify config file for the linux kernel +# +# $Id: linux-indent.cfg 488 2006-09-09 12:44:38Z bengardner $ +# Taken from the uncrustify distribution under license (GPL2+) +# +# sample usage: +# uncrustify --replace -c uncrustify.cfg foo.c +# +# + +indent_with_tabs = 2 # 1=indent to level only, 2=indent with tabs +align_with_tabs = TRUE # use tabs to align +align_on_tabstop = TRUE # align on tabstops +input_tab_size = 8 # original tab size +output_tab_size = 8 # new tab size +indent_columns = 4 + +indent_label = 2 # pos: absolute col, neg: relative column + + +# +# inter-symbol newlines +# + +nl_enum_brace = remove # "enum {" vs "enum \n {" +nl_union_brace = remove # "union {" vs "union \n {" +nl_struct_brace = remove # "struct {" vs "struct \n {" +nl_do_brace = remove # "do {" vs "do \n {" +nl_if_brace = remove # "if () {" vs "if () \n {" +nl_for_brace = remove # "for () {" vs "for () \n {" +nl_else_brace = remove # "else {" vs "else \n {" +nl_while_brace = remove # "while () {" vs "while () \n {" +nl_switch_brace = remove # "switch () {" vs "switch () \n {" +nl_brace_while = remove # "} while" vs "} \n while" - cuddle while +nl_brace_else = remove # "} else" vs "} \n else" - cuddle else +nl_func_var_def_blk = 1 +nl_fcall_brace = remove # "list_for_each() {" vs "list_for_each()\n{" +nl_fdef_brace = force # "int foo() {" vs "int foo()\n{" +# nl_after_return = TRUE; +# nl_before_case = 1 + +# Add or remove newline between return type and function name in definition +nl_func_type_name = force +nl_enum_leave_one_liners = True +nl_enum_brace = Remove +nl_after_struct = 0 +# +# Source code modifications +# + +# mod_paren_on_return = remove # "return 1;" vs "return (1);" +# mod_full_brace_if = remove # "if (a) a--;" vs "if (a) { a--; }" +# mod_full_brace_for = remove # "for () a--;" vs "for () { a--; }" +# mod_full_brace_do = remove # "do a--; while ();" vs "do { a--; } while ();" +# mod_full_brace_while = remove # "while (a) a--;" vs "while (a) { a--; }" + + +# +# inter-character spacing options +# + +sp_before_ptr_star = force +sp_between_ptr_star = remove +sp_after_ptr_star = remove + +# sp _return_paren = force # "return (1);" vs "return(1);" +sp_sizeof_paren = force # "sizeof (int)" vs "sizeof(int)" +sp_before_sparen = force # "if (" vs "if(" +sp_after_sparen = force # "if () {" vs "if (){" +sp_sparen_brace = force +sp_after_cast = force # "(int) a" vs "(int)a" +sp_inside_braces = add # "{ 1 }" vs "{1}" +sp_inside_braces_struct = add # "{ 1 }" vs "{1}" +sp_inside_braces_enum = add # "{ 1 }" vs "{1}" +sp_assign = force +sp_arith = force +sp_bool = add +sp_compare = add +sp_assign = add +sp_after_comma = add +sp_func_def_paren = force # "int foo (){" vs "int foo(){" +sp_func_call_paren = force # "foo (" vs "foo(" +sp_func_proto_paren = force # "int foo ();" vs "int foo();" +sp_brace_else = force # "} else" vs "}else" +sp_else_brace = force # "else {" vs "else{" +# +# Aligning stuff +# + +align_enum_equ_span = 4 # '=' in enum definition +# align_nl_cont = TRUE +# align_var_def_span = 2 +# align_var_def_inline = TRUE +# align_var_def_star = FALSE +# align_var_def_colon = TRUE +# align_assign_span = 1 +align_struct_init_span = 0 # align stuff in a structure init '= { }' +align_right_cmt_span = 8 # align comments span this much in func +# align_pp_define_span = 8; +# align_pp_define_gap = 4; + +# cmt_star_cont = FALSE + +# indent_brace = 0 -- cgit v1.2.3 From 9e701465ebb43bcd5a56155be404758976e66c1f Mon Sep 17 00:00:00 2001 From: Tomi Ollila Date: Tue, 24 Jan 2012 22:55:59 +0200 Subject: uncrustify.cfg: label indent, some known types, not, # and ## Adjusted some uncrustify variables to get closer to prevailing style: * Label indent (for goto) relative to current indentation. * Registered GMimeObject and mime_node_t being as types. * Space after ! (not) operator. * No space after 'stringify' (#) preprosessor token. * No spacing change around ## (option not versatile enough). There are at least 3 cases where attention needs to be paid: * If there is newline between function name and open paren in function call, the paren (and args) are indented too far right. * #define HOUR (60 *MINUTE) -- i.e. no space after star (*). * void (*foo)(args) -- i.e no space between (name) and (args). --- devel/uncrustify.cfg | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'devel') diff --git a/devel/uncrustify.cfg b/devel/uncrustify.cfg index 1dbc5e4..d8075ba 100644 --- a/devel/uncrustify.cfg +++ b/devel/uncrustify.cfg @@ -16,8 +16,7 @@ input_tab_size = 8 # original tab size output_tab_size = 8 # new tab size indent_columns = 4 -indent_label = 2 # pos: absolute col, neg: relative column - +indent_label = -2 # pos: absolute col, neg: relative column # # inter-symbol newlines @@ -55,6 +54,11 @@ nl_after_struct = 0 # mod_full_brace_do = remove # "do a--; while ();" vs "do { a--; } while ();" # mod_full_brace_while = remove # "while (a) a--;" vs "while (a) { a--; }" +# +# Extra types used in notmuch source. +# (add more on demand) + +type GMimeObject mime_node_t # # inter-character spacing options @@ -63,6 +67,9 @@ nl_after_struct = 0 sp_before_ptr_star = force sp_between_ptr_star = remove sp_after_ptr_star = remove +sp_not = force +sp_pp_concat = ignore # XXX 'remove' drops leading space also +sp_pp_stringify = remove # sp _return_paren = force # "return (1);" vs "return(1);" sp_sizeof_paren = force # "sizeof (int)" vs "sizeof(int)" -- cgit v1.2.3 From 022a2810809ffba4a7bcb71ed3483d2cb29d1c77 Mon Sep 17 00:00:00 2001 From: David Bremner Date: Fri, 27 Jan 2012 19:46:58 -0400 Subject: STYLE: Initial draft of coding style document This was edited by (at least) Austin, Tomi, and myself. Amended with Austin's proposed wording for indentation. --- devel/STYLE | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 devel/STYLE (limited to 'devel') diff --git a/devel/STYLE b/devel/STYLE new file mode 100644 index 0000000..094f71d --- /dev/null +++ b/devel/STYLE @@ -0,0 +1,88 @@ +C/C++ coding style +================== + +Tools +----- + +There is a file uncrustify.cfg in this directory that can be used to +approximate the prevailing code style. You can run it with e.g. + + uncrustify --replace -c devel/uncrustify.cfg foo.c + +You still have to use your judgement about accepting or rejecting the +changes uncrustify makes. With a nice git frontend, you can add the +lines you agree with and reject the rest. + +For Emacs users, the file .dir-locals.el in the top level source +directory will configure c-mode to automatically meet most of the +basic layout rules. I + +Indentation, Whitespace, and Layout +----------------------------------- + +The following nonsense code demonstrates many aspects of the style: + +static some_type +function (param_type param, param_type param) +{ + int i; + + for (i = 0; i < 10; i++) { + int j; + + j = i + 10; + + some_other_func (j, i); + } +} + +* Indent is 4 spaces with mixed tab/spaces and a tab width of 8. + (Specifically, a line should begin with zero or more tabs followed + by fewer than eight spaces.) + +* Use copious whitespace. In particular + - there is a space between the function name and the open paren in a call. + - likewise, there is a space following keywords such as if and while + - every binary operator should have space on either side. + +* No trailing whitespace. Please enable the standard pre-commit hook + in git (or an equivalent hook). + +* The name in a function prototype should start at the beginning of a line. + +* Opening braces "cuddle" (they are on the same line as the + if/for/while test) and are preceded by a space. The opening brace of + functions is the exception, and starts on a new line. + +* Comments are always C-style /* */ block comments. They should start + with a capital letter and generally be written in complete + sentences. Public library functions are documented immediately + before their prototype in lib/notmuch.h. Internal functions are + typically documented immediately before their definition. + +* Code lines should be less than 80 columns and comments should be + wrapped at 70 columns. + +Naming +------ + +* Use lowercase_with_underscores for function, variable, and type + names. + +* All structs should be typedef'd to a name ending with _t. If the + struct has a tag, it should be the same as the typedef name, minus + the trailing _t. + +libnotmuch conventions +---------------------------------- + +* Functions starting with notmuch_ in lib/notmuch.h are public and are + automatically exported from the shared library. Private library + functions should generally either be static or, if they are shared + between compilation units, start with _notmuch. + +* Functions in libnotmuch must not access user configuration files + (i.e. .notmuch-config) + +* Code which needs to be accessed from both the CLI and from + libnotmuch should be factored out into libutil (under util/). -- cgit v1.2.3 From 661c35712343408b4c034e13fc6cc8be7d580e21 Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Sun, 19 Feb 2012 19:26:23 -0500 Subject: Document the JSON schemata used by show and search --- devel/schemata | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ notmuch-search.c | 3 ++ notmuch-show.c | 2 + 3 files changed, 143 insertions(+) create mode 100644 devel/schemata (limited to 'devel') diff --git a/devel/schemata b/devel/schemata new file mode 100644 index 0000000..24ad775 --- /dev/null +++ b/devel/schemata @@ -0,0 +1,138 @@ +This file describes the schemata used for notmuch's structured output +format (currently JSON). + +[]'s indicate lists. List items can be marked with a '?', meaning +they are optional; or a '*', meaning there can be zero or more of that +item. {}'s indicate an object that maps from field identifiers to +values. An object field marked '?' is optional. |'s indicate +alternates (e.g., int|string means something can be an int or a +string). + +Common non-terminals +-------------------- + +# Number of seconds since the Epoch +unix_time = int + +# Thread ID, sans "thread:" +threadid = string + +# Message ID, sans "id:" +messageid = string + +notmuch show schema +------------------- + +# A top-level set of threads (do_show) +# Returned by notmuch show without a --part argument +thread_set = [thread*] + +# Top-level messages in a thread (show_messages) +thread = [thread_node*] + +# A message and its replies (show_messages) +thread_node = [ + message?, # present if --entire-thread or matched + [thread_node*] # children of message +] + +# A message (show_message) +message = { + # (format_message_json) + id: messageid, + match: bool, + filename: string, + timestamp: unix_time, # date header as unix time + date_relative: string, # user-friendly timestamp + tags: [string*], + + headers: headers, + body: [part] +} + +# A MIME part (show_message_body) +part = { + # format_part_start_json + id: int|string, # part id (currently DFS part number) + + # format_part_encstatus_json + encstatus?: encstatus, + + # format_part_sigstatus_json + sigstatus?: sigstatus, + + # format_part_content_json + content-type: string, + content-id?: string, + # if content-type starts with "multipart/": + content: [part*], + # if content-type is "message/rfc822": + content: [{headers: headers, body: [part]}], + # otherwise (leaf parts): + filename?: string, + content-charset?: string, + # A leaf part's body content is optional, but may be included if + # it can be correctly encoded as a string. Consumers should use + # this in preference to fetching the part content separately. + content?: string +} + +# The headers of a message (format_headers_json with raw headers) or +# a part (format_headers_message_part_json with pretty-printed headers) +headers = { + Subject: string, + From: string, + To?: string, + Cc?: string, + Bcc?: string, + Date: string +} + +# Encryption status (format_part_encstatus_json) +encstatus = [{status: "good"|"bad"}] + +# Signature status (format_part_sigstatus_json) +sigstatus = [signature*] + +signature = { + # signature_status_to_string + status: "none"|"good"|"bad"|"error"|"unknown", + # if status is "good": + fingerprint?: string, + created?: unix_time, + expires?: unix_time, + userid?: string + # if status is not "good": + keyid?: string + # if the signature has errors: + errors?: int +} + +notmuch search schema +--------------------- + +# --output=summary +summary = [thread*] + +# --output=threads +threads = [threadid*] + +# --output=messages +messages = [messageid*] + +# --output=files +files = [string*] + +# --output=tags +tags = [string*] + +thread = { + thread: threadid, + timestamp: unix_time, + date_relative: string, # user-friendly timestamp + matched: int, # number of matched messages + total: int, # total messages in thread + authors: string, # comma-separated names with | between + # matched and unmatched + subject: string +} diff --git a/notmuch-search.c b/notmuch-search.c index d504051..92ce38a 100644 --- a/notmuch-search.c +++ b/notmuch-search.c @@ -90,6 +90,9 @@ format_thread_json (const void *ctx, const int total, const char *authors, const char *subject); + +/* Any changes to the JSON format should be reflected in the file + * devel/schemata. */ static const search_format_t format_json = { "[", "{", diff --git a/notmuch-show.c b/notmuch-show.c index d930f94..93fb16f 100644 --- a/notmuch-show.c +++ b/notmuch-show.c @@ -65,6 +65,8 @@ format_part_content_json (GMimeObject *part); static void format_part_end_json (GMimeObject *part); +/* Any changes to the JSON format should be reflected in the file + * devel/schemata. */ static const notmuch_show_format_t format_json = { "[", NULL, "{", format_message_json, -- cgit v1.2.3 From 06a34f1407a3465724d7950e7179d7f1df130a2b Mon Sep 17 00:00:00 2001 From: Adam Wolfe Gordon Date: Sun, 18 Mar 2012 10:32:35 -0600 Subject: TODO: Add replying to multiple messages --- devel/TODO | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'devel') diff --git a/devel/TODO b/devel/TODO index 4dda6f4..7b750af 100644 --- a/devel/TODO +++ b/devel/TODO @@ -141,6 +141,14 @@ Simplify notmuch-reply to simply print the headers (we have the original values) rather than calling GMime (which encodes) and adding the confusing gmime-filter-headers.c code (which decodes). +Properly handle replying to multiple messages. Currently, the JSON +reply format only supports a single message, but the default reply +format accepts searches returning multiple messages. The expected +behavior of replying to multiple messages is not obvious, and there +are multiple ideas that might make sense. Some consensus needs to be +reached on this issue, and then both reply formats should be updated +to be consistent. + notmuch library --------------- Add support for custom flag<->tag mappings. In the notmuch -- cgit v1.2.3 From 5abc9c1097a54e0e8b62e468d51728edb26b9101 Mon Sep 17 00:00:00 2001 From: Adam Wolfe Gordon Date: Sun, 18 Mar 2012 10:32:37 -0600 Subject: schemata: Add documentation for JSON reply format. --- devel/schemata | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) (limited to 'devel') diff --git a/devel/schemata b/devel/schemata index 24ad775..728a46f 100644 --- a/devel/schemata +++ b/devel/schemata @@ -77,8 +77,9 @@ part = { content?: string } -# The headers of a message (format_headers_json with raw headers) or -# a part (format_headers_message_part_json with pretty-printed headers) +# The headers of a message (format_headers_json with raw headers +# and reply = FALSE) or a part (format_headers_message_part_json +# with pretty-printed headers) headers = { Subject: string, From: string, @@ -136,3 +137,25 @@ thread = { # matched and unmatched subject: string } + +notmuch reply schema +-------------------- + +reply = { + # The headers of the constructed reply (format_headers_json with + # raw headers and reply = TRUE) + reply-headers: reply_headers, + + # As in the show format (format_part_json) + original: message +} + +reply_headers = { + Subject: string, + From: string, + To?: string, + Cc?: string, + Bcc?: string, + In-reply-to: string, + References: string +} -- cgit v1.2.3 From 98cad5a207438601942ecb8142a41133d54f0fbc Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Sat, 7 Apr 2012 20:57:45 -0400 Subject: Sync schemata with current code structure The schema itself hasn't changed, but many of the references to functions in notmuch-show.c were out of date. --- devel/schemata | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) (limited to 'devel') diff --git a/devel/schemata b/devel/schemata index 728a46f..977cea7 100644 --- a/devel/schemata +++ b/devel/schemata @@ -36,7 +36,7 @@ thread_node = [ [thread_node*] # children of message ] -# A message (show_message) +# A message (format_part_json) message = { # (format_message_json) id: messageid, @@ -50,18 +50,13 @@ message = { body: [part] } -# A MIME part (show_message_body) +# A MIME part (format_part_json) part = { - # format_part_start_json id: int|string, # part id (currently DFS part number) - # format_part_encstatus_json encstatus?: encstatus, - - # format_part_sigstatus_json sigstatus?: sigstatus, - # format_part_content_json content-type: string, content-id?: string, # if content-type starts with "multipart/": @@ -77,9 +72,7 @@ part = { content?: string } -# The headers of a message (format_headers_json with raw headers -# and reply = FALSE) or a part (format_headers_message_part_json -# with pretty-printed headers) +# The headers of a message or part (format_headers_json with reply = FALSE) headers = { Subject: string, From: string, @@ -89,14 +82,14 @@ headers = { Date: string } -# Encryption status (format_part_encstatus_json) +# Encryption status (format_part_json) encstatus = [{status: "good"|"bad"}] # Signature status (format_part_sigstatus_json) sigstatus = [signature*] signature = { - # signature_status_to_string + # (signature_status_to_string) status: "none"|"good"|"bad"|"error"|"unknown", # if status is "good": fingerprint?: string, @@ -142,14 +135,14 @@ notmuch reply schema -------------------- reply = { - # The headers of the constructed reply (format_headers_json with - # raw headers and reply = TRUE) + # The headers of the constructed reply reply-headers: reply_headers, # As in the show format (format_part_json) original: message } +# Reply headers (format_headers_json with reply = TRUE) reply_headers = { Subject: string, From: string, -- cgit v1.2.3 From 00a8581e4dcc5112d502729b1698d9c1598d3413 Mon Sep 17 00:00:00 2001 From: Tomi Ollila Date: Tue, 7 Feb 2012 18:34:17 +0200 Subject: uncrustify.cfg: comments and more types Changes to devel/uncrustify.cfg: * Updated header comment to state this is config file for *notmuch*. * Added comment about the reason of 'type' keyword used. * Added some more custom types woth 'type' keyword. * Have (every) multiline comment lines start with '*'. --- devel/uncrustify.cfg | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) (limited to 'devel') diff --git a/devel/uncrustify.cfg b/devel/uncrustify.cfg index d8075ba..d24cf6e 100644 --- a/devel/uncrustify.cfg +++ b/devel/uncrustify.cfg @@ -1,13 +1,13 @@ # -# uncrustify config file for the linux kernel +# Uncrustify config file for notmuch. +# Based on uncrustify config file for the linux kernel # # $Id: linux-indent.cfg 488 2006-09-09 12:44:38Z bengardner $ # Taken from the uncrustify distribution under license (GPL2+) # -# sample usage: +# Sample usage: # uncrustify --replace -c uncrustify.cfg foo.c # -# indent_with_tabs = 2 # 1=indent to level only, 2=indent with tabs align_with_tabs = TRUE # use tabs to align @@ -18,6 +18,8 @@ indent_columns = 4 indent_label = -2 # pos: absolute col, neg: relative column +indent_cmt_with_tabs = false # true would align to tabstop always... + # # inter-symbol newlines # @@ -54,11 +56,14 @@ nl_after_struct = 0 # mod_full_brace_do = remove # "do a--; while ();" vs "do { a--; } while ();" # mod_full_brace_while = remove # "while (a) a--;" vs "while (a) { a--; }" -# -# Extra types used in notmuch source. -# (add more on demand) -type GMimeObject mime_node_t +# In case some custom types aren't detected properly by uncrustify +# add those to this section below. For example there are cases where +# uncrustify doesn't know whether a 'token' is part of pointer type +# or left operand of a binary multiplication operation. + +type GMimeObject GMimeCryptoContext GMimeCipherContext +type mime_node_t notmuch_message_t # # inter-character spacing options @@ -107,6 +112,6 @@ align_right_cmt_span = 8 # align comments span this much in func # align_pp_define_span = 8; # align_pp_define_gap = 4; -# cmt_star_cont = FALSE +cmt_star_cont = true # indent_brace = 0 -- cgit v1.2.3 From fdce20d365d58491bd82a5944915843972fc0f00 Mon Sep 17 00:00:00 2001 From: Mark Walters Date: Sat, 16 Jun 2012 11:21:45 +0100 Subject: Update devel/schemata for --entire-thread=false Also remove the Json --entire-thread item from devel/TODO. --- devel/TODO | 2 -- devel/schemata | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) (limited to 'devel') diff --git a/devel/TODO b/devel/TODO index 7b750af..eb757af 100644 --- a/devel/TODO +++ b/devel/TODO @@ -92,8 +92,6 @@ and email address in the From: line. We could also then easily support "notmuch compose --from " to support getting at alternate email addresses. -Fix the --format=json option to not imply --entire-thread. - Implement "notmuch search --exclude-threads=" to allow for excluding muted threads, (and any other negative, thread-based filtering that the user wants to do). diff --git a/devel/schemata b/devel/schemata index 977cea7..8fcab8e 100644 --- a/devel/schemata +++ b/devel/schemata @@ -32,7 +32,7 @@ thread = [thread_node*] # A message and its replies (show_messages) thread_node = [ - message?, # present if --entire-thread or matched + message?, # null if not matched and not --entire-thread [thread_node*] # children of message ] -- cgit v1.2.3 From 51a7cd3ddb5a902fe46cb6d16b1999c73af0d33a Mon Sep 17 00:00:00 2001 From: Mark Walters Date: Sat, 30 Jun 2012 12:14:15 +0100 Subject: Minor correction to devel/schemata In id:"87sjdm12d1.fsf@awakening.csail.mit.edu" Austin pointed out that devel/schemata needs a slight correction with the new --entire-thread=false option. This is that correction. --- devel/schemata | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'devel') diff --git a/devel/schemata b/devel/schemata index 8fcab8e..f7e1b69 100644 --- a/devel/schemata +++ b/devel/schemata @@ -32,7 +32,7 @@ thread = [thread_node*] # A message and its replies (show_messages) thread_node = [ - message?, # null if not matched and not --entire-thread + message|null, # null if not matched and not --entire-thread [thread_node*] # children of message ] -- cgit v1.2.3 From e7f5302114da0b86c6682cc676607c0d64c55e5e Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Tue, 3 Jul 2012 01:47:38 -0400 Subject: Add missing "tags" field to search schema This field is output by search, but it didn't make it into the documentation. --- devel/schemata | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'devel') diff --git a/devel/schemata b/devel/schemata index f7e1b69..6677a1c 100644 --- a/devel/schemata +++ b/devel/schemata @@ -128,7 +128,8 @@ thread = { total: int, # total messages in thread authors: string, # comma-separated names with | between # matched and unmatched - subject: string + subject: string, + tags: [string*] } notmuch reply schema -- cgit v1.2.3 From ed93d7919914d5eb11263cbc4ef864ad0bd54bff Mon Sep 17 00:00:00 2001 From: Mark Walters Date: Tue, 24 Jul 2012 19:23:30 +0100 Subject: schemata: update for --body=true|false option Previously body: was a compulsory field in a message. The new --body=false option causes notmuch show to omit this field so update schemata to reflect this. --- devel/schemata | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'devel') diff --git a/devel/schemata b/devel/schemata index 6677a1c..9cb25f5 100644 --- a/devel/schemata +++ b/devel/schemata @@ -47,7 +47,7 @@ message = { tags: [string*], headers: headers, - body: [part] + body?: [part] # omitted if --body=false } # A MIME part (format_part_json) -- cgit v1.2.3