[PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page
W. Trevor King
wking at tremily.us
Wed Dec 30 11:16:58 PST 2015
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 <a href=\"http://notmuchmail.org/nmbug\">nmbug</a>",
+ "header": "<html><head></head><body><h1>{title}</h1><p>{blurb}</p><h2>Views</h2>",
+ "footer": "<hr><p>Generated: {datetime}</p></html>",
+ "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
More information about the notmuch
mailing list