Hi Ploum,
I prepared a manual page for offpunk(1) while working on the package for Debian. The manpage can be obtained in groff format on Salsa1, or you can just use the one in attachment, if it passes through the issue tracker. Do you think it would be a nice addition to a larger audience?
The page was initially obtained from a stub using help2man2, but I was not very happy with the raw output, so resorted to do a couple of manual changes. I believe there is a way to build a manual page using argparse-manpage from python3-argparse-manpage package, but I didn't manage to make sense how I was supposed to use it. Their README3 file seems to suggest some adjustments may be necessary on upstream code.
I don't know for sure whether you would prefer an automatically generated manpage, or a manually written one well curated. The former has less risks of being outdated, won't require you to get into the quirky tool that is groff, and should generally be less distracting from your main work on Offpunk. But the latter will give you full control on what information you want to expose to your users through the "man" command. If you choose the latter, make sure to have a look at man(7) and man-pages(7) documents:
$ man 7 man
$ man 7 man-pages
Please consider this a wishlist item; the file format of manual pages is quirky enough that you may want to focus elsewhere. After all, that's how the help2man command came to appear. ;)
Have a nice day! :)
Hey, this is awesome and I definitely consider that having a man page is a must-have (especially as I plan to split the features of offpunk in 1) the browser itself and 2) a command-line tool to cache/get cached version of a specific URL.
What is still unclear for me is how this man page should be included in the repository. If you have any idea, patches or advices are welcome.
I think I prefer the manual approach to generating a man page to make a "good" man page which would also allow contributions.
Hi Ploum,
Ploum, on 2023-02-28:
What is still unclear for me is how this man page should be included in the repository. If you have any idea, patches or advices are welcome.
I don't have hard requirements. The page I wrote sits currently in my packaging directory. I just have to point to it with my debian/manpages file, which currently shows:
$ cat debian/manpages debian/*.1 $ ls debian/*.1 debian/offpunk.1The heavy lifting is then done by debhelper to put the manual at the right places so it is picked up by man(1), whatis(1), apropos(1) and the likes. When you make a manpage available, I will simply adjust the debian/manpages file to make it fetch your page from its newer location. I suppose a good place would be either alongside the script in ./offpunk.1, or with the rest of the documentation in ./doc/offpunk.1. I'm fine with both options.
I'm not well aware of the best practices for the distribution manual pages shipped with python3 modules in general, outside operating system packages. From strolling through python repositories I have at hand, they are either autogenerated somehow, written by Debian Developpers, or non-existent at all.
Have a nice day, :)
Étienne.
manpage was added in the mdoc format in man/offpunk.1