Idea: man page
Closed this issue · 5 comments
Currently, we don't have a man page for the pacman-mirrors command. I think it's better to do one for completeness.
How to do - content:
I think the content can be drawn from this wiki page and these docs. But how much we should include on the man page is open for discussion. I can help editing the content when I have time.
How to do - implementation:
http://www.eddieantonio.ca/blog/2015/12/18/authoring-manpages-in-markdown-with-pandoc/
I think Pandoc is the most useful tool as it can convert both html and markdown into man pages. That means we can reuse the wiki and docs easily.
However I'm not sure how this is exactly to be done. Should be do the pandoc conversion in the make system (this requires all contributors to have pandoc), or just someone regularly do the pandoc conversion and commit the output to here?
So, any ideas?
Good idea - I have no experience in man pages :) so you're welcome to fork it and make a PR.
I don't even know which tool is the right one but it seems wise to choose something which can parse the existing docs/index.md.
The chosen tool could be added to the CONTRIBUTE.md so those who actually work on the project knows it is needed.
Man page compiles from Documentation
Wow you're so fast! I am currently occupied by other things so I didn't respond (and I don't think I can contribute much now). Sorry for that.
I just have a quick look of the draft. And may be there are still several things:
- Now it's put at section 1 that's for general commands. But there is also a section 8 which is specifically for system administration commands and daemons (https://en.wikipedia.org/wiki/Man_page). Do you think section 8 is better? (The man page of "pacman" is at section 8)
- Have you put the metadata block (which contains the manual name, version number, date etc.)?
I think content wise the draft is already sufficient. Thank you very much for your great work!
Man page is created as pacman-mirrors(8)
The man page is created by make docs - which generates site hml also.
To convert the index.md to man it the project uses Pandoc
It installed by setup.py /usr/share/man/man8/
@philmmanjaro
When you can spare 5 minutes - will you check my code - and if OK make a new dev package available?
make docs - requires pandoc installed