debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-22 19:08:09 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
notmuch/doc/man1/notmuch-restore.rst

108 lines
3.2 KiB
ReStructuredText
Raw Normal View History

doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
.. _notmuch-restore(1):
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
===============
notmuch-restore
===============
SYNOPSIS
========
**notmuch** **restore** [--accumulate] [--format=(auto|batch-tag|sup)] [--input=<*filename*>]
DESCRIPTION
===========
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
Restores the tags from the given file (see :any:`notmuch-dump(1)`).
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
The input is read from the given filename, if any, or from stdin.
Supported options for **restore** include
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
.. program:: restore
.. option:: --accumulate
The union of the existing and new tags is applied, instead of
replacing each message's tags as they are read in from the dump
file.
.. option:: --format=(sup|batch-tag|auto)
Notmuch restore supports two plain text dump formats, with each
line specifying a message-id and a set of tags. For details of the
actual formats, see :any:`notmuch-dump(1)`.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
sup
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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).
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
batch-tag
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
The **batch-tag** dump format is intended to more robust
against malformed message-ids and tags containing whitespace
or non-\ **ascii(7)** characters. See :any:`notmuch-dump(1)` for
details on this format.
**notmuch restore** updates the maildir flags according to tag
changes if the **maildir.synchronize\_flags** configuration
option is enabled. See :any:`notmuch-config(1)` for details.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
auto
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
This option (the default) tries to guess the format from the
input. For correctly formed input in either supported format,
this heuristic, based the fact that batch-tag format contains
no parentheses, should be accurate.
.. option:: --include=(config|properties|tags)
Control what kind of metadata is restored.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
config
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
Restore configuration data to the database. Each configuration
line starts with "#@ ", followed by a space separated
key-value pair. Both key and value are hex encoded if needed.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
properties
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
Restore per-message (key,value) metadata. Each line starts
with "#= ", followed by a message id, and a space separated
list of key=value pairs. Ids, keys and values are hex encoded
if needed. See :any:`notmuch-properties(7)` for more details.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
tags
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
Restore per-message metadata, namely tags. See *format* above
for more details.
The default is to restore all available types of data. The option
can be specified multiple times to select some subset.
.. option:: --input=<filename>
Read input from given file instead of stdin.
doc: document notmuch-restore --input=filename option Document all options for completeness.
2015-01-27 20:48:16 +01:00
restore: transparently support gzipped input We rely completely on zlib to do the right thing in detecting gzipped input. Since our dump format is chosen to be 7 bit ascii, this should be fine.
2014-03-29 19:12:28 +01:00
GZIPPED INPUT
=============
\ **notmuch restore** will detect if the input is compressed in
doc: use manpage role references to external man pages Using manpage role references generates helpful links in html documentation, while retaining the same boldface style in the man pages. The external man page site is configurable. The Debian manpage site seems like a good fit for Notmuch.
2021-05-21 22:44:09 +02:00
:manpage:`gzip(1)` format and automatically decompress it while
reading. This detection does not depend on file naming and in
particular works for standard input.
restore: transparently support gzipped input We rely completely on zlib to do the right thing in detecting gzipped input. Since our dump format is chosen to be 7 bit ascii, this should be fine.
2014-03-29 19:12:28 +01:00
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
SEE ALSO
========
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
:any:`notmuch(1)`,
:any:`notmuch-config(1)`,
:any:`notmuch-count(1)`,
:any:`notmuch-dump(1)`,
:any:`notmuch-hooks(5)`,
:any:`notmuch-insert(1)`,
:any:`notmuch-new(1)`,
:any:`notmuch-properties(7)`,
:any:`notmuch-reply(1)`,
:any:`notmuch-search(1)`,
:any:`notmuch-search-terms(7)`,
:any:`notmuch-show(1)`,
:any:`notmuch-tag(1)`
Reference in a new issue Copy permalink