--- /dev/null
+Return-Path: <wking@tremily.us>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by arlo.cworth.org (Postfix) with ESMTP id CA5C16DE1B42\r
+ for <notmuch@notmuchmail.org>; Fri, 1 Jan 2016 22:10:39 -0800 (PST)\r
+X-Virus-Scanned: Debian amavisd-new at cworth.org\r
+X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References"\r
+X-Spam-Flag: NO\r
+X-Spam-Score: 0.04\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=0.04 tagged_above=-999 required=5 tests=[AWL=0.042,\r
+ DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001,\r
+ RCVD_IN_MSPIKE_H2=-0.001, SPF_PASS=-0.001] autolearn=disabled\r
+Received: from arlo.cworth.org ([127.0.0.1])\r
+ by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id QAcMTDmpZfDU for <notmuch@notmuchmail.org>;\r
+ Fri, 1 Jan 2016 22:10:37 -0800 (PST)\r
+Received: from resqmta-po-02v.sys.comcast.net (resqmta-po-02v.sys.comcast.net\r
+ [96.114.154.161])\r
+ by arlo.cworth.org (Postfix) with ESMTPS id 2C48D6DE1A2E\r
+ for <notmuch@notmuchmail.org>; Fri, 1 Jan 2016 22:10:02 -0800 (PST)\r
+Received: from resomta-po-03v.sys.comcast.net ([96.114.154.227])\r
+ by resqmta-po-02v.sys.comcast.net with comcast\r
+ id 0uA11s0014ueUHc01uA193; Sat, 02 Jan 2016 06:10:01 +0000\r
+Received: from mail.tremily.us ([73.221.72.168])\r
+ by resomta-po-03v.sys.comcast.net with comcast\r
+ id 0u801s0043dr3C901u80EX; Sat, 02 Jan 2016 06:08:00 +0000\r
+Received: from ullr.tremily.us (unknown [192.168.10.7])\r
+ by mail.tremily.us (Postfix) with ESMTPS id DC8EA1B2F583;\r
+ Fri, 1 Jan 2016 22:07:59 -0800 (PST)\r
+Received: (nullmailer pid 15185 invoked by uid 1000);\r
+ Sat, 02 Jan 2016 06:08:07 -0000\r
+From: "W. Trevor King" <wking@tremily.us>\r
+To: notmuch@notmuchmail.org\r
+Cc: David Bremner <david@tethera.net>,\r
+ Tomi Ollila <tomi.ollila@iki.fi>, Jani Nikula <jani@nikula.org>,\r
+ Carl Worth <cworth@cworth.org>, "W. Trevor King" <wking@tremily.us>\r
+Subject: [PATCH 4/5] notmuch-report: Add notmuch-report(1) and\r
+ notmuch-report.json(5) man pages\r
+Date: Fri, 1 Jan 2016 22:08:04 -0800\r
+Message-Id:\r
+ <fa4c13097bac48d833f4f4d981de237474fa1572.1451714099.git.wking@tremily.us>\r
+X-Mailer: git-send-email 2.1.0.60.g85f0837\r
+In-Reply-To: <cover.1451714099.git.wking@tremily.us>\r
+References: <cover.1451714099.git.wking@tremily.us>\r
+In-Reply-To: <cover.1451714099.git.wking@tremily.us>\r
+References: <cover.1451714099.git.wking@tremily.us>\r
+DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net;\r
+ s=q20140121; t=1451715001;\r
+ bh=I0GQKQ8byzorNKmWV7mN2GEJCbEvkR8d1BzWag3Kt34=;\r
+ h=Received:Received:Received:Received:From:To:Subject:Date:\r
+ Message-Id;\r
+ b=gagI4xIW51Zq95fvmDFALnqtSBWfzysPC0PfBuTJ8m9tam6obtU6KkHNzQfUS5+HA\r
+ 0Rlxf++kh5/ooTHY7Fj5IDIGZz9+4nSPYCCDDFFYJ/mlUJVl0TTguv82JAXqecBnW0\r
+ OBIBac83KHo9O9snLF2XKOOLPyel7va3TwXv62dNK/ljGlgDiYF3isU8CQT7NoIQ6U\r
+ BmSB/9REUaKHVTn+qpbe7xx6eJbwAYRB/WFL9q+xRYdGTzG5h7b6Xd22WNb42DPJUq\r
+ Dht7Zh1IhOuWuYyBI5ILir10M6DiJj2jAys7AA7WyLrwZC0TtwjOvGgKMxWXHWAHWp\r
+ hYK8y+gZmuxcw==\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.20\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <https://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch/>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <https://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Sat, 02 Jan 2016 06:10:40 -0000\r
+\r
+To describe the script and config file format, so folks don't have to\r
+dig through NEWS or the script's source to get that information.\r
+\r
+The Makefile and conf.py are excerpted from the main doc/ directory\r
+with minor simplifications and adjustments. The devel/nmbug/ scripts\r
+are largely independent of notmuch, and separating the docs here\r
+allows packagers to easily build the docs and install the scripts in a\r
+separate package, without complicating notmuch's core build/install\r
+process.\r
+---\r
+ devel/nmbug/doc/.gitignore | 2 +\r
+ devel/nmbug/doc/Makefile | 38 ++++++++\r
+ devel/nmbug/doc/conf.py | 67 +++++++++++++\r
+ devel/nmbug/doc/index.rst | 17 ++++\r
+ devel/nmbug/doc/man1/notmuch-report.1.rst | 54 +++++++++++\r
+ devel/nmbug/doc/man5/notmuch-report.json.5.rst | 129 +++++++++++++++++++++++++\r
+ devel/nmbug/notmuch-report | 19 ++--\r
+ 7 files changed, 318 insertions(+), 8 deletions(-)\r
+ create mode 100644 devel/nmbug/doc/.gitignore\r
+ create mode 100644 devel/nmbug/doc/Makefile\r
+ create mode 100644 devel/nmbug/doc/conf.py\r
+ create mode 100644 devel/nmbug/doc/index.rst\r
+ create mode 100644 devel/nmbug/doc/man1/notmuch-report.1.rst\r
+ create mode 100644 devel/nmbug/doc/man5/notmuch-report.json.5.rst\r
+\r
+diff --git a/devel/nmbug/doc/.gitignore b/devel/nmbug/doc/.gitignore\r
+new file mode 100644\r
+index 0000000..4930881\r
+--- /dev/null\r
++++ b/devel/nmbug/doc/.gitignore\r
+@@ -0,0 +1,2 @@\r
++*.pyc\r
++_build\r
+diff --git a/devel/nmbug/doc/Makefile b/devel/nmbug/doc/Makefile\r
+new file mode 100644\r
+index 0000000..7ea3ae7\r
+--- /dev/null\r
++++ b/devel/nmbug/doc/Makefile\r
+@@ -0,0 +1,38 @@\r
++# Makefile for Sphinx documentation\r
++#\r
++\r
++# You can set these variables from the command line.\r
++SPHINXOPTS =\r
++SPHINXBUILD = sphinx-build\r
++DOCBUILDDIR := _build\r
++\r
++SRCDIR ?= .\r
++ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(SRCDIR)\r
++\r
++MAN_RST_FILES := $(shell find $(SRCDIR)/man* -name '*.rst')\r
++MAN_ROFF_FILES := $(patsubst $(SRCDIR)/man%.rst,$(DOCBUILDDIR)/man/man%,$(MAN_RST_FILES))\r
++MAN_GZIP_FILES := $(addsuffix .gz,$(MAN_ROFF_FILES))\r
++\r
++.PHONY: build-man\r
++build-man: $(MAN_GZIP_FILES)\r
++\r
++%.gz: %\r
++ rm -f $@ && gzip --stdout $^ > $@\r
++\r
++$(MAN_ROFF_FILES): $(DOCBUILDDIR)/.roff.stamp\r
++\r
++# By using $(DOCBUILDDIR)/.roff.stamp instead of $(MAN_ROFF_FILES), we\r
++# convey to make that a single invocation of this recipe builds all\r
++# of the roff files. This prevents parallel make from starting an\r
++# instance of this recipe for each roff file.\r
++$(DOCBUILDDIR)/.roff.stamp $(MAN_ROFF_FILES): $(MAN_RST_FILES)\r
++ mkdir -p $(DOCBUILDDIR)\r
++ touch $(DOCBUILDDIR)/.roff.stamp\r
++ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man\r
++ for section in 1 5; do \\r
++ mkdir -p $(DOCBUILDDIR)/man/man$${section}; \\r
++ mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \\r
++ done\r
++\r
++clean:\r
++ rm -rf $(DOCBUILDDIR) $(SRCDIR)/conf.pyc\r
+diff --git a/devel/nmbug/doc/conf.py b/devel/nmbug/doc/conf.py\r
+new file mode 100644\r
+index 0000000..29379d0\r
+--- /dev/null\r
++++ b/devel/nmbug/doc/conf.py\r
+@@ -0,0 +1,67 @@\r
++# -*- coding: utf-8 -*-\r
++\r
++import os.path\r
++\r
++# The suffix of source filenames.\r
++source_suffix = '.rst'\r
++\r
++# The master toctree document.\r
++master_doc = 'index'\r
++\r
++# General information about the project.\r
++project = 'notmuch'\r
++authors = 'Carl Worth and many others'\r
++copyright = '2009-2015, {0}'.format(authors)\r
++\r
++location = os.path.dirname(__file__)\r
++\r
++dirname = location\r
++while True:\r
++ version_file = os.path.join(dirname, 'version')\r
++ if os.path.exists(version_file):\r
++ with open(version_file,'r') as f:\r
++ version = f.read().strip()\r
++ break\r
++ if dirname == '/':\r
++ raise ValueError(\r
++ 'no version file found in this directory or its ancestors')\r
++ dirname = os.path.dirname(dirname)\r
++\r
++# The full version, including alpha/beta/rc tags.\r
++release = version\r
++\r
++# List of patterns, relative to source directory, that match files and\r
++# directories to ignore when looking for source files.\r
++exclude_patterns = ['_build']\r
++\r
++# -- Options for manual page output ---------------------------------------\r
++\r
++# One entry per manual page. List of tuples\r
++# (source start file, name, description, authors, manual section).\r
++\r
++man_pages = [\r
++ ('man1/notmuch-report.1', 'notmuch-report',\r
++ 'generate reports from notmuch queries', [authors], 1),\r
++ ('man5/notmuch-report.json.5', 'notmuch-report.json',\r
++ 'configure notmuch-report', [authors], 5),\r
++]\r
++\r
++# If true, show URL addresses after external links.\r
++#man_show_urls = False\r
++\r
++# -- Options for Texinfo output -------------------------------------------\r
++\r
++# Grouping the document tree into Texinfo files. List of tuples\r
++# (source start file, target name, title, author,\r
++# dir menu entry, description, category)\r
++# If true, do not generate a @detailmenu in the "Top" node's menu.\r
++texinfo_no_detailmenu = True\r
++\r
++texinfo_documents = [\r
++ ('man1/notmuch-report.1', 'notmuch-report',\r
++ 'generate reports from notmuch queries', authors, 'notmuch-report',\r
++ 'generate reports from notmuch queries', 'Miscellaneous'),\r
++ ('man5/notmuch-report.json.5', 'notmuch-report.json',\r
++ 'configure notmuch-report', authors, 'notmuch-report.json',\r
++ 'configure notmuch-report', 'Miscellaneous'),\r
++]\r
+diff --git a/devel/nmbug/doc/index.rst b/devel/nmbug/doc/index.rst\r
+new file mode 100644\r
+index 0000000..51ac59e\r
+--- /dev/null\r
++++ b/devel/nmbug/doc/index.rst\r
+@@ -0,0 +1,17 @@\r
++Welcome to notmuch's dev-tool documentation!\r
++============================================\r
++\r
++Contents:\r
++\r
++.. toctree::\r
++ :titlesonly:\r
++\r
++ man1/notmuch-report.1\r
++ man5/notmuch-report.json.5\r
++\r
++Indices and tables\r
++==================\r
++\r
++* :ref:`genindex`\r
++* :ref:`modindex`\r
++* :ref:`search`\r
+diff --git a/devel/nmbug/doc/man1/notmuch-report.1.rst b/devel/nmbug/doc/man1/notmuch-report.1.rst\r
+new file mode 100644\r
+index 0000000..dfd82df\r
+--- /dev/null\r
++++ b/devel/nmbug/doc/man1/notmuch-report.1.rst\r
+@@ -0,0 +1,54 @@\r
++==============\r
++notmuch-report\r
++==============\r
++\r
++SYNOPSIS\r
++========\r
++\r
++**notmuch-report** [options ...]\r
++\r
++DESCRIPTION\r
++===========\r
++\r
++Generate HTML or plain-text reports showing query results.\r
++\r
++OPTIONS\r
++=======\r
++\r
++ ``-h``, ``--help``\r
++\r
++ Show a help message, including a list of available options, and\r
++ exit.\r
++\r
++ ``--text``\r
++ Output plain text instead of HTML.\r
++\r
++ ``--config`` <PATH>\r
++ Load config from given file. The format is described in\r
++ **notmuch-report.json(5)**. If this option is not set,\r
++ **notmuch-report** loads the config from the Git repository at\r
++ ``NMBGIT``. See :ref:`NMBGIT <NMBGIT>` for details.\r
++\r
++ ``--list-views``\r
++ List available views (by title) and exit.\r
++\r
++ ``--get-query`` <VIEW>\r
++ Print the configured query for view matching the given title.\r
++\r
++ENVIRONMENT\r
++===========\r
++\r
++.. _NMBGIT:\r
++\r
++ ``NMBGIT``\r
++ If ``--config PATH`` is not set, **notmuch-report** will attempt\r
++ to load a config file named ``notmuch-report.json`` from the\r
++ ``config`` branch of the ``NMBGIT`` repository (defaulting to\r
++ ``~/.nmbug``).\r
++\r
++SEE ALSO\r
++========\r
++\r
++**notmuch(1)**, **notmuch-report.json(5)**, **notmuch-search(1)**,\r
++ **notmuch-tag(1)**\r
++\r
+diff --git a/devel/nmbug/doc/man5/notmuch-report.json.5.rst b/devel/nmbug/doc/man5/notmuch-report.json.5.rst\r
+new file mode 100644\r
+index 0000000..4b5f84a\r
+--- /dev/null\r
++++ b/devel/nmbug/doc/man5/notmuch-report.json.5.rst\r
+@@ -0,0 +1,129 @@\r
++==============\r
++notmuch-report\r
++==============\r
++\r
++NAME\r
++====\r
++\r
++notmuch-report.json - configure output for **notmuch-report(1)**\r
++\r
++DESCRIPTION\r
++===========\r
++\r
++The config file is JSON_ with the following fields:\r
++\r
++meta\r
++ An object with page-wide information\r
++\r
++ title\r
++ Page title used in the default header.\r
++\r
++ blurb\r
++ Introduction paragraph used in the default header.\r
++\r
++ header\r
++ `Python format string`_ for the HTML header. Optional. It is\r
++ formatted with the following context:\r
++\r
++ date\r
++ The current UTC date.\r
++\r
++ datetime\r
++ The current UTC date-time.\r
++\r
++ title\r
++ The **meta.title** value.\r
++\r
++ blurb\r
++ The **meta.blurb** value.\r
++\r
++ encoding\r
++ The encoding used for the output file.\r
++\r
++ inter_message_padding\r
++ 0.25em, for consistent CSS generation.\r
++\r
++ border_radius\r
++ 0.5em, for consistent CSS generation.\r
++\r
++ footer\r
++ `Python format string`_ for the HTML footer. It is formatted with\r
++ the same context used for **meta.header**. Optional.\r
++\r
++ message-url\r
++ `Python format string`_ for message-linking URLs. Optional.\r
++ Defaults to linking Gmane_. It is formatted with the following\r
++ context:\r
++\r
++ message-id\r
++ The quoted_ message ID.\r
++\r
++ subject\r
++ The message subject.\r
++\r
++views\r
++ An array of view objects, where each object has the following\r
++ fields:\r
++\r
++ title\r
++ Header text for the view.\r
++\r
++ comment\r
++ Paragraph describing the view in more detail. Optional.\r
++\r
++ id\r
++ Anchor string for the view. Optional, defaulting to a slugged\r
++ form of the view title\r
++\r
++ query\r
++ An array of strings, which will be joined with 'and' to form the\r
++ view query.\r
++\r
++.. _Gmane: http://gmane.org/\r
++.. _JSON: http://json.org/\r
++.. _Python format string: https://docs.python.org/3/library/string.html#formatstrings\r
++.. _quoted: https://docs.python.org/3/library/urllib.parse.html#urllib.parse.quote\r
++\r
++EXAMPLE\r
++=======\r
++\r
++::\r
++\r
++ {\r
++ "meta": {\r
++ "title": "Notmuch Patches",\r
++ "blurb": "For more information see <a href=\"http://notmuchmail.org/nmbug\">nmbug</a>",\r
++ "header": "<html><head></head><body><h1>{title}</h1><p>{blurb}</p><h2>Views</h2>",\r
++ "footer": "<hr><p>Generated: {datetime}</p></html>",\r
++ "message-url": "http://mid.gmane.org/{message-id}"\r
++ },\r
++ "views": [\r
++ {\r
++ "title": "Bugs",\r
++ "comment": "Unresolved bugs.",\r
++ "query": [\r
++ "tag:notmuch::bug",\r
++ "not tag:notmuch::fixed",\r
++ "not tag:notmuch::wontfix"\r
++ ]\r
++ },\r
++ {\r
++ "title": "Review",\r
++ "comment": "These patches are under review, or waiting for feedback.",\r
++ "id": "under-review",\r
++ "query": [\r
++ "tag:notmuch::patch",\r
++ "not tag:notmuch::pushed",\r
++ "not tag:notmuch::obsolete",\r
++ "not tag:notmuch::stale",\r
++ "not tag:notmuch::wontfix",\r
++ "(tag:notmuch::moreinfo or tag:notmuch::needs-review)"\r
++ ]\r
++ }\r
++ ]\r
++ }\r
++\r
++SEE ALSO\r
++========\r
++\r
++**notmuch(1)**, **notmuch-report(1)**, **notmuch-search(1)**, **notmuch-tag(1)**\r
+diff --git a/devel/nmbug/notmuch-report b/devel/nmbug/notmuch-report\r
+index 5425e06..a4a3197 100755\r
+--- a/devel/nmbug/notmuch-report\r
++++ b/devel/nmbug/notmuch-report\r
+@@ -304,14 +304,17 @@ class HtmlPage (Page):\r
+ return self._slug_regexp.sub('-', string)\r
+ \r
+ parser = argparse.ArgumentParser(description=__doc__)\r
+-parser.add_argument('--text', help='output plain text format',\r
+- action='store_true')\r
+-parser.add_argument('--config', help='load config from given file',\r
+- metavar='PATH')\r
+-parser.add_argument('--list-views', help='list views',\r
+- action='store_true')\r
+-parser.add_argument('--get-query', help='get query for view',\r
+- metavar='VIEW')\r
++parser.add_argument(\r
++ '--text', action='store_true', help='output plain text format')\r
++parser.add_argument(\r
++ '--config', metavar='PATH',\r
++ help='load config from given file. '\r
++ 'The format is described in notmuch-report.json(5).')\r
++parser.add_argument(\r
++ '--list-views', action='store_true', help='list views')\r
++parser.add_argument(\r
++ '--get-query', metavar='VIEW', help='get query for view')\r
++\r
+ \r
+ args = parser.parse_args()\r
+ \r
+-- \r
+2.1.0.60.g85f0837\r
+\r
projects / notmuch-archives.git / commitdiff