Package: e2fsprogs
Version: 1.47.1-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
[test-][gn]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[test-groff is a script in the repository for "groff"] (local copy and
"troff" slightly changed by me).
* What was the outcome of this action?
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':264
troff:<stdin>:264: warning: ignoring escape character before a tab character
troff: backtrace: file '<stdin>':266
troff:<stdin>:266: warning: ignoring escape character before a tab character
troff: backtrace: file '<stdin>':284
troff:<stdin>:284: warning: ignoring escape character before a tab character
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: warning: ignoring escape character before a tab character
troff: backtrace: file '<stdin>':316
troff:<stdin>:316: warning: ignoring escape character before a tab character
* 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.10.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 e2fsprogs depends on:
ii libblkid1 2.40.2-8
ii libc6 2.40-2
ii libcom-err2 1.47.1-1
ii libext2fs2t64 1.47.1-1
ii libss2 1.47.1-1
ii libuuid1 2.40.2-8
ii logsave 1.47.1-1
Versions of packages e2fsprogs recommends:
pn e2fsprogs-l10n <none>
Versions of packages e2fsprogs suggests:
pn e2fsck-static <none>
pn fuse2fs <none>
pn gpart <none>
ii parted 3.6-4
-- no debconf information
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <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 outputs 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 e2image.8": (possibly shortened list)
mandoc: e2image.8:233:2: WARNING: skipping paragraph macro: br after PP
mandoc: e2image.8:263:2: WARNING: skipping paragraph macro: br after PP
mandoc: e2image.8:264:1: WARNING: undefined escape, printing literally: \
mandoc: e2image.8:266:1: WARNING: undefined escape, printing literally: \
mandoc: e2image.8:283:2: WARNING: skipping paragraph macro: br after PP
mandoc: e2image.8:284:1: WARNING: undefined escape, printing literally: \
mandoc: e2image.8:308:2: WARNING: skipping paragraph macro: br after PP
mandoc: e2image.8:309:1: WARNING: undefined escape, printing literally: \
mandoc: e2image.8:315:2: WARNING: skipping paragraph macro: br after PP
mandoc: e2image.8:316:1: WARNING: undefined escape, printing literally: \
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended. 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 "-" (end of options) then use "\-\-".
e2image.8:58:command) at regular intervals --- at boot time, and/or every week
or so.
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
130:.BI \-c
-.-.
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.
266:\ \fBbzip2 -z hda1.qcow2\fR
316:\ \fBe2image -arO 1048576 /dev/sda1 img\fR
-.-.
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.
125:attempt to find the appropriate blocksize. This search can be fooled in
127:with a particular blocksize. If the superblock is not found, e2image will
147:file is very likely not going to be useful. In some cases where the source
190:image format. See
219:etc. and can be run directly on the raw image file. In order to minimize
254:the raw image it is not sparse. The QCOW2 image minimize the amount of space
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':264
troff:<stdin>:264: warning: ignoring escape character before a tab character
troff: backtrace: file '<stdin>':266
troff:<stdin>:266: warning: ignoring escape character before a tab character
troff: backtrace: file '<stdin>':284
troff:<stdin>:284: warning: ignoring escape character before a tab character
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: warning: ignoring escape character before a tab character
troff: backtrace: file '<stdin>':316
troff:<stdin>:316: warning: ignoring escape character before a tab character
-.-.
Additionally:
Change '^\<tab>' to '\&<tab>' to avoid warnings from 'groff' and possibly
problems with mail software.
-.-
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them as
such and not as an end of sentence.
There is no need to add a '\&' before a full stop (.) if it has a character
before it!
--- e2image.8 2024-09-26 08:57:57.944921590 +0000
+++ e2image.8.new 2024-09-26 09:20:31.822594006 +0000
@@ -55,7 +55,7 @@ catastrophically corrupted file systems.
It is a very good idea to create image files for all file systems on a
system and save the partition layout (which can be generated using the
.B fdisk \-l
-command) at regular intervals --- at boot time, and/or every week or so.
+command) at regular intervals \(em at boot time, and/or every week or so.
The image file should be stored on some file system other than
the file system whose data it contains, to ensure that this data is
accessible in the case where the file system has been badly damaged.
@@ -122,12 +122,13 @@ The partition is copied as-is including
Set the file system blocksize in bytes. Normally,
.B e2image
will search for the superblock at various different block sizes in an
-attempt to find the appropriate blocksize. This search can be fooled in
-some cases. This option forces e2fsck to only try locating the superblock
-with a particular blocksize. If the superblock is not found, e2image will
-terminate with a fatal error.
+attempt to find the appropriate blocksize.
+This search can be fooled in some cases.
+This option forces e2fsck to only try locating the superblock
+with a particular blocksize.
+If the superblock is not found, e2image will terminate with a fatal error.
.TP
-.BI \-c
+.B \-c
Compare each block to be copied from the source
.I device
to the corresponding block in the target
@@ -187,7 +188,8 @@ Show progress of image-file creation.
Create a QCOW2-format image file instead of a normal image file, suitable
for use by virtual machine images, and other tools that can use the
.B .qcow
-image format. See
+image format.
+See
.B QCOW2 IMAGE FILES
below for details.
.TP
@@ -216,7 +218,7 @@ so that
.BR dumpe2fs (8),
.BR e2fsck (8),
.BR losetup (8),
-etc. and can be run directly on the raw image file. In order to minimize
+etc., and can be run directly on the raw image file. In order to minimize
the amount of disk space consumed by the raw image file, it is
created as a sparse file. (Beware of copying or
compressing/decompressing this file with utilities that don't understand
@@ -230,7 +232,6 @@ recommended command is as follows (repla
.B hda1
with the appropriate device for your system):
.PP
-.br
\fBe2image \-r /dev/hda1 \- | bzip2 > hda1.e2i.bz2\fR
.PP
This will only send the metadata information, without any data blocks.
@@ -251,7 +252,8 @@ The
.B \-Q
option will create a QCOW2 image file instead of a normal, or raw image file.
A QCOW2 image contains all the information the raw image does, however unlike
-the raw image it is not sparse. The QCOW2 image minimize the amount of space
+the raw image it is not sparse.
+The QCOW2 image minimize the amount of space
used by the image by storing it in special format which packs data closely
together, hence avoiding holes while still minimizing size.
.PP
@@ -260,10 +262,9 @@ e2fsprogs, use following commands (repla
.B hda1
with the appropriate device for your system):
.PP
+\& \fBe2image \-Q /dev/hda1 hda1.qcow2\fR
.br
-\ \fBe2image \-Q /dev/hda1 hda1.qcow2\fR
-.br
-\ \fBbzip2 -z hda1.qcow2\fR
+\& \fBbzip2 \-z hda1.qcow2\fR
.PP
This will only send the metadata information, without any data blocks.
As described for
@@ -280,9 +281,7 @@ such as for example
.PP
You can convert a .qcow2 image into a raw image with:
.PP
-.br
-\ \fBe2image \-r hda1.qcow2 hda1.raw\fR
-.br
+\& \fBe2image \-r hda1.qcow2 hda1.raw\fR
.PP
This can be useful to write a QCOW2 image containing all data to a
sparse image file where it can be loop mounted, or to a disk partition.
@@ -305,16 +304,12 @@ For example, if you have a
image of a whole hard drive that contains an ext2 fs in a partition
starting at 1 MiB, you can clone that image to a block device with:
.PP
-.br
-\ \fBe2image \-aro 1048576 img /dev/sda1\fR
-.br
+\& \fBe2image \-aro 1048576 img /dev/sda1\fR
.PP
Or you can clone a file system from a block device into an image file,
leaving room in the first MiB for a partition table with:
.PP
-.br
-\ \fBe2image -arO 1048576 /dev/sda1 img\fR
-.br
+\& \fBe2image \-arO 1048576 /dev/sda1 img\fR
.PP
If you specify at least one offset, and only one file, an in-place
move will be performed, allowing you to safely move the file system
