[PATCH 5/7] doc: Allow rst2man.py as an alternative to rst2man
On Sat, Apr 05 2014, "W. Trevor King" wrote:
> On Sat, Apr 05, 2014 at 10:05:31PM +0300, Tomi Ollila wrote:
>> On Sat, Apr 05 2014, W. Trevor King wrote:
>> > I use POSIX's 'command -v' [1] to find the path to rst2man?
>> >
>> > [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
>>
>> ?
>> Except the reference to _POSIX_ page. One knows how consistent these
>> specifications are; alternative:
>>
>> http://pubs.opengroup.org/onlinepubs/009695399/utilities/command.html
>>
>> mentions additionally that -v flag
>> "(On systems supporting the User Portability Utilities option.)"
>
> It's been a decade since POSIX 2004 ;). I'm not sure when the ?User
> Portability Utilities? caveat was removed, but I imagine most
> POSIX-aspiring shells have -v support. Short of citing POSIX 2013, I
> think I'd have to survey likely shells, and that seems even less
> reliable. Maybe I'm missunderstanding your suggested change?
>
>> Also, we don't give such a treatment to other command either; I'd rather
>> see RST2MAN=rst2man, RST2MAN=rst2man.py *and* RST2MAN= lines used
>> instead -- the last to set RST2MAN to empty string instead of being unset.
>
> I'm fine with that. Alternatively, we could add an:
>
> if -n "${RST2MAN}"
>
> clause to the front of the detection code to allow users with oddball
> scripts (maybe a null set) to override RST2MAN at configure time:
>
> $ RST2MAN=/my/custom/rst_to_man_converter ./configure
> $ make
>
> instead of at make-invocation time:
>
> $ ./configure
> $ make RST2MAN=/my/custom/rst_to_man_converter
>
> That would consolidate configuration around the 'config' call, and
> make explicitly emptying the RST2MAN variable more clearly superfluous
> (although I'm still fine with an explicit empty).
>
> Thoughts?
If we did that, what about other commands, starting with sphinx-build
(that is harder as python -m `sphinx.writers.manpage` fails even
sphinx-build is set to something else; in case of sphinx,
make SPHINXBUILD=sphinx-1.0-build works, for example in RHEL 6.2
machines...
...doing --with-rst2man=my.custom.rst_to_man_converter and make things
look consistent would required considerable amount of development
(and review!) time...
ATM I'd just settle with plain command names and empty RST2MAN in case not
found.
>
> Trevor
>
> --
More Thoughts?
Tomi
[PATCH 5/7] doc: Allow rst2man.py as an alternative to rst2man
On Sat, Apr 05 2014, "W. Trevor King" wrote:
> 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
>
> I use POSIX's 'command -v' [1] to find the path to rst2man or
> rst2man.py, and save that as RST2MAN in Makefile.config. 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. Then pass the
> configured RST2MAN path through to prerst2man.py to use in its system
> call.
>
> [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
This series looks good to me.
Except the reference to _POSIX_ page. One knows how consistent these
specifications are; alternative:
http://pubs.opengroup.org/onlinepubs/009695399/utilities/command.html
mentions additionally that -v flag
"(On systems supporting the User Portability Utilities option.)"
Also, we don't give such a treatment to other command either; I'd rather
see RST2MAN=rst2man, RST2MAN=rst2man.py *and* RST2MAN= lines used
instead -- the last to set RST2MAN to empty string instead of being unset.
Tomi
> ---
> configure | 12 +++-
> doc/Makefile.local | 6 +++---
> doc/prerst2man.py | 9 +
> 3 files changed, 15 insertions(+), 12 deletions(-)
>
> diff --git a/configure b/configure
> index 1d430b9..81c286b 100755
> --- a/configure
> +++ b/configure
> @@ -400,7 +400,6 @@ printf "Checking if sphinx is available and supports
> nroff output... "
> 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
> @@ -408,10 +407,12 @@ else
> printf "Checking if rst2man is available... "
> if rst2man -V > /dev/null 2>&1; then
> printf "Yes.\n"
> - have_rst2man=1
> + RST2MAN=$(command -v rst2man)
> +elif rst2man.py -V > /dev/null 2>&1; then
> + printf "Yes.\n"
> + RST2MAN=$(command -v rst2man.py)
> else
> printf "No (so will not install man pages).\n"
> - have_rst2man=0
> fi
> fi
>
> @@ -788,8 +789,9 @@ HAVE_EMACS = ${have_emacs}
> # Whether there's a sphinx-build binary available for building documentation
> HAVE_SPHINX=${have_sphinx}
>
> -# Whether there's a rst2man binary available for building documentation
> -HAVE_RST2MAN=${have_rst2man}
> +# 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 0980c71..e08fc99 100644
> --- a/doc/Makefile.local
> +++ b/doc/Makefile.local
> @@ -42,8 +42,8 @@ ifeq ($(HAVE_SPHINX),1)
> mkdir -p $(DOCBUILDDIR)/man/man$${section}; \
> mv $(DOCBUILDDIR)/man/*.$${section}
> $(DOCBUILDDIR)/man/man$${section}; \
> done
> -else ifeq ($(HAVE_RST2MAN),1)
> - $(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
> +else ifdef RST2MAN
> + $(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
> else
> @echo "Fatal: build dependency fail."
> @false
> @@ -51,7 +51,7 @@ endif
>
> # Do not try to build or install man pages if a man page converter is
> # not available.
> -ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
> +ifeq ($(HAVE_SPHINX)$(RST2MAN),0)
> build-man:
> install-man:
> @echo "No sphinx or rst2man, will not install man pages."
> diff --git a/doc/prerst2man.py b/doc/prerst2man.py
> index 437dea9..81ce817 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)
> @@ -59,5 +60,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]))
> --
> 1.9.1.353.gc66d89d
>
> ___
> notmuch mailing list
> notmuch at notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch
[PATCH 5/7] doc: Allow rst2man.py as an alternative to rst2man
On Sat, Apr 05, 2014 at 10:05:31PM +0300, Tomi Ollila wrote:
> On Sat, Apr 05 2014, W. Trevor King wrote:
> > I use POSIX's 'command -v' [1] to find the path to rst2man?
> >
> > [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
>
> ?
> Except the reference to _POSIX_ page. One knows how consistent these
> specifications are; alternative:
>
> http://pubs.opengroup.org/onlinepubs/009695399/utilities/command.html
>
> mentions additionally that -v flag
> "(On systems supporting the User Portability Utilities option.)"
It's been a decade since POSIX 2004 ;). I'm not sure when the ?User
Portability Utilities? caveat was removed, but I imagine most
POSIX-aspiring shells have -v support. Short of citing POSIX 2013, I
think I'd have to survey likely shells, and that seems even less
reliable. Maybe I'm missunderstanding your suggested change?
> Also, we don't give such a treatment to other command either; I'd rather
> see RST2MAN=rst2man, RST2MAN=rst2man.py *and* RST2MAN= lines used
> instead -- the last to set RST2MAN to empty string instead of being unset.
I'm fine with that. Alternatively, we could add an:
if -n "${RST2MAN}"
clause to the front of the detection code to allow users with oddball
scripts (maybe a null set) to override RST2MAN at configure time:
$ RST2MAN=/my/custom/rst_to_man_converter ./configure
$ make
instead of at make-invocation time:
$ ./configure
$ make RST2MAN=/my/custom/rst_to_man_converter
That would consolidate configuration around the 'config' call, and
make explicitly emptying the RST2MAN variable more clearly superfluous
(although I'm still fine with an explicit empty).
Thoughts?
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
-- next part --
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: OpenPGP digital signature
URL:
[PATCH 5/7] doc: Allow rst2man.py as an alternative to rst2man
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
I use POSIX's 'command -v' [1] to find the path to rst2man or
rst2man.py, and save that as RST2MAN in Makefile.config. 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. Then pass the
configured RST2MAN path through to prerst2man.py to use in its system
call.
[1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
---
configure | 12 +++-
doc/Makefile.local | 6 +++---
doc/prerst2man.py | 9 +
3 files changed, 15 insertions(+), 12 deletions(-)
diff --git a/configure b/configure
index 1d430b9..81c286b 100755
--- a/configure
+++ b/configure
@@ -400,7 +400,6 @@ printf "Checking if sphinx is available and supports nroff
output... "
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
@@ -408,10 +407,12 @@ else
printf "Checking if rst2man is available... "
if rst2man -V > /dev/null 2>&1; then
printf "Yes.\n"
- have_rst2man=1
+ RST2MAN=$(command -v rst2man)
+elif rst2man.py -V > /dev/null 2>&1; then
+ printf "Yes.\n"
+ RST2MAN=$(command -v rst2man.py)
else
printf "No (so will not install man pages).\n"
- have_rst2man=0
fi
fi
@@ -788,8 +789,9 @@ HAVE_EMACS = ${have_emacs}
# Whether there's a sphinx-build binary available for building documentation
HAVE_SPHINX=${have_sphinx}
-# Whether there's a rst2man binary available for building documentation
-HAVE_RST2MAN=${have_rst2man}
+# 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 0980c71..e08fc99 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -42,8 +42,8 @@ ifeq ($(HAVE_SPHINX),1)
mkdir -p $(DOCBUILDDIR)/man/man$${section}; \
mv $(DOCBUILDDIR)/man/*.$${section}
$(DOCBUILDDIR)/man/man$${section}; \
done
-else ifeq ($(HAVE_RST2MAN),1)
- $(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
+else ifdef RST2MAN
+ $(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
else
@echo "Fatal: build dependency fail."
@false
@@ -51,7 +51,7 @@ endif
# Do not try to build or install man pages if a man page converter is
# not available.
-ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
+ifeq ($(HAVE_SPHINX)$(RST2MAN),0)
build-man:
install-man:
@echo "No sphinx or rst2man, will not install man pages."
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 437dea9..81ce817 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)
@@ -59,5 +60,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]))
--
1.9.1.353.gc66d89d
