Package: icu-devtools
Version: 72.1-6
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 ' $' <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: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:24: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:27: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:30: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:34: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:36: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:39: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:58: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:60: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:72: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:75: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:91: warning: trailing space in the line
an.tmac:<stdin>:118: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
troff:<stdin>:139: warning: trailing space in the line
an.tmac:<stdin>:145: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:148: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:153: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:156: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:159: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:169: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:172: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:175: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:177: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:188: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:228: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:232: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:244: warning: trailing space in the line
an.tmac:<stdin>:251: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:255: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:266: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:268: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:299: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:301: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:311: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:313: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:323: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:325: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:406: warning: trailing space in the line
an.tmac:<stdin>:426: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:433: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an-end-check:<stdin>: Warning: Different number of .RS and .RE calls,
an-RS-open=1 at end of file
* 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.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)
Versions of packages icu-devtools depends on:
ii libc6 2.40-5
ii libgcc-s1 14.2.0-12
ii libicu72 72.1-6
ii libstdc++6 14.2.0-12
icu-devtools recommends no packages.
icu-devtools suggests no packages.
-- no debconf information
Input file is uconv.1
Output from "mandoc -T lint uconv.1": (shortened list)
1 skipping paragraph macro: PP empty
1 unterminated quoted argument
4 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z uconv.1": (shortened list)
35 Use macro '.B' for one argument or split argument.
2 Use macro '.I' for one argument or split argument.
22 .BI is for at least 2 arguments, got 1
13 .BR is for at least 2 arguments, got 1
2 .IR is for at least 2 arguments, got 1
4 trailing space in the line
-.-.
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
3
-.-.
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.
uconv.1:443:Copyright (C) 2000-2005 IBM, Inc. and others.
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) 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 "-"
(begin of an option or end of options)
then use "\-\-".
uconv.1:175:.BI "\--canon"
-.-.
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:.BI "\-V\fP, \fB\-\-version"
24:.BI "\-s\fP, \fB\-\-silent"
27:.BI "\-v\fP, \fB\-\-verbose"
30:.BI "\-l\fP, \fB\-\-list"
34:.BI "\-\-default-code"
36:.BI "\-L\fP, \fB\-\-list\-transliterators"
39:.BI "\-\-canon"
58:.BI "\-\-fallback"
60:.BI "\-\-no\-fallback"
72:.BI "\-\-add\-signature"
75:.BI "\-\-remove\-signature"
118:.IR transliteration
145:.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
148:.BR "\-V\fP, \fB\-\-version"
153:.BI "\-s\fP, \fB\-\-silent"
156:.BI "\-v\fP, \fB\-\-verbose"
159:.BI "\-l\fP, \fB\-\-list"
169:.BI "\-\-default-code"
172:.BI "\-L\fP, \fB\-\-list\-transliterators"
175:.BI "\--canon"
177:.BI "\-l\fP, \fB\-\-list"
188:.IR transliteration
228:.BI "\-\-fallback"
232:.BI "\-\-no\-fallback"
251:.BI "\-\-add\-signature"
255:.BI "\-\-remove\-signature"
266:.BR "\-\-from\-callback"
268:.BR "\-\-to\-callback"
299:.BR %U\fIhhhh\fP
301:.BR %U\fIhhhh\fP%U\fIhhhh\fP
311:.BR \eu\fIhhhh\fP
313:.BR \eu\fIhhhh\fP\eu\fIhhhh\fP
323:.BR \eu\fIhhhh\fP
325:.BR \eU\fIhhhhhhhh\fP
426:.BR uconv
433:.BR uconv
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
99:.BR - ,
-.-.
Add a 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.
93:(i.e. the data are first transcoded from their original encoding to
-.-.
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 "\&".
N.B.
The number of lines affected can be too large to be in a patch.
93:(i.e. the data are first transcoded from their original encoding to
100:the default encoding is used. Thus, calling
111:the destination encoding. Some encodings, for example, offer a default
113:such characters in the input. Other callbacks offer a useful visual
132:making it easy to replace it in scripts. It is not necessarily the case,
165:encoding and exit. If
197:encoding. See section
210:encoding. See section
224:encoding. See section
240:bytes at a time. The default block size is
263:supports specifying callbacks to handle invalid data. Callbacks can be
273:names, along with a description of their behavior. The list of
306:character. Characters from planes 1 and above are written as a pair of
318:character. Characters from planes 1 and above are written as a pair of
422:encountered. This may be confusing to users of GNU
425:sequence. For multi-byte character sets or encodings, this means that
443:Copyright (C) 2000-2005 IBM, Inc. and others.
-.-.
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: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:24: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:27: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:30: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:34: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:36: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:39: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:58: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:60: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:72: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:75: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:91: warning: trailing space in the line
an.tmac:<stdin>:118: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
troff:<stdin>:139: warning: trailing space in the line
an.tmac:<stdin>:145: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:148: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:153: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:156: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:159: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:169: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:172: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:175: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:177: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:188: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:228: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:232: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:244: warning: trailing space in the line
an.tmac:<stdin>:251: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:255: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:266: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:268: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:299: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:301: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:311: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:313: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:323: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:325: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:406: warning: trailing space in the line
an.tmac:<stdin>:426: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:433: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an-end-check:<stdin>: Warning: Different number of .RS and .RE calls,
an-RS-open=1 at end of file
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
--- uconv.1 2025-01-23 21:16:08.535220447 +0000
+++ uconv.1.new 2025-01-24 14:19:25.306282723 +0000
@@ -15,67 +15,67 @@
.SH SYNOPSIS
.B uconv
[
-.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
+.BR \-h ", " \-? ", " \-\-help
]
[
-.BI "\-V\fP, \fB\-\-version"
+.BR \-V ", " \-\-version
]
[
-.BI "\-s\fP, \fB\-\-silent"
+.BR \-s ", " \-\-silent
]
[
-.BI "\-v\fP, \fB\-\-verbose"
+.BR \-v ", " \-\-verbose
]
[
-.BI "\-l\fP, \fB\-\-list"
+.BR \-l ", " \-\-list
|
-.BI "\-l\fP, \fB\-\-list\-code" " code"
+.BR \-l ", " \-\-list\-code " \fIcode\fR"
|
-.BI "\-\-default-code"
+.B \-\-default-code
|
-.BI "\-L\fP, \fB\-\-list\-transliterators"
+.BR \-L ", " \-\-list\-transliterators
]
[
-.BI "\-\-canon"
+.B \-\-canon
]
[
-.BI "\-x" " transliteration
+.BI "\-x " transliteration
]
[
-.BI "\-\-to\-callback" " callback"
+.BI \-\-to\-callback " callback"
|
-.B "\-c"
+.B \-c
]
[
-.BI "\-\-from\-callback" " callback"
+.BI \-\-from\-callback " callback"
|
-.B "\-i"
+.B \-i
]
[
-.BI "\-\-callback" " callback"
+.BI \-\-callback " callback"
]
[
-.BI "\-\-fallback"
+.B \-\-fallback
|
-.BI "\-\-no\-fallback"
+.B \-\-no\-fallback
]
[
-.BI "\-b\fP, \fB\-\-block\-size" " size"
+.BR \-b ", " \-\-block\-size " \fIsize\fR"
]
[
-.BI "\-f\fP, \fB\-\-from\-code" " encoding"
+.BR \-f ", " \-\-from\-code " \fIencoding\fR"
]
[
-.BI "\-t\fP, \fB\-\-to\-code" " encoding"
+.BR \-t ", " \-\-to\-code " \fIencoding\fR"
]
[
-.BI "\-\-add\-signature"
+.B \-\-add\-signature
]
[
-.BI "\-\-remove\-signature"
+.B \-\-remove\-signature
]
[
-.BI "\-o\fP, \fB\-\-output" " file"
+.BR \-o ", " \-\-output " \fIfile\fR"
]
[
.IR file .\|.\|.
@@ -88,16 +88,17 @@ converts, or transcodes, each given
.I file
is specified) from one
.I encoding
-to another.
+to another.
The transcoding is done using Unicode as a pivot encoding
-(i.e. the data are first transcoded from their original encoding to
+(i.e., the data are first transcoded from their original encoding to
Unicode, and then from Unicode to the destination encoding).
.PP
If an
.I encoding
is not specified or is
-.BR - ,
-the default encoding is used. Thus, calling
+.BR \- ,
+the default encoding is used.
+Thus, calling
.B uconv
with no
.I encoding
@@ -108,14 +109,16 @@ When calling
.BR uconv ,
it is possible to specify callbacks that are used to handle invalid
characters in the input, or characters that cannot be transcoded to
-the destination encoding. Some encodings, for example, offer a default
+the destination encoding.
+Some encodings, for example, offer a default
substitution character that can be used to represent the occurrence of
-such characters in the input. Other callbacks offer a useful visual
+such characters in the input.
+Other callbacks offer a useful visual
representation of the invalid data.
.PP
.B uconv
can also run the specified
-.IR transliteration
+.I transliteration
on the transcoded data,
in which case transliteration will happen as an intermediate step,
after the data have been transcoded to Unicode.
@@ -129,153 +132,160 @@ For transcoding purposes,
.B uconv
options are compatible with those of
.BR iconv (1),
-making it easy to replace it in scripts. It is not necessarily the case,
+making it easy to replace it in scripts.
+It is not necessarily the case,
however, that the encoding names used by
.B uconv
and ICU are the same as the ones used by
.BR iconv (1).
Also, options that provide informational data, such as the
.B \-l\fP, \fB\-\-list
-one offered by some
+one offered by some
.BR iconv (1)
variants such as GNU's, produce data in a slightly different and
easier to parse format.
.SH OPTIONS
.TP
-.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
+.BR \-h ", " \-? ", " \-\-help
Print help about usage and exit.
.TP
-.BR "\-V\fP, \fB\-\-version"
+.BR \-V ", " \-\-version
Print the version of
.B uconv
and exit.
.TP
-.BI "\-s\fP, \fB\-\-silent"
+.BR \-s ", " \-\-silent
Suppress messages during execution.
.TP
-.BI "\-v\fP, \fB\-\-verbose"
+.BR \-v ", " \-\-verbose
Display extra informative messages during execution.
.TP
-.BI "\-l\fP, \fB\-\-list"
+.BR \-l ", " \-\-list
List all the available encodings and exit.
.TP
-.BI "\-l\fP, \fB\-\-list\-code" " code"
+.BR \-l ", " \-\-list\-code " \fIcode\fR"
List only the
.I code
-encoding and exit. If
+encoding and exit.
+If
.I code
is not a proper encoding, exit with an error.
.TP
-.BI "\-\-default-code"
+.B \-\-default-code
List only the name of the default encoding and exit.
.TP
-.BI "\-L\fP, \fB\-\-list\-transliterators"
+.BR \-L ", " \-\-list\-transliterators
List all the available transliterators and exit.
.TP
-.BI "\--canon"
+.B \-\-canon
If used with
-.BI "\-l\fP, \fB\-\-list"
+.BR \-l ,\ \-\-list
or
-.BR "\-\-default-code" ,
+.BR \-\-default-code ,
the list of encodings is produced in a format compatible with
.BR convrtrs.txt (5).
If used with
-.BR "\-L\fP, \fB\-\-list\-transliterators" ,
+.BR \-L ", " \-\-list\-transliterators ,
print only one transliterator name per line.
.TP
-.BI "\-x" " transliteration"
+.BI \-x " transliteration"
Run the given
-.IR transliteration
+.I transliteration
on the transcoded Unicode data,
and use the transliterated data as input for the transcoding to
the destination encoding.
.TP
-.BI "\-\-to\-callback" " callback"
+.BI \-\-to\-callback " callback"
Use
.I callback
to handle characters that cannot be transcoded to the destination
-encoding. See section
+encoding.
+See section
.B CALLBACKS
for details on valid callbacks.
.TP
-.B "\-c"
+.B \-c
Omit invalid characters from the output.
Same as
.BR "\-\-to\-callback skip" .
.TP
-.BI "\-\-from\-callback" " callback"
+.BI \-\-from\-callback " callback"
Use
.I callback
to handle characters that cannot be transcoded from the original
-encoding. See section
+encoding.
+See section
.B CALLBACKS
for details on valid callbacks.
.TP
-.B "\-i"
+.B \-i
Ignore invalid sequences in the input.
Same as
.BR "\-\-from\-callback skip" .
.TP
-.BI "\-\-callback" " callback"
+.BI \-\-callback " callback"
Use
.I callback
to handle both characters that cannot be transcoded from the original
encoding and characters that cannot be transcoded to the destination
-encoding. See section
+encoding.
+See section
.B CALLBACKS
for details on valid callbacks.
.TP
-.BI "\-\-fallback"
+.B \-\-fallback
Use the fallback mapping when transcoding from
Unicode to the destination encoding.
.TP
-.BI "\-\-no\-fallback"
+.B \-\-no\-fallback
Do not use the fallback mapping when transcoding from Unicode to the
destination encoding.
This is the default.
.TP
-.BI "\-b\fP, \fB\-\-block\-size" " size"
+.BR \-b ", " \-\-block\-size " \fIsize\fR"
Read input in blocks of
.I size
-bytes at a time. The default block size is
+bytes at a time.
+The default block size is
4096.
.TP
-.BI "\-f\fP, \fB\-\-from\-code" " encoding"
-Set the original encoding of the data to
+.BR \-f ", " \-\-from\-code " \fIencoding\fR"
+Set the original encoding of the data to
.IR encoding .
.TP
-.BI "\-t\fP, \fB\-\-to\-code" " encoding"
+.BR \-t ", " \-\-to\-code " \fIencoding\fR"
Transcode the data to
.IR encoding .
.TP
-.BI "\-\-add\-signature"
+.B \-\-add\-signature
Add a U+FEFF Unicode signature character (BOM) if the output charset
supports it and does not add one anyway.
.TP
-.BI "\-\-remove\-signature"
+.B \-\-remove\-signature
Remove a U+FEFF Unicode signature character (BOM).
.TP
-.BI "\-o\fP, \fB\-\-output" " file"
+.BR \-o ", " \-\-output " \fIfile\fR"
Write the transcoded data to
.IR file .
.SH CALLBACKS
.B uconv
-supports specifying callbacks to handle invalid data. Callbacks can be
+supports specifying callbacks to handle invalid data.
+Callbacks can be
set for both directions of transcoding: from the original encoding to
Unicode, with the
-.BR "\-\-from\-callback"
+.B \-\-from\-callback
option, and from Unicode to the destination encoding, with the
-.BR "\-\-to\-callback"
+.B \-\-to\-callback
option.
.PP
The following is a list of valid
.I callback
-names, along with a description of their behavior. The list of
+names, along with a description of their behavior.
+The list of
callbacks actually supported by
.B uconv
is displayed when it is called with
-.BR "\-h\fP, \fB\-\-help" .
-.PP
+.BR \-h ", " \-\-help .
.TP \w'\fBescape-unicode'u+3n
.B substitute
Write the encoding's substitute sequence, or the Unicode
@@ -296,33 +306,35 @@ Same as
.TP
.B escape-icu
Replace the missing characters with a string of the format
-.BR %U\fIhhhh\fP
+.BI %U hhhh
for plane 0 characters, and
-.BR %U\fIhhhh\fP%U\fIhhhh\fP
+.BI %U hhhh %U hhhh
for planes 1 and above characters,
where
.I hhhh
is the hexadecimal value of one of the UTF-16 code units representing the
-character. Characters from planes 1 and above are written as a pair of
+character.
+Characters from planes 1 and above are written as a pair of
UTF-16 surrogate code units.
.TP
.B escape-java
Replace the missing characters with a string of the format
-.BR \eu\fIhhhh\fP
+.BI \eu hhhh
for plane 0 characters, and
-.BR \eu\fIhhhh\fP\eu\fIhhhh\fP
+.BI \eu hhhh \eu hhhh
for planes 1 and above characters,
where
.I hhhh
is the hexadecimal value of one of the UTF-16 code units representing the
-character. Characters from planes 1 and above are written as a pair of
+character.
+Characters from planes 1 and above are written as a pair of
UTF-16 surrogate code units.
.TP
.B escape-c
Replace the missing characters with a string of the format
-.BR \eu\fIhhhh\fP
+.BI \eu hhhh
for plane 0 characters, and
-.BR \eU\fIhhhhhhhh\fP
+.BI \eU hhhhhhhh
for planes 1 and above characters,
where
.I hhhh
@@ -336,21 +348,21 @@ Same as
.TP
.B escape-xml-hex
Replace the missing characters with a string of the format
-.BR &#x\fIhhhh\fP; ,
+.BR &#x \fIhhhh\fP ; ,
where
.I hhhh
is the hexadecimal value of the Unicode codepoint.
.TP
.B escape-xml-dec
Replace the missing characters with a string of the format
-.BR &#\fInnnn\fP; ,
+.BR &# \fInnnn\fP ; ,
where
.I nnnn
is the decimal value of the Unicode codepoint.
.TP
.B escape-unicode
Replace the missing characters with a string of the format
-.BR {U+\fIhhhh\fP} ,
+.BR {U+ \fIhhhh\fP } ,
where
.I hhhh
is the hexadecimal value of the Unicode codepoint.
@@ -365,7 +377,9 @@ Convert data from a given
to the platform encoding:
.RS 4
-.B \fR$ \fPuconv \-f \fIencoding\fP
+.\".B \fR$ \fPuconv \-f \fIencoding\fP
+$
+.BI "uconv \-f " encoding
.RE
.PP
Check if a
@@ -374,7 +388,8 @@ contains valid data for a given
.IR encoding :
.RS 4
-.B \fR$ \fPuconv \-f \fIencoding\fP \-c \fIfile\fP >/dev/null
+$
+.BI "uconv \-f " encoding " \-c " file " >/dev/null"
.RE
.PP
Convert a UTF-8
@@ -384,26 +399,31 @@ to a given
and ensure that the resulting text is good for any version of HTML:
.RS 4
-.B \fR$ \fPuconv \-f utf-8 \-t \fIencoding\fP \e
+.\".B \fR$ \fPuconv \-f utf-8 \-t \fIencoding\fP \e
+$
+.BI "uconv \-f utf-8 \-t " encoding " \e"
.br
-.B " \-\-callback escape-xml-dec \fIfile\fP"
+.BI " \-\-callback escape-xml-dec " file
+
.RE
-.PP
Display the names of the Unicode code points in a UTF-file:
.RS 4
-.B \fR$ \fPuconv \-f utf-8 \-x any-name \fIfile\fP
+$
+.BI "uconv \-f utf-8 \-x any-name " file
+.\".B \fR$ \fPuconv \-f utf-8 \-x any-name \fIfile\fP
.RE
.PP
Print the name of a Unicode code point whose value is known (\fBU+30AB\fP
in this example):
.RS 4
-.B \fR$ \fPecho '\eu30ab' | uconv \-x 'hex-any; any-name'; echo
+$
+.B echo '\eu30ab' | uconv \-x 'hex-any; any-name'; echo
.br
{KATAKANA LETTER KA}{LINE FEED}
.br
-$
+$
.RE
(The names are delimited by curly braces.
@@ -413,24 +433,27 @@ Normalize UTF-8 data using Unicode NFKC,
and map Katakana to Hiragana:
.RS 4
-.B \fR$ \fPuconv \-f utf-8 \-t utf-8 \e
+.RB $ " uconv \-f utf-8 \-t utf-8 \e"
.br
.B " \-x '::nfkc; [:Cc:] >; ::katakana-hiragana;'"
+.RE
.SH CAVEATS AND BUGS
.B uconv
does report errors as occurring at the first invalid byte
-encountered. This may be confusing to users of GNU
+encountered.
+This may be confusing to users of GNU
.BR iconv (1),
which reports errors as occurring at the first byte of an invalid
-sequence. For multi-byte character sets or encodings, this means that
-.BR uconv
+sequence.
+For multi-byte character sets or encodings, this means that
+.B uconv
error positions may be at a later offset in the input stream than
would be the case with GNU
.BR iconv (1).
.PP
The reporting of error positions when a transliterator is used may be
inaccurate or unavailable, in which case
-.BR uconv
+.B uconv
will report the offset in the output stream at which the error
occurred.
.SH AUTHORS
@@ -440,6 +463,6 @@ Yves Arrouye
.SH VERSION
72.1
.SH COPYRIGHT
-Copyright (C) 2000-2005 IBM, Inc. and others.
+Copyright (C) 2000\(en2005 IBM, Inc.\& and others.
.SH SEE ALSO
.BR iconv (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.
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 -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 -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)
-.-
