Added pki-server markdown page

[edewata]

The pki-server.8 man page has been converted into Markdown
page. The CMake script has been modified to generate a man
page from the Markdown page.

The pki.spec has been modified to add build dependency on
golang-github-cpuguy83-go-md2man.

https://pagure.io/dogtagpki/issue/2858

The Markdown page can be viewed here.

[SilleBille]

@edewata this looks like a good approach.

I have few comments. I see that cpuguys83/go-md2man is used to convert md to man pages.

1. How reliable is this package?
2. I see the last commit was made on "Jun 19, 2018" and a note saying "** Work in Progress **". Does this package exist across all platforms?
3. We use python-sphinx that is already included as a build requirement. Here is the instruction to convert md to man
4. I feel sphinx is complicated to use. If we decide to add a new build requirement, why not use ronn. ronn exists in all platforms.

My original plan was to host docs in a central server and publish the man page as HTML as well. Here is the issue that I submitted to readthedocs. I have included a flow diagram for reference :)

[edewata]

Thanks for the feedback.

1. How reliable is this package?

In terms of bugs or availability? I'm not sure we can find a definitive answer to that, but judging from the build history it looks like it has been used for sometime and is continuously being built in Fedora and RHEL:
https://koji.fedoraproject.org/koji/packageinfo?packageID=19354

2. I see the last commit was made on "Jun 19, 2018" and a note saying "** Work in Progress **". Does this package exist across all platforms?

I suppose you're referring to this? https://github.com/cpuguy83/go-md2man
I'm not sure about that particular project, but I'm looking at this for examples:
https://github.com/sunaku/md2man

What matters is we can use the actual package on the platform. I can confirm that it is available on Fedora and RHEL, and it looks like it is available on Debian too.

3. We use [python-sphinx](https://github.com/dogtagpki/pki/blob/master/pki.spec#L209) that is already included as a build requirement. Here is the [instruction](https://www.sphinx-doc.org/en/master/usage/markdown.html) to convert md to man

I'm not familiar with sphinx and I don't see an actual example. I think we can use md2man as an initial implementation, but later we can certainly switch to sphinx if that is superior to md2man.

4. I feel `sphinx` is complicated to use. If we decide to add a new build requirement, why not use [ronn](https://github.com/rtomayko/ronn). `ronn` exists in all platforms.

I couldn't find ronn in RHEL.

My original plan was to host docs in a central server and publish the man page as HTML as well. Here is the issue that I submitted to readthedocs. I have included a flow diagram for reference :)

We can still do that. With this patch at least we can start converting the man pages to markdown. The markdown pages will be the master document and stored in git repo to simplify the development. The build artifacts (i.e. the man pages and HTML pages) can be published somewhere else if necessary.

[SilleBille]

I'm not familiar with sphinx and I don't see an actual example. I think we can use md2man as an initial implementation, but later we can certainly switch to sphinx if that is superior to md2man.

We can still do that. With this patch at least we can start converting the man pages to markdown. The markdown pages will be the master document and stored in git repo to simplify the development. The build artifacts (i.e. the man pages and HTML pages) can be published somewhere else if necessary.

The issue is: different packages expect different md styles. If we decide to move from md2man to sphinx in future, we might have to reformat all the markdown files.

Here is an example that is given as input to ronn. Comapre the raw formats of both md files and you'll see the differences. Though the header in markdown appears little awkward, it generates a perfect HTML and roff artifacts. I assume we won't be redirecting users to markdown files but HTML files, right?

I couldn't find ronn in RHEL.

It goes by the name rubygem-ronn

[edewata]

The issue is: different packages expect different md styles. If we decide to move from md2man to sphinx in future, we might have to reformat all the markdown files.

There might be some differences, but I don't expect that to be major since they are all markdown files.

Here is an example that is given as input to ronn. Comapre the raw formats of both md files and you'll see the differences. Though the header in markdown appears little awkward, it generates a perfect HTML and roff artifacts. I assume we won't be redirecting users to markdown files but HTML files, right?

Actually, we want to be able to view the source (i.e. markdown) directly on GitHub so that mistakes can be found and fixed quickly. Compare the md2man input with the ronn input above, it looks good when viewed online (as markdown) and offline (as man pages). If necessary we can later find a tool that can convert it to a good HTML too, but it's a lower priority since the markdown page already looks pretty good.

I couldn't find ronn in RHEL.

It goes by the name rubygem-ronn

Right, but it's not in buildroot.

[edewata]

Here's another md2man example.

[SilleBille]

Tested on local. The generated roff artificat looks perfect! Approving 👍

[edewata]

Thanks!