Re: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

[Tomi Ollila]

On Thu, Dec 31 2015, David Bremner  wrote:

> Jani Nikula  writes:
>
>> On Wed, 30 Dec 2015, "W. Trevor King"  wrote:
>>> To describe the config file format, so folks don't have to dig through
>>> NEWS or the nmbug-status source to get that information.
>>
>> Overall I approve of the series (though I did not do a thorough
>> review).
>>
>> I am wondering about the man page though. I find it slightly confusing
>> there would be a man page named after the tool describing just the
>> config, but not the tool itself.
>
> For me it's a bit odd to have a man page for a tool we don't install by
> default. Is it maybe time to "promote" nmbug-status to the notmuch-
> namespace and install it by default? That would have to be somehow tied
> to installing the python bindings; or else the script could just print a
> helpful error message if the bindings are not found.
>
> This would also allow addressing Tomi's comment about testing, by adding
> a couple of tests to the test suite.

What we could simply have at the time being:

  devel/nmbug/nmbug
  devel/nmbug/nmbug.rst (or .1)
  devel/nmbug/nmbug-status
  devel/nmbug/nmbug-status.rst (or .1)
  devel/nmbug/nmbug-status-config
  devel/nmbug/nmbug-status-config.rst (or .5)

(and if .rst:s, a Makefile to build the namual pages)

The responsibility to install the tools could be
outside of notmuch for now...

Tomi

>
> d
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

[David Bremner]

Tomi Ollila  writes:

>
> What we could simply have at the time being:
>
>   devel/nmbug/nmbug
>   devel/nmbug/nmbug.rst (or .1)
>   devel/nmbug/nmbug-status
>   devel/nmbug/nmbug-status.rst (or .1)
>   devel/nmbug/nmbug-status-config
>   devel/nmbug/nmbug-status-config.rst (or .5)
>
> (and if .rst:s, a Makefile to build the namual pages)
>
> The responsibility to install the tools could be
> outside of notmuch for now...

This simpler option is also fine with me, and would be faster to review
and apply.

d
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

[David Bremner]

"W. Trevor King"  writes:

> So separate --without-… configure flags for each script, which will
> also control the associated man pages and handle runtime-dependency
> warnings/errors?

Or just have e.g. the nmbug-status install depend on the hypothetical
--without-python flag.  

>
> Looking over our current configure, I see we have a --without-ruby,
> but no --without-python.  I may file a separate patch adding that, so
> folks with Python installed can still opt-out of notmuch's Python
> bindings.

That seems sensible in any case. Although we'd have to double check that
the build itself doesn't depend on python.  It might make sense to
distinguish between the python bindings (needed for nmbug-status) and
python itself, needed for the test-suite (at least) and nmbug.
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

[W. Trevor King]

On Fri, Jan 01, 2016 at 01:23:37PM +0200, Tomi Ollila wrote:
> What we could simply have at the time being:
> 
>   devel/nmbug/nmbug
>   devel/nmbug/nmbug.rst (or .1)
>   devel/nmbug/nmbug-status
>   devel/nmbug/nmbug-status.rst (or .1)
>   devel/nmbug/nmbug-status-config
>   devel/nmbug/nmbug-status-config.rst (or .5)
> 
> (and if .rst:s, a Makefile to build the namual pages)

This is closer to my “separate project” idea [1], and works for me as
far as this series goes.  By not providing install tooling, we also
avoid David's concern about strongly linking the independent tools
[2].  I'll push something like it in a v2.

Once we land that, I may file a subsequent series renaming the scripts
and configs to something more general.  But we can hash that out in
that series' thread.

Cheers,
Trevor

[1]: http://thread.gmane.org/gmane.mail.notmuch.general/21535/focus=21536
 id:20151231202815.gl3...@odin.tremily.us
[2]: http://thread.gmane.org/gmane.mail.notmuch.general/21535/focus=21537
 id:87d1tm46ax.fsf@zancas.localnet

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy


signature.asc
Description: OpenPGP digital signature
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

[David Bremner]

Jani Nikula  writes:

> On Wed, 30 Dec 2015, "W. Trevor King"  wrote:
>> To describe the config file format, so folks don't have to dig through
>> NEWS or the nmbug-status source to get that information.
>
> Overall I approve of the series (though I did not do a thorough
> review).
>
> I am wondering about the man page though. I find it slightly confusing
> there would be a man page named after the tool describing just the
> config, but not the tool itself.

For me it's a bit odd to have a man page for a tool we don't install by
default. Is it maybe time to "promote" nmbug-status to the notmuch-
namespace and install it by default? That would have to be somehow tied
to installing the python bindings; or else the script could just print a
helpful error message if the bindings are not found.

This would also allow addressing Tomi's comment about testing, by adding
a couple of tests to the test suite.

d
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

[W. Trevor King]

On Thu, Dec 31, 2015 at 06:11:34PM -0400, David Bremner wrote:
> W. Trevor King writes:
> > On Thu, Dec 31, 2015 at 01:39:21PM -0400, David Bremner wrote:
> >> For me it's a bit odd to have a man page for a tool we don't
> >> install by default. Is it maybe time to "promote" nmbug-status to
> >> the notmuch- namespace and install it by default?
> >
> > Sounds good to me.  And Gentoo has installed it (if you've set the
> > ‘nmbug’ USE flag [1]) since 0.11.1-r1, 2012-02-21 [2].  I'm not
> > sure what the new names should be.  nmbug → notmuch-dtag (for
> > distributed tag) and nmbug-status → notmuch-report?
>
> I'm not sure we need to deal with both tools in lockstep. It's not
> like there's an actual dependence of nmbug-status on nmbug.

Agreed.  I think they're both pretty useful though, and I don't see a
point to *not* promoting one to “easy to install with an appropriately
generic name”.  However, I'm fine promoting the tools in two separate
patch series if that would be easier to review.

> Yes, these things are easy to solve in most packaging systems, but
> we want notmuch to be installable from source as well.

So separate --without-… configure flags for each script, which will
also control the associated man pages and handle runtime-dependency
warnings/errors?

Looking over our current configure, I see we have a --without-ruby,
but no --without-python.  I may file a separate patch adding that, so
folks with Python installed can still opt-out of notmuch's Python
bindings.

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy


signature.asc
Description: OpenPGP digital signature
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

[David Bremner]

"W. Trevor King"  writes:

> On Thu, Dec 31, 2015 at 01:39:21PM -0400, David Bremner wrote:
>
>> For me it's a bit odd to have a man page for a tool we don't install
>> by default. Is it maybe time to "promote" nmbug-status to the
>> notmuch- namespace and install it by default?
>
> Sounds good to me.  And Gentoo has installed it (if you've set the
> ‘nmbug’ USE flag [1]) since 0.11.1-r1, 2012-02-21 [2].  I'm not sure
> what the new names should be.  nmbug → notmuch-dtag (for distributed
> tag) and nmbug-status → notmuch-report?
>

I'm not sure we need to deal with both tools in lockstep. It's not like
there's an actual dependence of nmbug-status on nmbug. 

>> That would have to be somehow tied to installing the python
>> bindings;
>
> On Gentoo, that happens via REQUIRED_USE [3,4].  An alternative for
> packaging systems without USE-flag-style flexibility would be to spin
> them off into a separate project that depends on Git and notmuch's
> Python bindings.
>

Yes, these things are easy to solve in most packaging systems, but we
want notmuch to be installable from source as well. 
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

[W. Trevor King]

On Thu, Dec 31, 2015 at 01:39:21PM -0400, David Bremner wrote:
> Jani Nikula writes:
> > I am wondering about the man page though. I find it slightly
> > confusing there would be a man page named after the tool
> > describing just the config, but not the tool itself.

Yeah, a man page about the tool itself would be good.  If I add one,
we'd have a situation like procmail(1) and procmailrc(5).  One
difficulty for naming the config-file-format man page is that
status-config.json is not a particularly specific name.  If we're
renaming the tools anyway, I'd suggest we just go with
${EVENTUAL_NMBUG_STATUS_NAME}.json for the default config filename and
man page.

> For me it's a bit odd to have a man page for a tool we don't install
> by default. Is it maybe time to "promote" nmbug-status to the
> notmuch- namespace and install it by default?

Sounds good to me.  And Gentoo has installed it (if you've set the
‘nmbug’ USE flag [1]) since 0.11.1-r1, 2012-02-21 [2].  I'm not sure
what the new names should be.  nmbug → notmuch-dtag (for distributed
tag) and nmbug-status → notmuch-report?

> That would have to be somehow tied to installing the python
> bindings;

On Gentoo, that happens via REQUIRED_USE [3,4].  An alternative for
packaging systems without USE-flag-style flexibility would be to spin
them off into a separate project that depends on Git and notmuch's
Python bindings.

Cheers,
Trevor

[1]: 
https://gitweb.gentoo.org/repo/gentoo.git/tree/net-mail/notmuch/metadata.xml
[2]: 
https://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo-x86/net-mail/notmuch/ChangeLog?hideattic=0=1.23=markup
[3]: 
https://gitweb.gentoo.org/repo/gentoo.git/tree/net-mail/notmuch/notmuch-0.21.ebuild?id=45ba77ab1dee61a2590c9f4903e620c5cf4d5f68#n23
[4]: https://projects.gentoo.org/pms/6/pms.html#x1-890008.2.7

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy


signature.asc
Description: OpenPGP digital signature
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch

[PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

[W. Trevor King]

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 000..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