[RFC Patch v2 2/3] man: partial conversion to pod.
From: David Bremner 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. 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 | 184 --- man/man7/notmuch-search-terms.7 | 266 pod/notmuch-search-terms.pod| 233 +++ pod/notmuch.pod | 149 ++ 8 files changed, 440 insertions(+), 454 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 5243f6a..a0c53e2 100755 --- a/configure +++ b/configure @@ -371,6 +371,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" @@ -687,6 +696,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/' > $@ + .PHONY: $(dir)/version.texi $(dir)/version.texi: version printf "@set VERSION ${VERSION}\n" > $@ @@ -29,5 +45,8 @@ install-info: ${info} mkdir -p "$(DESTDIR)$(INFODIR)" install -m0644 $(info) "$(DESTDIR)$(INFODIR)" install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) + for ifile in $(man_info); do \ + install-info --info-dir=${DESTDIR}${INFODIR} $${ifile}; \ + done -CLEAN := $(CLEAN) $(info) +CLEAN := $(CLEAN) $(info) $(man_entry) $(dir)/version.texi diff --git a/man/Makefile.local b/man/Makefile.local index 72e2a18..ceb5063 100644 --- a/man/Makefile.local +++ b/man/Makefile.local @@ -21,6 +21,8 @@ MAN1 := \ MAN5 := $(dir)/man5/notmuch-hooks.5 MAN7 := $(dir)/man7/notmuch-search-terms.7 +GENERATED_MAN := $(MAIN_PAGE) $(MAN7) + MAN1_GZ := $(addsuffix .gz,$(MAN1)) MAN5_GZ := $(addsuffix .gz,$(MAN5)) MAN7_GZ := $(addsuffix .gz,$(MAN7)) @@ -32,6 +34,21 @@ COMPRESSED_MAN := $(MAN1_GZ) $(MAN5_GZ) $(MAN7_GZ) %.gz: % gzip --stdout $^ > $@ +POD2MAN_RECIPE = mkdir -p $(@D) && \ +pod2man --section=$(subst .,,$(suffix $@)) \ +--center="Notmuch Documentation" --release=${VERSION} $< > $@ + +$(dir)/man1/%.1: $(dir)/../pod/%.pod + $(POD2MAN_RECIPE) + +$(dir)/man5/%.5: $(dir)/../pod/%.pod + $(POD2MAN_RECIPE) + +$(dir)/man7/%.7: $(dir)/../pod/%.pod + $(POD2MAN_RECIPE) + +CLEAN := $(CLEAN) $(NROFF7) + .PHONY: install-man update-man-versions install-man: $(COMPRESSED_MAN) @@ -50,4 +67,4 @@ update-man-versions: $(MAN_SOURCE) < $$file.bak > $$file; \ done -CLEAN := $(CLEAN) $(COM
[RFC Patch v2 2/3] man: partial conversion to pod.
From: David Bremner 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. 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 | 184 --- man/man7/notmuch-search-terms.7 | 266 pod/notmuch-search-terms.pod| 233 +++ pod/notmuch.pod | 149 ++ 8 files changed, 440 insertions(+), 454 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 5243f6a..a0c53e2 100755 --- a/configure +++ b/configure @@ -371,6 +371,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" @@ -687,6 +696,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/' > $@ + .PHONY: $(dir)/version.texi $(dir)/version.texi: version printf "@set VERSION ${VERSION}\n" > $@ @@ -29,5 +45,8 @@ install-info: ${info} mkdir -p "$(DESTDIR)$(INFODIR)" install -m0644 $(info) "$(DESTDIR)$(INFODIR)" install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) + for ifile in $(man_info); do \ + install-info --info-dir=${DESTDIR}${INFODIR} $${ifile}; \ + done -CLEAN := $(CLEAN) $(info) +CLEAN := $(CLEAN) $(info) $(man_entry) $(dir)/version.texi diff --git a/man/Makefile.local b/man/Makefile.local index 72e2a18..ceb5063 100644 --- a/man/Makefile.local +++ b/man/Makefile.local @@ -21,6 +21,8 @@ MAN1 := \ MAN5 := $(dir)/man5/notmuch-hooks.5 MAN7 := $(dir)/man7/notmuch-search-terms.7 +GENERATED_MAN := $(MAIN_PAGE) $(MAN7) + MAN1_GZ := $(addsuffix .gz,$(MAN1)) MAN5_GZ := $(addsuffix .gz,$(MAN5)) MAN7_GZ := $(addsuffix .gz,$(MAN7)) @@ -32,6 +34,21 @@ COMPRESSED_MAN := $(MAN1_GZ) $(MAN5_GZ) $(MAN7_GZ) %.gz: % gzip --stdout $^ > $@ +POD2MAN_RECIPE = mkdir -p $(@D) && \ +pod2man --section=$(subst .,,$(suffix $@)) \ +--center="Notmuch Documentation" --release=${VERSION} $< > $@ + +$(dir)/man1/%.1: $(dir)/../pod/%.pod + $(POD2MAN_RECIPE) + +$(dir)/man5/%.5: $(dir)/../pod/%.pod + $(POD2MAN_RECIPE) + +$(dir)/man7/%.7: $(dir)/../pod/%.pod + $(POD2MAN_RECIPE) + +CLEAN := $(CLEAN) $(NROFF7) + .PHONY: install-man update-man-versions install-man: $(COMPRESSED_MAN) @@ -50,4 +67,4 @@ update-man-versions: $(MAN_SOURCE) < $$file.bak > $$file; \ done -CLEAN := $(