Feature: author manpage in markdown

[orndorffgrant]

Please describe the scenario where the new feature would be useful

3082

Describe the solution you'd like

authoring our manpage in markdown will make it easier to update, because the dev team is familiar with markdown syntax

we may be able to do this with pandoc?

[orndorffgrant]

Something like this pandoc --standalone --to man pro.1.md -o pro.1

[allgeo]

Hi @orndorffgrant, I would like to contribute to this feature if it is still relevant. It seems feasible to generate the manpage from markdown using pandoc. The approach would be to use a markdown template (instead of the current manpage template) while still automatically generating the command entries for the manpage (d5cf2b5), followed by the conversion using Pandoc.

I believe this approach could also address issues #3311 & #3312 if they are still relevant.

Thank you!

[orndorffgrant]

Hi @allgeo and thanks for offering the help! You're absolutely welcome to contribute this feature. I highly recommend you stick with only solving one problem at a time, so don't try to solve #3311 and #3312 at the same time as this one.

If you're interested I can assign you to this issue.

[allgeo]

Yes, please assign the issue to me. I will focus only on this issue as you suggested.

If I'm not mistaken, at the moment the ubuntu-advantage.1 is the man page that's generated using the ubuntu-advantage.1.template template where the command entries are filled in during the generation. Is the process of generating the man page a manual process? For instance, is the clidocgen.py script run manually by one of the devs, or is there some automation workflow that I missed?

[orndorffgrant]

Great! Yes you're right. Running clidocgen.py is a manual task.