On 12/02/2022 05:57, Helge Kreutzmann wrote:
Dear coreutils maintainer,
the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including coreutils) as
well for a large variety of target languages.
During their work translators notice different possible issues in the
original (english) man pages. Sometimes 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 in 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: arch.1
Issue: missing markup (B<>)
"uname(1), uname(2)"
I'm not sure about marking up references like this.
There should be enough context from the reference
for the man page reader to display appropriately.
For e.g. I use vim to display man pages, and references
like this are highlighted, and can be followed.
Also looking at other projects, I don't see explicitly
highlighted referenced man pages.
Man page: expand.1
Issue: Missing full stop
"use comma separated list of tab positions The last specified position can"
Already fixed upstream.
Man page: ls.1
Issue: seems to be an unnecessary split of paragraphs; join with next one
"can be augmented with a B<--sort> option, but any use of B<--sort>=I<\\,none"
"\\/> (B<-U>) disables grouping"
--
Man page: ls.1
Issue: seems to be an unnecessary split of paragraphs; join with next one
msgid "that points to a directory"
--
Yes good point.
The issue here is those newlines are generated due to inconsistent indentation.
Attached is a patch to ls to make the indentation consistent.
Man page: ls.1
Issue 1: LS_COLORS → B<LS_COLORS>
There are other env vars mentioned.
I'm not sure why this one, or any should be highlighted.
Issue 2: dircolors → B<dircolors>(1)
Good point re the (1). Added in second patch.
Man page: rmdir.1
Issue: join this string with the next one "is non-empty"
"ignore each failure that is solely because a directory"
Added in third patch.
I also noticed an erroneous blank line added in the man page
after the first option. I adjusted the column of the description
to 21 to avoid that, and in a further (4th) patch I adjusted
the description column of --help and --version is all commands
to use column 21 also.
Man page: test.1
Issue: [ → test
"Full documentation E<lt>https://www.gnu.org/software/coreutils/[E<gt>"
This is subtle. The link above (with [) does actually work.
Though I notice it's not highlighted appropriately by gnome-terminal
at least, so would be better to use "test" instead.
This is done in patch 5.
Man page: unexpand.1
Issue: Missing full stop
"use comma separated list of tab positions The last specified position can"
Already fixed upstream.
Marking this as done.
cheers,
Pádraig
From 195e943be732d1d1fe5576786596b49be409f1aa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <p...@draigbrady.com>
Date: Sat, 12 Feb 2022 18:43:25 +0000
Subject: [PATCH 5/5] doc: avoid using "[" is URLS in --help output
* src/system.h (emit_ancillary_info): While supported if entered
manually, the "[" character is not highlighted as part of a
URL by default in terminals, so avoid using it.
Addresses https://bugs.gnu.org/53946
---
src/system.h | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/src/system.h b/src/system.h
index 08cfd3bc0..09498a172 100644
--- a/src/system.h
+++ b/src/system.h
@@ -716,8 +716,12 @@ emit_ancillary_info (char const *program)
fputs (_("Report any translation bugs to "
"<https://translationproject.org/team/>\n"), stdout);
}
+ /* .htaccess on the coreutils web site maps programs to the appropriate page,
+ however we explicitly handle "[" -> "test" here as the "[" is not
+ recognized as part of a URL by default in terminals. */
+ char const *url_program = STREQ (program, "[") ? "test" : program;
printf (_("Full documentation <%s%s>\n"),
- PACKAGE_URL, program);
+ PACKAGE_URL, url_program);
printf (_("or available locally via: info '(coreutils) %s%s'\n"),
node, node == program ? " invocation" : "");
}
--
2.26.2
From d35b305109032ed7521e808b74758e9943d74b6f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <p...@draigbrady.com>
Date: Sat, 12 Feb 2022 18:23:48 +0000
Subject: [PATCH 4/5] doc: adust --help, --version alignment
* src/system.h: Adjust the alignment of the --help
and --version option descriptions, to start at column 21.
This better aligns with the descriptions of most commands,
and also aligns with the minimum column a description must
start at to ensure a blank line is not output when a description
follows an option on a line by itself.
---
src/system.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/src/system.h b/src/system.h
index 16fcc38e7..08cfd3bc0 100644
--- a/src/system.h
+++ b/src/system.h
@@ -410,9 +410,9 @@ enum
"for details about the options it supports.\n")
#define HELP_OPTION_DESCRIPTION \
- _(" --help display this help and exit\n")
+ _(" --help display this help and exit\n")
#define VERSION_OPTION_DESCRIPTION \
- _(" --version output version information and exit\n")
+ _(" --version output version information and exit\n")
#include "closein.h"
#include "closeout.h"
--
2.26.2
From a4d8d58429ab299709b2ba630a54110c77022ec4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <p...@draigbrady.com>
Date: Sat, 12 Feb 2022 18:16:10 +0000
Subject: [PATCH 3/5] doc: rmdir: improve --help formatting
* src/rmdir.c (usage): Move description to column 21,
so that a --long-option on its own line without a
trailing description, doesn't have an erroneous blank
line inserted between the option and description.
Also group descriptions with blank lines rather than indents,
so that man pages don't have erroneous blank lines
added within the description.
Addresses https://bugs.gnu.org/53946
---
src/rmdir.c | 14 ++++++++++----
1 file changed, 10 insertions(+), 4 deletions(-)
diff --git a/src/rmdir.c b/src/rmdir.c
index f13aa8e09..53311db8d 100644
--- a/src/rmdir.c
+++ b/src/rmdir.c
@@ -175,15 +175,21 @@ usage (int status)
fputs (_("\
Remove the DIRECTORY(ies), if they are empty.\n\
\n\
+"), stdout);
+ fputs (_("\
--ignore-fail-on-non-empty\n\
- ignore each failure that is solely because a directory\n\
+ ignore each failure that is solely because a directory\n\
is non-empty\n\
+\n\
"), stdout);
fputs (_("\
- -p, --parents remove DIRECTORY and its ancestors; e.g., 'rmdir -p a/b/c' is\
+ -p, --parents remove DIRECTORY and its ancestors; e.g., 'rmdir -p a/b/c'\
\n\
- similar to 'rmdir a/b/c a/b a'\n\
- -v, --verbose output a diagnostic for every directory processed\n\
+ is similar to 'rmdir a/b/c a/b a'\n\
+\n\
+"), stdout);
+ fputs (_("\
+ -v, --verbose output a diagnostic for every directory processed\n\
"), stdout);
fputs (HELP_OPTION_DESCRIPTION, stdout);
fputs (VERSION_OPTION_DESCRIPTION, stdout);
--
2.26.2
From dc689eba5710d9f607cb5f2bc2bfe944bb9042a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <p...@draigbrady.com>
Date: Sat, 12 Feb 2022 18:03:38 +0000
Subject: [PATCH 2/5] doc: ls: reference dircolors(1) from --help
* src/ls.c (usage): s/dircolors/dircolors(1)/.
* man/ls.x [SEE ALSO]: Reference dircolors(1).
Addresses https://bugs.gnu.org/53946
---
man/ls.x | 2 ++
src/ls.c | 2 +-
2 files changed, 3 insertions(+), 1 deletion(-)
diff --git a/man/ls.x b/man/ls.x
index 4b7e3f46d..83dd4969e 100644
--- a/man/ls.x
+++ b/man/ls.x
@@ -2,3 +2,5 @@
ls \- list directory contents
[DESCRIPTION]
.\" Add any additional description here
+[SEE ALSO]
+dircolors(1)
diff --git a/src/ls.c b/src/ls.c
index e1d1b85e2..53f80076b 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -5609,7 +5609,7 @@ The WHEN argument defaults to 'always' and can also be 'auto' or 'never'.\n\
Using color to distinguish file types is disabled both by default and\n\
with --color=never. With --color=auto, ls emits color codes only when\n\
standard output is connected to a terminal. The LS_COLORS environment\n\
-variable can change the settings. Use the dircolors command to set it.\n\
+variable can change the settings. Use the dircolors(1) command to set it.\n\
"), stdout);
fputs (_("\
\n\
--
2.26.2
From 353ba4978fc0fb1e1fba6f62954793bd809424c3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <p...@draigbrady.com>
Date: Sat, 12 Feb 2022 17:52:32 +0000
Subject: [PATCH 1/5] doc: ls: improve --help formatting
* src/ls.c (usage): Use blank lines to group multi-line
option descriptions, rather than indenting.
This results in more consistent alignment of descriptions,
and also avoids erroneous new lines in generated in man pages.
Addresses https://bugs.gnu.org/53946
---
src/ls.c | 91 ++++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 68 insertions(+), 23 deletions(-)
diff --git a/src/ls.c b/src/ls.c
index 6ba8c0cad..e1d1b85e2 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -5413,14 +5413,18 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
"), stdout);
fputs (_("\
--block-size=SIZE with -l, scale sizes by SIZE when printing them;\n\
- e.g., '--block-size=M'; see SIZE format below\n\
+ e.g., '--block-size=M'; see SIZE format below\n\
+\n\
"), stdout);
fputs (_("\
-B, --ignore-backups do not list implied entries ending with ~\n\
+"), stdout);
+ fputs (_("\
-c with -lt: sort by, and show, ctime (time of last\n\
- modification of file status information);\n\
- with -l: show ctime and sort by name;\n\
- otherwise: sort by ctime, newest first\n\
+ modification of file status information);\n\
+ with -l: show ctime and sort by name;\n\
+ otherwise: sort by ctime, newest first\n\
+\n\
"), stdout);
fputs (_("\
-C list entries by columns\n\
@@ -5432,8 +5436,13 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
-f list all entries in directory order\n\
-F, --classify[=WHEN] append indicator (one of */=>@|) to entries WHEN\n\
--file-type likewise, except do not append '*'\n\
+"), stdout);
+ fputs (_("\
--format=WORD across -x, commas -m, horizontal -x, long -l,\n\
- single-column -1, verbose -l, vertical -C\n\
+ single-column -1, verbose -l, vertical -C\n\
+\n\
+"), stdout);
+ fputs (_("\
--full-time like -l --time-style=full-iso\n\
"), stdout);
fputs (_("\
@@ -5442,8 +5451,9 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
fputs (_("\
--group-directories-first\n\
group directories before files;\n\
- can be augmented with a --sort option, but any\n\
- use of --sort=none (-U) disables grouping\n\
+ can be augmented with a --sort option, but any\n\
+ use of --sort=none (-U) disables grouping\n\
+\n\
"), stdout);
fputs (_("\
-G, --no-group in a long listing, don't print group names\n\
@@ -5455,21 +5465,30 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
fputs (_("\
-H, --dereference-command-line\n\
follow symbolic links listed on the command line\n\
+"), stdout);
+ fputs (_("\
--dereference-command-line-symlink-to-dir\n\
follow each command line symbolic link\n\
- that points to a directory\n\
+ that points to a directory\n\
+\n\
+"), stdout);
+ fputs (_("\
--hide=PATTERN do not list implied entries matching shell PATTERN\
\n\
- (overridden by -a or -A)\n\
+ (overridden by -a or -A)\n\
+\n\
"), stdout);
fputs (_("\
--hyperlink[=WHEN] hyperlink file names WHEN\n\
"), stdout);
fputs (_("\
- --indicator-style=WORD append indicator with style WORD to entry names:\
+ --indicator-style=WORD\n\
+ append indicator with style WORD to entry names:\n\
+ none (default), slash (-p),\n\
+ file-type (--file-type), classify (-F)\n\
\n\
- none (default), slash (-p),\n\
- file-type (--file-type), classify (-F)\n\
+"), stdout);
+ fputs (_("\
-i, --inode print the index number of each file\n\
-I, --ignore=PATTERN do not list implied entries matching shell PATTERN\
\n\
@@ -5477,13 +5496,19 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
fputs (_("\
-k, --kibibytes default to 1024-byte blocks for file system usage;\
\n\
- used only with -s and per directory totals\n\
+ used only with -s and per directory totals\n\
+\n\
"), stdout);
fputs (_("\
-l use a long listing format\n\
+"), stdout);
+ fputs (_("\
-L, --dereference when showing file information for a symbolic\n\
- link, show information for the file the link\n\
- references rather than for the link itself\n\
+ link, show information for the file the link\n\
+ references rather than for the link itself\n\
+\n\
+"), stdout);
+ fputs (_("\
-m fill width with a comma separated list of entries\
\n\
"), stdout);
@@ -5496,14 +5521,22 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
"), stdout);
fputs (_("\
-q, --hide-control-chars print ? instead of nongraphic characters\n\
+"), stdout);
+ fputs (_("\
--show-control-chars show nongraphic characters as-is (the default,\n\
- unless program is 'ls' and output is a terminal)\
+ unless program is 'ls' and output is a terminal)\
+\n\
\n\
+"), stdout);
+ fputs (_("\
-Q, --quote-name enclose entry names in double quotes\n\
+"), stdout);
+ fputs (_("\
--quoting-style=WORD use quoting style WORD for entry names:\n\
- literal, locale, shell, shell-always,\n\
- shell-escape, shell-escape-always, c, escape\n\
- (overrides QUOTING_STYLE environment variable)\n\
+ literal, locale, shell, shell-always,\n\
+ shell-escape, shell-escape-always, c, escape\n\
+ (overrides QUOTING_STYLE environment variable)\n\
+\n\
"), stdout);
fputs (_("\
-r, --reverse reverse order while sorting\n\
@@ -5512,18 +5545,25 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
"), stdout);
fputs (_("\
-S sort by file size, largest first\n\
+"), stdout);
+ fputs (_("\
--sort=WORD sort by WORD instead of name: none (-U), size (-S)\
,\n\
- time (-t), version (-v), extension (-X), width\n\
+ time (-t), version (-v), extension (-X), width\n\
+\n\
+"), stdout);
+ fputs (_("\
--time=WORD change the default of using modification times;\n\
access time (-u): atime, access, use;\n\
change time (-c): ctime, status;\n\
birth time: birth, creation;\n\
with -l, WORD determines which time to show;\n\
with --sort=time, sort by WORD (newest first)\n\
+\n\
"), stdout);
fputs (_("\
- --time-style=TIME_STYLE time/date format with -l; see TIME_STYLE below\n\
+ --time-style=TIME_STYLE\n\
+ time/date format with -l; see TIME_STYLE below\n\
"), stdout);
fputs (_("\
-t sort by time, newest first; see --time\n\
@@ -5531,9 +5571,14 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
"), stdout);
fputs (_("\
-u with -lt: sort by, and show, access time;\n\
- with -l: show access time and sort by name;\n\
- otherwise: sort by access time, newest first\n\
+ with -l: show access time and sort by name;\n\
+ otherwise: sort by access time, newest first\n\
+\n\
+"), stdout);
+ fputs (_("\
-U do not sort; list entries in directory order\n\
+"), stdout);
+ fputs (_("\
-v natural sort of (version) numbers within text\n\
"), stdout);
fputs (_("\
--
2.26.2
