From: David Bremner Date: Thu, 6 Mar 2014 13:20:44 +0000 (+2000) Subject: Sphinx man pages, round n+2 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=9c04bd85436b56ee6cbe58da113c42e73c57f3dc;p=notmuch-archives.git Sphinx man pages, round n+2 --- diff --git a/2e/2e2116e3d212e258bc0b37bdebcd6cd298f8c5 b/2e/2e2116e3d212e258bc0b37bdebcd6cd298f8c5 new file mode 100644 index 000000000..02e9b3e6d --- /dev/null +++ b/2e/2e2116e3d212e258bc0b37bdebcd6cd298f8c5 @@ -0,0 +1,175 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 12CE8431FBF + for ; Thu, 6 Mar 2014 05:21:11 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: 0 +X-Spam-Level: +X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none] + autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id M7ngo465HM1d for ; + Thu, 6 Mar 2014 05:21:03 -0800 (PST) +Received: from yantan.tethera.net (yantan.tethera.net [199.188.72.155]) + (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id 32BDB431FAE + for ; Thu, 6 Mar 2014 05:21:03 -0800 (PST) +Received: from remotemail by yantan.tethera.net with local (Exim 4.80) + (envelope-from ) id 1WLYEO-0000vI-T8 + for notmuch@notmuchmail.org; Thu, 06 Mar 2014 09:21:00 -0400 +Received: (nullmailer pid 2390 invoked by uid 1000); Thu, 06 Mar 2014 + 13:20:57 -0000 +From: David Bremner +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> +X-Mailer: git-send-email 1.8.5.3 +In-Reply-To: +References: +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +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: Thu, 06 Mar 2014 13:21:11 -0000 + +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