Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More man page fixes #2652

Merged
merged 6 commits into from
Mar 7, 2024
Merged

More man page fixes #2652

merged 6 commits into from
Mar 7, 2024

Conversation

a3a3el
Copy link
Contributor

@a3a3el a3a3el commented Mar 2, 2024

Fixes for some warnings and formatting errors

@djcb
Copy link
Owner

djcb commented Mar 3, 2024

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
Copy link
Contributor Author

a3a3el commented Mar 3, 2024

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

@djcb
Copy link
Owner

djcb commented Mar 3, 2024

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
Copy link
Contributor Author

a3a3el commented Mar 6, 2024

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
Copy link
Owner

djcb commented Mar 6, 2024

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
Copy link
Contributor Author

a3a3el commented Mar 6, 2024

Cool. I will go with the hyphens.

1.12.0 includes a new mu-move.1 man-page but the list of man-pages in
man/meson.build was not updated, so it is not built.

Signed-off-by: Jeremy Sowden <azazel@debian.org>
There's a closing asterisk missing from a bold string.

Signed-off-by: Jeremy Sowden <azazel@debian.org>
In org-mode, underscores are used to represent subscripts.  Thus, `a_b`
will be transcoded to `a\d\s-2b\s+2\u`.  Configure org-mode only to do
this for `a_{b}`.

Signed-off-by: Jeremy Sowden <azazel@debian.org>
The tables don't define any captions, and ox-man outputs a `.TB` macro that
groff does not support.

Signed-off-by: Jeremy Sowden <azazel@debian.org>
The command names are formatted inconsistently, e.g.:

    * NAME

    ~mu add~ - add one or more messages to the database

versus:

    * NAME

    *mu cfind* is the *mu* command to find contacts in the *mu* database and export them

versus:

    * NAME

    mu server - the mu backend for the mu4e e-mail client

and the format, with a space between "mu" and the subcommand, is not compatible
with mandb(8).  Use formatting which is consistent and replace the spaces with
hyphens.

Signed-off-by: Jeremy Sowden <azazel@debian.org>
The man-page sources use single quotes to quote text.  However, this can be
problematic in man-pages because if a single quote appears at the beginning of a
line the following word is interpreted by troff as a macro.  For example, this
paragraph in mu-easy.7:

    What if we want to see some of the body of the message? You can get a 'summary'
    of the first lines of the message using the \fI\-\-summary\-len\fP option, which will
   'summarize' the first \fIn\fP lines of the message:

elicits this warning:

    $ man --warnings obj-x86_64-linux-gnu/man/mu-easy.7 >/dev/null
    troff:<standard input>:166: warning: macro 'summarize'' not defined

and gets truncated:

    What  if  we want to see some of the body of the message? You can get a
    'summary' of the first lines of the message using the --summary-len op‐
    tion, which will

One could adjust the line-wrapping to move the quoted text away from the
beginning of the line, but that is fragile.  Another possibility would be to use
the troff escape-sequences for open and close quotes (`\(oq` and `\(cq`
respectively), but ox-man is being used precisely to avoid having to handle
troff directly.  Instead use back-ticks for left quotes.  Thus:

    What if we want to see some of the body of the message? You can get a `summary'
    of the first lines of the message using the \fI\-\-summary\-len\fP option, which will
   `summarize' the first \fIn\fP lines of the message:

which is rendered correctly:

    What  if  we want to see some of the body of the message? You can get a
    `summary' of the first lines of the message using the --summary-len op-
    tion, which will `summarize' the first n lines of the message:

Signed-off-by: Jeremy Sowden <azazel@debian.org>
@a3a3el
Copy link
Contributor Author

a3a3el commented Mar 6, 2024

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

@djcb djcb merged commit 06134d3 into djcb:master Mar 7, 2024
2 checks passed
@djcb
Copy link
Owner

djcb commented Mar 7, 2024

Merged -- thanks!

@a3a3el a3a3el deleted the more-man-page-fixes branch May 1, 2024 19:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants