Package: mailcap
Version: 3.70+nmu1
Severity: minor
Tags: patch
Dear Maintainer,
here are some notes and editorial fixes for the manual.
The patch is in the attachment.
-.-
The difference between the formatted outputs can be seen with:
nroff -man <file1> > <out1>
nroff -man <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "
instead of "nroff -man"
Add the option "-t", if the file contains a table.
Read the output of "diff -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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint update-mime.8":
mandoc: update-mime.8:12:2: WARNING: skipping paragraph macro: PP after SH
mandoc: update-mime.8:197:39: STYLE: unterminated quoted argument
-.-.
Input file is update-mime.8.
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.
update-mime.8:64:probably a good idea to add a "priority=[1-4]" option so
specific
-.-.
Change two HYPHEN-MINUSES (code 0x055, 2D) to an em-dash (\(em),
if one is intended. An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters) transforms an en-dash (\(en ) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-" (end of options) then use "\-\-".
update-mime.8:84:suitable for mail transport -- that is, a
Content-Transfer-Encoding
update-mime.8:137:a test -- it is a requirement for the environment in which
the program
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
20:.BI \-\-local
129:.BI needsterminal
142:.BI copiousoutput
158:.BI textualnewlines
-.-.
Find a repeated word
! 183 --> the
-.-.
Wrong distance between sentences.
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.
N.B
The number of lines affected is too large to be in the patch.
193:mailcap entries. These entries are given a lower priority than those
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
182:.B mime-support,
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
37:.BR mailcap.order(5)
-.-.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (990, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.4.13-1 (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 mailcap depends on:
ii media-types 10.1.0
ii perl 5.36.0-9
Versions of packages mailcap recommends:
ii bzip2 1.0.8-5+b1
ii file 1:5.45-2
ii xz-utils 5.4.4-0.1
mailcap suggests no packages.
-- no debconf information
The difference between the formatted outputs can be seen with:
nroff -man <file1> > <out1>
nroff -man <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "
instead of "nroff -man"
Add the option "-t", if the file contains a table.
Read the output of "diff -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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint update-mime.8":
mandoc: update-mime.8:12:2: WARNING: skipping paragraph macro: PP after SH
mandoc: update-mime.8:197:39: STYLE: unterminated quoted argument
-.-.
Input file is update-mime.8.
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.
update-mime.8:64:probably a good idea to add a "priority=[1-4]" option so
specific
-.-.
Change two HYPHEN-MINUSES (code 0x055, 2D) to an em-dash (\(em),
if one is intended. An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters) transforms an en-dash (\(en ) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-" (end of options) then use "\-\-".
update-mime.8:84:suitable for mail transport -- that is, a
Content-Transfer-Encoding
update-mime.8:137:a test -- it is a requirement for the environment in which
the program
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
20:.BI \-\-local
129:.BI needsterminal
142:.BI copiousoutput
158:.BI textualnewlines
-.-.
Find a repeated word
! 183 --> the
-.-.
Wrong distance between sentences.
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.
N.B
The number of lines affected is too large to be in the patch.
193:mailcap entries. These entries are given a lower priority than those
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
182:.B mime-support,
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
37:.BR mailcap.order(5)
-.-.
