Subject: bug#18428: closed (Re: bug#18428: Bug#760861: bug#18428: coreutils binary breaks coreutils documentation)

From: [email-masked] (GNU bug Tracking System)
Date: Tue, 09 Sep 2014 09:51:03 +0000

Your bug report

#18428: coreutils binary breaks coreutils documentation

which was filed against the coreutils package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
18428: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=18428
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#18428: Bug#760861: bug#18428: coreutils binary breaks coreutils documentation
From: Pádraig Brady <[email-masked]>
To: [email-masked]
Cc: Alex Deymo <[email-masked]>, Mike Frysinger <[email-masked]>
Date: Tue, 09 Sep 2014 10:50:14 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

On 09/09/2014 04:55 AM, Paul Eggert wrote:
> Subject: [PATCH 1/4] doc: mention which commands are optional

I was thinking that the bst way to do that would be to adjust things
so that the node wasn't installed if the command wasn't.  But it's better
to have this info generally available online also, so +1

> Subject: [PATCH 2/4] doc: rename "coreutils invocation" to "Multi-call

I had done essentially this in my local patch :) so +1

One caveat is that `coreutils --help` is now not accurate
in its presented texinfo node name.  Though I wouldn't
worry about that TBH, especially if relegating coreutils(1)
to a helper command in libexec.  Now some systems may very well like the
explicit option of `coreutils $cmd ...`, but since we need the
--coreutils-prog option too I'd be on for keeping this as a helper command.

I've attached the now optional patch to adjust node names,
which I'm 60:40 for applying since it works with pinfo.

> Subject: [PATCH 3/4] maint: prefer 'return status;' to 'exit (status);' in 'main'

simpler so +1
There were a couple of syntax-check errors with this,
fixed in the attached.

> Subject: [PATCH 4/4] maint: avoid file-scope names of the form _[a-z]*

+1

Marking this bug as done...

thanks!
Pádraig.
>From 20f46a2e347a53855b70b47297cd1856741d6265 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Tue, 9 Sep 2014 10:25:39 +0100
Subject: [PATCH 1/2] maint: fix syntax-check issues in recent commit

Avoid 2 new syntax-check failures introduced in commit v8.23-19-g8defcee

* cfg.mk (sc_some_programs_must_avoid_exit_failure): s/exit/return/.
* src/whoami.c (main): Reinstate translation marker for diagnostic.
---
 cfg.mk       |    2 +-
 src/whoami.c |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/cfg.mk b/cfg.mk
index 26a5966..178ff76 100644
--- a/cfg.mk
+++ b/cfg.mk
@@ -436,7 +436,7 @@ sc_prohibit_test_empty:
 sc_some_programs_must_avoid_exit_failure:
 	@grep -nw EXIT_FAILURE						\
 	    $$(git grep -El '[^T]_FAILURE|EXIT_CANCELED' src)		\
-	  | grep -vE '= EXIT_FAILURE|exit \(.* \?' | grep .		\
+	  | grep -vE '= EXIT_FAILURE|return .* \?' | grep .		\
 	    && { echo '$(ME): do not use EXIT_FAILURE in the above'	\
 		  1>&2; exit 1; } || :
 
diff --git a/src/whoami.c b/src/whoami.c
index 545e521..5ec0dc1 100644
--- a/src/whoami.c
+++ b/src/whoami.c
@@ -84,7 +84,7 @@ main (int argc, char **argv)
   uid = geteuid ();
   pw = (uid == NO_UID && errno ? NULL : getpwuid (uid));
   if (!pw)
-    error (EXIT_FAILURE, errno, "cannot find name for user ID %lu",
+    error (EXIT_FAILURE, errno, _("cannot find name for user ID %lu"),
            (unsigned long int) uid);
   puts (pw->pw_name);
   return EXIT_SUCCESS;
-- 
1.7.7.6

>From 8e8c8fe1bccc47ec6a07ac44cf5af88e7cd3f3dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Tue, 9 Sep 2014 02:05:45 +0100
Subject: [PATCH 2/2] doc: adjust reference to info nodes in man pages

old form: coreutils '$cmd invocation'
new form: '(coreutils) $cmd invocation'

The old form erroneously referenced the node for the 'coreutils'
multi-call program.  Now that problematic node name was renamed
in commit v8.23-18-g72e470b, but the newer less ambiguous form
also has the advantage of working with the pinfo viewer for example.

* man/local.mk: Adjust man page references to texinfo nodes.
* src/system.h: Adjust --help references to texinfo nodes.
---
 man/local.mk |    2 +-
 src/system.h |    3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/man/local.mk b/man/local.mk
index f4b213f..f2d1357 100644
--- a/man/local.mk
+++ b/man/local.mk
@@ -102,7 +102,7 @@ man/dynamic-deps.mk: Makefile
 		     --source='$(PACKAGE_STRING)'			\
 		     --include=$(srcdir)/man/$$name.x			\
 		     --output=$$t/$$name.1 $$t/$$argv			\
-		     --info-page='coreutils \(aq'$$name' invocation\(aq' \
+		     --info-page='\(aq(coreutils) '$$name' invocation\(aq' \
 	  && sed \
 	       -e 's|$*\.td/||g' \
 	       -e '/For complete documentation/d' \
diff --git a/src/system.h b/src/system.h
index 162446c..00180cb 100644
--- a/src/system.h
+++ b/src/system.h
@@ -582,7 +582,8 @@ emit_ancillary_info (void)
                 last_component (program_name));
     }
   printf (_("For complete documentation, run: "
-            "info coreutils '%s invocation'\n"), last_component (program_name));
+            "info '(coreutils) %s invocation'\n"),
+          last_component (program_name));
 }
 
 static inline void
-- 
1.7.7.6

Subject: coreutils binary breaks coreutils documentation
From: Bob Proulx <[email-masked]>
To: [email-masked]
Date: Mon, 8 Sep 2014 11:26:52 -0600
List-Id: <debbugs-submit.debbugs.gnu.org>

Vincent Lefevre reported to the Debian BTS that the new documentation
shipped for the recently added coreutils binary breaks the existing
documentation for all of the coreutils utilities.

  https://bugs.debian.org/760861

Confirmed.  Perhaps the documentation node name can be changed to be
something non-conflicting with the package name?  Or perhaps only
conditionally built if the binary is built?  Or Vincent's suggestion
to use upper case.  Or...?

If correspondents wish their responses logged to the Debian bug log
please add [email-masked] to the email recipients list.  (Two
BTS instances are a little difficult to stitch together until both bug
numbers are known.)

Bob

Original Debian report by Vincent Lefevre follows:

Subject: coreutils: in man pages, info invocation is incorrect: replace coreutils by Coreutils
Package: coreutils
Version: 8.23-2
Severity: minor

For instance, in the touch(1) man page:

  The full documentation for touch is maintained as a Texinfo manual.  If
  the info and touch programs are properly installed at  your  site,  the
  command

         info coreutils 'touch invocation'

  should give you access to the complete manual.

This is now incorrect (as of 8.23?), because it gives the page:

2.14 ‘coreutils’: Multi-call binary
===================================

‘coreutils’ invokes an individual utility, either implicitly selected by
the last component of ‘argv[0]’, or by explicitly calling ‘coreutils’
with the ‘--coreutils-prog’ option.  Synopsis:

     coreutils --coreutils-prog=PROGRAM …

The correct info invocation now is:

    info Coreutils 'touch invocation'

Note: Since the coreutils utility doesn't seem to exist in Debian, this
section could be removed, but this problem may reappear in the future.
So, it's better to use the capital letter C.