More man page fixes

[a3a3el]

Fixes for some warnings and formatting errors

[djcb]

Thanks, but changing to e.g., mu_add and rebuilding gives me (man -l build/man/mu-add.1)

NAME
       muadd - add one or more messages to the database

am I missing something?

[a3a3el]

Have you applied the full series? In particular: "man: fix formatting of underscores".

[djcb]

Ah, testing the whole branch, I get e.g. mu_server in man.
Looking at the generated text:

.TH "MU-SERVER" "1"

.SH "NAME"
.PP
mu_server - the mu backend for the mu4e e-mail client

the underscore is unwanted.

[a3a3el]

Since you're not a fan of the underscores, I've done some more research. :) As I mentioned in the commit message the reason to introduce the underscore was to allow mandb to parse the NAME sections for use by whatis and apropos. The lexgrog man-page, which describes the script that mandb uses to do the parsing explains that it will try to parse many different formats, but not ones that contain white space. I cannot now find the man-page that recommended underscores, but I've looked at some other software that has per-subcommand man-pages (git, docker, cargo), and in all cases hyphens were used. For example:

.SH "NAME"
git-blame \- Show what revision and author last modified each line of a file
.SH "SYNOPSIS"
.sp
.nf
\fIgit blame\fR [\-c] [\-b] [\-l] [\-\-root] [\-t] [\-f] [\-n] [\-s] [\-e] [\-p] [\-w] [\-\-incremental]
            [\-L <range>] [\-S <revs\-file>] [\-M] [\-C] [\-C] [\-C] [\-\-since=<date>]
            [\-\-ignore\-rev <rev>] [\-\-ignore\-revs\-file <file>]
            [\-\-color\-lines] [\-\-color\-by\-age] [\-\-progress] [\-\-abbrev=<n>]
            [ \-\-contents <file> ] [<rev> | \-\-reverse <rev>\&.\&.<rev>] [\-\-] <file>
.fi
.sp

Would hyphens be acceptable?

.SH "NAME"
.PP
mu-add - add one or more messages to the database

.SH "SYNOPSIS"
.PP
\fBmu [common-options] add [options] <file> [<files>]\fP

[djcb]

Oh, the _ was by design? Yeah, I'm not a fan of that :-) And parsing by some tools is secondary to the human reader I think.

But, a hyphen is acceptable though, since it's a bit less ugly, and since reflects the name of the manpage (i.e., man mu-add); probably also why those other tools use it.

[a3a3el]

Cool. I will go with the hyphens.

[a3a3el]

I've also tweaked a couple of commit messages and changed the order of the commits to put the short ones first.

[djcb]

Merged -- thanks!