[RFC Patch v2 2/3] man: partial conversion to pod.

2013-04-24 Thread da...@tethera.net 
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

[RFC Patch v2 2/3] man: partial conversion to pod.

2013-04-24 Thread david 
From: David Bremner brem...@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.

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 21; 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 21; 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 := $(CLEAN) $(COMPRESSED_MAN)