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>:26: style: 1 leading space(s) on input line
* 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 mmdf.5
Output from "mandoc -T lint mmdf.5": (shortened list)
1 skipping paragraph macro: br after br
2 skipping paragraph macro: br after sp
2 skipping paragraph macro: br before sp
-.-.
Output from "test-groff -mandoc -t -ww -z mmdf.5": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
-.-.
Add a comma (Oxford 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.
16:mailbox format used by some MTAs and MUAs (i.e.
-.-.
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.
24:according to \fBRFC822\fP / \fBRFC2822\fP, followed by a postmark. The file
25:format is line-oriented. Lines are separated by line feed characters (ASCII
26:10). A postmark line consists of the four characters "^A^A^A^A" (Control-A;
74:the file has new mail. Many MUAs place a Status: header in
89:locking is mostly used on recent, POSIX-compliant systems. Use of
98:Dotlocking is used on all kinds of systems. In order to lock an
102:\fIfolder\fR resides. The application then tries to use the
105:to the temporary file. The success of the
109:calls. If the link has succeeded, the mail folder is considered
110:dotlocked. The temporary file can then safely be unlinked.
125:all individual locks were obtained. When one of the individual
134: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".
mmdf.5:85: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.
8:.TH mmdf 5 "February 18th, 2002" "Unix" "User Manuals"
87:.IP "\(bu"
94:.IP "\(bu"
97:.IP "\(bu"
-.-.
Section headings (.SH and .SS) do not need quoting.
145:.SH "CONFORMING TO"
153:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:161: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
--- mmdf.5 2025-02-13 23:55:59.878942732 +0000
+++ mmdf.5.new 2025-02-14 00:17:17.768766956 +0000
@@ -5,7 +5,7 @@
.\" Updated :
.\" Notes : needs a lot of work
.\"
-.TH mmdf 5 "February 18th, 2002" "Unix" "User Manuals"
+.TH mmdf 5 "February 18th, 2002" Unix "User Manuals"
.\"
.SH NAME
MMDF \- Multi\-channel Memorandum Distribution Facility mailbox format
@@ -13,18 +13,21 @@ MMDF \- Multi\-channel Memorandum Distri
.SH DESCRIPTION
This document describes the
.B MMDF
-mailbox format used by some MTAs and MUAs (i.e.
+mailbox format used by some MTAs and MUAs (i.e.,
.BR scomail (1))
to store mail messages locally.
.PP
An
.B MMDF
mailbox 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, followed by a postmark. The file
-format is line-oriented. Lines are separated by line feed characters (ASCII
-10). A postmark line consists of the four characters "^A^A^A^A" (Control-A;
-ASCII 1).
+Each message consists of a postmark,
+followed by an e-mail message formatted according to
+\fBRFC822\fP / \fBRFC2822\fP,
+followed by a postmark.
+The file format is line-oriented.
+Lines are separated by line feed characters (ASCII 10).
+A postmark line consists of the four characters "^A^A^A^A"
+(Control-A; ASCII 1).
.TP
Example of a \fBMMDF\fP mailbox holding two mails:
.RS
@@ -37,12 +40,9 @@ From: exam...@example.com
To: exam...@example.org
.br
Subject: test
-.br
.sp
-.br
>From what I learned about the MMDF-format:
.br
-.br
^A^A^A^A
.br
^A^A^A^A
@@ -52,9 +52,7 @@ From: exam...@example.com
To: exam...@example.org
.br
Subject: test 2
-.br
.sp
-.br
bar
.br
^A^A^A^A
@@ -71,9 +69,9 @@ mailboxes as such lines have no special
If the modification-time (usually determined via
.BR stat (2))
of a nonempty mailbox 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.
+the file has new mail.
+Many MUAs place a Status: header in each message to indicate
+which messages have already been read.
.\"
.SH LOCKING
Since
@@ -82,32 +80,41 @@ files are frequently accessed by multipl
.B MMDF
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 MMDF
-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 MMDF
+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 MMDF
-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 MMDF
+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
\fIfolder.lock\fR file.
@@ -122,17 +129,19 @@ system calls in order to avoid deadlocks
If multiple methods are combined, an
.B MMDF
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.
+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 MMDF
-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 MMDF
files.
.\"
@@ -142,7 +151,7 @@ files.
.\"
.\" .SH SECURITY
.\"
-.SH "CONFORMING TO"
+.SH CONFORMING TO
.B MMDF
is not part of any currently supported standard.
.\"
@@ -150,7 +159,7 @@ is not part of any currently supported s
.B MMDF
was developed at the University of Delaware by Dave Crocker.
.\"
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR scomail (1),
.BR fcntl (2),
.BR flock (2),
@@ -158,7 +167,7 @@ was developed at the University of Delaw
.BR stat (2),
.BR mbox (5),
.BR RFC822 ,
-.BR RFC2822
+.B RFC2822
.SH AUTHOR
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)
