Package: isoquery
Version: 3.3.4-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?
<stdin>:193: warning: table wider than line length minus indentation
an.tmac:<stdin>:197: warning: .l = 1920u = 80n = 80m, .i = 216u, TW (table
width) = 1752u = 73n = 73m
* 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 isoquery depends on:
ii libc6 2.41-4
ii libglib2.0-0t64 2.84.0-1
ii libjson-glib-1.0-0 1.10.6+ds-1
Versions of packages isoquery recommends:
ii iso-codes 4.17.0-1
isoquery suggests no packages.
-- no debconf information
Input file is isoquery.1
Output from "mandoc -T lint isoquery.1": (shortened list)
1 skipping insecure request: mso
1 skipping unknown macro: LINKSTYLE blue R < >
-.-.
Output from "test-nroff -mandoc -t -ww -z isoquery.1": (shortened list)
1 .l = 1920u = 80n = 80m, .i = 216u, TW (table width) = 1752u = 73n = 73m
1 table wider than line length minus indentation
-.-.
Show if asciidoctor generated this.
Who is actually generating this man page? Debian or upstream?
Is the generating software out of date?
4:.\" Generator: Asciidoctor 2.0.20
Latest version is Asciidoctor 2.0.23
-.-.
Add a "\&" (or a comma (Oxford comma)) after "e.g." and "i.e.",
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.
167:The columns are ISO 3166\-2 code, subset type (e.g. State, Province,
-.-.
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"
49:The ISO standard to use. Possible values: 639\-2, 639\-3, 639\-5, 3166\-1,
71:Official name for the supplied codes. This may be the same
77:Common name for the supplied codes. This may be the same
150:letters, you can use the \fB\-\-flag\fP command line option. Those
167:The columns are ISO 3166\-2 code, subset type (e.g. State, Province,
184:withdrawal date, and name. The columns for numeric code, comment, and
203:bibliographic code, and the alpha\-2 code. The second and third columns
221:You can trim down the results by specifying only some codes. Moreover,
236:alpha\-2, bibliographic, and the language name. Both alpha\-2 and
bibliographic
251:ISO 639\-5 is also available. The displayed columns are alpha\-3 and name.
264:standard by using the following command. The first of the columns is
266:to the currency. The name of the currency is shown in the third column.
280:the numerical code assigned to the script. The name of the script
-.-.
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.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 195, length 81
YUG YUCS 891 1993\-07\-28 Yugoslavia, Socialist Federal Republic
of
Longest line is: 81 characters.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
isoquery.1:31:isoquery \- search and display various ISO codes (country,
language, â¦)
isoquery.1:50:3166\-2, 3166\-3, 4217, 15924 (default: 3166\-1)
isoquery.1:72:as \fB\-\-name\fP (only applies to ISO 3166\-1)
isoquery.1:78:as \fB\-\-name\fP (only applies to ISO 639\-2, 639\-3, and
3166\-1)
isoquery.1:287:Jpan 413 Japanese (alias for Han + Hiragana + Katakana)
-.-.
Only one space character after a possible end of sentence
(after a punctuation, that can end a sentence).
isoquery.1:49:The ISO standard to use. Possible values: 639\-2, 639\-3, 639\-5,
3166\-1,
isoquery.1:71:Official name for the supplied codes. This may be the same
isoquery.1:77:Common name for the supplied codes. This may be the same
isoquery.1:150:letters, you can use the \fB\-\-flag\fP command line option.
Those
isoquery.1:167:The columns are ISO 3166\-2 code, subset type (e.g. State,
Province,
isoquery.1:184:withdrawal date, and name. The columns for numeric code,
comment, and
isoquery.1:203:bibliographic code, and the alpha\-2 code. The second and third
columns
isoquery.1:221:You can trim down the results by specifying only some codes.
Moreover,
isoquery.1:236:alpha\-2, bibliographic, and the language name. Both alpha\-2
and bibliographic
isoquery.1:251:ISO 639\-5 is also available. The displayed columns are alpha\-3
and name.
isoquery.1:264:standard by using the following command. The first of the
columns is
isoquery.1:266:to the currency. The name of the currency is shown in the third
column.
isoquery.1:280:the numerical code assigned to the script. The name of the script
-.-.
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
isoquery.1:31:isoquery \- search and display various ISO codes (country,
language, â¦)
isoquery.1:39:matching entries, if specified on the command line.
isoquery.1:40:Moreover, it\(cqs possible to get all available translations for
isoquery.1:43:This program follows the usual GNU command line syntax, with long
options
isoquery.1:49:The ISO standard to use. Possible values: 639\-2, 639\-3, 639\-5,
3166\-1,
isoquery.1:50:3166\-2, 3166\-3, 4217, 15924 (default: 3166\-1)
isoquery.1:102:If called without any command line options, \fBisoquery\fP will
print a
isoquery.1:105:the alpha\-3 code, and the numerical code assigned to the
country listed
isoquery.1:119:If you need only some countries, you can specify any of the
codes in
isoquery.1:133:Should you need the translations of the countries\*(Aq names,
just specify
isoquery.1:150:letters, you can use the \fB\-\-flag\fP command line option.
Those
isoquery.1:164:All of the above works for different ISO standards as well, so
you can
isoquery.1:167:The columns are ISO 3166\-2 code, subset type (e.g. State,
Province,
isoquery.1:168:etc.\&), parent, and name.
isoquery.1:183:The columns are alpha\-3 code, alpha\-4 code, numeric code,
comment,
isoquery.1:184:withdrawal date, and name. The columns for numeric code,
comment, and
isoquery.1:202:For ISO 639\-2, the first three columns are the alpha\-3 code,
the
isoquery.1:203:bibliographic code, and the alpha\-2 code. The second and third
columns
isoquery.1:235:If you want to use ISO 639\-3, the displayed columns are
alpha\-3, scope, type,
isoquery.1:236:alpha\-2, bibliographic, and the language name. Both alpha\-2
and bibliographic
isoquery.1:265:the alpha\-3 code, and the second one is the numerical code
assigned
isoquery.1:278:If you need to get script names, you can use the ISO 15924 table.
isoquery.1:279:The first of the columns is the alpha\-4 code, and the second
one is
-.-.
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.
isoquery.1:10:.TH "ISOQUERY" "1" "2024-04-27" "3.3.4" "\ \&"
isoquery.1:30:.SH "NAME"
isoquery.1:32:.SH "SYNOPSIS"
isoquery.1:34:.SH "DESCRIPTION"
isoquery.1:42:.SH "OPTIONS"
isoquery.1:101:.SH "EXAMPLES"
isoquery.1:293:.SH "FILES"
isoquery.1:384:.SH "AUTHOR"
isoquery.1:386:.MTO "toddy\(atdebian.org" "" ""
-.-.
Use ".na" (no adjustment) instead of ".ad l" (and ".ad" to begin the
same adjustment again as before).
15:.ad l
23:. ad l
26:. ad l
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
30:.SH "NAME"
32:.SH "SYNOPSIS"
34:.SH "DESCRIPTION"
42:.SH "OPTIONS"
101:.SH "EXAMPLES"
293:.SH "FILES"
384:.SH "AUTHOR"
-.-.
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.
temp.table:1:.TH "ISOQUERY" "1" "2024-04-27" "3.3.4" "\ \&"
-.-.
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
<stdin>:193: warning: table wider than line length minus indentation
an.tmac:<stdin>:197: warning: .l = 1920u = 80n = 80m, .i = 216u, TW (table
width) = 1752u = 73n = 73m
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
-.-
Tables:
Put data, that are wider than the header in a centered last column,
in a "T{\n...\nT}" block.
Table headers, that are wider than any data in the corresponding column,
do not need to be centered, so left adjustment (l, L) is sufficient.
--- isoquery.1 2025-03-16 23:37:32.408486465 +0000
+++ isoquery.1.new 2025-03-17 00:43:28.415442212 +0000
@@ -109,9 +109,12 @@ in the fourth column.
.nf
.fam C
$ isoquery
-AW ABW 533 Aruba
-[â¦]
-ZW ZWE 716 Zimbabwe
+.TS
+l l l l .
+AW ABW 533 Aruba
+[â¦] \& \& \&
+ZW ZWE 716 Zimbabwe
+.TE
.fam
.fi
.if n .RE
@@ -123,9 +126,12 @@ the first three columns to cut down the
.nf
.fam C
$ isoquery so nor 484
-SO SOM 706 Somalia
-NO NOR 578 Norway
-MX MEX 484 Mexico
+.TS
+l l l l .
+SO SOM 706 Somalia
+NO NOR 578 Norway
+MX MEX 484 Mexico
+.TE
.fam
.fi
.if n .RE
@@ -139,9 +145,12 @@ translation available for the specified
.nf
.fam C
$ isoquery \-\-locale=nl fr de es
-FR FRA 250 Frankrijk
-DE DEU 276 Duitsland
-ES ESP 724 Spanje
+.TS
+l l l l .
+FR FRA 250 Frankrijk
+DE DEU 276 Duitsland
+ES ESP 724 Spanje
+.TE
.fam
.fi
.if n .RE
@@ -154,9 +163,12 @@ letters can be displayed as a country fl
.nf
.fam C
$ isoquery \-\-flag \-\-locale=nl fr de es
-FR FRA 250 ð«ð· Frankrijk
-DE DEU 276 ð©ðª Duitsland
-ES ESP 724 ðªð¸ Spanje
+.TS
+l l l l l .
+FR FRA 250 ð«ð· Frankrijk
+DE DEU 276 ð©ðª Duitsland
+ES ESP 724 ðªð¸ Spanje
+.TE
.fam
.fi
.if n .RE
@@ -164,7 +176,7 @@ ES ESP 724 ðªð¸ Sp
All of the above works for different ISO standards as well, so you can
switch to the more extensive standard ISO 3166\-2 by using the \fB\-\-iso\fP
command line option.
-The columns are ISO 3166\-2 code, subset type (e.g. State, Province,
+The columns are ISO 3166\-2 code, subset type (e.g.\& State, Province,
etc.\&), parent, and name.
The third column (parent) may be empty.
.sp
@@ -172,9 +184,12 @@ The third column (parent) may be empty.
.nf
.fam C
$ isoquery \-\-iso=3166\-2
-AD\-02 Parish Canillo
-[â¦]
-ZW\-MW Province Mashonaland West
+.TS
+l l l .
+AD\-02 Parish Canillo
+[â¦] \& \&
+ZW\-MW Province Mashonaland West
+.TE
.fam
.fi
.if n .RE
@@ -185,18 +200,18 @@ withdrawal date, and name. The columns f
withdrawal date may be empty.
.sp
.if n .RS 4
-.nf
.fam C
$ isoquery \-\-iso=3166\-3
.TS
l l l l l.
AFI AIDJ 262 1977 French Afars and Issas
ANT ANHH 532 1993\-07\-12 Netherlands Antilles [â¦]
-YUG YUCS 891 1993\-07\-28 Yugoslavia, Socialist Federal Republic
of
+YUG YUCS 891 1993\-07\-28 T{
+Yugoslavia, Socialist Federal Republic of
+T}
ZAR ZRCD 180 1997\-07\-14 Zaire, Republic of
.TE
.fam
-.fi
.if n .RE
.sp
For ISO 639\-2, the first three columns are the alpha\-3 code, the
@@ -207,13 +222,16 @@ may be empty.
.nf
.fam C
$ isoquery \-\-iso=639\-2
-aar aa Afar
-abk ab Abkhazian
-ace Achinese
-[â¦]
-zun Zuni
-zxx No linguistic content; Not applicable
-zza Zaza; Dimili; Dimli; Kirdki; Kirmanjki; Zazaki
+.TS
+l l l l l .
+aar \& \& aa Afar
+abk \& \& ab Abkhazian
+ace \& \& \& Achinese
+[â¦] \& \& \& \&
+zun \& \& \& Zuni
+zxx \& \& \& No linguistic content; Not applicable
+zza \& \& \& Zaza; Dimili; Dimli; Kirdki; Kirmanjki; Zazaki
+.TE
.fam
.fi
.if n .RE
@@ -225,9 +243,12 @@ the option to get translated names is al
.nf
.fam C
$ isoquery \-\-iso=639\-2 \-\-locale=pt vi bo kl
-vie vi Vietnamita
-bod tib bo tibetano
-kal kl Kalaallisut; Greenlandic
+.TS
+l l l l .
+vie \& vi Vietnamita
+bod tib bo tibetano
+kal \& kl Kalaallisut; Greenlandic
+.TE
.fam
.fi
.if n .RE
@@ -240,10 +261,13 @@ may be empty.
.nf
.fam C
$ isoquery \-i 639\-3 aal new spa guc
-aal I L Afade
-new I L Newari
-spa I L es Spanish
-guc I L Wayuu
+.TS
+l l l l l .
+aal I L \& Afade
+new I L \& Newari
+spa I L es Spanish
+guc I L \& Wayuu
+.TE
.fam
.fi
.if n .RE
@@ -254,8 +278,11 @@ ISO 639\-5 is also available. The displa
.nf
.fam C
$ isoquery \-i 639\-5 aus tut
-aus Australian languages
-tut Altaic languages
+.TS
+l l .
+aus Australian languages
+tut Altaic languages
+.TE
.fam
.fi
.if n .RE
@@ -269,8 +296,11 @@ to the currency. The name of the currenc
.nf
.fam C
$ isoquery \-\-iso=4217 \-\-locale=da cad 392
-CAD 124 Canadisk dollar
-JPY 392 Yen
+.TS
+l l l .
+CAD 124 Canadisk dollar
+JPY 392 Yen
+.TE
.fam
.fi
.if n .RE
@@ -284,9 +314,12 @@ is shown in the third column.
.nf
.fam C
$ isoquery \-\-iso=15924 jpan latn 280
-Jpan 413 Japanese (alias for Han + Hiragana + Katakana)
-Latn 215 Latin
-Visp 280 Visible Speech
+.TS
+l l l .
+Jpan 413 Japanese (alias for Han + Hiragana + Katakana)
+Latn 215 Latin
+Visp 280 Visible Speech
+.TE
.fam
.fi
.if n .RE
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)
-.-
