RE: [PATCH 05/13] Have cmake run man pages through text substitution

Weiny, Ira
2016-09-26T18:17:03Z

> On Mon, Sep 26, 2016 at 03:19:53PM +0000, Hefty, Sean wrote:
> > > Infiniband-diags uses rst through rst2man. But if I had to do it
> > > over I would probably do it different. rst2man is not always
> > > installed and has caused build issues for some people. Whatever
> > > tool we use I would recommend it be something common. I'm not too
> familiar with markdown.
> > > Is this really common now?
> >
> > Only by those who want to provide actual documentation.
>
> Markdown is very popular on github and the integrated processing of the
> web UI is why I picked it for the docs I started. But rst started the trend of
> structued ascii..
>
> IMHO, rst is more widely available in distros today than pandoc.
>
> rst2man is incredibly widely distributed: it comes with python-docutils which
> is widely included in every distribution. I have no idea why people would
> complain to you on that point. If something comes in-box in all the distros
> then it is fair game to depend upon, IMHO.

I thought so to. But python-docutils is in the "optional" section of RH.

https://ask.openstack.org/en/question/67176/python-docutils-openstack-installation/

>
> > Libfabric uses a daemon that checks for updates to the markdown pages.
> > If it finds any, it generates the man page and commits those changes
> > to the source tree. So the tar file always has the actual man page.
> > Our tool selection was based on what worked well with github and web
> > page generation.
>
> I generally frown on checking in built files, but yeah, that is an option.

Yep I agree. But I resorted to this as well.

:-(

Ira