[PATCH 2/3] man: partial conversion to pod.
Tomi Ollila
tomi.ollila at iki.fi
Mon Jan 13 13:06:03 PST 2014
David Bremner <david at tethera.net> writes:
> From: David Bremner <bremner at 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 at 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 at 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
More information about the notmuch
mailing list