Util-Linux Archive on lore.kernel.org
 help / color / Atom feed
* Errors in man pages of util-linux
@ 2020-05-03 19:13 Helge Kreutzmann
  2020-05-09 18:53 ` Michael Kerrisk
  0 siblings, 1 reply; 7+ messages in thread
From: Helge Kreutzmann @ 2020-05-03 19:13 UTC (permalink / raw)
  To: util-linux; +Cc: Mario Blättermann


[-- Attachment #1: Type: text/plain, Size: 38292 bytes --]

Dear util-linux maintainers.
the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including util-linux) as
well for a large variety of target languages.

During their work translators notice different possible issues in the
original (english) man pages. Sometiems this is a straightforward
typo, sometimes a hard to read sentence, sometimes this is a
convention not held up and sometimes we simply do not understand the 
original.

We use several distributions as sources and update regularly (at
least every 2 month). This means we are fairly recent (some
distributions like archlinux also update frequently) but might miss
the latest upstream version once a while, so the error might be
already fixed. We apologize and ask you to close the issue immediately
if this should be the case, but given the huge volume of projects and
the very limited number of volunteers we are not able to double check
each and every issue.

Secondly we translators see the manpages in the neutral po format,
i.e. converted and harmonized, but not the original source (be it man,
groff, xml or other). So we cannot provide a true patch (where
possible), but only an approximation which you need to convert into
your source format.

Finally the issues I'm reporting have accumulated over time and are
not always discovered by me, so sometimes my description of the
problem my be a bit limited - do not hesitate to ask so we can clarify
them.

I'm now reporting the errors for your project. If future reports should 
use another channel, please let me know.

**

Man page: adjtime_config.5
Issue: Superfluous comma after "is"

"The format of the adjtime file is, in ASCII."
--
Man page: adjtime_config.5
Issue: hwckock → hwclock

"The Hardware Clock is usually not very accurate.  However, much of its "
"inaccuracy is completely predictable - it gains or loses the same amount of "
"time every day.  This is called systematic drift.  The util hwclock keeps "
"the file /etc/adjtime, that keeps some historical information.  For more "
"details see \"B<The Adjust Function>\" and \"B<The Adjtime File>\" sections "
"from B<hwckock>(8)  man page."
--
Man page: agetty.8
Issue: agetty → B<agetty>

"Display the current issue file (or other) on the current terminal and exit.  "
"Use this option to review the current setting, it is not designed for any "
"other purpose.  Note that output may use some default or incomplete "
"information as proper output depends on terminal and agetty command line."
--
Man page: agetty.8
Issue: I<inittab(5)> → B<inittab>(5)

"This section shows examples for the process field of an entry in the I</etc/"
"inittab> file.  You'll have to prepend appropriate values for the other "
"fields.  See I<inittab(5)> for more details."
--
Man page: agetty.8
Issue: commandline → command line

"Some programs use \"--\" to indicate that the rest of the command line "
"should not be interpreted as options.  Use this feature if available by "
"passing \"--\" before the username gets passed by \\eu."
--
Man page: agetty.8
Issue: agetty → B<agetty>

"Since version 2.35 additional locations for issue file and directory are "
"supported. If the default I</etc/issue> does not exist than agetty checks "
"for I</run/issue> and I</run/issue.d>, thereafter for I</usr/lib/issue> and "
"I</usr/lib/issue.d>.  The directory /etc is expected for host specific "
"configuration, /run is expected for generated stuff and /usr/lib for static "
"distribution maintained configuration."
--
Man page: agetty.8
Issue: If not any configured → If no configured

"Insert the IPv4 address of the specified network interface (for example: "
"\\e4{eth0}).  If the I<interface> argument is not specified, then select the "
"first fully configured (UP, non-LOCALBACK, RUNNING) interface.  If not any "
"configured interface is found, fall back to the IP address of the machine's "
"hostname."
--
Man page: blkid.8
Issue: Missing markup from "mount"

"This option forces B<blkid> to use udev when used for LABEL or UUID tokens "
"in B<--match-token>. The goal is to provide output consistent with another "
"utils (like mount, etc.)  on systems where the same tag is used for multiple "
"devices."
--
Man page: blkzone.8
Issue: Double full stop

"Display the number of zones returned in the report or the range of sectors "
"reset.."
--
Man page: chfn.1
Issue: Missing markup for command name

"The chfn command is part of the util-linux package and is available from "
"https://www.kernel.org/pub/linux/utils/util-linux/."
--
Man page: chsh.1
Issue: Missing markup for command name

"The chsh command is part of the util-linux package and is available from "
"https://www.kernel.org/pub/linux/utils/util-linux/."
--
Man page: col.1
Issue: Missing markup for command name

"The col command is part of the util-linux package and is available from E<."
"UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
"Kernel Archive E<.UE .>"
--
Man page: colcrt.1
Issue: invisible → partially invisible

"Causes all half-lines to be printed, effectively double spacing the output.  "
"Normally, a minimal space output format is used which will suppress empty "
"lines.  The program never suppresses two consecutive empty lines, however.  "
"The B<-2> option is useful for sending output to the line printer when the "
"output contains superscripts and subscripts which would otherwise be "
"invisible."
--
Man page: colcrt.1
Issue: B<'-'> → B<->

"Should fold underlines onto blanks even with the B<'-'> option so that a "
"true underline character would show."
--
Man page: colrm.1
Issue: Missing markup for command name

"The colrm command is part of the util-linux package and is available from E<."
"UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
"Kernel Archive E<.UE .>"
--
Man page: column.1
Issue: Missing markup for command name

"The column command is part of the util-linux package and is available from "
"https://www.kernel.org/pub/linux/utils/util-linux/."
--
Man page: column.1
Issue: Missing markup for command name

"By default, the column command will merge multiple adjacent delimiters into "
"a single delimiter when using the E<.Fl t> option; this option disables that "
"behavior. This option is a Debian GNU/Linux extension."
--
Man page: fdisk.8
Issue: Why is the full stop at the end in bold?

"Specify the sector size of the disk.  Valid values are 512, 1024, 2048, and "
"4096.  (Recent kernels know the sector size.  Use this option only on old "
"kernels or to override the kernel's ideas.)  Since util-linux-2.17, B<fdisk> "
"differentiates between logical and physical sector size.  This option "
"changes both sector sizes to I<sectorsize>B<.>"
--
Man page: fdisk.8
Issue: "when create" → "when creating"

"Don't erase the begin of the first disk sector when create a new disk "
"label.  This feature is supported for GPT and MBR."
--
Man page: fdisk.8
Issue: Missing markup of file (names)

"The I<device> is usually /dev/sda, /dev/sdb or so.  A device name refers to "
"the entire disk.  Old systems without libata (a library used inside the "
"Linux kernel to support ATA host controllers and devices) make a difference "
"between IDE and SCSI disks.  In such cases the device name will be /dev/hd* "
"(IDE) or /dev/sd* (SCSI)."
--
Man page: fdisk.8
Issue: Content: Do need to mark partitions with »volume« and »volume
                header«

"An IRIX/SGI disklabel can describe 16 partitions, the eleventh of which "
"should be an entire `volume' partition, while the ninth should be labeled "
"`volume header'.  The volume header will also cover the partition table, i."
"e., it starts at block zero and extends by default over five cylinders.  The "
"remaining space in the volume header may be used by header directory "
"entries.  No partitions may overlap with the volume header.  Also do not "
"change its type or make some filesystem on it, since you will lose the "
"partition table.  Use this type of label only when working with Linux on "
"IRIX/SGI machines or IRIX/SGI disks under Linux."
--
Man page: fdisk.8
Issue: Missing markup of fdisk

"Usually all goes well by default, and there are no problems if Linux is the "
"only system on the disk.  However, if the disk has to be shared with other "
"operating systems, it is often a good idea to let an fdisk from another "
"operating system make at least one partition.  When Linux boots it looks at "
"the partition table, and tries to deduce what (fake) geometry is required "
"for good cooperation with other systems."
--
Man page: fsck.minix.8
Issue: Replace \(en with Unicode U+2013 '-

msgid "/dev/hda[1\\(en63]"

msgid "/dev/hdb[1\\(en63]"

msgid "/dev/sda[1\\(en15]"

msgid "/dev/sdb[1\\(en15]"
--
Man page: fstrim.8
Issue: Markup of fstrim

"Minimum contiguous free range to discard, in bytes. (This value is "
"internally rounded up to a multiple of the filesystem block size.)  Free "
"ranges smaller than this will be ignored and fstrim will adjust the minimum "
"if it's smaller than the device's minimum, and report that (fstrim_range."
"minlen) back to userspace.  By increasing this value, the fstrim operation "
"will complete more quickly for filesystems with badly fragmented freespace, "
"although not all blocks will be discarded.  The default value is zero, "
"discarding every free block."
--
Man page: getopt.1
Issue: Missing comma when enumarating Shells (after sh)

"Set quoting conventions to those of I<shell>.  If the B<-s> option is not "
"given, the E<.SM BASH> conventions are used.  Valid arguments are currently "
"'B<sh>' 'B<bash>', 'B<csh>', and 'B<tcsh>'."
--
Man page: hardlink.1
Issue: Markup up of command options missing

"Among equal files, keep the oldest file (least recent modification time). By "
"default, the newest file is kept. If --maximize or --minimize is specified, "
"the link count has a higher precedence than the time of modification."

"A regular expression to include files. If the option --exclude has been "
"given, this option re-includes files which would otherwise be excluded. If "
"the option is used without --exclude, only files matched by the pattern are "
"included."

"B<hardlink> , as of version 0.3 RC1, improperly calculates the amount of "
"space saved if the option --respect-name is specified. In previous versions, "
"the amount was wrong in almost all other cases as well."
--
Man page: hardlink.1
Issue: Markup up of "hardlink" missing

"B<hardlink> assumes that the trees it operates on do not change during "
"operation. If a tree does change, the result is undefined and potentially "
"dangerous. For example, if a regular file is replaced by a device, hardlink "
"may start reading from the device. If a component of a path is replaced by a "
"symbolic link or file permissions change, security may be compromised. Do "
"not run hardlink on a changing tree or on a tree controlled by another user."

"The program hardlink and this manpage have been written by Julian Andres "
"Klode, and are licensed under the MIT license. See the code of hardlink for "
"further information."
--
Man page: hexdump.1
Issue: When markup is used (B<>), no extra quoting is necessary

"I<Canonical hex+ASCII display>.  Display the input offset in hexadecimal, "
"followed by sixteen space-separated, two-column, hexadecimal bytes, followed "
"by the same sixteen bytes in B<%_p> format enclosed in 'B<|>' characters."

"Output characters in the default character set.  Non-printing characters are "
"displayed as a single 'B<\\&.>'."
--
Man page: hexdump.1
Issue: Missing closing bracket (for fprintf)

"The format is required and must be surrounded by double quote (\" \") "
"marks.  It is interpreted as a fprintf-style format string (see "
"B<fprintf>(3), with the following exceptions:"
--
Man page: hexdump.1
Issue: identical → almost identical

"Identical to the B<\\&_a> conversion string except that it is only performed "
"once, when all of the input data has been processed."
--
Man page: hexdump.1
Issue: Missing mark up for "hexdump"

"When put at the end of a format specifier, hexdump highlights the respective "
"string with the color specified.  Conditions, if present, are evaluated "
"prior to highlighting."

"The hexdump command is part of the util-linux package and is available from "
"E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> "
"Linux Kernel Archive E<.UE .>"
--
Man page: hexdump.1
Issue: Mixed markup (B<>) and quoting for conversion characters

"Further output by such format strings is replaced by an equivalent number of "
"spaces.  An equivalent number of spaces is defined as the number of spaces "
"output by an B<s> conversion character with the same field width and "
"precision as the original conversion character or conversion string but with "
"any 'B<\\&+>', \\' \\', 'B<\\&#>' conversion flag characters removed, and "
"referencing a NULL string."
--
Man page: hexdump.1
Issue: ``|'' → B<|>

"E<.Em Canonical hex+ASCII display>.  Display the input offset in "
"hexadecimal, followed by sixteen space-separated, two column, hexadecimal "
"bytes, followed by the same sixteen bytes in %_p format enclosed in ``|'' "
"characters."
--
Man page: hwclock.8
Issue: Markup up correct? (around option)

"Use\\ B<--verbose>.  The\\ B<\\%--debug\\ >option has been deprecated and "
"may be repurposed or removed in a future release."
--
Man page: hwclock.8
Issue: Replace comma by full stop

"Update the Hardware Clock's drift factor in I</etc/adjtime>.  It can only be "
"used with B<--set> or B<\\%--systohc>,"
--
Man page: hwclock.8
Issue: Paragraph hard to read

"Significantly increased system shutdown times (as of v2.31 when not using B<"
"\\%--update-drift> the RTC is not read)."
--
Man page: hwclock.8
Issue: date-time → date time??

msgid "There are two types of date-time clocks:"
--
Man page: hwclock.8
Issue: Spaces in and around the final B<>

"Some Linux distributions attempt to automatically calculate the System Clock "
"drift with B<\\%adjtimex>'s compare operation.  Trying to correct one "
"drifting clock by using another drifting clock as a reference is akin to a "
"dog trying to catch its own tail.  Success may happen eventually, but great "
"effort and frustration will likely precede it.  This automation may yield an "
"improvement over no configuration, but expecting optimum results would be in "
"error.  A better choice for manual configuration would be B<\\%adjtimex>'sB< "
"--log >options."
--
Man page: hwclock.8
Issue: Missing Space at beginning of line

msgid "TheI< System Clock >time must be correct at shutdown!"
--
Man page: libblkid.3
Issue: evaluate → determine?

"The high-level part of the library supports two methods to evaluate LABEL/"
"UUID.  It reads information directly from a block device or read information "
"from /dev/disk/by-* udev symlinks.  The udev is preferred method by default."
--
Man page: libblkid.3
Issue: Missing markup for command name

"libblkid is part of the util-linux package since version 2.15 and is "
"available from https://www.kernel.org/pub/linux/utils/util-linux/."
--
Man page: logger.1
Issue: Superfluous space before full stop

"Use datagrams (UDP) only.  By default the connection is tried to the syslog "
"port defined in /etc/services, which is often 514 ."
--
Man page: logger.1
Issue: Missing markup of command name

"Log the PID of the logger process with each line.  When the optional "
"argument I<id> is specified, then it is used instead of the logger command's "
"PID.  The use of B<--id=$$> (PPID) is recommended in scripts that send "
"several messages."

"Write a systemd journal entry.  The entry is read from the given I<file>, "
"when specified, otherwise from standard input.  Each line must begin with a "
"field that is accepted by journald; see B<systemd.journal-fields>(7)  for "
"details.  The use of a MESSAGE_ID field is generally a good idea, as it "
"makes finding entries easy.  Examples:"

"Use the specified I<port>.  When this option is not specified, the port "
"defaults to syslog for udp and to syslog-conn for tcp connections."

"Most receivers accept messages larger than 1KiB over any type of syslog "
"protocol.  As such, the B<--size> option affects logger in all cases (not "
"only when B<--rfc5424> was used)."
--
Man page: logger.1
Issue: or the journal → to the journal?

"Causes everything to be done except for writing the log message to the "
"system log, and removing the connection or the journal.  This option can be "
"used together with B<--stderr> for testing purposes."
--
Man page: logger.1
Issue: Missing markup of parameters

"B<logger> currently generates the B<timeQuality> standardized element only.  "
"RFC 5424 also describes the elements B<origin> (with parameters ip, "
"enterpriseId, software and swVersion) and B<meta> (with parameters "
"sequenceId, sysUpTime and language).  These element IDs may be specified "
"without the B<@>I<digits> suffix."
--
Man page: logger.1
Issue: Missing markup file names, command names etc.

"Print errors about Unix socket connections.  The I<mode> can be a value of "
"B<off>, B<on>, or B<auto>.  When the mode is auto logger will detect if the "
"init process is systemd, and if so assumption is made /dev/log can be used "
"early at boot.  Other init systems lack of /dev/log will not cause errors "
"that is identical with messaging using B<openlog>(3)  system call.  The "
"B<logger>(1)  before version 2.26 used openlog, and hence was unable to "
"detected loss of messages sent to Unix sockets."
--
Man page: logger.1
Issue: The »to« marks a range inside a list. Shouldn't be bold.

msgid "B<  to>"
--
Man page: logger.1
Issue: Missing markup for command name

"The logger command is part of the util-linux package and is available from "
"E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> "
"Linux Kernel Archive E<.UE .>"
--
Man page: login.1
Issue: Missing full stop

"The default is to check I</etc\\:/hushlogins> and if it does not exist then "
"I<~/.hushlogin>"

"If set, it will be used to define the PATH environment variable when a "
"regular user logs in.  The default value is I</usr\\:/local\\:/bin:\\:/bin:"
"\\:/usr\\:/bin>"
--
Man page: login.1
Issue: Missing markup for lastlog

"Highest user ID number for which the lastlog entries should be updated.  As "
"higher user IDs are usually tracked by remote user identity and "
"authentication services there is no need to create a huge sparse lastlog "
"file for them.  No LASTLOG_UID_MAX option present in the configuration means "
"that there is no user ID limit for writing lastlog entries."
--
Man page: login.1
Issue: Missing markup for command name

"A recursive login, as used to be possible in the good old days, no longer "
"works; for most purposes B<su>(1)  is a satisfactory substitute.  Indeed, "
"for security reasons, login does a vhangup() system call to remove any "
"possible listening processes on the tty.  This is to avoid password "
"sniffing.  If one uses the command B<login>, then the surrounding shell gets "
"killed by vhangup() because it's no longer the true owner of the tty.  This "
"can be avoided by using B<exec login> in a top-level shell or xterm."
--
Man page: login.1
Issue: Missing markup for command name

"The login command is part of the util-linux package and is available from E<."
"UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
"Kernel Archive E<.UE .>"
--
Man page: lscpu.1
Issue: superfluous quoting around B<>

"When specifying the I<list> argument, the string of option, equal sign (=), "
"and I<list> must not contain any blanks or other whitespace.  Examples: 'B<-"
"C=NAME,ONE-SIZE>' or 'B<--caches=NAME,ONE-SIZE>'."
--
Man page: lslogins.1
Issue: specify → specified, than → then

"Note that relation between user and group may be invisible for primary group "
"if the user is not explicitly specify as group member (e.g., in /etc/group). "
"If the command lslogins scans for groups than it uses groups database only, "
"and user database with primary GID is not used at all."
--
Man page: lslogins.1
Issue: IDS → IDs

"Only show data of users with a login specified in I<logins> (user names or "
"user IDS).  More than one login may be specified; the list has to be comma-"
"separated.  The unknown login names are ignored."
--
Man page: lslogins.1
Issue: Markup and closing bracket are wrongly interleaved

msgid "Display information related to login by password (see also B<-afL).>"
--
Man page: lsmem.1
Issue: output compatible → output is compatible

"The default output compatible with original implementation from s390-tools, "
"but it's strongly recommended to avoid using default outputs in your "
"scripts.  Always explicitly define expected columns by using the B<--output> "
"option together with a columns list in environments where a stable output is "
"required."
--
Man page: lsmem.1
Issue: First sentence: Broken?

"The B<lsmem> command lists a new memory range always when the current memory "
"block distinguish from the previous block by some output column.  This "
"default behavior is possible to override by the B<--split> option (e.g., "
"B<lsmem --split=ZONES>).  The special word \"none\" may be used to ignore "
"all differences between memory blocks and to create as large as possible "
"continuous ranges.  The opposite semantic is B<--all> to list individual "
"memory blocks."
--
Man page: lsns.8
Issue: 2nd sentence broken wording

"B<NSFS> column, printed when B<net> is specified for B<--type> option, is "
"special; it uses multi-line cells.  Use the option B<--nowrap> is for "
"switching to \",\" separated single-line representation."
--
Man page: mkswap.8
Issue: No such section in swapon.8

"Please read notes from B<swapon>(8)  about B<the swap file use restrictions> "
"(holes, preallocation and copy-on-write issues)."
--
Man page: mount.8
Issue: bythe → by the

"The same filesystem may be mounted more than once, and in some cases (e.g., "
"network filesystems) the same filesystem may be mounted on the same "
"mountpoint more times. The mount command does not implement any policy to "
"control this behavior. All behavior is controlled by the kernel and it is "
"usually specific to the filesystem driver. The exception is B<--all>, in "
"this case already mounted filesystems are ignored (see B<--all> below for "
"more details)."
--
Man page: mount.8
Issue: disables B<--options-source-force> → enables!

"Source of default options.  I<source> is comma separated list of B<fstab>, "
"B<mtab> and B<disable>.  B<disable> disables B<fstab> and B<mtab> and "
"disables B<--options-source-force>.  Default value is B<fstab,mtab>."
--
Man page: mount.8
Issue: The wording is rather unusual english, improve?

"Note that specify B<-w> on command line forces B<mount> command to never try "
"read-only mount on write-protected devices. The default is try read-only if "
"the previous mount syscall with read-write flags failed."
--
Man page: mount.8
Issue: Does this include other executable like scripts?

msgid "Permit execution of binaries."
--
Man page: mount.8
Issue: maintain → maintaining

"The same as B<X-*> options, but stored permanently in the user space. It "
"means the options are also available for umount or another operations.  Note "
"that maintain mount options in user space is tricky, because it's necessary "
"use libmount based tools and there is no guarantee that the options will be "
"always available (for example after a move mount operation or in unshared "
"namespace)."
--
Man page: mount.8
Issue: mount → B<mount>

"Allow to make a target directory (mountpoint) if it does not exit yet.  The "
"optional argument I<mode> specifies the filesystem access mode used for "
"B<mkdir>(2)  in octal notation.  The default mode is 0755.  This "
"functionality is supported only for root users or when mount executed "
"without suid permissions.  The option is also supported as x-mount.mkdir, "
"this notation is deprecated since v2.30."
--
Man page: mount.8
Issue: URL does not allow login (2019-01-29)

"A remount option which permits online expansion of reiserfs partitions.  "
"Instructs reiserfs to assume that the device has I<number> blocks.  This "
"option is designed for use with devices which are under logical volume "
"management (LVM).  There is a special I<resizer> utility which can be "
"obtained from I<ftp://ftp.namesys.com/pub/reiserfsprogs>."
--
Man page: mount.8
Issue: man page is no longer available from the attr project: http://git.savannah.nongnu.org/cgit/attr.git/tree/man

msgid "Enable Extended User Attributes.  See the B<attr>(1)  manual page."
--
Man page: mount.8
Issue: Nowadays it is only called macOS

"For filesystems created by OpenStep (currently read only).  The same "
"filesystem type is also used by Mac OS X."
--
Man page: nologin.8
Issue: Missing markup for command name

"If the file /etc/nologin.txt exists, nologin displays its contents to the "
"user instead of the default message."

"The nologin command is part of the util-linux package and is available from "
"E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> "
"Linux Kernel Archive E<.UE .>"
--
Man page: nsenter.1
Issue: The second sentence is missing a »in B<clone>(2).«?

"Children will have a set of PID to process mappings separate from the "
"B<nsenter> process For further details, see B<pid_namespaces>(7)  and the "
"discussion of the B<CLONE_NEWPID> flag in B<nsenter> will fork by default if "
"changing the PID namespace, so that the new program and its children share "
"the same PID namespace and are visible to each other.  If B<--no-fork> is "
"used, the new program will be exec'ed without forking."
--
Man page: raw.8
Issue: Superfluous space after B<-q>

msgid "With B<-q> , specify that all bound raw devices should be queried."
--
Man page: rfkill.8
Issue: B<block id|type> → B<block >I<id|type>

msgid "B<block id>|B<type> [...]"

msgid "B<unblock id>|B<type> [...]"
--
Man page: rtcwake.8
Issue: to terminal → the terminal

"The suspend setup may be interrupted by active hardware; for example "
"wireless USB input devices that continue to send events for some fraction of "
"a second after the return key is pressed.  B<rtcwake> tries to avoid this "
"problem and it waits to terminal to settle down before entering a system "
"sleep."
--
Man page: runuser.1
Issue: Markup missing and copy → sync?
 
"Create pseudo-terminal for the session. The independent terminal provides "
"better security as user does not share terminal with the original session.  "
"This allow to avoid TIOCSTI ioctl terminal injection and another security "
"attacks against terminal file descriptors. The all session is also possible "
"to move to background (e.g., \"runuser --pty -u username -- command &\").  "
"If the pseudo-terminal is enabled then runuser command works as a proxy "
"between the sessions (copy stdin and stdout)."
--
Man page: script.1
Issue: B<scriptreplay (1)> → B<scriptreplay>(1)

"B<script> makes a typescript of everything on your terminal session.  The "
"terminal data are stored in raw form to the log file and information about "
"timing to another (optional) structured log file.  The timing log file is "
"necessary to replay the session later by B<scriptreplay (1)> and to store "
"additional information about the session."
--
Man page: script.1
Issue 1: or all the on → or all in the one
Issue 2: supports new timing → supports a new timing

"Since version 2.35 B<script> supports multiple streams and allows to log "
"input and output to separate files or all the one file.  This version also "
"supports new timing file which records additional information.  The command "
"B<scriptreplay --summary> then provides all the information."
--
Man page: script.1
Issue 1: itentifier → identifier
Issue 2: socond → second

"The first field is entry type itentifier ('I'nput, 'O'utput, 'H'eader, "
"'S'ignal).  The socond field is how much time elapsed since the previous "
"entry, and rest of the entry is type specific data."
--
Man page: script.1
Issue: Superfluous comma at the end

"B<csh>(1)  (for the I<history> mechanism), B<scriptreplay>(1), "
"B<scriptlive>(1),"
--
Man page: script.1
Issue: Missing markup for command name

"B<script> is primarily designed for interactive terminal sessions.  When "
"stdin is not a terminal (for example: B<echo foo | script>), then the "
"session can hang, because the interactive shell within the script session "
"misses EOF and B<script> has no clue when to close the session.  See the "
"B<NOTES> section for more information."

"The script command is part of the util-linux package and is available from "
"E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> "
"Linux Kernel Archive E<.UE .>"
msgstr ""
"Der Befehl B<script> ist Teil des Pakets util-linux, welches aus dem E<.UR "
"https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
"Kernel-Archiv E<.UE> heruntergeladen werden kann."
--
Man page: scriptlive.1
Issue 1: --log-io → B<--log-io>
Issue 2: --log-in → B<--log-in>

"B<Be careful!> Do not forget that the typescript may contains arbitrary "
"commands.  It is recommended to use B<\"scriptreplay --stream in --log-in "
"typescript\"> (or with --log-io instead of --log-in) to verify the "
"typescript before it is executed by B<scriptlive>(1)."
--
Man page: scriptlive.1
Issue 1: B<script (1)> → B<script>(1)
Issue 2: split the groff code correctly

"aliast to B<-t>, maintained for compatibility with B<script (1)> command "
"line options.  B<-d>,B< --divisor >I<number> Speed up the replay displaying "
"this I<number> of times.  The argument is a floating point number.  It's "
"called divisor because it divides the timings by this factor.  This option "
"overrides old-style arguments."
--
Man page: scriptlive.1
Issue: scriptlive → B<scriptlive>

"The scriptlive command is part of the util-linux package and is available "
"from E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/"
"> Linux Kernel Archive E<.UE .>"
--
Man page: scriptreplay.1
Issue: second »speed-up« should be actually »speed-down«

"If the third parameter or B<--divisor> is specified, it is used as a speed-"
"up multiplier.  For example, a speed-up of 2 makes B<scriptreplay> go twice "
"as fast, and a speed-up of 0.1 makes it go ten times slower than the "
"original session."
--
Man page: scriptreplay.1
Issue 1: aliast → alias
Issue 2: B<script (1)> → B<script>(1)

"aliast to B<-t>, maintained for compatibility with B<script (1)> command "
"line options."
--
Man page: scriptreplay.1
Issue: scriptreplay → B<scriptreplay>

"Specifies how to use CR (0x0D, carriage return) character from log files.  "
"The default mode is I<auto>, in this case CR is replaced with line break for "
"stdin log, because otherwise scriptreplay will overwrite the same line.  The "
"another modes are I<never> and I<always>."
--
Man page: scriptreplay.1
Issue: B<script>(1)) → B<script>(1)

"Display details about session recorded in the specified timing file and "
"exit.  The session has to be recorded by I<advanced> format (see "
"B<script>(1))  option B<--logging-format> for more details)."
--
Man page: scriptreplay.1
Issue 1: scriptreplay → B<scriptreplay>
Issue 2: --log-io → B<--log-io>

"Forces scriptreplay to print only specified stream.  The supported stream "
"types are I<in>, I<out>, I<signal>, or I<info>.  This option is recommended "
"for multi-stream logs (e.g., --log-io)  to print only specified data."
--
Man page: scriptreplay.1
Issue: output doesn't match the real output exactly

"% script --log-timing file.tm --log-out script.out\n"
"Script started, file is script.out\n"
"% ls\n"
"E<lt>etc, etcE<gt>\n"
"% exit\n"
"Script done, file is script.out\n"
--
Man page: setarch.8
Issue: arch → setarch?

msgid "B<arch> [options] [I<program> [I<argument>...]]"
--
Man page: setpriv.1
Issue: regual → regular

"Clears all the environment variables except TERM; initializes the "
"environment variables HOME, SHELL, USER, LOGNAME according to the user's "
"passwd entry; sets PATH to I</usr/local/bin:/bin:/usr/bin> for a regual user "
"and to I</usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin> for "
"root."
--
Man page: sfdisk.8
Issue: sfdisk → B<sfdisk>

"The optional I<path> specifies log file name. The log file contains "
"information about all read/write operations on the partition data. The word "
"\"@default\" as a I<path> forces sfdisk to use ~/sfdisk-E<lt>devnameE<gt>."
"move for the log.  The log is optional since v2.35."

"Specify sector size. This header is informative only and it is not used when "
"sfdisk creates a new partition table, in this case the real device specific "
"value is always used and sector size from the dump is ignored."
--
Man page: sfdisk.8
Issue 1: fsync → B<fsync>(2)
Issue 2: dara → data

"Use fsync system call after each write when move dara to a new location by "
"B<--move-data>."
--
Man page: sfdisk.8
Issue: partitions → partition

"Wipe filesystem, RAID and partition-table signatures from a newly created "
"partitions, in order to avoid possible collisions.  The argument I<when> can "
"be B<auto>, B<never> or B<always>.  When this option is not given, the "
"default is B<auto>, in which case signatures are wiped only when in "
"interactive mode and after confirmation by user.  In all cases detected "
"signatures are reported by warning messages after a new partition is "
"created.  See also B<wipefs>(8)  command."
--
Man page: sfdisk.8
Issue: Last sentence: If the ... then the

"The default value of I<start> is the first non-assigned sector aligned "
"according to device I/O limits.  The default start offset for the first "
"partition is 1 MiB.  The offset may be followed by the multiplicative "
"suffixes (KiB, MiB, GiB, TiB, PiB, EiB, ZiB and YiB) then the number is "
"interpreted as offset in bytes."
--
Man page: sfdisk.8
Issue: Last sentence: The offset … then → If the offset … then

"The first non-assigned sector aligned according to device I/O limits.  The "
"default start offset for the first partition is 1 MiB. The offset may be "
"followed by the multiplicative suffixes (KiB, MiB, GiB, TiB, PiB, EiB, ZiB "
"and YiB) then the number is interpreted as offset in bytes."
--
Man page: sfdisk.8
Issue: s ir → it

"I<bootable> is specified as [B<*>|B<->], with as default not-bootable.  The "
"value of this field is irrelevant for Linux - when Linux runs it has been "
"booted already - but ir might play a role for certain boot loaders and for "
"other operating systems."
--
Man page: su.1
Issue: Missing markup for command name

"The su command is part of the util-linux package and is available from E<.UR "
"https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
"Kernel Archive E<.UE .>"
--
Man page: swapon.8
Issue: Missing markup for nocow

"Swap files on Btrfs are supported since Linux 5.0 on files with nocow "
"attribute.  See the B<btrfs>(5)  manual page for more details."
--
Man page: swapon.8
Issue: Missing markup for command name

"The swapon command is part of the util-linux package and is available from "
"https://www.kernel.org/pub/linux/utils/util-linux/."
--
Man page: swapon.8
Issue: not be static → be dynamic

"B<swapon> may not work correctly when using a swap file with some versions "
"of B<btrfs>.  This is due to btrfs being a copy-on-write filesystem: the "
"file location may not be static and corruption can result.  Btrfs actively "
"disallows the use of swap files on its filesystems by refusing to map the "
"file."
--
Man page: umount.8
Issue: libmount → B<libmount>

"Since version 2.35 B<umount> command does not exit when user permissions are "
"inadequate by internal libmount security rules.  It drops suid permissions "
"and continue as regular non-root user. It allows to support use-cases where "
"root permissions are not necessary (e.g., fuse filesystems, user namespaces, "
"etc)."
--
Man page: unshare.1
Issue: = → B<=>?

msgid "B<-C>,B< --cgroup>[=I<file>]"
--
Man page: unshare.1
Issue: can not → cannot

"The proc and sysfs filesystems mounting as root in a user namespace have to "
"be restricted so that a less privileged user can not get more access to "
"sensitive files that a more privileged user made unavailable. In short the "
"rule for proc and sysfs is as close to a bind mount as possible."
--
Man page: wdctl.8
Issue: than → then

"If the device is already used or user has no permissions to read from the "
"device than B<wdctl> reads data from sysfs.  In this case information about "
"supported features (flags) might be missing."
--
Man page: wdctl.8
Issue: Missing markup for command name

"The write command is part of the util-linux package and is available from "
"https://www.kernel.org/pub/linux/utils/util-linux/."

Greetings

           Helge

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Errors in man pages of util-linux
  2020-05-03 19:13 Errors in man pages of util-linux Helge Kreutzmann
@ 2020-05-09 18:53 ` Michael Kerrisk
  2020-05-09 19:00   ` Helge Kreutzmann
  0 siblings, 1 reply; 7+ messages in thread
From: Michael Kerrisk @ 2020-05-09 18:53 UTC (permalink / raw)
  To: Helge Kreutzmann
  Cc: util-linux, Mario Blättermann, Karel Zak, Michael Kerrisk-manpages

[CC += Karel]

Hello Helge ;-),

I think no maintainer wants to deal with a 1000-line mail listing 100+
minor bugs. May I suggest making the maintainer's life a little easier
by breaking things up into pieces. For example, one mail per manual
page (which would be 43 mails by my count).  But maybe Karel has
another suggestion on how you could make his life easier.

With best regards,

Michael



On Sun, May 3, 2020 at 9:20 PM Helge Kreutzmann <debian@helgefjell.de> wrote:
>
> Dear util-linux maintainers.
> the manpage-l10n project maintains a large number of translations of
> man pages both from a large variety of sources (including util-linux) as
> well for a large variety of target languages.
>
> During their work translators notice different possible issues in the
> original (english) man pages. Sometiems this is a straightforward
> typo, sometimes a hard to read sentence, sometimes this is a
> convention not held up and sometimes we simply do not understand the
> original.
>
> We use several distributions as sources and update regularly (at
> least every 2 month). This means we are fairly recent (some
> distributions like archlinux also update frequently) but might miss
> the latest upstream version once a while, so the error might be
> already fixed. We apologize and ask you to close the issue immediately
> if this should be the case, but given the huge volume of projects and
> the very limited number of volunteers we are not able to double check
> each and every issue.
>
> Secondly we translators see the manpages in the neutral po format,
> i.e. converted and harmonized, but not the original source (be it man,
> groff, xml or other). So we cannot provide a true patch (where
> possible), but only an approximation which you need to convert into
> your source format.
>
> Finally the issues I'm reporting have accumulated over time and are
> not always discovered by me, so sometimes my description of the
> problem my be a bit limited - do not hesitate to ask so we can clarify
> them.
>
> I'm now reporting the errors for your project. If future reports should
> use another channel, please let me know.
>
> **
>
> Man page: adjtime_config.5
> Issue: Superfluous comma after "is"
>
> "The format of the adjtime file is, in ASCII."
> --
> Man page: adjtime_config.5
> Issue: hwckock → hwclock
>
> "The Hardware Clock is usually not very accurate.  However, much of its "
> "inaccuracy is completely predictable - it gains or loses the same amount of "
> "time every day.  This is called systematic drift.  The util hwclock keeps "
> "the file /etc/adjtime, that keeps some historical information.  For more "
> "details see \"B<The Adjust Function>\" and \"B<The Adjtime File>\" sections "
> "from B<hwckock>(8)  man page."
> --
> Man page: agetty.8
> Issue: agetty → B<agetty>
>
> "Display the current issue file (or other) on the current terminal and exit.  "
> "Use this option to review the current setting, it is not designed for any "
> "other purpose.  Note that output may use some default or incomplete "
> "information as proper output depends on terminal and agetty command line."
> --
> Man page: agetty.8
> Issue: I<inittab(5)> → B<inittab>(5)
>
> "This section shows examples for the process field of an entry in the I</etc/"
> "inittab> file.  You'll have to prepend appropriate values for the other "
> "fields.  See I<inittab(5)> for more details."
> --
> Man page: agetty.8
> Issue: commandline → command line
>
> "Some programs use \"--\" to indicate that the rest of the command line "
> "should not be interpreted as options.  Use this feature if available by "
> "passing \"--\" before the username gets passed by \\eu."
> --
> Man page: agetty.8
> Issue: agetty → B<agetty>
>
> "Since version 2.35 additional locations for issue file and directory are "
> "supported. If the default I</etc/issue> does not exist than agetty checks "
> "for I</run/issue> and I</run/issue.d>, thereafter for I</usr/lib/issue> and "
> "I</usr/lib/issue.d>.  The directory /etc is expected for host specific "
> "configuration, /run is expected for generated stuff and /usr/lib for static "
> "distribution maintained configuration."
> --
> Man page: agetty.8
> Issue: If not any configured → If no configured
>
> "Insert the IPv4 address of the specified network interface (for example: "
> "\\e4{eth0}).  If the I<interface> argument is not specified, then select the "
> "first fully configured (UP, non-LOCALBACK, RUNNING) interface.  If not any "
> "configured interface is found, fall back to the IP address of the machine's "
> "hostname."
> --
> Man page: blkid.8
> Issue: Missing markup from "mount"
>
> "This option forces B<blkid> to use udev when used for LABEL or UUID tokens "
> "in B<--match-token>. The goal is to provide output consistent with another "
> "utils (like mount, etc.)  on systems where the same tag is used for multiple "
> "devices."
> --
> Man page: blkzone.8
> Issue: Double full stop
>
> "Display the number of zones returned in the report or the range of sectors "
> "reset.."
> --
> Man page: chfn.1
> Issue: Missing markup for command name
>
> "The chfn command is part of the util-linux package and is available from "
> "https://www.kernel.org/pub/linux/utils/util-linux/."
> --
> Man page: chsh.1
> Issue: Missing markup for command name
>
> "The chsh command is part of the util-linux package and is available from "
> "https://www.kernel.org/pub/linux/utils/util-linux/."
> --
> Man page: col.1
> Issue: Missing markup for command name
>
> "The col command is part of the util-linux package and is available from E<."
> "UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
> "Kernel Archive E<.UE .>"
> --
> Man page: colcrt.1
> Issue: invisible → partially invisible
>
> "Causes all half-lines to be printed, effectively double spacing the output.  "
> "Normally, a minimal space output format is used which will suppress empty "
> "lines.  The program never suppresses two consecutive empty lines, however.  "
> "The B<-2> option is useful for sending output to the line printer when the "
> "output contains superscripts and subscripts which would otherwise be "
> "invisible."
> --
> Man page: colcrt.1
> Issue: B<'-'> → B<->
>
> "Should fold underlines onto blanks even with the B<'-'> option so that a "
> "true underline character would show."
> --
> Man page: colrm.1
> Issue: Missing markup for command name
>
> "The colrm command is part of the util-linux package and is available from E<."
> "UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
> "Kernel Archive E<.UE .>"
> --
> Man page: column.1
> Issue: Missing markup for command name
>
> "The column command is part of the util-linux package and is available from "
> "https://www.kernel.org/pub/linux/utils/util-linux/."
> --
> Man page: column.1
> Issue: Missing markup for command name
>
> "By default, the column command will merge multiple adjacent delimiters into "
> "a single delimiter when using the E<.Fl t> option; this option disables that "
> "behavior. This option is a Debian GNU/Linux extension."
> --
> Man page: fdisk.8
> Issue: Why is the full stop at the end in bold?
>
> "Specify the sector size of the disk.  Valid values are 512, 1024, 2048, and "
> "4096.  (Recent kernels know the sector size.  Use this option only on old "
> "kernels or to override the kernel's ideas.)  Since util-linux-2.17, B<fdisk> "
> "differentiates between logical and physical sector size.  This option "
> "changes both sector sizes to I<sectorsize>B<.>"
> --
> Man page: fdisk.8
> Issue: "when create" → "when creating"
>
> "Don't erase the begin of the first disk sector when create a new disk "
> "label.  This feature is supported for GPT and MBR."
> --
> Man page: fdisk.8
> Issue: Missing markup of file (names)
>
> "The I<device> is usually /dev/sda, /dev/sdb or so.  A device name refers to "
> "the entire disk.  Old systems without libata (a library used inside the "
> "Linux kernel to support ATA host controllers and devices) make a difference "
> "between IDE and SCSI disks.  In such cases the device name will be /dev/hd* "
> "(IDE) or /dev/sd* (SCSI)."
> --
> Man page: fdisk.8
> Issue: Content: Do need to mark partitions with »volume« and »volume
>                 header«
>
> "An IRIX/SGI disklabel can describe 16 partitions, the eleventh of which "
> "should be an entire `volume' partition, while the ninth should be labeled "
> "`volume header'.  The volume header will also cover the partition table, i."
> "e., it starts at block zero and extends by default over five cylinders.  The "
> "remaining space in the volume header may be used by header directory "
> "entries.  No partitions may overlap with the volume header.  Also do not "
> "change its type or make some filesystem on it, since you will lose the "
> "partition table.  Use this type of label only when working with Linux on "
> "IRIX/SGI machines or IRIX/SGI disks under Linux."
> --
> Man page: fdisk.8
> Issue: Missing markup of fdisk
>
> "Usually all goes well by default, and there are no problems if Linux is the "
> "only system on the disk.  However, if the disk has to be shared with other "
> "operating systems, it is often a good idea to let an fdisk from another "
> "operating system make at least one partition.  When Linux boots it looks at "
> "the partition table, and tries to deduce what (fake) geometry is required "
> "for good cooperation with other systems."
> --
> Man page: fsck.minix.8
> Issue: Replace \(en with Unicode U+2013 '-
>
> msgid "/dev/hda[1\\(en63]"
>
> msgid "/dev/hdb[1\\(en63]"
>
> msgid "/dev/sda[1\\(en15]"
>
> msgid "/dev/sdb[1\\(en15]"
> --
> Man page: fstrim.8
> Issue: Markup of fstrim
>
> "Minimum contiguous free range to discard, in bytes. (This value is "
> "internally rounded up to a multiple of the filesystem block size.)  Free "
> "ranges smaller than this will be ignored and fstrim will adjust the minimum "
> "if it's smaller than the device's minimum, and report that (fstrim_range."
> "minlen) back to userspace.  By increasing this value, the fstrim operation "
> "will complete more quickly for filesystems with badly fragmented freespace, "
> "although not all blocks will be discarded.  The default value is zero, "
> "discarding every free block."
> --
> Man page: getopt.1
> Issue: Missing comma when enumarating Shells (after sh)
>
> "Set quoting conventions to those of I<shell>.  If the B<-s> option is not "
> "given, the E<.SM BASH> conventions are used.  Valid arguments are currently "
> "'B<sh>' 'B<bash>', 'B<csh>', and 'B<tcsh>'."
> --
> Man page: hardlink.1
> Issue: Markup up of command options missing
>
> "Among equal files, keep the oldest file (least recent modification time). By "
> "default, the newest file is kept. If --maximize or --minimize is specified, "
> "the link count has a higher precedence than the time of modification."
>
> "A regular expression to include files. If the option --exclude has been "
> "given, this option re-includes files which would otherwise be excluded. If "
> "the option is used without --exclude, only files matched by the pattern are "
> "included."
>
> "B<hardlink> , as of version 0.3 RC1, improperly calculates the amount of "
> "space saved if the option --respect-name is specified. In previous versions, "
> "the amount was wrong in almost all other cases as well."
> --
> Man page: hardlink.1
> Issue: Markup up of "hardlink" missing
>
> "B<hardlink> assumes that the trees it operates on do not change during "
> "operation. If a tree does change, the result is undefined and potentially "
> "dangerous. For example, if a regular file is replaced by a device, hardlink "
> "may start reading from the device. If a component of a path is replaced by a "
> "symbolic link or file permissions change, security may be compromised. Do "
> "not run hardlink on a changing tree or on a tree controlled by another user."
>
> "The program hardlink and this manpage have been written by Julian Andres "
> "Klode, and are licensed under the MIT license. See the code of hardlink for "
> "further information."
> --
> Man page: hexdump.1
> Issue: When markup is used (B<>), no extra quoting is necessary
>
> "I<Canonical hex+ASCII display>.  Display the input offset in hexadecimal, "
> "followed by sixteen space-separated, two-column, hexadecimal bytes, followed "
> "by the same sixteen bytes in B<%_p> format enclosed in 'B<|>' characters."
>
> "Output characters in the default character set.  Non-printing characters are "
> "displayed as a single 'B<\\&.>'."
> --
> Man page: hexdump.1
> Issue: Missing closing bracket (for fprintf)
>
> "The format is required and must be surrounded by double quote (\" \") "
> "marks.  It is interpreted as a fprintf-style format string (see "
> "B<fprintf>(3), with the following exceptions:"
> --
> Man page: hexdump.1
> Issue: identical → almost identical
>
> "Identical to the B<\\&_a> conversion string except that it is only performed "
> "once, when all of the input data has been processed."
> --
> Man page: hexdump.1
> Issue: Missing mark up for "hexdump"
>
> "When put at the end of a format specifier, hexdump highlights the respective "
> "string with the color specified.  Conditions, if present, are evaluated "
> "prior to highlighting."
>
> "The hexdump command is part of the util-linux package and is available from "
> "E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> "
> "Linux Kernel Archive E<.UE .>"
> --
> Man page: hexdump.1
> Issue: Mixed markup (B<>) and quoting for conversion characters
>
> "Further output by such format strings is replaced by an equivalent number of "
> "spaces.  An equivalent number of spaces is defined as the number of spaces "
> "output by an B<s> conversion character with the same field width and "
> "precision as the original conversion character or conversion string but with "
> "any 'B<\\&+>', \\' \\', 'B<\\&#>' conversion flag characters removed, and "
> "referencing a NULL string."
> --
> Man page: hexdump.1
> Issue: ``|'' → B<|>
>
> "E<.Em Canonical hex+ASCII display>.  Display the input offset in "
> "hexadecimal, followed by sixteen space-separated, two column, hexadecimal "
> "bytes, followed by the same sixteen bytes in %_p format enclosed in ``|'' "
> "characters."
> --
> Man page: hwclock.8
> Issue: Markup up correct? (around option)
>
> "Use\\ B<--verbose>.  The\\ B<\\%--debug\\ >option has been deprecated and "
> "may be repurposed or removed in a future release."
> --
> Man page: hwclock.8
> Issue: Replace comma by full stop
>
> "Update the Hardware Clock's drift factor in I</etc/adjtime>.  It can only be "
> "used with B<--set> or B<\\%--systohc>,"
> --
> Man page: hwclock.8
> Issue: Paragraph hard to read
>
> "Significantly increased system shutdown times (as of v2.31 when not using B<"
> "\\%--update-drift> the RTC is not read)."
> --
> Man page: hwclock.8
> Issue: date-time → date time??
>
> msgid "There are two types of date-time clocks:"
> --
> Man page: hwclock.8
> Issue: Spaces in and around the final B<>
>
> "Some Linux distributions attempt to automatically calculate the System Clock "
> "drift with B<\\%adjtimex>'s compare operation.  Trying to correct one "
> "drifting clock by using another drifting clock as a reference is akin to a "
> "dog trying to catch its own tail.  Success may happen eventually, but great "
> "effort and frustration will likely precede it.  This automation may yield an "
> "improvement over no configuration, but expecting optimum results would be in "
> "error.  A better choice for manual configuration would be B<\\%adjtimex>'sB< "
> "--log >options."
> --
> Man page: hwclock.8
> Issue: Missing Space at beginning of line
>
> msgid "TheI< System Clock >time must be correct at shutdown!"
> --
> Man page: libblkid.3
> Issue: evaluate → determine?
>
> "The high-level part of the library supports two methods to evaluate LABEL/"
> "UUID.  It reads information directly from a block device or read information "
> "from /dev/disk/by-* udev symlinks.  The udev is preferred method by default."
> --
> Man page: libblkid.3
> Issue: Missing markup for command name
>
> "libblkid is part of the util-linux package since version 2.15 and is "
> "available from https://www.kernel.org/pub/linux/utils/util-linux/."
> --
> Man page: logger.1
> Issue: Superfluous space before full stop
>
> "Use datagrams (UDP) only.  By default the connection is tried to the syslog "
> "port defined in /etc/services, which is often 514 ."
> --
> Man page: logger.1
> Issue: Missing markup of command name
>
> "Log the PID of the logger process with each line.  When the optional "
> "argument I<id> is specified, then it is used instead of the logger command's "
> "PID.  The use of B<--id=$$> (PPID) is recommended in scripts that send "
> "several messages."
>
> "Write a systemd journal entry.  The entry is read from the given I<file>, "
> "when specified, otherwise from standard input.  Each line must begin with a "
> "field that is accepted by journald; see B<systemd.journal-fields>(7)  for "
> "details.  The use of a MESSAGE_ID field is generally a good idea, as it "
> "makes finding entries easy.  Examples:"
>
> "Use the specified I<port>.  When this option is not specified, the port "
> "defaults to syslog for udp and to syslog-conn for tcp connections."
>
> "Most receivers accept messages larger than 1KiB over any type of syslog "
> "protocol.  As such, the B<--size> option affects logger in all cases (not "
> "only when B<--rfc5424> was used)."
> --
> Man page: logger.1
> Issue: or the journal → to the journal?
>
> "Causes everything to be done except for writing the log message to the "
> "system log, and removing the connection or the journal.  This option can be "
> "used together with B<--stderr> for testing purposes."
> --
> Man page: logger.1
> Issue: Missing markup of parameters
>
> "B<logger> currently generates the B<timeQuality> standardized element only.  "
> "RFC 5424 also describes the elements B<origin> (with parameters ip, "
> "enterpriseId, software and swVersion) and B<meta> (with parameters "
> "sequenceId, sysUpTime and language).  These element IDs may be specified "
> "without the B<@>I<digits> suffix."
> --
> Man page: logger.1
> Issue: Missing markup file names, command names etc.
>
> "Print errors about Unix socket connections.  The I<mode> can be a value of "
> "B<off>, B<on>, or B<auto>.  When the mode is auto logger will detect if the "
> "init process is systemd, and if so assumption is made /dev/log can be used "
> "early at boot.  Other init systems lack of /dev/log will not cause errors "
> "that is identical with messaging using B<openlog>(3)  system call.  The "
> "B<logger>(1)  before version 2.26 used openlog, and hence was unable to "
> "detected loss of messages sent to Unix sockets."
> --
> Man page: logger.1
> Issue: The »to« marks a range inside a list. Shouldn't be bold.
>
> msgid "B<  to>"
> --
> Man page: logger.1
> Issue: Missing markup for command name
>
> "The logger command is part of the util-linux package and is available from "
> "E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> "
> "Linux Kernel Archive E<.UE .>"
> --
> Man page: login.1
> Issue: Missing full stop
>
> "The default is to check I</etc\\:/hushlogins> and if it does not exist then "
> "I<~/.hushlogin>"
>
> "If set, it will be used to define the PATH environment variable when a "
> "regular user logs in.  The default value is I</usr\\:/local\\:/bin:\\:/bin:"
> "\\:/usr\\:/bin>"
> --
> Man page: login.1
> Issue: Missing markup for lastlog
>
> "Highest user ID number for which the lastlog entries should be updated.  As "
> "higher user IDs are usually tracked by remote user identity and "
> "authentication services there is no need to create a huge sparse lastlog "
> "file for them.  No LASTLOG_UID_MAX option present in the configuration means "
> "that there is no user ID limit for writing lastlog entries."
> --
> Man page: login.1
> Issue: Missing markup for command name
>
> "A recursive login, as used to be possible in the good old days, no longer "
> "works; for most purposes B<su>(1)  is a satisfactory substitute.  Indeed, "
> "for security reasons, login does a vhangup() system call to remove any "
> "possible listening processes on the tty.  This is to avoid password "
> "sniffing.  If one uses the command B<login>, then the surrounding shell gets "
> "killed by vhangup() because it's no longer the true owner of the tty.  This "
> "can be avoided by using B<exec login> in a top-level shell or xterm."
> --
> Man page: login.1
> Issue: Missing markup for command name
>
> "The login command is part of the util-linux package and is available from E<."
> "UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
> "Kernel Archive E<.UE .>"
> --
> Man page: lscpu.1
> Issue: superfluous quoting around B<>
>
> "When specifying the I<list> argument, the string of option, equal sign (=), "
> "and I<list> must not contain any blanks or other whitespace.  Examples: 'B<-"
> "C=NAME,ONE-SIZE>' or 'B<--caches=NAME,ONE-SIZE>'."
> --
> Man page: lslogins.1
> Issue: specify → specified, than → then
>
> "Note that relation between user and group may be invisible for primary group "
> "if the user is not explicitly specify as group member (e.g., in /etc/group). "
> "If the command lslogins scans for groups than it uses groups database only, "
> "and user database with primary GID is not used at all."
> --
> Man page: lslogins.1
> Issue: IDS → IDs
>
> "Only show data of users with a login specified in I<logins> (user names or "
> "user IDS).  More than one login may be specified; the list has to be comma-"
> "separated.  The unknown login names are ignored."
> --
> Man page: lslogins.1
> Issue: Markup and closing bracket are wrongly interleaved
>
> msgid "Display information related to login by password (see also B<-afL).>"
> --
> Man page: lsmem.1
> Issue: output compatible → output is compatible
>
> "The default output compatible with original implementation from s390-tools, "
> "but it's strongly recommended to avoid using default outputs in your "
> "scripts.  Always explicitly define expected columns by using the B<--output> "
> "option together with a columns list in environments where a stable output is "
> "required."
> --
> Man page: lsmem.1
> Issue: First sentence: Broken?
>
> "The B<lsmem> command lists a new memory range always when the current memory "
> "block distinguish from the previous block by some output column.  This "
> "default behavior is possible to override by the B<--split> option (e.g., "
> "B<lsmem --split=ZONES>).  The special word \"none\" may be used to ignore "
> "all differences between memory blocks and to create as large as possible "
> "continuous ranges.  The opposite semantic is B<--all> to list individual "
> "memory blocks."
> --
> Man page: lsns.8
> Issue: 2nd sentence broken wording
>
> "B<NSFS> column, printed when B<net> is specified for B<--type> option, is "
> "special; it uses multi-line cells.  Use the option B<--nowrap> is for "
> "switching to \",\" separated single-line representation."
> --
> Man page: mkswap.8
> Issue: No such section in swapon.8
>
> "Please read notes from B<swapon>(8)  about B<the swap file use restrictions> "
> "(holes, preallocation and copy-on-write issues)."
> --
> Man page: mount.8
> Issue: bythe → by the
>
> "The same filesystem may be mounted more than once, and in some cases (e.g., "
> "network filesystems) the same filesystem may be mounted on the same "
> "mountpoint more times. The mount command does not implement any policy to "
> "control this behavior. All behavior is controlled by the kernel and it is "
> "usually specific to the filesystem driver. The exception is B<--all>, in "
> "this case already mounted filesystems are ignored (see B<--all> below for "
> "more details)."
> --
> Man page: mount.8
> Issue: disables B<--options-source-force> → enables!
>
> "Source of default options.  I<source> is comma separated list of B<fstab>, "
> "B<mtab> and B<disable>.  B<disable> disables B<fstab> and B<mtab> and "
> "disables B<--options-source-force>.  Default value is B<fstab,mtab>."
> --
> Man page: mount.8
> Issue: The wording is rather unusual english, improve?
>
> "Note that specify B<-w> on command line forces B<mount> command to never try "
> "read-only mount on write-protected devices. The default is try read-only if "
> "the previous mount syscall with read-write flags failed."
> --
> Man page: mount.8
> Issue: Does this include other executable like scripts?
>
> msgid "Permit execution of binaries."
> --
> Man page: mount.8
> Issue: maintain → maintaining
>
> "The same as B<X-*> options, but stored permanently in the user space. It "
> "means the options are also available for umount or another operations.  Note "
> "that maintain mount options in user space is tricky, because it's necessary "
> "use libmount based tools and there is no guarantee that the options will be "
> "always available (for example after a move mount operation or in unshared "
> "namespace)."
> --
> Man page: mount.8
> Issue: mount → B<mount>
>
> "Allow to make a target directory (mountpoint) if it does not exit yet.  The "
> "optional argument I<mode> specifies the filesystem access mode used for "
> "B<mkdir>(2)  in octal notation.  The default mode is 0755.  This "
> "functionality is supported only for root users or when mount executed "
> "without suid permissions.  The option is also supported as x-mount.mkdir, "
> "this notation is deprecated since v2.30."
> --
> Man page: mount.8
> Issue: URL does not allow login (2019-01-29)
>
> "A remount option which permits online expansion of reiserfs partitions.  "
> "Instructs reiserfs to assume that the device has I<number> blocks.  This "
> "option is designed for use with devices which are under logical volume "
> "management (LVM).  There is a special I<resizer> utility which can be "
> "obtained from I<ftp://ftp.namesys.com/pub/reiserfsprogs>."
> --
> Man page: mount.8
> Issue: man page is no longer available from the attr project: http://git.savannah.nongnu.org/cgit/attr.git/tree/man
>
> msgid "Enable Extended User Attributes.  See the B<attr>(1)  manual page."
> --
> Man page: mount.8
> Issue: Nowadays it is only called macOS
>
> "For filesystems created by OpenStep (currently read only).  The same "
> "filesystem type is also used by Mac OS X."
> --
> Man page: nologin.8
> Issue: Missing markup for command name
>
> "If the file /etc/nologin.txt exists, nologin displays its contents to the "
> "user instead of the default message."
>
> "The nologin command is part of the util-linux package and is available from "
> "E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> "
> "Linux Kernel Archive E<.UE .>"
> --
> Man page: nsenter.1
> Issue: The second sentence is missing a »in B<clone>(2).«?
>
> "Children will have a set of PID to process mappings separate from the "
> "B<nsenter> process For further details, see B<pid_namespaces>(7)  and the "
> "discussion of the B<CLONE_NEWPID> flag in B<nsenter> will fork by default if "
> "changing the PID namespace, so that the new program and its children share "
> "the same PID namespace and are visible to each other.  If B<--no-fork> is "
> "used, the new program will be exec'ed without forking."
> --
> Man page: raw.8
> Issue: Superfluous space after B<-q>
>
> msgid "With B<-q> , specify that all bound raw devices should be queried."
> --
> Man page: rfkill.8
> Issue: B<block id|type> → B<block >I<id|type>
>
> msgid "B<block id>|B<type> [...]"
>
> msgid "B<unblock id>|B<type> [...]"
> --
> Man page: rtcwake.8
> Issue: to terminal → the terminal
>
> "The suspend setup may be interrupted by active hardware; for example "
> "wireless USB input devices that continue to send events for some fraction of "
> "a second after the return key is pressed.  B<rtcwake> tries to avoid this "
> "problem and it waits to terminal to settle down before entering a system "
> "sleep."
> --
> Man page: runuser.1
> Issue: Markup missing and copy → sync?
>
> "Create pseudo-terminal for the session. The independent terminal provides "
> "better security as user does not share terminal with the original session.  "
> "This allow to avoid TIOCSTI ioctl terminal injection and another security "
> "attacks against terminal file descriptors. The all session is also possible "
> "to move to background (e.g., \"runuser --pty -u username -- command &\").  "
> "If the pseudo-terminal is enabled then runuser command works as a proxy "
> "between the sessions (copy stdin and stdout)."
> --
> Man page: script.1
> Issue: B<scriptreplay (1)> → B<scriptreplay>(1)
>
> "B<script> makes a typescript of everything on your terminal session.  The "
> "terminal data are stored in raw form to the log file and information about "
> "timing to another (optional) structured log file.  The timing log file is "
> "necessary to replay the session later by B<scriptreplay (1)> and to store "
> "additional information about the session."
> --
> Man page: script.1
> Issue 1: or all the on → or all in the one
> Issue 2: supports new timing → supports a new timing
>
> "Since version 2.35 B<script> supports multiple streams and allows to log "
> "input and output to separate files or all the one file.  This version also "
> "supports new timing file which records additional information.  The command "
> "B<scriptreplay --summary> then provides all the information."
> --
> Man page: script.1
> Issue 1: itentifier → identifier
> Issue 2: socond → second
>
> "The first field is entry type itentifier ('I'nput, 'O'utput, 'H'eader, "
> "'S'ignal).  The socond field is how much time elapsed since the previous "
> "entry, and rest of the entry is type specific data."
> --
> Man page: script.1
> Issue: Superfluous comma at the end
>
> "B<csh>(1)  (for the I<history> mechanism), B<scriptreplay>(1), "
> "B<scriptlive>(1),"
> --
> Man page: script.1
> Issue: Missing markup for command name
>
> "B<script> is primarily designed for interactive terminal sessions.  When "
> "stdin is not a terminal (for example: B<echo foo | script>), then the "
> "session can hang, because the interactive shell within the script session "
> "misses EOF and B<script> has no clue when to close the session.  See the "
> "B<NOTES> section for more information."
>
> "The script command is part of the util-linux package and is available from "
> "E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> "
> "Linux Kernel Archive E<.UE .>"
> msgstr ""
> "Der Befehl B<script> ist Teil des Pakets util-linux, welches aus dem E<.UR "
> "https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
> "Kernel-Archiv E<.UE> heruntergeladen werden kann."
> --
> Man page: scriptlive.1
> Issue 1: --log-io → B<--log-io>
> Issue 2: --log-in → B<--log-in>
>
> "B<Be careful!> Do not forget that the typescript may contains arbitrary "
> "commands.  It is recommended to use B<\"scriptreplay --stream in --log-in "
> "typescript\"> (or with --log-io instead of --log-in) to verify the "
> "typescript before it is executed by B<scriptlive>(1)."
> --
> Man page: scriptlive.1
> Issue 1: B<script (1)> → B<script>(1)
> Issue 2: split the groff code correctly
>
> "aliast to B<-t>, maintained for compatibility with B<script (1)> command "
> "line options.  B<-d>,B< --divisor >I<number> Speed up the replay displaying "
> "this I<number> of times.  The argument is a floating point number.  It's "
> "called divisor because it divides the timings by this factor.  This option "
> "overrides old-style arguments."
> --
> Man page: scriptlive.1
> Issue: scriptlive → B<scriptlive>
>
> "The scriptlive command is part of the util-linux package and is available "
> "from E<.UR https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/"
> "> Linux Kernel Archive E<.UE .>"
> --
> Man page: scriptreplay.1
> Issue: second »speed-up« should be actually »speed-down«
>
> "If the third parameter or B<--divisor> is specified, it is used as a speed-"
> "up multiplier.  For example, a speed-up of 2 makes B<scriptreplay> go twice "
> "as fast, and a speed-up of 0.1 makes it go ten times slower than the "
> "original session."
> --
> Man page: scriptreplay.1
> Issue 1: aliast → alias
> Issue 2: B<script (1)> → B<script>(1)
>
> "aliast to B<-t>, maintained for compatibility with B<script (1)> command "
> "line options."
> --
> Man page: scriptreplay.1
> Issue: scriptreplay → B<scriptreplay>
>
> "Specifies how to use CR (0x0D, carriage return) character from log files.  "
> "The default mode is I<auto>, in this case CR is replaced with line break for "
> "stdin log, because otherwise scriptreplay will overwrite the same line.  The "
> "another modes are I<never> and I<always>."
> --
> Man page: scriptreplay.1
> Issue: B<script>(1)) → B<script>(1)
>
> "Display details about session recorded in the specified timing file and "
> "exit.  The session has to be recorded by I<advanced> format (see "
> "B<script>(1))  option B<--logging-format> for more details)."
> --
> Man page: scriptreplay.1
> Issue 1: scriptreplay → B<scriptreplay>
> Issue 2: --log-io → B<--log-io>
>
> "Forces scriptreplay to print only specified stream.  The supported stream "
> "types are I<in>, I<out>, I<signal>, or I<info>.  This option is recommended "
> "for multi-stream logs (e.g., --log-io)  to print only specified data."
> --
> Man page: scriptreplay.1
> Issue: output doesn't match the real output exactly
>
> "% script --log-timing file.tm --log-out script.out\n"
> "Script started, file is script.out\n"
> "% ls\n"
> "E<lt>etc, etcE<gt>\n"
> "% exit\n"
> "Script done, file is script.out\n"
> --
> Man page: setarch.8
> Issue: arch → setarch?
>
> msgid "B<arch> [options] [I<program> [I<argument>...]]"
> --
> Man page: setpriv.1
> Issue: regual → regular
>
> "Clears all the environment variables except TERM; initializes the "
> "environment variables HOME, SHELL, USER, LOGNAME according to the user's "
> "passwd entry; sets PATH to I</usr/local/bin:/bin:/usr/bin> for a regual user "
> "and to I</usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin> for "
> "root."
> --
> Man page: sfdisk.8
> Issue: sfdisk → B<sfdisk>
>
> "The optional I<path> specifies log file name. The log file contains "
> "information about all read/write operations on the partition data. The word "
> "\"@default\" as a I<path> forces sfdisk to use ~/sfdisk-E<lt>devnameE<gt>."
> "move for the log.  The log is optional since v2.35."
>
> "Specify sector size. This header is informative only and it is not used when "
> "sfdisk creates a new partition table, in this case the real device specific "
> "value is always used and sector size from the dump is ignored."
> --
> Man page: sfdisk.8
> Issue 1: fsync → B<fsync>(2)
> Issue 2: dara → data
>
> "Use fsync system call after each write when move dara to a new location by "
> "B<--move-data>."
> --
> Man page: sfdisk.8
> Issue: partitions → partition
>
> "Wipe filesystem, RAID and partition-table signatures from a newly created "
> "partitions, in order to avoid possible collisions.  The argument I<when> can "
> "be B<auto>, B<never> or B<always>.  When this option is not given, the "
> "default is B<auto>, in which case signatures are wiped only when in "
> "interactive mode and after confirmation by user.  In all cases detected "
> "signatures are reported by warning messages after a new partition is "
> "created.  See also B<wipefs>(8)  command."
> --
> Man page: sfdisk.8
> Issue: Last sentence: If the ... then the
>
> "The default value of I<start> is the first non-assigned sector aligned "
> "according to device I/O limits.  The default start offset for the first "
> "partition is 1 MiB.  The offset may be followed by the multiplicative "
> "suffixes (KiB, MiB, GiB, TiB, PiB, EiB, ZiB and YiB) then the number is "
> "interpreted as offset in bytes."
> --
> Man page: sfdisk.8
> Issue: Last sentence: The offset … then → If the offset … then
>
> "The first non-assigned sector aligned according to device I/O limits.  The "
> "default start offset for the first partition is 1 MiB. The offset may be "
> "followed by the multiplicative suffixes (KiB, MiB, GiB, TiB, PiB, EiB, ZiB "
> "and YiB) then the number is interpreted as offset in bytes."
> --
> Man page: sfdisk.8
> Issue: s ir → it
>
> "I<bootable> is specified as [B<*>|B<->], with as default not-bootable.  The "
> "value of this field is irrelevant for Linux - when Linux runs it has been "
> "booted already - but ir might play a role for certain boot loaders and for "
> "other operating systems."
> --
> Man page: su.1
> Issue: Missing markup for command name
>
> "The su command is part of the util-linux package and is available from E<.UR "
> "https://\\:www.kernel.org\\:/pub\\:/linux\\:/utils\\:/util-linux/> Linux "
> "Kernel Archive E<.UE .>"
> --
> Man page: swapon.8
> Issue: Missing markup for nocow
>
> "Swap files on Btrfs are supported since Linux 5.0 on files with nocow "
> "attribute.  See the B<btrfs>(5)  manual page for more details."
> --
> Man page: swapon.8
> Issue: Missing markup for command name
>
> "The swapon command is part of the util-linux package and is available from "
> "https://www.kernel.org/pub/linux/utils/util-linux/."
> --
> Man page: swapon.8
> Issue: not be static → be dynamic
>
> "B<swapon> may not work correctly when using a swap file with some versions "
> "of B<btrfs>.  This is due to btrfs being a copy-on-write filesystem: the "
> "file location may not be static and corruption can result.  Btrfs actively "
> "disallows the use of swap files on its filesystems by refusing to map the "
> "file."
> --
> Man page: umount.8
> Issue: libmount → B<libmount>
>
> "Since version 2.35 B<umount> command does not exit when user permissions are "
> "inadequate by internal libmount security rules.  It drops suid permissions "
> "and continue as regular non-root user. It allows to support use-cases where "
> "root permissions are not necessary (e.g., fuse filesystems, user namespaces, "
> "etc)."
> --
> Man page: unshare.1
> Issue: = → B<=>?
>
> msgid "B<-C>,B< --cgroup>[=I<file>]"
> --
> Man page: unshare.1
> Issue: can not → cannot
>
> "The proc and sysfs filesystems mounting as root in a user namespace have to "
> "be restricted so that a less privileged user can not get more access to "
> "sensitive files that a more privileged user made unavailable. In short the "
> "rule for proc and sysfs is as close to a bind mount as possible."
> --
> Man page: wdctl.8
> Issue: than → then
>
> "If the device is already used or user has no permissions to read from the "
> "device than B<wdctl> reads data from sysfs.  In this case information about "
> "supported features (flags) might be missing."
> --
> Man page: wdctl.8
> Issue: Missing markup for command name
>
> "The write command is part of the util-linux package and is available from "
> "https://www.kernel.org/pub/linux/utils/util-linux/."
>
> Greetings
>
>            Helge
>
> --
>       Dr. Helge Kreutzmann                     debian@helgefjell.de
>            Dipl.-Phys.                   http://www.helgefjell.de/debian.php
>         64bit GNU powered                     gpg signed mail preferred
>            Help keep free software "libre": http://www.ffii.de/

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Errors in man pages of util-linux
  2020-05-09 18:53 ` Michael Kerrisk
@ 2020-05-09 19:00   ` Helge Kreutzmann
  2020-05-09 19:05     ` Michael Kerrisk
  0 siblings, 1 reply; 7+ messages in thread
From: Helge Kreutzmann @ 2020-05-09 19:00 UTC (permalink / raw)
  To: Michael Kerrisk; +Cc: util-linux, Mario Blättermann, Karel Zak


[-- Attachment #1: Type: text/plain, Size: 927 bytes --]

Hello Michael,
On Sat, May 09, 2020 at 08:53:31PM +0200, Michael Kerrisk wrote:
> Hello Helge ;-),
> 
> I think no maintainer wants to deal with a 1000-line mail listing 100+
> minor bugs. May I suggest making the maintainer's life a little easier
> by breaking things up into pieces. For example, one mail per manual
> page (which would be 43 mails by my count).  But maybe Karel has
> another suggestion on how you could make his life easier.

Sure, I can do this, it did not see this mentioned for reporting bugs
in util-linux, hence I did not do so.

Will do so soon, probably tomorrow.

Greetings

          Helge
-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Errors in man pages of util-linux
  2020-05-09 19:00   ` Helge Kreutzmann
@ 2020-05-09 19:05     ` Michael Kerrisk
  2020-05-11  9:27       ` Karel Zak
  0 siblings, 1 reply; 7+ messages in thread
From: Michael Kerrisk @ 2020-05-09 19:05 UTC (permalink / raw)
  To: Helge Kreutzmann
  Cc: util-linux, Mario Blättermann, Karel Zak, Michael Kerrisk-manpages

On Sat, May 9, 2020 at 9:00 PM Helge Kreutzmann <debian@helgefjell.de> wrote:
>
> Hello Michael,
> On Sat, May 09, 2020 at 08:53:31PM +0200, Michael Kerrisk wrote:
> > Hello Helge ;-),
> >
> > I think no maintainer wants to deal with a 1000-line mail listing 100+
> > minor bugs. May I suggest making the maintainer's life a little easier
> > by breaking things up into pieces. For example, one mail per manual
> > page (which would be 43 mails by my count).  But maybe Karel has
> > another suggestion on how you could make his life easier.
>
> Sure, I can do this, it did not see this mentioned for reporting bugs
> in util-linux, hence I did not do so.
>
> Will do so soon, probably tomorrow.

Maybe hold off for a day or three before investing effort on this.
Karel may have a better idea than mine re his preferred method of
reporting.

Thanks,

Michael

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Errors in man pages of util-linux
  2020-05-09 19:05     ` Michael Kerrisk
@ 2020-05-11  9:27       ` Karel Zak
  2020-05-11  9:50         ` Helge Kreutzmann
  2020-05-11 10:32         ` Michael Kerrisk (man-pages)
  0 siblings, 2 replies; 7+ messages in thread
From: Karel Zak @ 2020-05-11  9:27 UTC (permalink / raw)
  To: Michael Kerrisk; +Cc: Helge Kreutzmann, util-linux, Mario Blättermann

On Sat, May 09, 2020 at 09:05:50PM +0200, Michael Kerrisk wrote:
> On Sat, May 9, 2020 at 9:00 PM Helge Kreutzmann <debian@helgefjell.de> wrote:
> >
> > Hello Michael,
> > On Sat, May 09, 2020 at 08:53:31PM +0200, Michael Kerrisk wrote:
> > > Hello Helge ;-),

Thanks for your report Helge.

> > > I think no maintainer wants to deal with a 1000-line mail listing 100+
> > > minor bugs. May I suggest making the maintainer's life a little easier
> > > by breaking things up into pieces. For example, one mail per manual
> > > page (which would be 43 mails by my count).  But maybe Karel has
> > > another suggestion on how you could make his life easier.

Well, that's simple, send patches ;-)))

> > Sure, I can do this, it did not see this mentioned for reporting bugs
> > in util-linux, hence I did not do so.
> >
> > Will do so soon, probably tomorrow.

I think Michael is right. If we will split it then more volunteers can 
work on it and it will be more easy to maintain all the task.

> Maybe hold off for a day or three before investing effort on this.
> Karel may have a better idea than mine re his preferred method of
> reporting.

I have no another idea (maybe github issue(s), but it will be invisible
for many contributors).
 
  Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Errors in man pages of util-linux
  2020-05-11  9:27       ` Karel Zak
@ 2020-05-11  9:50         ` Helge Kreutzmann
  2020-05-11 10:32         ` Michael Kerrisk (man-pages)
  1 sibling, 0 replies; 7+ messages in thread
From: Helge Kreutzmann @ 2020-05-11  9:50 UTC (permalink / raw)
  To: Karel Zak; +Cc: Michael Kerrisk, util-linux, Mario Blättermann


[-- Attachment #1: Type: text/plain, Size: 2018 bytes --]

Hello Karel,
On Mon, May 11, 2020 at 11:27:34AM +0200, Karel Zak wrote:
> On Sat, May 09, 2020 at 09:05:50PM +0200, Michael Kerrisk wrote:
> > On Sat, May 9, 2020 at 9:00 PM Helge Kreutzmann <debian@helgefjell.de> wrote:
> > > On Sat, May 09, 2020 at 08:53:31PM +0200, Michael Kerrisk wrote:
> > > > Hello Helge ;-),
> 
> Thanks for your report Helge.
> 
> > > > I think no maintainer wants to deal with a 1000-line mail listing 100+
> > > > minor bugs. May I suggest making the maintainer's life a little easier
> > > > by breaking things up into pieces. For example, one mail per manual
> > > > page (which would be 43 mails by my count).  But maybe Karel has
> > > > another suggestion on how you could make his life easier.
> 
> Well, that's simple, send patches ;-)))
> 
> > > Sure, I can do this, it did not see this mentioned for reporting bugs
> > > in util-linux, hence I did not do so.
> > >
> > > Will do so soon, probably tomorrow.
> 
> I think Michael is right. If we will split it then more volunteers can 
> work on it and it will be more easy to maintain all the task.

Right, will do so, but due to other commitments it might take a few
days (hopefully faster).

Also Mario has send me privately some suggestions for fixing which I
will integrate.

> > Maybe hold off for a day or three before investing effort on this.
> > Karel may have a better idea than mine re his preferred method of
> > reporting.
> 
> I have no another idea (maybe github issue(s), but it will be invisible
> for many contributors).

I personally prefer a mail interface and not yet another account, so
I'll send the issues the the recipients of this e-mail soon.

Greetings

          Helge
-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Errors in man pages of util-linux
  2020-05-11  9:27       ` Karel Zak
  2020-05-11  9:50         ` Helge Kreutzmann
@ 2020-05-11 10:32         ` Michael Kerrisk (man-pages)
  1 sibling, 0 replies; 7+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-05-11 10:32 UTC (permalink / raw)
  To: Karel Zak; +Cc: Helge Kreutzmann, util-linux, Mario Blättermann

Hello Karel

On Mon, 11 May 2020 at 11:27, Karel Zak <kzak@redhat.com> wrote:
>
> On Sat, May 09, 2020 at 09:05:50PM +0200, Michael Kerrisk wrote:
> > On Sat, May 9, 2020 at 9:00 PM Helge Kreutzmann <debian@helgefjell.de> wrote:
> > >
> > > Hello Michael,
> > > On Sat, May 09, 2020 at 08:53:31PM +0200, Michael Kerrisk wrote:
> > > > Hello Helge ;-),
>
> Thanks for your report Helge.
>
> > > > I think no maintainer wants to deal with a 1000-line mail listing 100+
> > > > minor bugs. May I suggest making the maintainer's life a little easier
> > > > by breaking things up into pieces. For example, one mail per manual
> > > > page (which would be 43 mails by my count).  But maybe Karel has
> > > > another suggestion on how you could make his life easier.
>
> Well, that's simple, send patches ;-)))

So, I've recently been through this process with Helge for 100+
man-pages bug reports.Here's my experience/summary for what its worth:
* Because of info I have on the project website, Helge sent bug reports
  one per mail, so one day without warning, I got 138 mails :-).
  (My preference really is separate mails for each issue. But I told
  Helge I would have liked a little warning first :-).)

* A large number of the reports just required simple one-line edits that
  could often be done in a minute.
* It was clear that the effort required for Helge to make patches would
  be rather greater than me just doing the one-line edits
* Making patches requires an added layer of work for Helge, since
  he/the translators are working with a mutated version of the source.
  (The flip side of this is that it is occasionally a little tricky to convert
  the text that Helge is sending you back to the corresponding page
  source.)

> > Maybe hold off for a day or three before investing effort on this.
> > Karel may have a better idea than mine re his preferred method of
> > reporting.
>
> I have no another idea (maybe github issue(s), but it will be invisible
> for many contributors).

Have mercy! Please no... :-).

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, back to index

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-05-03 19:13 Errors in man pages of util-linux Helge Kreutzmann
2020-05-09 18:53 ` Michael Kerrisk
2020-05-09 19:00   ` Helge Kreutzmann
2020-05-09 19:05     ` Michael Kerrisk
2020-05-11  9:27       ` Karel Zak
2020-05-11  9:50         ` Helge Kreutzmann
2020-05-11 10:32         ` Michael Kerrisk (man-pages)

Util-Linux Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/util-linux/0 util-linux/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 util-linux util-linux/ https://lore.kernel.org/util-linux \
		util-linux@vger.kernel.org
	public-inbox-index util-linux

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.util-linux


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git