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

Jason Gunthorpe
2016-09-26T17:47:13Z

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.

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

Jason