install info docs v1

classic Classic list List threaded Threaded
11 messages Options
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

install info docs v1

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


_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

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

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

_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by David Bremner-2
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

_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by David Bremner-2
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

_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by David Bremner-2
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

_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by David Bremner-2
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

_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by David Bremner-2
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

_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by David Bremner-2
---
 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

_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by David Bremner-2
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

_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
Tomi Ollila-2 Tomi Ollila-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by David Bremner-2
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
> [hidden email]
> https://notmuchmail.org/mailman/listinfo/notmuch
_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch
David Bremner-2 David Bremner-2
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by David Bremner-2
David Bremner <[hidden email]> writes:

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

Series pushed to master.

d
_______________________________________________
notmuch mailing list
[hidden email]
https://notmuchmail.org/mailman/listinfo/notmuch