From: David Bremner <david@tethera.net>
To: notmuch@notmuchmail.org
Subject: Sphinx man pages, round n+2
Date: Thu,  6 Mar 2014 09:20:44 -0400
Message-Id: <1394112048-2151-1-git-send-email-david@tethera.net>
In-Reply-To: <m2d2i0jz2h.fsf@guru.guru-group.fi>
References: <m2d2i0jz2h.fsf@guru.guru-group.fi>
Precedence: list

This is the second non-RFC version of these patches, based on Tomi's comments, 
and also adding documentation (for the doc build process) and dependencies.

Interdiff follows:

diff --git a/INSTALL b/INSTALL
index fce9352..690b0ef 100644
--- a/INSTALL
+++ b/INSTALL
@@ -60,16 +60,30 @@ Talloc which are each described below:
 
 	Talloc is available from http://talloc.samba.org/
 
+Building Documentation
+----------------------
+
+By default the documentation for notmuch is built using sphinx.
+
+Sphinx is available from www.sphinx-doc.org.
+
+If you prefer, you can build the man pages using rst2man, from the
+python docutils package. See doc/INSTALL for details.
+
+
+Installing Dependencies from Packages
+-------------------------------------
+
 On a modern, package-based operating system you can install all of the
 dependencies with a simple simple command line. For example:
 
   For Debian and similar:
 
-        sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev
+        sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev python-sphinx
 
   For Fedora and similar:
 
-	sudo yum install xapian-core-devel gmime-devel libtalloc-devel
+	sudo yum install xapian-core-devel gmime-devel libtalloc-devel python-sphinx
 
 On other systems, a similar command can be used, but the details of
 the package names may be different.
diff --git a/debian/control b/debian/control
index 475b787..caf8a5d 100644
--- a/debian/control
+++ b/debian/control
@@ -15,6 +15,7 @@ Build-Depends:
  libz-dev,
  python-all (>= 2.6.6-3~),
  python3-all (>= 3.1.2-7~),
+ python-sphinx (>= 1.0),
  ruby, ruby-dev (>>1:1.9.3~),
  emacs23-nox | emacs23 (>=23~) | emacs23-lucid (>=23~) |
  emacs24-nox | emacs24 (>=24~) | emacs24-lucid (>=24~),
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..a60fb31
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,2 @@
+docdeps.mk
+_build
diff --git a/doc/INSTALL b/doc/INSTALL
new file mode 100644
index 0000000..e37c2b9
--- /dev/null
+++ b/doc/INSTALL
@@ -0,0 +1,24 @@
+This file contains some more detailed information about building and
+installing the documentation.
+
+Building with sphinx.
+---------------------
+
+- You need sphinx at least version 1.0.
+
+- You can build build and install man pages with 'make install-man'
+
+- You can build man, info, html, and pdf versions of the docs
+  (currently only the man pages) with
+
+     'make install-{man|info|html|pdf}'
+
+Building the man pages
+----------------------
+
+- You can build the man pages with rst2man (from python-docutils) with
+  'make rst2man'.
+
+- Currently there is no support to automagically install the resulting
+  nroff files, but it should work to modify the target install-man
+  in doc/Makefile.local.
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 19861a7..fd64f70 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -19,7 +19,7 @@ ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
 .PHONY: install-man
 
 %.gz: %
-	gzip -k -f $^
+	rm -f $@ && gzip --stdout $^ > $@
 
 sphinx-html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
@@ -37,7 +37,7 @@ sphinx-info: sphinx-texinfo
 rst2man:
 	$(prerst2man) $(DOCBUILDDIR)/.. $(DOCBUILDDIR)/man
 
-include $(dir)/docdeps.mk
+-include $(dir)/docdeps.mk
 
 MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
 
diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
index 343927f..9710294 100644
--- a/doc/man1/notmuch.rst
+++ b/doc/man1/notmuch.rst
@@ -85,7 +85,7 @@ OTHER COMMANDS
 --------------
 
 Several of the notmuch commands accept search terms with a common
-syntax. See *notmuch-search-terms*\ (7) for more details on the
+syntax. See **notmuch-search-terms**\ (7) for more details on the
 supported syntax.
 
 The **search**, **show** and **count** commands are used to query the