[PATCH] doc: Allow rst2man.py as an alternative to rst2man

[PATCH] doc: Allow rst2man.py as an alternative to rst2man

[Tomi Ollila]

From: W. Trevor King <wking@tremily.us>

Gentoo's dev-python/docutils-0.10 installs Docutils scripts with a
*.py extension, so I have /usr/bin/rst2man.py and no rst2man script.
This patch supports users with both types of systems by checking for
rst2man, falling back on rst2man.py, and giving up only if neither is
found.  Users can also set the new RST2MAN path variable explicitly
when they call Make:

  make RST2MAN=/my/custom/rst_to_man_converter build-man

We pass the configured RST2MAN path through to prerst2man.py to use in
its system call.

We can use a non-empty RST2MAN to check for the availability of an
rst2man program, so there's no need for a separate HAVE_RST2MAN.
However, we keep the existing HAVE_RST2MAN for consistency with
HAVE_SPHINX.
---

rebased original
id:2621721db05068dffb65b88cd50d2a5b49e967f5.1405220724.git.wking@tremily.us

rebased by simply doing patch -p1 < patchfile and then creating commit.


 configure          | 20 +++++++++++++++-----
 doc/Makefile.local |  2 +-
 doc/prerst2man.py  |  9 +++++----
 3 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/configure b/configure
index 9c98040c4531..8a4305f8bde3 100755
--- a/configure
+++ b/configure
@@ -455,17 +455,23 @@ if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev
     printf "Yes.\n"
     have_sphinx=1
     have_rst2man=0
+    RST2MAN=
 else
     printf "No (falling back to rst2man).\n"
     have_sphinx=0
 
     printf "Checking if rst2man is available... "
-    if rst2man -V > /dev/null 2>&1; then
-       printf "Yes.\n"
-       have_rst2man=1
-    else
-       printf "No (so will not install man pages).\n"
+    for RST2MAN in rst2man rst2man.py; do
+	if "${RST2MAN}" -V > /dev/null 2>&1; then
+	    have_rst2man=1
+	    printf "Yes (${RST2MAN}).\n"
+	    break
+	fi
+	RST2MAN=
+    done
+    if [ -z "${RST2MAN}" ]; then
        have_rst2man=0
+       printf "No (so will not install man pages).\n"
     fi
 fi
 
@@ -861,6 +867,10 @@ HAVE_RST2MAN=${have_rst2man}
 # Whether there's a doxygen binary available for building api documentation
 HAVE_DOXYGEN=${have_doxygen}
 
+# The path to the rst2man program for building documentation.  Set to
+# an empty string if no such program is available.
+RST2MAN=${RST2MAN}
+
 # The directory to which desktop files should be installed
 desktop_dir = \$(prefix)/share/applications
 
diff --git a/doc/Makefile.local b/doc/Makefile.local
index e7d0bac8f3fb..a13cb3731664 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -51,7 +51,7 @@ ifeq ($(HAVE_SPHINX),1)
 	    mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
 	done
 else ifeq ($(HAVE_RST2MAN),1)
-	$(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
+	$(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
 else
 	@echo "Fatal: build dependency fail."
 	@false
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 968722a1c750..2e87976c5d96 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -4,8 +4,9 @@ from os.path import dirname, isdir
 from os import makedirs, system
 import re
 
-sourcedir = argv[1]
-outdir = argv[2]
+rst2man = argv[1]
+sourcedir = argv[2]
+outdir = argv[3]
 
 if not isdir(outdir):
     makedirs(outdir, 0o755)
@@ -60,5 +61,5 @@ for page in man_pages:
     outfile.write("".join(lines))
     outfile.close()
 
-    system('set -x; rst2man {0} {1}/{2}.{3}'
-           .format(filename, outdir, page[0], page[4]))
+    system('set -x; {0} {1} {2}/{3}.{4}'
+           .format(rst2man, filename, outdir, page[0], page[4]))
-- 
2.0.0

[PATCH] doc: Allow rst2man.py as an alternative to rst2man

[David Bremner]

From: "W. Trevor King" <wking@tremily.us>

Gentoo's dev-python/docutils-0.10 installs Docutils scripts with a
*.py extension, so I have /usr/bin/rst2man.py and no rst2man script.
This patch supports users with both types of systems by checking for
rst2man, falling back on rst2man.py, and giving up only if neither is
found.  Users can also set the new RST2MAN path variable explicitly
when they call Make:

  make RST2MAN=/my/custom/rst_to_man_converter build-man

We pass the configured RST2MAN path through to prerst2man.py to use in
its system call.

We can use a non-empty RST2MAN to check for the availability of an
rst2man program, so there's no need for a separate HAVE_RST2MAN.
However, we keep the existing HAVE_RST2MAN for consistency with
HAVE_SPHINX.
---

At the risk of bike-shedding, rewrite the configure check to be more
"obvious". This is pretty subjective, but in particular I'm not a big
fan of resetting RST2MAN at the bottom of every iteration of the for
loop.  Also conform a bit more to the convention of using a lower case variable in configure and assigning it in Makefile.

For some reason it bugs me a bit to pass RST2MAN as an extra command line argument, but I guess taking some arguments by command line and some by environment variables would also be icky.

configure          | 23 ++++++++++++++++-------
 doc/Makefile.local |  2 +-
 doc/prerst2man.py  |  9 +++++----
 3 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/configure b/configure
index 137acea..fdf5bad 100755
--- a/configure
+++ b/configure
@@ -444,21 +444,27 @@ else
 fi
 
 printf "Checking if sphinx is available and supports nroff output... "
+have_sphinx=0
+have_rst2man=0
+
 if hash sphinx-build > /dev/null 2>&1 && ${python} -m sphinx.writers.manpage > /dev/null 2>&1 ; then
     printf "Yes.\n"
     have_sphinx=1
-    have_rst2man=0
 else
     printf "No (falling back to rst2man).\n"
-    have_sphinx=0
 
+    rst2man=
     printf "Checking if rst2man is available... "
-    if rst2man -V > /dev/null 2>&1; then
-       printf "Yes.\n"
-       have_rst2man=1
-    else
+    for name in rst2man rst2man.py; do
+	if "${name}" -V > /dev/null 2>&1; then
+	    printf "Yes (${name}).\n"
+	    have_rst2man=1
+	    rst2man=$name
+	    break
+	fi
+    done
+    if [ $have_rst2man -eq 0 ]; then
        printf "No (so will not install man pages).\n"
-       have_rst2man=0
     fi
 fi
 
@@ -854,6 +860,9 @@ HAVE_RST2MAN=${have_rst2man}
 # Whether there's a doxygen binary available for building api documentation
 HAVE_DOXYGEN=${have_doxygen}
 
+# The path to the rst2man program for building documentation.
+RST2MAN = ${rst2man}
+
 # The directory to which desktop files should be installed
 desktop_dir = \$(prefix)/share/applications
 
diff --git a/doc/Makefile.local b/doc/Makefile.local
index e7d0bac..a13cb37 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -51,7 +51,7 @@ ifeq ($(HAVE_SPHINX),1)
 	    mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
 	done
 else ifeq ($(HAVE_RST2MAN),1)
-	$(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
+	$(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
 else
 	@echo "Fatal: build dependency fail."
 	@false
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 968722a..2e87976 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -4,8 +4,9 @@ from os.path import dirname, isdir
 from os import makedirs, system
 import re
 
-sourcedir = argv[1]
-outdir = argv[2]
+rst2man = argv[1]
+sourcedir = argv[2]
+outdir = argv[3]
 
 if not isdir(outdir):
     makedirs(outdir, 0o755)
@@ -60,5 +61,5 @@ for page in man_pages:
     outfile.write("".join(lines))
     outfile.close()
 
-    system('set -x; rst2man {0} {1}/{2}.{3}'
-           .format(filename, outdir, page[0], page[4]))
+    system('set -x; {0} {1} {2}/{3}.{4}'
+           .format(rst2man, filename, outdir, page[0], page[4]))
-- 
2.1.3

Re: [PATCH] doc: Allow rst2man.py as an alternative to rst2man

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1111 bytes --]

On Sat, Jan 03, 2015 at 04:49:27PM +0100, David Bremner wrote:
> At the risk of bike-shedding, rewrite the configure check to be more
> "obvious". This is pretty subjective, but in particular I'm not a
> big fan of resetting RST2MAN at the bottom of every iteration of the
> for loop.  Also conform a bit more to the convention of using a
> lower case variable in configure and assigning it in Makefile.

I'm fine with all of these changes.

> @@ -854,6 +860,9 @@ HAVE_RST2MAN=${have_rst2man}
>  # Whether there's a doxygen binary available for building api documentation
>  HAVE_DOXYGEN=${have_doxygen}
>  
> +# The path to the rst2man program for building documentation.
> +RST2MAN = ${rst2man}
> +
>  # The directory to which desktop files should be installed
>  desktop_dir = \$(prefix)/share/applications
>  

I'd keep the RST2MAN entry right after HAVE_RST2MAN, instead of having
HAVE_DOXYGEN between them.

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH] doc: Allow rst2man.py as an alternative to rst2man

[Tomi Ollila]

On Sat, Jan 03 2015, "W. Trevor King" <wking@tremily.us> wrote:

> On Sat, Jan 03, 2015 at 04:49:27PM +0100, David Bremner wrote:
>> At the risk of bike-shedding, rewrite the configure check to be more
>> "obvious". This is pretty subjective, but in particular I'm not a
>> big fan of resetting RST2MAN at the bottom of every iteration of the
>> for loop.  Also conform a bit more to the convention of using a
>> lower case variable in configure and assigning it in Makefile.
>
> I'm fine with all of these changes.

I am also -- and I'd prefer lower-case variables -- however the convention
of using lower case variables is not so clear here (or weren't until
David's ${python} path ;) -- we have mixup of upper & lower case variables
there, and otoh, other (auto)configure scripts seems to use *_RST2MAN.

But, instead of working this further we could also consider Jani's irc comment
of dropping rs2man support altogether... or just keep the status quo and
instruct users just install (recent enough) sphinx to their systems to get
man pages created...

Tomi

PS: In one Scientific Linux 6.2 system I build and run notmuch I have

  # Whether there's a sphinx-build binary available for building documentation
  HAVE_SPHINX=0

  # Whether there's a rst2man binary available for building documentation
  HAVE_RST2MAN=1

because sphinx-build is not recent enough -- sphinx-1.0-build would be but
as it cannot be used by default and as rst2man (w/o .py) works I have not bothered.
I'd presume anyone else using such an old system will have bigger problems
getting their notmuch compiled (recent enough zlib being one of those), so
this makes me wonder whether there is actually anyone needing rst2man there
(besides me, of course :)

Re: [PATCH] doc: Allow rst2man.py as an alternative to rst2man

[David Bremner]

Tomi Ollila <tomi.ollila@iki.fi> writes:

> I'd presume anyone else using such an old system will have bigger
> problems getting their notmuch compiled (recent enough zlib being one
> of those), so this makes me wonder whether there is actually anyone
> needing rst2man there (besides me, of course :)

I guess the original reasoning was that rst2man was part of
python/docutils and so more likely to already be available.  

d

Re: [PATCH] doc: Allow rst2man.py as an alternative to rst2man

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 459 bytes --]

On Sat, Jan 03, 2015 at 07:12:13PM +0200, Tomi Ollila wrote:
> … so this makes me wonder whether there is actually anyone needing
> rst2man there…

Requiring Sphinx >= 1.0 (2010-07-23 [1]) to build man pages is fine
with me.

Cheers,
Trevor

[1]: https://pypi.python.org/pypi/Sphinx/1.0

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]