Package: manpages
Version: 6.9.1-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[Use "groff -e ' $' <file>" to find 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?
troff: backtrace: file '<stdin>':357
troff:<stdin>:357: warning: unbalanced 'el' request
* 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.11.9-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)
manpages depends on no packages.
manpages recommends no packages.
Versions of packages manpages suggests:
ii man-db [man-browser] 2.13.0-1
-- no debconf information
Input file is zic.8
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
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
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.
Lines should thus be shorter.
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 -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 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 -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint zic.8 ": (shortened list)
1 missing date, using ""
2 undefined escape, printing literally
-.-.
Output from "test-groff -mandoc -t -ww -b -z zic.8 ": (shortened list)
1 unbalanced 'el' request
-.-.
Output from "mandoc -T lint zic.8 ":
mandoc: zic.8:3:11: WARNING: missing date, using "": TH
mandoc: zic.8:19:18: WARNING: undefined escape, printing literally: \\
mandoc: zic.8:19:9: WARNING: undefined escape, printing literally: \\
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Line 298, length 99
\*<https://pubs\*:.opengroup\*:.org/\*:onlinepubs/\*:9699919799/\*:basedefs/\*:V1_chap06\*:.html\*>
Line 334, length 140
.ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u
+\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00w\0\0'u +\w'1:00d\0\0'u
Line 527, length 89
.ta \w'Zone\0\0'u +\w'Asia/Amman\0\0'u +\w'STDOFF\0\0'u +\w'Jordan\0\0'u
+\w'FORMAT\0\0'u
Line 658, length 140
.ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'2006\0\0'u +\w'\*-\0\0'u
+\w'Oct\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u
Line 663, length 97
.ta \w'# Zone\0\0'u +\w'America/Menominee\0\0'u +\w'STDOFF\0\0'u
+\w'RULES\0\0'u +\w'FORMAT\0\0'u
Line 732, length 96
.ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u
+\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u
Line 811, length 140
.ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u
+\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u
Line 824, length 97
.ta \w'# Zone\0\0'u +\w'Europe/Zurich\0\0'u +\w'0:29:45.50\0\0'u
+\w'RULES\0\0'u +\w'FORMAT\0\0'u
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
816:.sp .5
-.-.
Two or more space charaters between printable characters.
When the distance is between sentences,
start the beginning of the second one on a separate line
("semantic newline").
248:an extended POSIX.1-2017 TZ string. For example, as of 2023 this problem
256:output formats. These compatibility issues affect only timestamps
300:non-PPCS bytes. Non-PPCS characters typically occur only in comments:
848:apply. From 1981 to the present, EU daylight saving rules have
854:here, but are included for completeness. Since 1981, daylight
863:were initially used, respectively. Since
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':357
troff:<stdin>:357: warning: unbalanced 'el' request
-.-
To the warning:
The '.if, .ie, and .el requests take only one logical line with them, a block
(\{...\}) counts as a logical line for the translator "groff".
See "Troff User's Manual", https://troff.org/54.pdf, chapter 16, item
"multi-line".
--- zic.8 2024-11-25 09:50:03.388308951 +0000
+++ zic.8.new 2024-11-25 03:25:14.618201152 +0000
@@ -245,16 +245,18 @@ for
.PP
The output file does not contain all the information about the
long-term future of a timezone, because the future cannot be summarized as
-an extended POSIX.1-2017 TZ string. For example, as of 2023 this problem
-occurs for Morocco's daylight-saving rules, as these rules are based
-on predictions for when Ramadan will be observed, something that
-an extended POSIX.1-2017 TZ string cannot represent.
+an extended POSIX.1-2017 TZ string.
+For example,
+as of 2023 this problem occurs for Morocco's daylight-saving rules,
+as these rules are based on predictions for when Ramadan will be observed,
+something that an extended POSIX.1-2017 TZ string cannot represent.
.PP
The output contains data that may not be handled properly by client
code designed for older
.B zic
-output formats. These compatibility issues affect only timestamps
-before 1970 or after the start of 2038.
+output formats.
+These compatibility issues affect only timestamps before 1970
+or after the start of 2038.
.PP
The output contains a truncated leap second table,
which can cause some older TZif readers to misbehave.
@@ -297,7 +299,8 @@ is typically UTF-8 or ASCII; it should h
for the POSIX Portable Character Set (PPCS)
\*<https://pubs\*:.opengroup\*:.org/\*:onlinepubs/\*:9699919799/\*:basedefs/\*:V1_chap06\*:.html\*>
and the encoding's non-unibyte characters should consist entirely of
-non-PPCS bytes. Non-PPCS characters typically occur only in comments:
+non-PPCS bytes.
+Non-PPCS characters typically occur only in comments:
although output file names and time zone abbreviations can contain
nearly any character, other software will work better if these are
limited to the restricted syntax described under the
@@ -353,8 +356,10 @@ nor
To allow for future extensions,
an unquoted name should not contain characters from the set
.ie \n(.g .q \f(CR!$%&\(aq()*,/:;<=>?@[\e]\(ha\(ga{|}\(ti\fP .
-.el .ie t .q \f(CW!$%&'()*,/:;<=>?@[\e]^\(ga{|}~\fP .
-.el .q !$%&'()*,/:;<=>?@[\e]^`{|}~ .
+.el \{\
+. ie t .q \f(CW!$%&'()*,/:;<=>?@[\e]^\(ga{|}~\fP .
+. el .q !$%&'()*,/:;<=>?@[\e]^`{|}~ .
+.\}
.TP
.B FROM
Gives the first year in which the rule applies.
@@ -845,14 +850,17 @@ treats this by rounding it to 0:29:46.
After 1894-06-01 at 00:00 the UT offset became one hour
and Swiss daylight saving rules (defined with lines beginning with
.q "Rule Swiss")
-apply. From 1981 to the present, EU daylight saving rules have
-applied, and the UTC offset has remained at one hour.
+apply.
+From 1981 to the present,
+EU daylight saving rules have applied,
+and the UTC offset has remained at one hour.
.PP
In 1941 and 1942, daylight saving time applied from the first Monday
in May at 01:00 to the first Monday in October at 02:00.
-The pre-1981 EU daylight-saving rules have no effect
-here, but are included for completeness. Since 1981, daylight
-saving has begun on the last Sunday in March at 01:00 UTC.
+The pre-1981 EU daylight-saving rules have no effect here,
+but are included for completeness.
+Since 1981,
+daylight saving has begun on the last Sunday in March at 01:00 UTC.
Until 1995 it ended the last Sunday in September at 01:00 UTC,
but this changed to the last Sunday in October starting in 1996.
.PP
@@ -860,10 +868,10 @@ For purposes of display,
.q "LMT"
and
.q "BMT"
-were initially used, respectively. Since
-Swiss rules and later EU rules were applied, the time zone abbreviation
-has been CET for standard time and CEST for daylight saving
-time.
+were initially used, respectively.
+Since Swiss rules and later EU rules were applied,
+the time zone abbreviation has been CET for standard time
+and CEST for daylight saving time.
.SH FILES
.TP
.I /etc/localtime
