Expand several man pages and fix missing man page for sndfile-waveform

[musicinmybrain]

Expand the man pages for:

• sndfile-generate-chirp
• sndfile-jackplay
• sndfile-mix-to-mono
• sndfile-spectrogram

to be at least as useful as their --help output.

---

I saw that there is a man page for sndfile-waveform, contrary to my claim in #77, but it is not included in the release tarball, so I fixed that in this PR too. (sndfile-waveform.1 was missing from dist_man_MANS in Makefile.am; the fix may be obsolete soon, as it looks like the project is switching to CMake, and sndfile-waveform.1 is not missing from SNDFILE_TOOLS_MANS in CMakeLists.txt.)

---

I did not touch the man page for sndfile-resample, since it is relatively recently updated and in good condition.

The man pages I updated were, and are, in -man format, groff_man(7); the man page for sndfile-resample is in -mdoc format, groff_mdoc(7); and the man page for sndfile-waveform is generated by help2man. This mixture is unfortunate, but I’m not proposing to change it, as:

• I did not want to write -mdoc format from scratch or set up the command output for help2man for the man pages I updated.
• The other two man pages are already complete and apparently maintaned, so it would be presumptuous of me to rewrite them just to match my preferred format.

[evpobr]

@SoapGentoo , can you take these new PRs?

[SoapGentoo]

@musicinmybrain if you like, you can propose a consistent, uniform format and we'll take it

[evpobr]

the man page for sndfile-waveform is generated by help2man

So it is standard manpage or it is not?

[musicinmybrain]

the man page for sndfile-waveform is generated by help2man

So it is standard manpage or it is not?

Yeah, it’s fine! It’s a -man format page like the ones I hand-wrote. It’s just that it’s based entirely on the --help output, and designed to be regenerated rather than edited when the C source changes. So it is a third way of doing man pages even though the result is the same basic format I used.

Sometimes it’s hard to get what you want with help2man. In that case it may be better used as a one-time starting point for a hand-written man page. On the other hand, if the output is acceptable, it has the obvious advantage that you only have to edit the documentation in one place.

[musicinmybrain]

@musicinmybrain if you like, you can propose a consistent, uniform format and we'll take it

If I were proposing to be the Sndfile-tools Man Page Person in perpetuum, I certainly would. But I’m likely to wander off eventually, and I wonder if there are organizational reasons not to. By re-writing some of the man pages so they all follow a consistent format, it would make it easier for the average contributor to work across all of them, but perhaps at the cost of making it harder or less pleasant for the original contributors of one or more man pages to maintain their contributions.

It looks like @x42, who was responsible for using help2man for sndfile-waveform, hasn’t committed here in a while, but @erikd certainly has. I guess updating everything to the -mdoc format it looks like they now prefer could work for them and for me, and would at least be consistent for other contributors (I do think -man is simpler to follow even though -mdoc is nicer to write in some ways)—but I know -man a lot better, so it would take a while.

I’ll think about it. I’m interested in your thoughts on the above, as well.