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