From: Jani Nikula Date: Tue, 27 Jan 2015 19:48:14 +0000 (+0200) Subject: [PATCH 1/5] doc: bring notmuch-dump manual page in line with the rest X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=431a7bfcb19c833e69486667d24d93b4fa1d53c5;p=notmuch-archives.git [PATCH 1/5] doc: bring notmuch-dump manual page in line with the rest --- diff --git a/b5/7daa1044358549792e40f977c919bdce1a5019 b/b5/7daa1044358549792e40f977c919bdce1a5019 new file mode 100644 index 000000000..2edc0eaa1 --- /dev/null +++ b/b5/7daa1044358549792e40f977c919bdce1a5019 @@ -0,0 +1,190 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 3D2B9431FD0 + for ; Tue, 27 Jan 2015 11:48:13 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: 1.738 +X-Spam-Level: * +X-Spam-Status: No, score=1.738 tagged_above=-999 required=5 + tests=[DNS_FROM_AHBL_RHSBL=2.438, RCVD_IN_DNSWL_LOW=-0.7] + autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id x13iVYVPBqTX for ; + Tue, 27 Jan 2015 11:48:10 -0800 (PST) +Received: from mail-wi0-f182.google.com (mail-wi0-f182.google.com + [209.85.212.182]) (using TLSv1 with cipher RC4-SHA (128/128 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id D940C431FCB + for ; Tue, 27 Jan 2015 11:48:08 -0800 (PST) +Received: by mail-wi0-f182.google.com with SMTP id n3so7346107wiv.3 + for ; Tue, 27 Jan 2015 11:48:07 -0800 (PST) +X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; + d=1e100.net; s=20130820; + h=x-gm-message-state:from:to:cc:subject:date:message-id; + bh=xfpTrDSeGKO5P4vYzODUH3qqqMH9IHMznVn/F3xQnAs=; + b=hHwYWWLYLmYJlJPwgFC6kiNEk+5cIBe9FC4NgIfM5hbUPS4GWGP1+f/Aprba8PHz4E + WaGz/NN8EBSTtYE8ueNjWdfVtC9kxoBMYlkPiSGvVu4CZCnAvJiRxaZayjCeQHEvPYx5 + PyOnbQfsWMpE0TF9Sc7pXDfRaJrIodE2ePwH+/QtKS5pgTpjULyTgdEoWUY3XPXQaxqY + oczfXckVB29kF5TyCuUovUindefkbjwyheLkuGOEQF1ohnZ1mVWaA6PjFPcfONmyCYHd + +d2kwlp5D/lkavg0HCG+TffRfbRL5B5BryErCujB50pGTErmv3vlpQVYITLO+krqYk8c + Wq2w== +X-Gm-Message-State: + ALoCoQlWEeWpKEN7gen4dud3nXyzJDDOPH6P7Mye4Kb/SnQvUs3mkWd8PusH0ZfquszltLbQ4AFV +X-Received: by 10.194.84.105 with SMTP id x9mr1979180wjy.17.1422388087622; + Tue, 27 Jan 2015 11:48:07 -0800 (PST) +Received: from localhost (mobile-internet-5d6ab0-235.dhcp.inet.fi. + [93.106.176.235]) by mx.google.com with ESMTPSA id + ej10sm19492658wib.1.2015.01.27.11.48.05 + (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); + Tue, 27 Jan 2015 11:48:05 -0800 (PST) +From: Jani Nikula +To: notmuch@notmuchmail.org +Subject: [PATCH 1/5] doc: bring notmuch-dump manual page in line with the rest +Date: Tue, 27 Jan 2015 21:48:14 +0200 +Message-Id: <1422388098-16333-1-git-send-email-jani@nikula.org> +X-Mailer: git-send-email 2.1.4 +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Tue, 27 Jan 2015 19:48:13 -0000 + +Fix indentation of options. Move search terms description before +options. Fix synopsis. +--- + doc/man1/notmuch-dump.rst | 100 ++++++++++++++++++++++++---------------------- + 1 file changed, 53 insertions(+), 47 deletions(-) + +diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst +index d94cb4f84496..3a6d0b34f505 100644 +--- a/doc/man1/notmuch-dump.rst ++++ b/doc/man1/notmuch-dump.rst +@@ -5,7 +5,7 @@ notmuch-dump + SYNOPSIS + ======== + +-**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...] ++**notmuch** **dump** [--gzip] [--format=(batch-tag|sup)] [--output=<*file*>] [--] [<*search-term*> ...] + + DESCRIPTION + =========== +@@ -19,52 +19,58 @@ recreated from the messages themselves. The output of notmuch dump is + therefore the only critical thing to backup (and much more friendly to + incremental backup than the native database files.) + +-``--gzip`` +- Compress the output in a format compatible with **gzip(1)**. +- +-``--format=(sup|batch-tag)`` +- Notmuch restore supports two plain text dump formats, both with one +- message-id per line, followed by a list of tags. +- +- **batch-tag** +- The default **batch-tag** dump format is intended to more robust +- against malformed message-ids and tags containing whitespace or +- non-\ **ascii(7)** characters. Each line has the form +- +- +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- +- id:<*quoted-message-id*\ > +- +- Tags are hex-encoded by replacing every byte not matching the +- regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two +- digit hex encoding. The message ID is a valid Xapian query, +- quoted using Xapian boolean term quoting rules: if the ID +- contains whitespace or a close paren or starts with a double +- quote, it must be enclosed in double quotes and double quotes +- inside the ID must be doubled. The astute reader will notice +- this is a special case of the batch input format for +- **notmuch-tag(1)**; note that the single message-id query is +- mandatory for **notmuch-restore(1)**. +- +- **sup** +- The **sup** dump file format is specifically chosen to be +- compatible with the format of files produced by sup-dump. So if +- you've previously been using sup for mail, then the **notmuch +- restore** command provides you a way to import all of your tags +- (or labels as sup calls them). Each line has the following form +- +- <*message-id*\ > **(** <*tag*\ > ... **)** +- +- with zero or more tags are separated by spaces. Note that +- (malformed) message-ids may contain arbitrary non-null +- characters. Note also that tags with spaces will not be +- correctly restored with this format. +- +- With no search terms, a dump of all messages in the database will be +- generated. A "--" argument instructs notmuch that the remaining +- arguments are search terms. +- +- See **notmuch-search-terms(7)** for details of the supported syntax +- for . ++See **notmuch-search-terms(7)** for details of the supported syntax ++for . With no search terms, a dump of all messages in ++the database will be generated. A "--" argument instructs notmuch that ++the remaining arguments are search terms. ++ ++Supported options for **dump** include ++ ++ ``--gzip`` ++ Compress the output in a format compatible with **gzip(1)**. ++ ++ ``--format=(sup|batch-tag)`` ++ Notmuch restore supports two plain text dump formats, both with one ++ message-id per line, followed by a list of tags. ++ ++ **batch-tag** ++ ++ The default **batch-tag** dump format is intended to more ++ robust against malformed message-ids and tags containing ++ whitespace or non-\ **ascii(7)** characters. Each line has ++ the form ++ ++ +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- ++ id:<*quoted-message-id*\ > ++ ++ Tags are hex-encoded by replacing every byte not matching ++ the regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is ++ the two digit hex encoding. The message ID is a valid ++ Xapian query, quoted using Xapian boolean term quoting ++ rules: if the ID contains whitespace or a close paren or ++ starts with a double quote, it must be enclosed in double ++ quotes and double quotes inside the ID must be ++ doubled. The astute reader will notice this is a special ++ case of the batch input format for **notmuch-tag(1)**; ++ note that the single message-id query is mandatory for ++ **notmuch-restore(1)**. ++ ++ **sup** ++ ++ The **sup** dump file format is specifically chosen to be ++ compatible with the format of files produced by ++ sup-dump. So if you've previously been using sup for mail, ++ then the **notmuch restore** command provides you a way to ++ import all of your tags (or labels as sup calls ++ them). Each line has the following form ++ ++ <*message-id*\ > **(** <*tag*\ > ... **)** ++ ++ with zero or more tags are separated by spaces. Note that ++ (malformed) message-ids may contain arbitrary non-null ++ characters. Note also that tags with spaces will not be ++ correctly restored with this format. ++ + + SEE ALSO + ======== +-- +2.1.4 +