Re: [PATCH 5/7] doc: Allow as an alternative to rst2man

Subject: Re: [PATCH 5/7] doc: Allow as an alternative to rst2man

Date: Sun, 06 Apr 2014 11:37:09 +0300

To: W. Trevor King


From: Tomi Ollila

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]:
>> …
>> Except the reference to _POSIX_ page. One knows how consistent these
>> specifications are; alternative:
>> 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, *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 

...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

> Trevor
> -- 

More Thoughts?