From: Tomi Ollila <tomi.ollila@iki.fi>
To: David Bremner <david@tethera.net>, notmuch@notmuchmail.org
Subject: Re: [PATCH 2/3] man: partial conversion to pod.
In-Reply-To: <1388921950-5017-3-git-send-email-david@tethera.net>
References: <1366852752-3584-1-git-send-email-david@tethera.net>
	<1388921950-5017-1-git-send-email-david@tethera.net>
	<1388921950-5017-3-git-send-email-david@tethera.net>
User-Agent: Notmuch/0.17+34~g98b959f (http://notmuchmail.org) Emacs/24.3.1
	(x86_64-unknown-linux-gnu)
Date: Mon, 13 Jan 2014 23:06:03 +0200
Message-ID: <m2mwizoamc.fsf@guru.guru-group.fi>
MIME-Version: 1.0
Content-Type: text/plain
Cc: David Bremner <bremner@debian.org>
Precedence: list

David Bremner <david@tethera.net> writes:

> From: David Bremner <bremner@debian.org>
>
> This allows generation of man page and info document from the same source.
> It is also a bit more friendly to edit for most people.

IMHO it is good idea to have common format where to produce man, info &
html files. If we're going to need pandoc then the question of source
format explodes with choices...


> The conversion was done as follows:
>
>  % groff -e -mandoc -Tascii -rHY=0 $* | rman -f POD | sed  -e '/./,/^$/!d' -e 's/
>
> Some small hand-editing of the .pod may be needed afterwards.
> ---
>  INSTALL                         |   6 +
>  configure                       |  12 ++
>  info/Makefile.local             |  25 +++-
>  man/Makefile.local              |  19 ++-
>  man/man1/notmuch.1              | 190 ----------------------------
>  man/man7/notmuch-search-terms.7 | 269 ----------------------------------------
>  pod/notmuch-search-terms.pod    | 235 +++++++++++++++++++++++++++++++++++
>  pod/notmuch.pod                 | 155 +++++++++++++++++++++++
>  8 files changed, 448 insertions(+), 463 deletions(-)
>  delete mode 100644 man/man1/notmuch.1
>  delete mode 100644 man/man7/notmuch-search-terms.7
>  create mode 100644 pod/notmuch-search-terms.pod
>  create mode 100644 pod/notmuch.pod
>
> diff --git a/INSTALL b/INSTALL
> index 451bf05..697b7b2 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -60,6 +60,12 @@ Talloc which are each described below:
>  
>  	Talloc is available from http://talloc.samba.org/
>  
> +	pod2man
> +	-------
> +
> +	Some of the documentation is built with pod2man. This is part
> +	of the standard Perl distribution since Perl 5.6.0
> +
>  	texinfo
>  	-------
>  
> diff --git a/configure b/configure
> index e75c1d4..6dadbaa 100755
> --- a/configure
> +++ b/configure
> @@ -389,6 +389,15 @@ else
>      have_emacs=0
>  fi
>  
> +printf "Checking for pod2man... "
> +if pod2man --help > /dev/null 2>&1; then
> +    printf "Yes.\n"
> +    have_pod2man=1
> +else
> +    printf "No (man page install may fail)\n"
> +    have_pod2man=0
> +fi
> +
>  printf "Checking for makeinfo... "
>  if makeinfo --version > /dev/null 2>&1; then
>      printf "Yes.\n"
> @@ -768,6 +777,9 @@ HAVE_MAKEINFO = ${have_makeinfo}
>  # Whether there's an install-info binary available
>  HAVE_INSTALLINFO = ${have_installinfo}
>  
> +# Is pod2man in the path?
> +HAVE_POD2MAN = ${have_pod2man}
> +
>  # where to install info files
>  
>  INFODIR = ${INFODIR}
> diff --git a/info/Makefile.local b/info/Makefile.local
> index 55e9740..cca891a 100644
> --- a/info/Makefile.local
> +++ b/info/Makefile.local
> @@ -2,10 +2,14 @@
>  
>  dir := info
>  
> +man_texi :=  $(dir)/notmuch.texi $(dir)/notmuch-search-terms.texi
> +man_info := $(man_texi:.texi=.info)
> +man_entry := $(man_texi:.texi=.entry)
> +
>  texi_sources :=  $(dir)/notmuch-emacs.texi
>  emacs_info := $(texi_sources:.texi=.info)
>  
> -info := $(emacs_info)
> +info := $(emacs_info) $(man_info)
>  
>  ifeq ($(HAVE_MAKEINFO),1)
>  all: $(info)
> @@ -15,11 +19,23 @@ ifeq ($(HAVE_INSTALLINFO),1)
>  install: install-info
>  endif
>  
> -%.info: %.texi
> +%.entry: ../pod/%.pod
> +	printf "@dircategory Notmuch\n@direntry\n" > $@
> +	printf "* %s: (%s). " $(*F) $(*F) >> $@
> +	podselect -section Name $< | \
> +	  perl -n -e  's/notmuch.* - (.*)/\u\L$$1/ && print' >> $@
> +	printf "@end direntry\n" >> $@
> +
> +%.info: %.texi %.entry
>  	makeinfo --no-split -o $@ $<
>  
>  $(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi

> +%.texi: ../pod/%.pod
> +	# a nasty hack, but the nicer ways seem to have bugs.
> +	pod2texi  $< | \
> +	   sed 's/@node Top/@include $(*F).entry\n@node Top/' > $@

This usage of pipeline above is problematic as if pod2texi returns nonzero
it is shadowed by return value of sed. Therefore a temporary file is
needed for this kind of operation.


Tomi