From: W. Trevor King Date: Wed, 30 Dec 2015 19:16:58 +0000 (+1600) Subject: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=9770ddedf399fbfb30ef7923376b5730bcacb411;p=notmuch-archives.git [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page --- diff --git a/4b/7529b95d3a61817cedf2e3291009b35d83c2a1 b/4b/7529b95d3a61817cedf2e3291009b35d83c2a1 new file mode 100644 index 000000000..99d2d76e3 --- /dev/null +++ b/4b/7529b95d3a61817cedf2e3291009b35d83c2a1 @@ -0,0 +1,316 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by arlo.cworth.org (Postfix) with ESMTP id 9364F6DE1A7C + for ; Wed, 30 Dec 2015 11:29:32 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at cworth.org +X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" +X-Spam-Flag: NO +X-Spam-Score: -0.011 +X-Spam-Level: +X-Spam-Status: No, score=-0.011 tagged_above=-999 required=5 tests=[AWL=0.091, + DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, + RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_PASS=-0.001] + autolearn=disabled +Received: from arlo.cworth.org ([127.0.0.1]) + by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id nTBTuXnhf2lD for ; + Wed, 30 Dec 2015 11:29:30 -0800 (PST) +Received: from resqmta-po-02v.sys.comcast.net (resqmta-po-02v.sys.comcast.net + [96.114.154.161]) + by arlo.cworth.org (Postfix) with ESMTPS id B144F6DE1AE3 + for ; Wed, 30 Dec 2015 11:29:27 -0800 (PST) +Received: from resomta-po-15v.sys.comcast.net ([96.114.154.239]) + by resqmta-po-02v.sys.comcast.net with comcast + id zvQ91r0055AAYLo01vQgUL; Wed, 30 Dec 2015 19:24:40 +0000 +Received: from mail.tremily.us ([73.221.72.168]) + by resomta-po-15v.sys.comcast.net with comcast + id zvNe1r0083dr3C901vNeeN; Wed, 30 Dec 2015 19:22:39 +0000 +Received: by mail.tremily.us (Postfix, from userid 1000) + id 5DDB31B2C3F3; Wed, 30 Dec 2015 11:22:38 -0800 (PST) +DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=tremily.us; s=odin; + t=1451503358; bh=7lpg1sMhj9F2V24M7ZoPVzRvgec3lUkeYWQsVc63neo=; + h=Resent-From:Resent-Date:Resent-To:From:To:Cc:Subject:Date: + In-Reply-To:References:In-Reply-To:References; + b=RELugRBbl4Q4h/+b9eZ+Y7RoKzEtOwWmoFpPqALlPgsA8qgyhjTNzZlpUlBccSY/8 + U5p6RM0ASQ5i58whUNlD9Kbb6F9Tqs9gJfhgD0p5YkcM8o390d+W8gVt5epuXfauc4 + lqw6dO2z7sd7Agt3O5InRSNuTJ4FqpNAJ1nlS5rE= +Resent-From: "W. Trevor King" +Resent-Date: Wed, 30 Dec 2015 11:22:38 -0800 +Resent-Message-ID: <20151230192238.GD2452@odin.tremily.us> +Resent-To: notmuch@notmuchmail.org +From: "W. Trevor King" +To: notmuch@notmuchmail.org +Cc: David Bremner , + Tomi Ollila , Jani Nikula , + Carl Worth , "W. Trevor King" +Subject: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page +Date: Wed, 30 Dec 2015 11:16:58 -0800 +Message-Id: + <0a1bd306cb2e306ff49d72b6d2466c1d4a0ade2b.1451502495.git.wking@tremily.us> +X-Mailer: git-send-email 2.1.0.60.g85f0837 +In-Reply-To: +References: +In-Reply-To: +References: +DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net; + s=q20140121; t=1451503480; + bh=7gqjWospgux+NSTERSMc3/4miGJ8PQuaMvON5bxZghQ=; + h=Received:Received:Received:From:To:Subject:Date:Message-Id; + b=uIJ+a8FCuum3wB1prlKSB0yP1d7UVryLHarW/CFqnGwbJHxWRxeOvW1N/EN8+hWf8 + uDGtRZt3eHZyk8H7IcVTlNilTov1+kVLCVc6vVfnUvsSMwF/XfJhOcGNGxnIudrEfA + P2kix5HUOnrFKpxs8SSkbQU18/1Xs3tVJ8a/jK/h3FqShEQ5iqButtLqzFDvz58dw/ + nIhxmGqB6x5TSaI+WV1r9/Z+CgNhWf55HUoMDx23iV6WBd6r7syUetYlkfs4kfZvcV + 0J9qs16WcNK8CRqMVRWciucUMxMItGpB0uCeD8WX/lTbI9T+oPmrg62A74+Aa9k0KM + uWBlNuUTvCNjQ== +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.20 +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: Wed, 30 Dec 2015 19:29:32 -0000 + +To describe the config file format, so folks don't have to dig through +NEWS or the nmbug-status source to get that information. +--- + NEWS | 5 ++ + devel/nmbug/nmbug-status | 19 ++++--- + doc/conf.py | 6 ++ + doc/index.rst | 1 + + doc/man5/nmbug-status.rst | 136 ++++++++++++++++++++++++++++++++++++++++++++++ + 5 files changed, 159 insertions(+), 8 deletions(-) + create mode 100644 doc/man5/nmbug-status.rst + +diff --git a/NEWS b/NEWS +index 9f2e860..9a6a757 100644 +--- a/NEWS ++++ b/NEWS +@@ -1,6 +1,11 @@ + Notmuch 0.22 (UNRELEASED) + ========================= + ++Documentation ++------------- ++ ++A new `nmbug-status(5)` describes `nmbug-status`'s JSON config file. ++ + nmbug-status + ------------ + +diff --git a/devel/nmbug/nmbug-status b/devel/nmbug/nmbug-status +index d72f1db..336d0d2 100755 +--- a/devel/nmbug/nmbug-status ++++ b/devel/nmbug/nmbug-status +@@ -309,14 +309,17 @@ class HtmlPage (Page): + return self._slug_regexp.sub('-', string) + + parser = argparse.ArgumentParser(description=__doc__) +-parser.add_argument('--text', help='output plain text format', +- action='store_true') +-parser.add_argument('--config', help='load config from given file', +- metavar='PATH') +-parser.add_argument('--list-views', help='list views', +- action='store_true') +-parser.add_argument('--get-query', help='get query for view', +- metavar='VIEW') ++parser.add_argument( ++ '--text', action='store_true', help='output plain text format') ++parser.add_argument( ++ '--config', metavar='PATH', ++ help='load config from given file. ' ++ 'The format is described in nmbug-status(5).') ++parser.add_argument( ++ '--list-views', action='store_true', help='list views') ++parser.add_argument( ++ '--get-query', metavar='VIEW', help='get query for view') ++ + + args = parser.parse_args() + +diff --git a/doc/conf.py b/doc/conf.py +index 65adafe..eac747e 100644 +--- a/doc/conf.py ++++ b/doc/conf.py +@@ -118,6 +118,9 @@ man_pages = [ + u'add/remove tags for all messages matching the search terms', + [u'Carl Worth and many others'], 1), + ++('man5/nmbug-status','nmbug-status', ++ u'configuration for nmbug-status', ++ [u'Carl Worth and many others'], 5), + + ] + # If true, show URL addresses after external links. +@@ -180,4 +183,7 @@ texinfo_documents = [ + ('man1/notmuch-tag','notmuch-tag',u'notmuch Documentation', + u'Carl Worth and many others', 'notmuch-tag', + 'add/remove tags for all messages matching the search terms','Miscellaneous'), ++('man5/nmbug-status','nmbug-status',u'notmuch Documentation', ++ u'Carl Worth and many others', 'nmbug-status', ++ 'configuration for nmbug-status','Miscellaneous'), + ] +diff --git a/doc/index.rst b/doc/index.rst +index 3f0e6e6..bcb1dd0 100644 +--- a/doc/index.rst ++++ b/doc/index.rst +@@ -23,6 +23,7 @@ Contents: + man7/notmuch-search-terms + man1/notmuch-show + man1/notmuch-tag ++ man5/nmbug-status + + Indices and tables + ================== +diff --git a/doc/man5/nmbug-status.rst b/doc/man5/nmbug-status.rst +new file mode 100644 +index 0000000..5b59bdd +--- /dev/null ++++ b/doc/man5/nmbug-status.rst +@@ -0,0 +1,136 @@ ++============ ++nmbug-status ++============ ++ ++NAME ++==== ++ ++status-config.json - configure output for **nmbug-status(1)** ++ ++DESCRIPTION ++=========== ++ ++The config file is JSON_ with the following fields: ++ ++meta ++ An object with page-wide information ++ ++ title ++ Page title used in the default header. ++ ++ blurb ++ Introduction paragraph used in the default header. ++ ++ header ++ `Python format string`_ for the HTML header. Optional. It is ++ formatted with the following context: ++ ++ date ++ The current UTC date. ++ ++ datetime ++ The current UTC date-time. ++ ++ title ++ The **meta.title** value. ++ ++ blurb ++ The **meta.blurb** value. ++ ++ encoding ++ The encoding used for the output file. ++ ++ inter_message_padding ++ 0.25em, for consistent CSS generation. ++ ++ border_radius ++ 0.5em, for consistent CSS generation. ++ ++ footer ++ `Python format string`_ for the HTML footer. It is formatted with ++ the same context used for **meta.header**. Optional. ++ ++ message-url ++ `Python format string`_ for message-linking URLs. Optional. ++ Defaults to linking Gmane_. It is formatted with the following ++ context: ++ ++ message-id ++ The quoted_ message ID. ++ ++ subject ++ The message subject. ++ ++views ++ An array of view objects, where each object has the following ++ fields: ++ ++ title ++ Header text for the view. ++ ++ comment ++ Paragraph describing the view in more detail. Optional. ++ ++ id ++ Anchor string for the view. Optional, defaulting to a slugged ++ form of the view title ++ ++ query ++ An array of strings, which will be joined with 'and' to form the ++ view query. ++ ++.. _Gmane: http://gmane.org/ ++.. _JSON: http://json.org/ ++.. _Python format string: https://docs.python.org/3/library/string.html#formatstrings ++.. _quoted: https://docs.python.org/3/library/urllib.parse.html#urllib.parse.quote ++ ++EXAMPLE ++======= ++ ++:: ++ ++ { ++ "meta": { ++ "title": "Notmuch Patches", ++ "blurb": "For more information see nmbug", ++ "header": "

{title}

{blurb}

Views

", ++ "footer": "

Generated: {datetime}

", ++ "message-url": "http://mid.gmane.org/{message-id}" ++ }, ++ "views": [ ++ { ++ "title": "Bugs", ++ "comment": "Unresolved bugs.", ++ "query": [ ++ "tag:notmuch::bug", ++ "not tag:notmuch::fixed", ++ "not tag:notmuch::wontfix" ++ ] ++ }, ++ { ++ "title": "Review", ++ "comment": "These patches are under review, or waiting for feedback.", ++ "id": "under-review", ++ "query": [ ++ "tag:notmuch::patch", ++ "not tag:notmuch::pushed", ++ "not tag:notmuch::obsolete", ++ "not tag:notmuch::stale", ++ "not tag:notmuch::wontfix", ++ "(tag:notmuch::moreinfo or tag:notmuch::needs-review)" ++ ] ++ } ++ ] ++ } ++ ++FILES ++===== ++ ++If ``--config PATH`` is not set, ``nmbug-status`` will attempt to load ++a config file named ``status-config.json`` from the ``config`` branch ++of the ``NMBGIT`` repository (defaulting to ``~/.nmbug``). ++ ++SEE ALSO ++======== ++ ++**notmuch(1)**, **notmuch-search(1)**, **notmuch-tag(1)** +-- +2.1.0.60.g85f0837 +