install info docs v1

install info docs v1

[David Bremner]

I was recently reminded we still don't install the info docs for
notmuch-emacs, so I set out to remedy that. The other issue is that
the notmuch-emacs docs are not very good. I found somethings that I
thought would be simple to be rather frustrating in trying to update
notmuch-emacs.rst. That could well just be a lack of fluency in rst on
my part. I did wonder if maybe we should consider using some sphinx
extension for elisp. I didn't find a well maintained and widely
distributed one.  sphinxcontrib-emacs apparently doesn't support
python3 which is a blocker for me.  flycheck embeds an extension [1] that
looks fairly nice. It's GPL3+ so we would in principle fork/embed it.

[1]: https://github.com/flycheck/flycheck/blob/master/doc/elisp.py

[PATCH 1/8] configure: check for makeinfo and install-info

[David Bremner]

These are needed to build and install (respectively) the info format
documentation.
---
 configure | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/configure b/configure
index cbb3b7cc..37db04d0 100755
--- a/configure
+++ b/configure
@@ -633,6 +633,8 @@ if [ $WITH_RUBY = "1" ] ; then
 fi
 
 have_sphinx=0
+have_makeinfo=0
+have_install_info=0
 if [ $WITH_DOCS = "1" ] ; then
     printf "Checking if sphinx is available and supports nroff output... "
     if command -v sphinx-build > /dev/null && ${python} -m sphinx.writers.manpage > /dev/null 2>&1 ; then
@@ -641,6 +643,20 @@ if [ $WITH_DOCS = "1" ] ; then
     else
 	printf "No (so will not install man pages).\n"
     fi
+    printf "Checking if makeinfo is available... "
+    if command -v makeinfo > /dev/null; then
+	printf "Yes.\n"
+	have_makeinfo=1
+    else
+	printf "No (so will not build info pages).\n"
+    fi
+    printf "Checking if install-info is available... "
+    if command -v install-info > /dev/null; then
+	printf "Yes.\n"
+	have_install_info=1
+    else
+	printf "No (so will not install info pages).\n"
+    fi
 fi
 
 if [ $WITH_DESKTOP = "1" ]; then
@@ -1068,6 +1084,12 @@ HAVE_EMACS = ${have_emacs}
 # Whether there's a sphinx-build binary available for building documentation
 HAVE_SPHINX=${have_sphinx}
 
+# Whether there's a makeinfo binary available for building info format documentation
+HAVE_MAKEINFO=${have_makeinfo}
+
+# Whether there's an install-info binary available for installing info format documentation
+HAVE_INSTALL_INFO=${have_install_info}
+
 # Whether there's a doxygen binary available for building api documentation
 HAVE_DOXYGEN=${have_doxygen}
 
-- 
2.17.0

Re: [PATCH 1/8] configure: check for makeinfo and install-info

[David Bremner]

David Bremner <david@tethera.net> writes:

> These are needed to build and install (respectively) the info format
> documentation.

Series pushed to master.

d

[PATCH 2/8] configure: set 'infodir'

[David Bremner]

This turns --infodir from an ignored option into a real one
---
 configure | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/configure b/configure
index 37db04d0..3cefdcc6 100755
--- a/configure
+++ b/configure
@@ -139,6 +139,7 @@ Fine tuning of some installation directories is available:
 	--libdir=DIR		Install libraries to DIR [PREFIX/lib]
 	--includedir=DIR	Install header files to DIR [PREFIX/include]
 	--mandir=DIR		Install man pages to DIR [PREFIX/share/man]
+	--infodir=DIR		Install man pages to DIR [PREFIX/share/man]
 	--sysconfdir=DIR	Read-only single-machine data [PREFIX/etc]
 	--emacslispdir=DIR	Emacs code [PREFIX/share/emacs/site-lisp]
 	--emacsetcdir=DIR	Emacs miscellaneous files [PREFIX/share/emacs/site-lisp]
@@ -162,7 +163,6 @@ configure-script calling conventions, but don't do anything yet:
 
 	--build=<cpu>-<vendor>-<os>	Currently ignored
 	--host=<cpu>-<vendor>-<os>	Currently ignored
-	--infodir=DIR			Currently ignored
 	--datadir=DIR			Currently ignored
 	--localstatedir=DIR		Currently ignored
 	--libexecdir=DIR		Currently ignored
@@ -185,6 +185,8 @@ for option; do
 	INCLUDEDIR="${option#*=}"
     elif [ "${option%%=*}" = '--mandir' ] ; then
 	MANDIR="${option#*=}"
+    elif [ "${option%%=*}" = '--infodir' ] ; then
+	INFODIR="${option#*=}"
     elif [ "${option%%=*}" = '--sysconfdir' ] ; then
 	SYSCONFDIR="${option#*=}"
     elif [ "${option%%=*}" = '--emacslispdir' ] ; then
@@ -265,8 +267,6 @@ for option; do
 	true
     elif [ "${option%%=*}" = '--host' ] ; then
 	true
-    elif [ "${option%%=*}" = '--infodir' ] ; then
-	true
     elif [ "${option%%=*}" = '--datadir' ] ; then
 	true
     elif [ "${option%%=*}" = '--localstatedir' ] ; then
@@ -1068,6 +1068,9 @@ includedir = ${INCLUDEDIR:=\$(prefix)/include}
 # The directory to which man pages should be installed
 mandir = ${MANDIR:=\$(prefix)/share/man}
 
+# The directory to which man pages should be installed
+infodir = ${INFODIR:=\$(prefix)/share/info}
+
 # The directory to which read-only (configuration) files should be installed
 sysconfdir = ${SYSCONFDIR:=\$(prefix)/etc}
 
-- 
2.17.0

[PATCH 3/8] doc: install build and install info pages

[David Bremner]

All of the man pages are installed as info pages, plus
the (unfinished) notmuch-emacs manual
---
 INSTALL            |  7 +++++--
 Makefile.local     |  4 ++--
 doc/Makefile.local | 23 +++++++++++++++++++++++
 3 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/INSTALL b/INSTALL
index 056e9fac..6e6f4799 100644
--- a/INSTALL
+++ b/INSTALL
@@ -80,6 +80,9 @@ of sphinx (Jul. 2010).
 
 Sphinx is available from www.sphinx-doc.org.
 
+To install the documentation as "info" pages, you will need the
+additional tools makeinfo and install-info.
+
 Installing Dependencies from Packages
 -------------------------------------
 
@@ -88,11 +91,11 @@ dependencies with a single simple command line. For example:
 
   For Debian and similar:
 
-        sudo apt-get install libxapian-dev libgmime-3.0-dev libtalloc-dev zlib1g-dev python3-sphinx
+        sudo apt-get install libxapian-dev libgmime-3.0-dev libtalloc-dev zlib1g-dev python3-sphinx texinfo install-info
 
   For Fedora and similar:
 
-	sudo yum install xapian-core-devel gmime-devel libtalloc-devel zlib-devel python3-sphinx
+	sudo yum install xapian-core-devel gmime-devel libtalloc-devel zlib-devel python3-sphinx texinfo info
 
 On other systems, a similar command can be used, but the details of
 the package names may be different.
diff --git a/Makefile.local b/Makefile.local
index 2bf0e17a..82145e1b 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -1,7 +1,7 @@
 # -*- makefile -*-
 
 .PHONY: all
-all: notmuch notmuch-shared build-man ruby-bindings
+all: notmuch notmuch-shared build-man build-info ruby-bindings
 ifeq ($(MAKECMDGOALS),)
 ifeq ($(shell cat .first-build-message 2>/dev/null),)
 	@NOTMUCH_FIRST_BUILD=1 $(MAKE) --no-print-directory all
@@ -260,7 +260,7 @@ notmuch-shared: $(notmuch_client_modules) lib/$(LINKER_NAME)
 	$(call quiet,$(FINAL_NOTMUCH_LINKER) $(CFLAGS)) $(notmuch_client_modules) $(FINAL_NOTMUCH_LDFLAGS) -o $@
 
 .PHONY: install
-install: all install-man
+install: all install-man install-info
 	mkdir -p "$(DESTDIR)$(prefix)/bin/"
 	install notmuch-shared "$(DESTDIR)$(prefix)/bin/notmuch"
 ifeq ($(MAKECMDGOALS), install)
diff --git a/doc/Makefile.local b/doc/Makefile.local
index a1739e15..16459e35 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -24,6 +24,12 @@ MAN_ROFF_FILES := $(MAN1_ROFF) $(MAN5_ROFF) $(MAN7_ROFF)
 
 MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
 
+MAN1_TEXI := $(patsubst $(srcdir)/doc/man1/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN1_RST))
+MAN5_TEXI := $(patsubst $(srcdir)/doc/man5/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN5_RST))
+MAN7_TEXI := $(patsubst $(srcdir)/doc/man7/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN7_RST))
+INFO_TEXI_FILES := $(MAN1_TEXI) $(MAN5_TEXI) $(MAN7_TEXI) $(DOCBUILDDIR)/texinfo/notmuch-emacs.texi
+INFO_INFO_FILES := $(INFO_TEXI_FILES:.texi=.info)
+
 .PHONY: sphinx-html sphinx-texinfo sphinx-info
 
 .PHONY: install-man build-man apidocs install-apidocs
@@ -98,6 +104,23 @@ install-man: ${MAN_GZIP_FILES}
 	cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
 endif
 
+ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO),11)
+build-info:
+	@echo "Missing sphinx or makeinfo, not building info pages"
+else
+build-info: sphinx-info
+endif
+
+ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO)$(HAVE_INSTALL_INFO),111)
+install-info:
+	@echo "Missing prerequisites, not installing info pages"
+else
+install-info: build-info
+	mkdir -m0755 -p "$(DESTDIR)$(infodir)"
+	install -m0644 $(INFO_INFO_FILES) $(DESTDIR)$(infodir)
+	for file in $(INFO_INFO_FILES); do install-info $$file $(DESTDIR)$(infodir)/dir; done
+endif
+
 $(dir)/config.dox: version.stamp
 	echo "PROJECT_NAME = \"Notmuch $(VERSION)\"" > $@
 	echo "INPUT=${srcdir}/lib/notmuch.h" >> $@
-- 
2.17.0

[PATCH 4/8] doc: install info files in elpa package

[David Bremner]

The duplication of effort in installing into different places seems
unavoidable; or more precisely not worth avoiding by more extensive
gnu-make-isms.
---
 emacs/Makefile.local | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/emacs/Makefile.local b/emacs/Makefile.local
index 040e64d4..1b3ef584 100644
--- a/emacs/Makefile.local
+++ b/emacs/Makefile.local
@@ -80,9 +80,14 @@ endif
 
 elpa: $(ELPA_FILE)
 
-notmuch-emacs-%.tar: ${elpa_sources}
+ELPA_DIR=.elpa-build/notmuch-${ELPA_VERSION}
+notmuch-emacs-%.tar: ${elpa_sources} build-info
 	mkdir -p .elpa-build/notmuch-${ELPA_VERSION}
-	cp ${elpa_sources} .elpa-build/notmuch-${ELPA_VERSION}
+	cp ${elpa_sources} ${ELPA_DIR}
+ifeq ($(HAVE_SPHINX)$(HAVE_MAKEINFO)$(HAVE_INSTALL_INFO),111)
+	cp ${INFO_INFO_FILES} ${ELPA_DIR}
+	for file in ${INFO_INFO_FILES}; do install-info $$file ${ELPA_DIR}/dir; done
+endif
 	tar -C .elpa-build -cf $@ notmuch-${ELPA_VERSION}
 	rm -r .elpa-build
 
-- 
2.17.0

[PATCH 5/8] debian: install info pages as part of elpa-emacs

[David Bremner]

This is a simple way to make the info pages available, since the emacs
package system deals with the annoying bits.  If there is many people
who want the info pages outside of emacs, we could consider a seperate
binary package, but currently it doesn't seem worthwhile.
---
 debian/elpa-notmuch.elpa | 1 +
 1 file changed, 1 insertion(+)

diff --git a/debian/elpa-notmuch.elpa b/debian/elpa-notmuch.elpa
index b4e9e172..a070ae5f 100644
--- a/debian/elpa-notmuch.elpa
+++ b/debian/elpa-notmuch.elpa
@@ -1 +1,2 @@
 emacs/*.el
+debian/tmp/usr/share/info/*
-- 
2.17.0

Re: [PATCH 5/8] debian: install info pages as part of elpa-emacs

[Tomi Ollila]

On Mon, May 21 2018, David Bremner wrote:

> This is a simple way to make the info pages available, since the emacs
> package system deals with the annoying bits.  If there is many people
> who want the info pages outside of emacs, we could consider a seperate
> binary package, but currently it doesn't seem worthwhile.

This series looks pretty OK to me, except this 'seperate' ;/

Tomi


> ---
>  debian/elpa-notmuch.elpa | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/debian/elpa-notmuch.elpa b/debian/elpa-notmuch.elpa
> index b4e9e172..a070ae5f 100644
> --- a/debian/elpa-notmuch.elpa
> +++ b/debian/elpa-notmuch.elpa
> @@ -1 +1,2 @@
>  emacs/*.el
> +debian/tmp/usr/share/info/*
> -- 
> 2.17.0
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> https://notmuchmail.org/mailman/listinfo/notmuch

[PATCH 6/8] doc: initial documentation for notmuch-show-mode

[David Bremner]

This is pretty minimal, but will hopefully inspire others to
contribute more complete documentation. If nothing else, it points out
'?'.
---
 doc/notmuch-emacs.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 5e25996f..62c1b709 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -177,6 +177,37 @@ variables.
 notmuch-show
 ============
 
+``notmuch-show-mode`` is used to display a single thread of email from
+your email archives.
+
+By default, various components of email messages, (citations,
+signatures, already-read messages), are hidden. You can make
+these parts visible by clicking with the mouse button or by
+pressing RET after positioning the cursor on a hidden part.
+
+``<space>``
+    Scroll the current message (if necessary),
+    advance to the next message, or advance to the next thread (if
+    already on the last message of a thread).
+
+``N``
+    Move to next message
+
+``P``
+    Move to previous message (or start of current message)
+
+``n``
+    Move to next matching message
+
+``p``
+    Move to previous matching message
+
+``+,-``
+    Add or remove arbitrary tags from the current message.
+
+``?``
+    Display full set of key bindings
+
 notmuch-tree
 ============
 
-- 
2.17.0

[PATCH 7/8] doc: initial documentation for notmuch-tree mode

[David Bremner]

---
 doc/notmuch-emacs.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 62c1b709..1d3291b8 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -208,9 +208,34 @@ pressing RET after positioning the cursor on a hidden part.
 ``?``
     Display full set of key bindings
 
+.. _notmuch-tree:
+
 notmuch-tree
 ============
 
+``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
+email archives. Each line in the buffer represents a single
+message giving the relative date, the author, subject, and any
+tags.
+
+``<return>``
+   Displays that message.
+
+``N``
+    Move to next message
+
+``P``
+    Move to previous message
+
+``n``
+    Move to next matching message
+
+``p``
+    Move to previous matching message
+
+``?``
+    Display full set of key bindings
+
 Global key bindings
 ===================
 
-- 
2.17.0

[PATCH 8/8] docs: add initial documentation for notmuch-tag-jump

[David Bremner]

This is mainly to improve discoverability. It seems that doing
variable cross-references is not easy without using some sphinx
extension/customization.
---
 doc/notmuch-emacs.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 1d3291b8..ce2e358e 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -245,6 +245,9 @@ following key bindings:
 ``j``
     Jump to saved searches using :ref:`notmuch-jump`.
 
+``k``
+    Tagging operations using :ref:`notmuch-tag-jump`
+
 .. _notmuch-jump:
 
 notmuch-jump
@@ -258,6 +261,22 @@ example, in the default configuration ``j i`` jumps immediately to the
 inbox search.  When you press ``j``, notmuch-jump shows the saved
 searches and their shortcut keys in the mini-buffer.
 
+.. _notmuch-tag-jump:
+
+notmuch-tag-jump
+----------------
+
+Tagging operations configured through ``notmuch-tagging-keys`` can
+be accessed via :kbd:`k` in :ref:`notmuch-show`,
+:ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
+prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
+operations specified in ``notmuch-tagging-keys``; i.e. each
+``+tag`` is replaced by ``-tag`` and vice versa.
+
+:index:`notmuch-tagging-keys`
+
+   A list of keys and corresponding tagging operations.
+
 Configuration
 =============
 
-- 
2.17.0