Package: console-setup
Version: 1.233
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 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>:63: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:101: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:105: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:112: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:130: 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: .IR is for at least 2 arguments, got 1
Use macro '.I' 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.6-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 console-setup depends on:
ii console-setup-linux 1.233
ii debconf [debconf-2.0] 1.5.89
ii keyboard-configuration 1.233
ii xkb-data 2.42-1
console-setup recommends no packages.
Versions of packages console-setup suggests:
ii locales 2.40-4
ii lsb-base 11.6
ii sysvinit-utils [lsb-base] 3.11-1
Versions of packages keyboard-configuration depends on:
ii debconf [debconf-2.0] 1.5.89
ii liblocale-gettext-perl 1.07-7+b1
ii xkb-data 2.42-1
Versions of packages console-setup-linux depends on:
ii init-system-helpers 1.68
ii initscripts 3.11-1
ii kbd 2.7.1-2
ii keyboard-configuration 1.233
console-setup-linux suggests no packages.
Versions of packages console-setup is related to:
pn console-common <none>
pn console-data <none>
pn console-tools <none>
pn gnome-control-center <none>
ii kbd 2.7.1-2
ii systemd 257.1-5
-- debconf information excluded
Input file is setupcon.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
-.-
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 setupcon.1": (shortened list)
-.-.
Output from "test-groff -mandoc -t -ww -z setupcon.1": (shortened list)
4 Use macro '.B' for one argument or split argument.
2 Use macro '.I' for one argument or split argument.
4 .BR is for at least 2 arguments, got 1
2 .IR is for at least 2 arguments, got 1
-.-.
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 "\-\-".
setupcon.1:80:.BR -v ,\ --verbose
setupcon.1:85:.BR -k ,\ --keyboard-only
setupcon.1:90:.BR -f ,\ --font-only
setupcon.1:97:.BR -t ,\ --terminal-only
setupcon.1:101:.BR --current-tty
setupcon.1:105:.BR --force
setupcon.1:112:.BR --save
setupcon.1:130:.BR --save-only
setupcon.1:132:.IR --save ,
setupcon.1:137:.BI --save-keyboard\ FILE
setupcon.1:143:.BI --setup-dir\ DIR
setupcon.1:157:.BR -h ,\ --help
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
80:.BR -v ,\ --verbose
85:.BR -k ,\ --keyboard-only
90:.BR -f ,\ --font-only
97:.BR -t ,\ --terminal-only
101:.BR --current-tty
105:.BR --force
112:.BR --save
130:.BR --save-only
132:.IR --save ,
137:.BI --save-keyboard\ FILE
143:.BI --setup-dir\ DIR
157:.BR -h ,\ --help
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
63:.IR VARIANT
101:.BR --current-tty
105:.BR --force
112:.BR --save
130:.BR --save-only
148:.IR DIR/morefiles
-.-.
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.
80:.BR -v ,\ --verbose
85:.BR -k ,\ --keyboard-only
90:.BR -f ,\ --font-only
97:.BR -t ,\ --terminal-only
101:.BR --current-tty
105:.BR --force
112:.BR --save
130:.BR --save-only
132:.IR --save ,
137:.BI --save-keyboard\ FILE
143:.BI --setup-dir\ DIR
157:.BR -h ,\ --help
-.-.
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.
69:On the other hand, if you use e.g.
-.-.
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 "\&".
81:Be more verbose. Use this option if something goes wrong or while
-.-.
Do not use more than two space characters between sentences or (better)
only a new line character.
81:Be more verbose. Use this option if something goes wrong or while
-.-.
Put a subordinate sentence (after a comma) on a new line.
36:If you have to switch often between different encodings, keyboards or
37:languages, you can prepare several alternative configuration files for
40:keyboard layout, but sometimes you need to type in German with German
46:for Greek. Also, create alternative configuration files for German
69:On the other hand, if you use e.g.
86:Setup the keyboard only, do not setup the font or the terminal. On
91:Setup the font only, do not setup the keyboard or the terminal. On
98:Setup the terminal only, do not setup the keyboard or the font.
126:early in the boot process, then you should run it with this option
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:63: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:101: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:105: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:112: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:130: 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: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
--- setupcon.1 2025-01-08 18:34:14.500548474 +0000
+++ setupcon.1.new 2025-01-08 19:13:26.360408772 +0000
@@ -19,7 +19,8 @@ setupcon \- sets up the font and the key
is a program for fast and easy setup of the font and the keyboard on
the console. Most of the time you invoke
.B setupcon
-without arguments. The keyboard configuration is specified in
+without arguments.
+The keyboard configuration is specified in
.I ~/.keyboard
or
.IR /etc/default/keyboard .
@@ -33,83 +34,92 @@ and
.BR console-setup (5)
for instructions how to configure these two files.
.P
-If you have to switch often between different encodings, keyboards or
-languages, you can prepare several alternative configuration files for
+If you have to switch often between different encodings,
+keyboards or languages,
+you can prepare several alternative configuration files for
.BR setupcon .
-Suppose that most of the time you will use Greek language with Greek
-keyboard layout, but sometimes you need to type in German with German
-keyboard layout. In this situation you should customize the main
-configuration files
+Suppose
+that most of the time
+you will use Greek language with Greek keyboard layout,
+but sometimes you need to type in German with German keyboard layout.
+In this situation you should customize the main configuration files
.nh
.RI ( keyboard " and " console-setup )
.hy
-for Greek. Also, create alternative configuration files for German
-named
+for Greek.
+Also,
+create alternative configuration files for German named
.nh
.IR keyboard.german " and " console-setup.german .
.hy
-Then in order to configure the console for Greek you will simply run
-the command with no arguments:
+Then
+in order to configure the console for Greek
+you will simply run the command with no arguments:
.I setupcon
-and in order to configure the console for German you will use
+and in order to configure the console for German
+you will use
.nh
.IR setupcon\ german .
.hy
-
-
.SH OPTIONS
-
.TP
-.IR VARIANT
-Specifies which configuration file to use. With no variant,
+.I VARIANT
+Specifies which configuration file to use.
+With no variant,
the configuration files of
.B setupcon
are named
.IR console-setup " and " keyboard .
-On the other hand, if you use e.g.
+On the other hand,
+if you use e.g.,
.I chukchi
as
.I VARIANT
then the configuration files are
.IR console-setup.chukchi " and " keyboard.chukchi .
In this way you can have easy access to several different
-configurations \- for example one for the Chukchi language and another
+configurations \(en for example one for the Chukchi language and another
for the default configuration.
.TP
-.BR -v ,\ --verbose
-Be more verbose. Use this option if something goes wrong or while
-experimenting with the configuration files.
+.BR \-v ,\ \-\-\,verbose
+Be more verbose.
+Use this option
+if something goes wrong
+or while experimenting with the configuration files.
.TP
-.BR -k ,\ --keyboard-only
-Setup the keyboard only, do not setup the font or the terminal. On
-Linux it is enough to do this configuration only once.
+.BR \-k ,\ \-\-\,keyboard-only
+Setup the keyboard only,
+do not setup the font or the terminal.
+On Linux it is enough to do this configuration only once.
.TP
-.BR -f ,\ --font-only
-Setup the font only, do not setup the keyboard or the terminal. On
-Linux this configuration should be repeated each time a new console
-driver is activated (for example when the frame buffer becomes
-active).
+.BR \-f ,\ \-\-\,font-only
+Setup the font only,
+do not setup the keyboard or the terminal.
+On Linux this configuration should be repeated each time a new console
+driver is activated
+(for example when the frame buffer becomes active).
.TP
-.BR -t ,\ --terminal-only
-Setup the terminal only, do not setup the keyboard or the font.
+.BR \-t ,\ \-\-\,terminal-only
+Setup the terminal only,
+do not setup the keyboard or the font.
.TP
-.BR --current-tty
+.B \-\-\,current-tty
Setup the only the current virtual terminal.
.TP
-.BR --force
+.B \-\-\,force
Do not check whether we are on the console. Notice that you can be
forced to hard-reboot your computer if you run
.B setupcon
with this option and the screen is controlled by a X server.
.TP
-.BR --save
+.B \-\-\,save
This option can be useful if you want to use
.B setupcon
early in the boot process while
@@ -123,29 +133,30 @@ in order to make them available before
.I /usr
is mounted. If you use
.B setupcon
-early in the boot process, then you should run it with this option
+early in the boot process,
+then you should run it with this option
after every change of the console configuration.
.TP
-.BR --save-only
+.B \-\-\,save-only
The same as
-.IR --save ,
+.IR \-\-\,save ,
but does not setup anything. This option can be useful if you want to
save the required files while the screen is controlled by a X server.
.TP
-.BI --save-keyboard\ FILE
+.BI \-\-\,save-keyboard\ FILE
For use by initrd builders. Do not configure anything. Save an
usable keyboard layout in
.IR FILE .
.TP
-.BI --setup-dir\ DIR
+.BI \-\-\,setup-dir\ DIR
For use by initrd builders. Do not configure anything. Arrange in
the directory
.I DIR
everything necessary in order to configure the console. The file
-.IR DIR/morefiles
+.I DIR/morefiles
lists all binaries the initrd builder has to install in the initrd
image. All other files in
.I DIR
@@ -154,7 +165,7 @@ console one has to run the script
.IR DIR/bin/setupcon .
.TP
-.BR -h ,\ --help
+.BR \-h ,\ \-\-\,help
Display usage information.
.SH FILES
