7e/77bc6e04478449bc7b7e86cc20859697f2d57e

   1 Return-Path: <wking@tremily.us>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id 1C251431FC3\r
   6         for <notmuch@notmuchmail.org>; Sat, 12 Jul 2014 20:11:37 -0700 (PDT)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References"\r
   9 X-Spam-Flag: NO\r
  10 X-Spam-Score: 0\r
  11 X-Spam-Level: \r
  12 X-Spam-Status: No, score=0 tagged_above=-999 required=5\r
  13         tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001]\r
  14         autolearn=disabled\r
  15 Received: from olra.theworths.org ([127.0.0.1])\r
  16         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  17         with ESMTP id loM2W6VKVRn8 for <notmuch@notmuchmail.org>;\r
  18         Sat, 12 Jul 2014 20:11:29 -0700 (PDT)\r
  19 Received: from qmta13.emeryville.ca.mail.comcast.net\r
  20         (qmta13.emeryville.ca.mail.comcast.net [76.96.27.243])\r
  21         by olra.theworths.org (Postfix) with ESMTP id 8BF22431FBD\r
  22         for <notmuch@notmuchmail.org>; Sat, 12 Jul 2014 20:11:29 -0700 (PDT)\r
  23 Received: from omta13.emeryville.ca.mail.comcast.net ([76.96.30.52])\r
  24         by qmta13.emeryville.ca.mail.comcast.net with comcast\r
  25         id Rf7B1o00217UAYkADfBVTx; Sun, 13 Jul 2014 03:11:29 +0000\r
  26 Received: from odin.tremily.us ([24.18.63.50])\r
  27         by omta13.emeryville.ca.mail.comcast.net with comcast\r
  28         id RfBU1o001152l3L8ZfBUNL; Sun, 13 Jul 2014 03:11:28 +0000\r
  29 Received: from mjolnir.tremily.us (unknown [192.168.0.150])\r
  30         by odin.tremily.us (Postfix) with ESMTPS id C6A751286F07;\r
  31         Sat, 12 Jul 2014 20:11:27 -0700 (PDT)\r
  32 Received: (nullmailer pid 31454 invoked by uid 1000);\r
  33         Sun, 13 Jul 2014 03:10:44 -0000\r
  34 From: "W. Trevor King" <wking@tremily.us>\r
  35 To: notmuch@notmuchmail.org\r
  36 Subject: [PATCH v3 4/5] doc: Consolidate Makefile targets around\r
  37         {build|install}-{format}\r
  38 Date: Sat, 12 Jul 2014 20:10:36 -0700\r
  39 Message-Id:\r
  40  <8f21be7fd9e04f2b0141d1b6d44b1273c2ec42ce.1405220724.git.wking@tremily.us>\r
  41 X-Mailer: git-send-email 1.9.1.353.gc66d89d\r
  42 In-Reply-To: <cover.1405220724.git.wking@tremily.us>\r
  43 References: <cover.1405220724.git.wking@tremily.us>\r
  44 In-Reply-To: <cover.1405220724.git.wking@tremily.us>\r
  45 References: <cover.1405220724.git.wking@tremily.us>\r
  46 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net;\r
  47         s=q20140121; t=1405221089;\r
  48         bh=ehsgb++EpTqdn5+NMx3mocWuwLSYPIEFRoXN3D75XOo=;\r
  49         h=Received:Received:Received:Received:From:To:Subject:Date:\r
  50         Message-Id;\r
  51         b=B/OWTb7iU/Vi+TKUfzQ1I3U81QqXey/qMh9pMYMI2scFa/wxDE7SFC0UfZN0TU2mR\r
  52         M01D5FZcgyhTB+LJ+2aPEqrkP5lkWB8IKlApUdkI9nLOA4+qFuFKhLIqND59U2nq5S\r
  53         mI/Vzz81baWbKQwaSBhpEdN9/ru2rbCJrwaZl8sKx6oLLHmTw3hUlOotg7e1NI/DxF\r
  54         1J+TQ/jst5Wou0E2DBbyBr4yHE0LmwP27GbrNTF3tueAyJDy2Oz1hAzOtEgYhe05qY\r
  55         x3z/ww+mddxvX+sF03NyUeUhbW/lXZ0vHLYb6ZW0x0rG7a0cLXFpXd+SMjR57FGyMK\r
  56         Sc/sggBVEQw7A==\r
  57 Cc: Tomi Ollila <tomi.ollila@iki.fi>\r
  58 X-BeenThere: notmuch@notmuchmail.org\r
  59 X-Mailman-Version: 2.1.13\r
  60 Precedence: list\r
  61 List-Id: "Use and development of the notmuch mail system."\r
  62         <notmuch.notmuchmail.org>\r
  63 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  64         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  65 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  66 List-Post: <mailto:notmuch@notmuchmail.org>\r
  67 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  68 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  69         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  70 X-List-Received-Date: Sun, 13 Jul 2014 03:11:37 -0000\r
  71 \r
  72 The rst2man target was removed in 9d9a700 (doc: build man pages at\r
  73 build time; introduce HAVE_SPHINX, HAVE_RST2MAN, 2014-03-13), but a\r
  74 reference in the install docs slipped through.  While I was removing\r
  75 that reference, I also:\r
  76 \r
  77 * Converted doc/INSTALL to reStructuredText, so I can link to Sphinx\r
  78   and Docutils directly.  Not everyone has access to Debian's\r
  79   python-docutils, so it's better to be genric here.\r
  80 * Converted from an unordered list to paragraphs, because I think it\r
  81   flows better.\r
  82 * Dropped the rst2man no-automatic-install caveat.  I don't think this\r
  83   applies to the current code, although I haven't tried to track down\r
  84   a commit that adds the automatic-install support.  Anyhow,\r
  85 \r
  86     $ make HAVE_SPHINX=0 HAVE_RST2MAN=1 RST2MAN=rst2man.py DESTDIR=/tmp/ install-man\r
  87 \r
  88   works for me.\r
  89 * Restructured the Makefile to use build- and install- prefixes\r
  90   consistently, regardless of Sphinx/rst2x backend.\r
  91 * Instead of disabling the build-man and install-man targets if\r
  92   HAVE_SPHINX and HAVE_RST2MAN are both empty, just pull build-man and\r
  93   install-man out of the default build tree.  That way:\r
  94 \r
  95     $ make HAVE_SPHINX=0 HAVE_RST2MAN=0 build-man\r
  96 \r
  97   will fail like it should, instead of successfully doing nothing.  If\r
  98   packagers *do* want to force building the docs, despite any config\r
  99   settings, you can override the BUILD_MAN and INSTALL_MAN variables:\r
 100 \r
 101     $ make BUILD_MAN=build-man all\r
 102 ---\r
 103  Makefile.local     | 14 ++++++++++++--\r
 104  doc/INSTALL        | 44 ++++++++++++++++++++++++++++++--------------\r
 105  doc/Makefile.local | 42 ++++++++++++++++++++++++------------------\r
 106  3 files changed, 66 insertions(+), 34 deletions(-)\r
 107 \r
 108 diff --git a/Makefile.local b/Makefile.local\r
 109 index fa07d81..83984fd 100644\r
 110 --- a/Makefile.local\r
 111 +++ b/Makefile.local\r
 112 @@ -43,6 +43,15 @@ GPG_FILE=$(SHA1_FILE).asc\r
 113  \r
 114  PV_FILE=bindings/python/notmuch/version.py\r
 115  \r
 116 +# Disable docs if we don't have the builders\r
 117 +ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)\r
 118 +BUILD_MAN =\r
 119 +INSTALL_MAN =\r
 120 +else\r
 121 +BUILD_MAN = build-man\r
 122 +INSTALL_MAN = install-man\r
 123 +endif\r
 124 +\r
 125  # Smash together user's values with our extra values\r
 126  FINAL_CFLAGS = -DNOTMUCH_VERSION=$(VERSION) $(CPPFLAGS) $(CFLAGS) $(WARN_CFLAGS) $(extra_cflags) $(CONFIGURE_CFLAGS)\r
 127  FINAL_CXXFLAGS = $(CPPFLAGS) $(CXXFLAGS) $(WARN_CXXFLAGS) $(extra_cflags) $(extra_cxxflags) $(CONFIGURE_CXXFLAGS)\r
 128 @@ -58,7 +67,7 @@ endif\r
 129  FINAL_LIBNOTMUCH_LDFLAGS = $(LDFLAGS) $(AS_NEEDED_LDFLAGS) $(CONFIGURE_LDFLAGS)\r
 130  \r
 131  .PHONY: all\r
 132 -all: notmuch notmuch-shared build-man\r
 133 +all: notmuch notmuch-shared $(BUILD_MAN)\r
 134  ifeq ($(MAKECMDGOALS),)\r
 135  ifeq ($(shell cat .first-build-message 2>/dev/null),)\r
 136         @NOTMUCH_FIRST_BUILD=1 $(MAKE) --no-print-directory all\r
 137 @@ -299,7 +308,8 @@ notmuch-shared: $(notmuch_client_modules) lib/$(LINKER_NAME)\r
 138         $(call quiet,$(FINAL_NOTMUCH_LINKER) $(CFLAGS)) $(notmuch_client_modules) $(FINAL_NOTMUCH_LDFLAGS) -o $@\r
 139  \r
 140  .PHONY: install\r
 141 -install: all install-man\r
 142 +\r
 143 +install: all $(INSTALL_MAN)\r
 144         mkdir -p "$(DESTDIR)$(prefix)/bin/"\r
 145         install notmuch-shared "$(DESTDIR)$(prefix)/bin/notmuch"\r
 146  ifeq ($(MAKECMDGOALS), install)\r
 147 diff --git a/doc/INSTALL b/doc/INSTALL\r
 148 index e37c2b9..8352f7b 100644\r
 149 --- a/doc/INSTALL\r
 150 +++ b/doc/INSTALL\r
 151 @@ -1,24 +1,40 @@\r
 152 +.. -*- rst -*-\r
 153 +\r
 154  This file contains some more detailed information about building and\r
 155  installing the documentation.\r
 156  \r
 157 -Building with sphinx.\r
 158 ----------------------\r
 159 +Building with Sphinx\r
 160 +--------------------\r
 161  \r
 162 -- You need sphinx at least version 1.0.\r
 163 +With Sphinx_ version 1.0 or greater, you can build HTML, man, and info\r
 164 +versions of the documentation with::\r
 165  \r
 166 -- You can build build and install man pages with 'make install-man'\r
 167 +  make build-{html|info|man}\r
 168  \r
 169 -- You can build man, info, html, and pdf versions of the docs\r
 170 -  (currently only the man pages) with\r
 171 +You can build and install the documentation with::\r
 172  \r
 173 -     'make install-{man|info|html|pdf}'\r
 174 +  make install-{info|man}\r
 175  \r
 176 -Building the man pages\r
 177 +Building with Docutils\r
 178  ----------------------\r
 179  \r
 180 -- You can build the man pages with rst2man (from python-docutils) with\r
 181 -  'make rst2man'.\r
 182 -\r
 183 -- Currently there is no support to automagically install the resulting\r
 184 -  nroff files, but it should work to modify the target install-man\r
 185 -  in doc/Makefile.local.\r
 186 +If you don't have Sphinx installed, you can use Docutils_ with the\r
 187 +same targets outlined above for Sphinx.  The Docutils converters\r
 188 +(rst2man, rst2html, etc.) are used instead of Sphinx.  Only the man\r
 189 +targets are currently supported.\r
 190 +\r
 191 +Configuring the builder\r
 192 +-----------------------\r
 193 +\r
 194 +The builder (Sphinx or rst2man) used for compilation is chosen based\r
 195 +on variables set in ``Makefile.config`` by the ``configure`` script.\r
 196 +If ``HAVE_SPHINX`` is 1, ``SPHINXBUILD`` (``sphinx-build`` by default)\r
 197 +is used to build the documentation.  If ``HAVE_SPHINX`` is not 1, and\r
 198 +``HAVE_RST2MAN`` is 1, ``RST2MAN`` is used to build the documentation.\r
 199 +The ``configure`` script autodetects ``rst2man`` or ``rst2man.py`` in\r
 200 +your ``PATH`` and sets an appropriate ``RST2MAN`` in\r
 201 +``Makefile.config``.  If neither ``HAVE_SPHINX`` nor ``HAVE_RST2MAN``\r
 202 +is 1, attempting to build the documentation will fail with an error.\r
 203 +\r
 204 +.. _Sphinx: http://sphinx-doc.org/\r
 205 +.. _Docutils: http://docutils.sourceforge.net/\r
 206 diff --git a/doc/Makefile.local b/doc/Makefile.local\r
 207 index 045f823..9b99c19 100644\r
 208 --- a/doc/Makefile.local\r
 209 +++ b/doc/Makefile.local\r
 210 @@ -13,22 +13,35 @@ mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py\r
 211  # Internal variables.\r
 212  ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir)\r
 213  \r
 214 -.PHONY: sphinx-html sphinx-texinfo sphinx-info\r
 215 +.PHONY: build-html build-info build-texinfo build-man\r
 216  \r
 217 -.PHONY: install-man build-man\r
 218 +.PHONY: install-info install-man\r
 219  \r
 220  %.gz: %\r
 221         rm -f $@ && gzip --stdout $^ > $@\r
 222  \r
 223 -sphinx-html:\r
 224 +build-html:\r
 225 +ifeq ($(HAVE_SPHINX),1)\r
 226         $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html\r
 227 +else\r
 228 +       @echo "fatal: no Sphinx, cannot build HTML docs"\r
 229 +       @false\r
 230 +endif\r
 231  \r
 232 -sphinx-texinfo:\r
 233 +build-texinfo:\r
 234 +ifeq ($(HAVE_SPHINX),1)\r
 235         $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo\r
 236 +else\r
 237 +       @echo "fatal: no Sphinx or rst2texinfo, cannot build texinfo docs"\r
 238 +       @false\r
 239 +endif\r
 240  \r
 241 -sphinx-info: sphinx-texinfo\r
 242 +build-info: build-texinfo\r
 243         make -C $(DOCBUILDDIR)/texinfo info\r
 244  \r
 245 +install-info: build-info\r
 246 +       make -C $(DOCBUILDDIR)/texinfo install-info\r
 247 +\r
 248  -include $(dir)/docdeps.mk\r
 249  \r
 250  MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})\r
 251 @@ -51,20 +64,14 @@ ifeq ($(HAVE_SPHINX),1)\r
 252  else ifeq ($(HAVE_RST2MAN),1)\r
 253         $(rstman2any) --converter "$(RST2MAN)" --input $(srcdir)/doc --output $(DOCBUILDDIR)/man\r
 254  else\r
 255 -       @echo "Fatal: build dependency fail."\r
 256 +       @echo "fatal: no Sphinx or rst2man, cannot build man pages"\r
 257         @false\r
 258  endif\r
 259 -       touch ${MAN_ROFF_FILES} $@\r
 260 -\r
 261 -# Do not try to build or install man pages if a man page converter is\r
 262 -# not available.\r
 263 -ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)\r
 264 -build-man:\r
 265 -install-man:\r
 266 -       @echo "No sphinx or rst2man, will not install man pages."\r
 267 -else\r
 268 -build-man: ${MAN_GZIP_FILES}\r
 269 -install-man: ${MAN_GZIP_FILES}\r
 270 +       touch "$@"\r
 271 +\r
 272 +build-man: $(MAN_ROFF_FILES)\r
 273 +\r
 274 +install-man: $(MAN_GZIP_FILES)\r
 275         mkdir -p "$(DESTDIR)$(mandir)/man1"\r
 276         mkdir -p "$(DESTDIR)$(mandir)/man5"\r
 277         mkdir -p "$(DESTDIR)$(mandir)/man7"\r
 278 @@ -72,7 +79,6 @@ install-man: ${MAN_GZIP_FILES}\r
 279         install -m0644 $(DOCBUILDDIR)/man/man5/*.5.gz $(DESTDIR)/$(mandir)/man5\r
 280         install -m0644 $(DOCBUILDDIR)/man/man7/*.7.gz $(DESTDIR)/$(mandir)/man7\r
 281         cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz\r
 282 -endif\r
 283  \r
 284  $(dir)/docdeps.mk: $(dir)/conf.py $(dir)/mkdocdeps.py\r
 285         $(mkdocdeps) $(srcdir)/doc $(DOCBUILDDIR) $@\r
 286 -- \r
 287 1.9.1.353.gc66d89d\r
 288 \r