Package: icu-devtools
Version: 76.1-3
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>:18: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:21: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:24: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:73: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:76: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:79: 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.17-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 icu-devtools depends on:
ii libc6 2.41-4
ii libgcc-s1 14.2.0-17
ii libicu76 76.1-3
ii libstdc++6 14.2.0-17
icu-devtools recommends no packages.
icu-devtools suggests no packages.
-- no debconf information
Input file is makeconv.1
Output from "mandoc -T lint makeconv.1": (shortened list)
1 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-nroff -mandoc -t -ww -z makeconv.1": (shortened list)
6 Use macro '.B' for one argument or split argument.
6 .BR is for at least 2 arguments, got 1
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
1
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
18:.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
21:.BR "\-c\fP, \fB\-\-copyright"
24:.BR "\-v\fP, \fB\-\-verbose"
73:.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
76:.BR "\-c\fP, \fB\-\-copyright"
79:.BR "\-v\fP, \fB\-\-verbose"
-.-.
Wrong distance (not two spaces) 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.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
34:into a binary file. The binary file has the same base name as
55:are handled as follows. If a comment (starting with a `#' sign) that
60:the comment runs up to the end of the line. This special
65:installation in ICU's data directory. They do not need to
91:packaged initially. For example, if converters were grouped together in
100:Specifies the directory containing ICU data. Defaults to
102:Some tools in ICU depend on the presence of the trailing slash. It is thus
109:Copyright (C) 2000 IBM, Inc. and others.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
makeconv.1:49:must be in the ICU ucm (Unicode Codepage Mapping) format in order
to
makeconv.1:55:are handled as follows. If a comment (starting with a `#' sign)
that
-.-.
Only one space character after a possible end of sentence
(after a punctuation, that can end a sentence).
makeconv.1:34:into a binary file. The binary file has the same base name as
makeconv.1:55:are handled as follows. If a comment (starting with a `#' sign)
that
makeconv.1:60:the comment runs up to the end of the line. This special
makeconv.1:65:installation in ICU's data directory. They do not need to
makeconv.1:91:packaged initially. For example, if converters were grouped
together in
makeconv.1:100:Specifies the directory containing ICU data. Defaults to
makeconv.1:102:Some tools in ICU depend on the presence of the trailing slash.
It is thus
makeconv.1:109:Copyright (C) 2000 IBM, Inc. and others.
-.-.
Put a subordinate sentence (after a comma) on a new line.
makeconv.1:43:This binary file can then be read directly by ICU, or used by
makeconv.1:57:the text starting with the `#' sign, and ending before the `|'
sign,
makeconv.1:59:Otherwise, or if the comment is the first thing on the line,
makeconv.1:69:They do need to be listed there if one wants to give them
aliases, or
makeconv.1:70:tags, though.
makeconv.1:91:packaged initially. For example, if converters were grouped
together in
makeconv.1:109:Copyright (C) 2000 IBM, Inc. and others.
-.-.
Space character after a macro call.
111:.BR convrtrs.txt (5)
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:18: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:21: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:24: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:73: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:76: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:79: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- makeconv.1 2025-03-18 13:18:53.531999052 +0000
+++ makeconv.1.new 2025-03-18 13:41:04.131967473 +0000
@@ -15,23 +15,24 @@
.SH SYNOPSIS
.B makeconv
[
-.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
+.BR \-h ", " \-?\& ", " \-\-help
]
[
-.BR "\-c\fP, \fB\-\-copyright"
+.BR \-c ", " \-\-copyright
]
[
-.BR "\-v\fP, \fB\-\-verbose"
+.BR \-v ", " \-\-verbose
]
[
-.BI "\-d\fP, \fB\-\-destdir" " destination"
+.BR \-d ", " \-\-destdir " \fIdestination\fP"
]
.IR convertertable " .\|.\|."
.SH DESCRIPTION
.B makeconv
converts the ICU converter table
.I convertertable
-into a binary file. The binary file has the same base name as
+into a binary file.
+The binary file has the same base name as
.I convertertable
but has a
.B .cnv
@@ -40,46 +41,56 @@ extension (instead of the typical
extension of the
.I convertertable
file).
-This binary file can then be read directly by ICU, or used by
+This binary file can then be read directly by ICU,
+or used by
.BR pkgdata (1)
for incorporation into a larger archive or library.
.PP
The
.I convertertable
-must be in the ICU ucm (Unicode Codepage Mapping) format in order to
+must be in the ICU ucm
+(Unicode Codepage Mapping)
+format in order to
be understood by
.BR makeconv .
The ICU ucm format is similar to the IBM NLTC upmap/tpmap/rpmap files.
Comments in the
.I convertertable
-are handled as follows. If a comment (starting with a `#' sign) that
-is after some text does contain the fallback indicator `|' then only
-the text starting with the `#' sign, and ending before the `|' sign,
+are handled as follows.
+If a comment
+(starting with a `#' sign)
+that is after some text
+does contain the fallback indicator `|'
+then only the text starting with the `#' sign,
+and ending before the `|' sign,
is ignored.
-Otherwise, or if the comment is the first thing on the line,
-the comment runs up to the end of the line. This special
-handling of comments is to accommodate the practice of putting fallback
-information in comments in the strict IBM NLTC ucmap format.
+Otherwise,
+or if the comment is the first thing on the line,
+the comment runs up to the end of the line.
+This special handling of comments is to accommodate the practice of
+putting fallback information in comments in the strict IBM NLTC ucmap
+format.
.PP
Note that new converters will be automatically found by ICU after their
-installation in ICU's data directory. They do not need to
-be listed in the
+installation in ICU's data directory.
+They do not need to be listed in the
.BR convrtrs.txt (5)
converters aliases file in order to be available to applications using ICU.
-They do need to be listed there if one wants to give them aliases, or
-tags, though.
+They do need to be listed there
+if one wants to give them aliases,
+or tags, though.
.SH OPTIONS
.TP
-.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
+.BR \-h ", " \-?\& ", " \-\-help
Print help about usage and exit.
.TP
-.BR "\-c\fP, \fB\-\-copyright"
+.BR \-c ", " \-\-copyright
Include a copyright notice in the binary data.
.TP
-.BR "\-v\fP, \fB\-\-verbose"
+.BR \-v ", " \-\-verbose
Display extra informative messages during execution.
.TP
-.BI "\-d\fP, \fB\-\-destdir" " destination"
+.BR \-d ", " \-\-destdir " \fIdestination\fP"
Set the destination directory to
.IR destination .
The default destination directory is specified by the environment variable
@@ -88,8 +99,10 @@ The default destination directory is spe
If an existing converter table is changed and recompiled using
.BR makeconv ,
the resulting binary file must be packaged in the same way that it was
-packaged initially. For example, if converters were grouped together in
-an archive or a library with
+packaged initially.
+For example,
+if converters were grouped together in an archive
+or a library with
.BR pkgdata (1),
then the archive or library must be rebuilt with the new binary file.
A standalone binary converter file will not take precedence over a
@@ -97,18 +110,20 @@ packaged one.
.SH ENVIRONMENT
.TP 10
.B ICU_DATA
-Specifies the directory containing ICU data. Defaults to
+Specifies the directory containing ICU data.
+Defaults to
.BR ${prefix}/share/icu/76.1/ .
-Some tools in ICU depend on the presence of the trailing slash. It is thus
-important to make sure that it is present if
+Some tools in ICU depend on the presence of the trailing slash.
+It is thus important to make sure
+that it is present if
.B ICU_DATA
is set.
.SH VERSION
76.1
.SH COPYRIGHT
-Copyright (C) 2000 IBM, Inc. and others.
+Copyright (C) 2000 IBM, Inc.\& and others.
.SH SEE ALSO
-.BR convrtrs.txt (5)
+.BR convrtrs.txt (5)
.br
.BR pkgdata (1)
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.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size 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)
-.-
