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

[Jason Gunthorpe <jgunthorpe-ePGOBjL8dl3ta4EC/59zMFaTQe2KTcn/@public.gmane.org>]

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
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html