Package: mutt
Version: 2.2.13-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
an.tmac:<stdin>:148: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:153: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:158: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:177: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages mutt depends on:
ii libc6 2.40-6
ii libgnutls30t64 3.8.9-2
ii libgpg-error0 1.51-3
ii libgpgme11t64 1.24.1-4
ii libgsasl18 2.2.1-1+b2
ii libgssapi-krb5-2 1.21.3-4
ii libidn2-0 2.3.7-2+b1
ii libncursesw6 6.5+20250125-2
ii libtinfo6 6.5+20250125-2
ii libtokyocabinet9t64 1.4.48-15.1+b1
ii zlib1g 1:1.3.dfsg+really1.3.1-1+b1
Versions of packages mutt recommends:
ii locales 2.40-6
ii mailcap 3.74
ii sensible-utils 0.0.24
Versions of packages mutt suggests:
ii aspell 0.60.8.1-3
ii ca-certificates 20241223
ii exim4-daemon-light [mail-transport-agent] 4.98-3+b1
ii gnupg 2.2.46-1
ii ispell 3.4.06-1
ii openssl 3.4.0-2
pn urlview <none>
Versions of packages mutt is related to:
ii mutt 2.2.13-1
-- no debconf information
Input file is mbox.5
Output from "mandoc -T lint mbox.5": (shortened list)
1 skipping paragraph macro: PP empty
-.-.
Output from "test-groff -mandoc -t -ww -z mbox.5": (shortened list)
1 Use macro '.B' for one argument or split argument.
3 Use macro '.I' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
3 .IR is for at least 2 arguments, got 1
-.-.
Change '-' (\-) to '\(en' (en-dash) for a (numeric) range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
mbox.5:44:the years 2000-2069. Software reading files in this format should
-.-.
Add a comma (Oxfort comma) (or \&) after "e.g." and "i.e.", or use English
words (man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
60:lines by prepending a '>' (i.e. ">From ", ">>From ", ...). The later
-.-.
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
27:formatted according to \fBRFC822\fP, \fBRFC2822\fP. The file format
28:is line-oriented. Lines are separated by line feed characters (ASCII 10).
32:address, followed by whitespace, and followed by a time stamp. This
37:as defined in \fBRFC2822\fP 3.4.1. The date is expected to be
44:the years 2000-2069. Software reading files in this format should
60:lines by prepending a '>' (i.e. ">From ", ">>From ", ...). The later
70:before storing it. Besides \fBMBOXO\fP and \fBMBOXRD\fP there is also
82:file is greater than the access-time the file has new mail. Many MUAs
97:locking is mostly used on recent, POSIX-compliant systems. Use of
106:Dotlocking is used on all kinds of systems. In order to lock an
110:\fIfolder\fR resides. The application then tries to use the
113:to the temporary file. The success of the
117:calls. If the link has succeeded, the mail folder is considered
118:dotlocked. The temporary file can then safely be unlinked.
133:all individual locks were obtained. When one of the individual
142:files. Failure to do so may result in loss of e-mail data, and in
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
mbox.5:28:is line-oriented. Lines are separated by line feed characters (ASCII
10).
mbox.5:60:lines by prepending a '>' (i.e. ">From ", ">>From ", ...). The later
mbox.5:93:Three different locking mechanisms (and combinations thereof) are in
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
95:.IP "\(bu"
102:.IP "\(bu"
105:.IP "\(bu"
-.-.
Section headings (.SH and .SS) do not need quoting.
166:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:148: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:153: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:158: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:177: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
--- mbox.5 2025-02-13 20:34:09.982085513 +0000
+++ mbox.5.new 2025-02-13 22:06:02.166465213 +0000
@@ -15,50 +15,67 @@ mbox \- Format for mail message storage.
This document describes the format traditionally used by Unix hosts
to store mail messages locally.
.B mbox
-files typically reside in the system's mail spool, under various
-names in users' Mail directories, and under the name
+files typically reside in the system's mail spool,
+under various names in users' Mail directories,
+and under the name
.B mbox
in users' home directories.
.PP
An
.B mbox
is a text file containing an arbitrary number of e-mail messages.
-Each message consists of a postmark, followed by an e-mail message
-formatted according to \fBRFC822\fP, \fBRFC2822\fP. The file format
-is line-oriented. Lines are separated by line feed characters (ASCII 10).
-.PP
-A postmark line consists of the four characters "From", followed by
-a space character, followed by the message's envelope sender
-address, followed by whitespace, and followed by a time stamp. This
-line is often called From_ line.
+Each message consists of a postmark,
+followed by an e-mail message formatted according to \fBRFC822\fP,
+\fBRFC2822\fP.
+The file format is line-oriented.
+Lines are separated by line feed characters
+(ASCII 10).
+.PP
+A postmark line consists of the four characters "From",
+followed by a space character,
+followed by the message's envelope sender address,
+followed by whitespace,
+and followed by a time stamp.
+This line is often called From_ line.
.PP
The sender address is expected to be
.B addr-spec
-as defined in \fBRFC2822\fP 3.4.1. The date is expected to be
+as defined in \fBRFC2822\fP 3.4.1.
+The date is expected to be
.B date-time
as output by
.BR asctime (3).
-For compatibility reasons with legacy software, two-digit years
-greater than or equal to 70 should be interpreted as the years
-1970+, while two-digit years less than 70 should be interpreted as
-the years 2000-2069. Software reading files in this format should
+For compatibility reasons with legacy software,
+two-digit years greater than or equal to 70 should be interpreted as the
+years 1970+,
+while two-digit years less than 70 should be interpreted as the years
+2000\(en2069.
+Software reading files in this format should
also be prepared to accept non-numeric timezone information such as
-"CET DST" for Central European Time, daylight saving time.
+"CET DST" for Central European Time,
+daylight saving time.
.PP
Example:
.IP "" 1
>From exam...@example.com Fri Jun 23 02:56:55 2000
.PP
In order to avoid misinterpretation of lines in message bodies
-which begin with the four characters "From", followed by a space
-character, the mail delivery agent must quote any occurrence
-of "From " at the start of a body line.
+which begin with the four characters "From",
+followed by a space character,
+the mail delivery agent must quote any occurrence of "From " at the start
+of a body line.
.sp
-There are two different quoting schemes, the first (\fBMBOXO\fP) only
-quotes plain "From " lines in the body by prepending a '>' to the
-line; the second (\fBMBOXRD\fP) also quotes already quoted "From "
-lines by prepending a '>' (i.e. ">From ", ">>From ", ...). The later
-has the advantage that lines like
+There are two different quoting schemes,
+the first
+(\fBMBOXO\fP)
+only quotes plain "From " lines in the body by prepending a '>' to the
+line;
+the second
+(\fBMBOXRD\fP)
+also quotes already quoted "From " lines by
+prepending a '>'
+(i.e., ">From ", ">>From ", ...).
+The later has the advantage that lines like
.IP "" 1
>From the command line you can use the '\-p' option
.PP
@@ -67,19 +84,23 @@ into
.IP "" 1
>>From the command line you can use the '\-p' option
.PP
-before storing it. Besides \fBMBOXO\fP and \fBMBOXRD\fP there is also
+before storing it.
+Besides \fBMBOXO\fP and \fBMBOXRD\fP there is also
\fBMBOXCL\fP which is \fBMBOXO\fP with a "Content-Length:"\-field with the
-number of bytes in the message body; some MUAs (like
+number of bytes in the message body; some MUAs
+(like
.BR mutt (1))
do automatically transform \fBMBOXO\fP mailboxes into \fBMBOXCL\fP ones when
ever they write them back as \fBMBOXCL\fP can be read by any \fBMBOXO\fP-MUA
without any problems.
.PP
-If the modification-time (usually determined via
+If the modification-time
+(usually determined via
.BR stat (2))
of a nonempty
.B mbox
-file is greater than the access-time the file has new mail. Many MUAs
+file is greater than the access-time the file has new mail.
+Many MUAs
place a Status: header in each message to indicate which messages have
already been read.
.\"
@@ -90,38 +111,49 @@ files are frequently accessed by multipl
.B mbox
files should generally not be accessed without locking.
.PP
-Three different locking mechanisms (and combinations thereof) are in
-general use:
-.IP "\(bu"
+Three different locking mechanisms
+(and combinations thereof)
+are in general use:
+.IP \(bu
.BR fcntl (2)
-locking is mostly used on recent, POSIX-compliant systems. Use of
-this locking method is, in particular, advisable if
-.B mbox
-files are accessed through the Network File System (NFS), since it
-seems the only way to reliably invalidate NFS clients' caches.
-.IP "\(bu"
+locking is mostly used on recent,
+POSIX-compliant systems.
+Use of this locking method is,
+in particular,
+advisable if
+.B mbox
+files are accessed through the Network File System (NFS),
+since it seems the only way to reliably invalidate NFS clients' caches.
+.IP \(bu
.BR flock (2)
locking is mostly used on BSD-based systems.
-.IP "\(bu"
-Dotlocking is used on all kinds of systems. In order to lock an
-.B mbox
-file named \fIfolder\fR, an application first creates a temporary file
-with a unique name in the directory in which the
-\fIfolder\fR resides. The application then tries to use the
+.IP \(bu
+Dotlocking is used on all kinds of systems.
+In order to lock an
+.B mbox
+file named \fIfolder\fR,
+an application first creates a temporary file
+with a unique name in the directory
+in which the \fIfolder\fR resides.
+The application then tries to use the
.BR link (2)
system call to create a hard link named \fIfolder.lock\fR
-to the temporary file. The success of the
+to the temporary file.
+The success of the
.BR link (2)
system call should be additionally verified using
.BR stat (2)
-calls. If the link has succeeded, the mail folder is considered
-dotlocked. The temporary file can then safely be unlinked.
+calls.
+If the link has succeeded,
+the mail folder is considered dotlocked.
+The temporary file can then safely be unlinked.
.IP ""
-In order to release the lock, an application just unlinks the
+In order to release the lock,
+an application just unlinks the
\fIfolder.lock\fR file.
.PP
-If multiple methods are combined, implementors should make sure to
-use the non-blocking variants of the
+If multiple methods are combined,
+implementors should make sure to use the non-blocking variants of the
.BR fcntl (2)
and
.BR flock (2)
@@ -130,40 +162,44 @@ system calls in order to avoid deadlocks
If multiple methods are combined, an
.B mbox
file must not be considered to have been successfully locked before
-all individual locks were obtained. When one of the individual
-locking methods fails, an application should release all locks it
-acquired successfully, and restart the entire locking procedure from
-the beginning, after a suitable delay.
-.PP
-The locking mechanism used on a particular system is a matter of
-local policy, and should be consistently used by all applications
-installed on the system which access
+all individual locks were obtained.
+When one of the individual
+locking methods fails,
+an application should release all locks it acquired successfully,
+and restart the entire locking procedure from the beginning,
+after a suitable delay.
+.PP
+The locking mechanism used on a particular system is a matter of local
+policy,
+and should be consistently used by all applications installed on the
+system which access
.B mbox
-files. Failure to do so may result in loss of e-mail data, and in
-corrupted
+files.
+Failure to do so may result in loss of e-mail data,
+and in corrupted
.B mbox
files.
.\"
.SH FILES
-.IR /var/spool/mail/$LOGNAME
+.I /var/spool/mail/$LOGNAME
.RS
\fB$LOGNAME\fP's incoming mail folder.
.RE
.PP
-.IR $HOME/mbox
+.I $HOME/mbox
.RS
-user's archived mail messages, in his \fB$HOME\fP directory.
+user's archived mail messages,
+in his \fB$HOME\fP directory.
.RE
.PP
-.IR $HOME/Mail/
+.I $HOME/Mail/
.RS
A directory in user's \fB$HOME\fP directory which is commonly used to hold
.B mbox
format folders.
.RE
-.PP
.\"
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR mutt (1),
.BR fcntl (2),
.BR flock (2),
@@ -174,7 +210,7 @@ format folders.
.BR mmdf (5),
.BR RFC822 ,
.BR RFC976 ,
-.BR RFC2822
+.BR RFC2822 .
.\"
.SH AUTHOR
Thomas Roessler <roess...@does-not-exist.org>, Urs Janssen <u...@tin.org>
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Line length should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
