sigmf-python
sigmf-python copied to clipboard
sigmf
Please provide man pages
While preparing packages for Debian, the lintian tool reports:
W: python3-sigmf: no-manual-page [usr/bin/sigmf_gui]
W: python3-sigmf: no-manual-page [usr/bin/sigmf_validate]
N:
N: Each binary in /usr/bin, /usr/sbin, /bin, /sbin or /usr/games should have
N: a manual page
N:
N: Note that though the man program has the capability to check for several
N: program names in the NAMES section, each of these programs should have its
N: own manual page (a symbolic link to the appropriate manual page is
N: sufficient) because other manual page viewers such as xman or tkman don't
N: support this.
N:
N: If the name of the manual page differs from the binary by case, man may be
N: able to find it anyway; however, it is still best practice to match the
N: exact capitalization of the executable in the manual page.
N:
...
A sigmf_gui.1 and a sigmf_validate.1 man page in the top level directory would suffice.
Also - webapp: perhaps too generic a name? It could use some documentation too.
Once that is done, a tag and a release would help define a version for a Debian package to use. Thanks, -Maitland
@maitbot I've got a manpages branch which adds a --version option to both tools, which then enables
help2man -N -n "sigmf_gui" -s1 -S "SigMF project" -o sigmf_gui.1 $(which sigmf_gui)
help2man -N -n "sigmf_validate" -s1 -S "SigMF project" -o sigmf_validate.1 $(which sigmf_gui)
Is it possible to add that to debian/rules? It'd be desirable to generate the man pages on the fly rather than to check them in, as they do contain version numbers that need to be extracted from the runtime, each time.
That depends on whether what we added here is useful to debian packaging or not!
We should add the following to the automated build process, then we can close this issue.
help2man -N -n "sigmf_validate" -s1 -S "SigMF project" -o sigmf_validate.1 $(which sigmf_validate)
help2man -N -n "sigmf_convert_wav" -s1 -S "SigMF project" -o sigmf_convert_wav.1 $(which sigmf_convert_wav)
Note these output files can be previewed with man ./sigmf_validate.1
@Teque5 would that help? We're building a python package, and those really don't have a way to install man pages, do they?
If we are building a man page that then nobody can use, and @maitbot has to manually extract from the artifact and copy into the right place, then kick of mandb: are we really helping debian or would they be just as happy building the man page themselves, now that we have provided the automatable way to do so?
I ask because I'm not keen on cluttering the python module with artifacts unrelated to python.