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

[Tomi Ollila]

On Sat, Apr 05 2014, "W. Trevor King" <wking at tremily.us> 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