Idea: man page - Githubissues

manjaro / pacman-mirrors

This repo has been archived. Our code is now hosted at

https://gitlab.manjaro.org

GNU General Public License v3.0

25 stars 16 forks source link

Idea: man page #97

Closed kennethso168 closed 7 years ago

kennethso168 commented 7 years ago

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?

fhdk commented 7 years ago

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.

fhdk commented 7 years ago

Man page compiles from Documentation

kennethso168 commented 7 years ago

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!

fhdk commented 7 years ago

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/

@Huluti @philmmanjaro

fhdk commented 7 years ago

@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