Package: e2fsprogs
Version: 1.47.2-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?
an.tmac:<stdin>:285: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:372: warning: cannot nest .TP or .TQ inside .TP; supply a tag
* 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.12-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.4-4
ii libc6 2.40-7
ii libcom-err2 1.47.2-1
ii libext2fs2t64 1.47.2-1
ii libss2 1.47.2-1
ii libuuid1 2.40.4-4
ii logsave 1.47.2-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 libarchive13t64 3.7.4-1.1
ii parted 3.6-4+b1
-- no debconf information
Input file is mke2fs.8
Output from "mandoc -T lint mke2fs.8": (shortened list)
1 input text line longer than 80 bytes: Copy the contents of...
1 input text line longer than 80 bytes: are specified then t...
1 line scope broken: TP breaks TP
-.-.
Output from "test-groff -mandoc -t -ww -z mke2fs.8": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
1 cannot nest .TP or .TQ inside .TP; supply a tag
-.-.
Change (or include a "FIXME" paragraph about) misused SI (metric)
numeric prefixes (or names) to the binary ones, like Ki (kibi), Mi
(mebi), Gi (gibi), or Ti (tebi), if indicated.
If the metric prefixes are correct, add the definitions or an
explanation to avoid misunderstanding.
162:does not have a suffix, it is interpreted as power-of-two kilobytes,
172:power-of-two kilobytes, megabytes, gigabytes, terabytes, etc.
208:file systems with block-size smaller or equal to the system page size - 4k
on
209:x86 systems, up to 64k on ppc64 or aarch64 depending on kernel
configuration).
213:option). In most common cases, the default block size is 4k. If
222:the blocksize be a multiple of 2k.
575:kilobytes.
605:(i.e., 1MB if using 1k blocks, 4MB if using 4k blocks, etc.)
-.-.
Add a (no-break, "\ " or "\~") space between a number and a unit,
as these are not one entity.
208:file systems with block-size smaller or equal to the system page size - 4k
on
209:x86 systems, up to 64k on ppc64 or aarch64 depending on kernel
configuration).
213:option). In most common cases, the default block size is 4k. If
222:the blocksize be a multiple of 2k.
605:(i.e., 1MB if using 1k blocks, 4MB if using 4k blocks, etc.)
-.-.
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.
208:file systems with block-size smaller or equal to the system page size - 4k
on
215:is preceded by a negative sign ('-'), then
242:at run-time. The special value "-" will read a tarball from standard input.
545:.B mke2fs -O journal_dev
568:.B -L
-.-.
Find a repeated word
! 788 --> is
! 826 --> clear
-.-.
Add a "\&" (or a comma (,)) 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.
440:N is the number of data-bearing disks in the RAID (e.g. for RAID 5 there is
one
-.-.
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 "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
N.B.
The number of lines affected can be too large to be in a patch.
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"
[List of affected lines removed]
-.-.
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 239, length 82
Copy the contents of the given directory or tarball into the root directory of
the
Line 422, length 81
are specified then the root directory permissions would be set in accordance
with
-.-.
Use \(en (en-dash) for a dash at the beginning (en) of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
mke2fs.8:208:file systems with block-size smaller or equal to the system page
size - 4k on
-.-.
Do not use more than two space characters between sentences or (better)
only a new line character.
170:blocks. If the fs-size is suffixed by 'k', 'm', 'g', 't'
235:man page for more details about bigalloc.) The default cluster size if
394:feature is set. The default quota types to be initialized if this
405:Specify the file system revision number. Revision 0 file systems
407:1995). This is only needed for testing or people who want to use
761:file. This option controls which file system options are used by
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
845:an undo file. This undo file can be used with e2undo(8) to restore the old
-.-.
The section part for a manual page is set in roman font.
234:.B ext4 (5)
-.-.
Use the name of units in text; use symbols in tables and
calculations.
The rule is to have a (no-break, \~) space between a number and
its units (see "www.bipm.org/en/publications/si-brochure")
208:file systems with block-size smaller or equal to the system page size - 4k
on
209:x86 systems, up to 64k on ppc64 or aarch64 depending on kernel
configuration).
213:option). In most common cases, the default block size is 4k. If
222:the blocksize be a multiple of 2k.
605:(i.e., 1MB if using 1k blocks, 4MB if using 4k blocks, etc.)
-.-.
Split a punctuation from a single argument, if a two-font macro is meant.
430:.I chunk size.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
mke2fs.8:155:partition (or file) named by
mke2fs.8:389:Specify the which quota types (usrquota, grpquota, prjquota) which
mke2fs.8:458:or is mounted (a truly dangerous thing to do), this option must be
mke2fs.8:479:create a larger virtual block group (or "flex_bg group") in an
mke2fs.8:528:create an appropriately sized journal (given the size of the file
system)
mke2fs.8:597:suffix (e.g., 'M', 'G', etc.) interpret it as the offset from the
mke2fs.8:601:Create an internal journal (i.e., stored inside the file system)
of size
mke2fs.8:607:file system size (whichever is smaller)
mke2fs.8:679:Create a file system with the given features (file system options),
mke2fs.8:753:Specify the file system type (i.e., ext2, ext3, ext4, etc.) that is
-.-.
Use thousand markers to make large numbers easy to read
207:from 1024 up to 65536 (however note that the kernel is able to mount only
231:feature. Valid cluster-size values range from 2 to 32768 times the
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:285: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:372: warning: cannot nest .TP or .TQ inside .TP; supply a tag
-.-
Additionally:
"that" used in on place instead fo "which".
-.-
Eliminate space between roman '(' and italic 'fast-commit-size'.
-.-
Add italic correction between roman ] and italic f in
-O [^]feature
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- mke2fs.8 2025-02-24 16:19:01.888784058 +0000
+++ mke2fs.8.new 2025-02-24 17:50:30.703902664 +0000
@@ -151,8 +151,10 @@ mke2fs \- create an ext2/ext3/ext4 file
]
.SH DESCRIPTION
.B mke2fs
-is used to create an ext2, ext3, or ext4 file system, usually in a disk
-partition (or file) named by
+is used to create an ext2, ext3, or ext4 file system,
+usually in a disk partition
+(or file)
+named by
.IR device .
.PP
The file system size is specified by
@@ -167,7 +169,8 @@ option is specified, in which case
.I fs-size
is interpreted as the number of
.I blocksize
-blocks. If the fs-size is suffixed by 'k', 'm', 'g', 't'
+blocks.
+If the fs-size is suffixed by 'k', 'm', 'g', 't'
(either upper-case or lower-case), then it is interpreted in
power-of-two kilobytes, megabytes, gigabytes, terabytes, etc.
If
@@ -204,22 +207,23 @@ manual page for more details.
.TP
.BI \-b " block-size"
Specify the size of blocks in bytes. Valid block-size values are powers of two
-from 1024 up to 65536 (however note that the kernel is able to mount only
-file systems with block-size smaller or equal to the system page size - 4k on
-x86 systems, up to 64k on ppc64 or aarch64 depending on kernel configuration).
+from 1024 up to 65,536 (however note that the kernel is able to mount only
+file systems with block-size smaller
+or equal to the system page size \(en 4\~KiB on x86 systems,
+up to 64\~KiB on ppc64 or aarch64 depending on kernel configuration).
If omitted, block-size is heuristically determined by the file system size and
the expected usage of the file system (see the
.B \-T
-option). In most common cases, the default block size is 4k. If
+option). In most common cases, the default block size is 4\~KiB. If
.I block-size
-is preceded by a negative sign ('-'), then
+is preceded by a negative sign ('\-'), then
.B mke2fs
will use heuristics to determine the
appropriate block size, with the constraint that the block size will be
at least
.I block-size
bytes. This is useful for certain hardware devices which require that
-the blocksize be a multiple of 2k.
+the blocksize be a multiple of 2\~KiB.
.TP
.B \-c
Check the device for bad blocks before creating the file system. If
@@ -228,18 +232,19 @@ test is used instead of a fast read-only
.TP
.B \-C " cluster-size"
Specify the size of cluster in bytes for file systems using the bigalloc
-feature. Valid cluster-size values range from 2 to 32768 times the
+feature. Valid cluster-size values range from 2 to 32,768 times the
filesystem blocksize and must be a power of 2. The cluster-size can
only be specified if the bigalloc feature is enabled. (See the
-.B ext4 (5)
+.BR ext4 (5)
man page for more details about bigalloc.) The default cluster size if
bigalloc is enabled is 16 times the block size.
.TP
.BI \-d " root-directory|tarball"
-Copy the contents of the given directory or tarball into the root directory of
the
+Copy the contents of the given directory
+or tarball into the root directory of the
file system. Tarball input is only available if mke2fs was compiled with
libarchive support enabled and if the libarchive shared library is available
-at run-time. The special value "-" will read a tarball from standard input.
+at run-time. The special value "\-" will read a tarball from standard input.
.TP
.B \-D
Use direct I/O when writing to the disk. This avoids mke2fs dirtying a
@@ -282,7 +287,7 @@ The following extended options are suppo
.TP
.B assume_storage_prezeroed\fR[\fB= \fI<0 to disable, 1 to enable>\fR]
If enabled,
-.BR mke2fs
+.B mke2fs
assumes that the storage device has been prezeroed, skips zeroing the journal
and inode tables, and annotates the block group flags to signal that the inode
table has been zeroed.
@@ -369,7 +374,6 @@ be 0, 1, or 2 backup superblocks created
Create the file system at an offset from the beginning of the device or
file. This can be useful when creating disk images for virtual machines.
.TP
-.TP
.BI orphan_file_size= size
Set size of the file for tracking unlinked but still open inodes and inodes
with truncate in progress. Larger file allows for better scalability, reserving
@@ -386,12 +390,14 @@ can be useful for certain specialized us
Shingled Drives.
.TP
.B quotatype
-Specify the which quota types (usrquota, grpquota, prjquota) which
-should be enabled in the created file system. The argument of this
+Specify the quota types
+(usrquota, grpquota, prjquota)
+that should be enabled in the created file system. The argument of this
extended option should be a colon separated list. This option has
effect only if the
.B quota
-feature is set. The default quota types to be initialized if this
+feature is set.
+The default quota types to be initialized if this
option is not specified is both user and group quotas. If the project
feature is enabled that project quotas will be initialized as well.
.TP
@@ -402,9 +408,11 @@ to support a file system that has
blocks.
.TP
.BI revision= fs-revision
-Specify the file system revision number. Revision 0 file systems
+Specify the file system revision number.
+Revision 0 file systems
provide compatibility with pre-1.2 Linux kernels (dating from before
-1995). This is only needed for testing or people who want to use
+1995).
+This is only needed for testing or people who want to use
very early, historical Linux systems. The current default (supported
by all modern Linux systems) is revision 1.
.TP
@@ -418,8 +426,9 @@ and avoid side-effects for users that do
file system to change based on the user running \fBmke2fs\fR.
.TP
.BI root_perms [=permissions]
-Specify the root directory permissions in octal format. If no permissions
-are specified then the root directory permissions would be set in accordance
with
+Specify the root directory permissions in octal format.
+If no permissions are specified
+then the root directory permissions would be set in accordance with
the default filesystem umask.
.TP
.BI stride= stride-size
@@ -427,7 +436,7 @@ Configure the file system for a RAID arr
.I stride-size
file system blocks. This is the number of blocks read or written to disk
before moving to the next disk, which is sometimes referred to as the
-.I chunk size.
+.IR "chunk size" .
This mostly affects placement of file system metadata like bitmaps at
.B mke2fs
time to avoid placing them on a single disk, which can hurt performance.
@@ -437,8 +446,9 @@ It may also be used by the block allocat
Configure the file system for a RAID array with
.I stripe-width
file system blocks per stripe. This is typically stride-size * N, where
-N is the number of data-bearing disks in the RAID (e.g. for RAID 5 there is one
-parity disk, so N will be the number of disks in the array minus 1).
+N is the number of data-bearing disks in the RAID
+(e.g.\& for RAID 5 there is one parity disk,
+so N will be the number of disks in the array minus 1).
This allows the block allocator to prevent read-modify-write of the
parity in a RAID stripe if possible when the data is written.
.TP
@@ -455,8 +465,9 @@ on a block special device, or if other p
In order to force
.B mke2fs
to create a file system even if the file system appears to be in use
-or is mounted (a truly dangerous thing to do), this option must be
-specified twice.
+or is mounted
+(a truly dangerous thing to do),
+this option must be specified twice.
.TP
.BI \-g " blocks-per-group"
Specify the number of blocks in a block group. There is generally no
@@ -476,8 +487,9 @@ option will specify the number of cluste
.TP
.BI \-G " number-of-groups"
Specify the number of block groups that will be packed together to
-create a larger virtual block group (or "flex_bg group") in an
-ext4 file system. This improves meta-data locality and performance
+create a larger virtual block group
+(or "flex_bg group")
+in an ext4 file system. This improves meta-data locality and performance
on meta-data heavy workloads. The number of groups must be a power
of 2 and may only be specified if the
.B flex_bg
@@ -525,7 +537,8 @@ all file systems, except for the GNU Hur
Create the file system with an ext3 journal. If the
.B \-J
option is not specified, the default journal parameters will be used to
-create an appropriately sized journal (given the size of the file system)
+create an appropriately sized journal
+(given the size of the file system)
stored within the file system. Note that you must be using a kernel
which has ext3 support in order to actually make use of the journal.
.TP
@@ -542,7 +555,7 @@ Attach the file system to the journal bl
The external
journal must already have been created using the command
.IP
-.B mke2fs -O journal_dev
+.B mke2fs \-O journal_dev
.I external-journal
.IP
Note that
@@ -565,7 +578,7 @@ to locate the external journal by either
stored in the ext2 superblock at the start of the journal. Use
.BR dumpe2fs (8)
to display a journal device's volume label and UUID. See also the
-.B -L
+.B \-L
option of
.BR tune2fs (8).
.TP
@@ -584,8 +597,8 @@ feature is turned on, fast commit area s
.B fast_commit
feature set is
.I journal-size
-+ (
-.I fast-commit-size
++
+.RI ( fast-commit-size
* 1024) megabytes. The total journal size may be no more than
10,240,000 file system blocks or half the total file system size
(whichever is smaller).
@@ -594,17 +607,22 @@ feature set is
Specify the location of the journal. The argument
.I journal-location
can either be specified as a block number, or if the number has a units
-suffix (e.g., 'M', 'G', etc.) interpret it as the offset from the
+suffix
+(e.g., 'M', 'G', etc.\&)
+interpret it as the offset from the
beginning of the file system.
.TP
.BI size= journal-size
-Create an internal journal (i.e., stored inside the file system) of size
+Create an internal journal
+(i.e., stored inside the file system)
+of size
.I journal-size
megabytes.
-The size of the journal must be at least 1024 file system blocks
-(i.e., 1MB if using 1k blocks, 4MB if using 4k blocks, etc.)
+The size of the journal must be at least 1024 bytes file system blocks
+(i.e., 1\~MiB if using 1\~KiB blocks, 4\~MiB if using 4\~KiB blocks, etc.)
and may be no more than 10,240,000 file system blocks or half the total
-file system size (whichever is smaller)
+file system size
+(whichever is smaller)
.RE
.IP
Only one of the
@@ -675,8 +693,9 @@ file system. The creator field is set b
.B mke2fs
executable was compiled for.
.TP
-.B "\-O \fR[^]\fIfeature\fR[,...]"
-Create a file system with the given features (file system options),
+.B "\-O \fR[^]\,\fIfeature\fR[,...]"
+Create a file system with the given features
+(file system options),
overriding the default file system options. The features that are
enabled by default are specified by the
.I base_features
@@ -750,15 +769,17 @@ file system so other options can be trie
.\" using the specified test.
.TP
.BI \-t " fs-type"
-Specify the file system type (i.e., ext2, ext3, ext4, etc.) that is
-to be created.
+Specify the file system type
+(i.e., ext2, ext3, ext4, etc.\&)
+that is to be created.
If this option is not specified,
.B mke2fs
will pick a default either via how
the command was run (for example, using a name of the form mkfs.ext2,
mkfs.ext3, etc.) or via a default as defined by the
.B /etc/mke2fs.conf
-file. This option controls which file system options are used by
+file.
+This option controls which file system options are used by
default, based on the
.B fstypes
configuration stanza in
@@ -785,7 +806,7 @@ types that are supported are defined in
The user may specify one or more usage types
using a comma separated list.
.sp
-If this option is is not specified,
+If this option is not specified,
.B mke2fs
will pick a single default usage type based on the size of the file system to
be created. If the file system size is less than 3 megabytes,
@@ -842,7 +863,9 @@ and exit.
.TP
.BI \-z " undo_file"
Before overwriting a file system block, write the old contents of the block to
-an undo file. This undo file can be used with e2undo(8) to restore the old
+an undo file. This undo file can be used with
+.BR e2undo (8)
+to restore the old
contents of the file system should something go wrong. If the empty string is
passed as the undo_file argument, the undo file will be written to a file named
mke2fs-\fIdevice\fR.e2undo in the directory specified via the
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)
-.-
