Re: pathchk info page should mention other leading brand

[Pádraig Brady]

address@hidden wrote:
> $ info cor pathchk
> When I read this info page the question that one asks is "What about
> Windows? I want to know if I zip up some files and give them to my
> friend, will there be some problem when he unzips them on Windows?"

Lots of variables there. What limits/charsets/encodings/permissions/...
does zip support, ditto for windos etc. Also consider reserved filenames
like CON etc. I'm not sure that pathchk should be mentioning anything
other that POSIX names, which is what it's actually testing.

>   2. The length of NAME is larger than the maximum supported by the
>      operating system.
> 
>   3. The length of one component of NAME is longer than its file
>      system's maximum.
> 
> but the OS would have warned us.
> 
>    A nonexistent NAME is not an error, so long a file with that name
>    could be created under the above conditions.
> 
> I see, it is for testing before making files on the current system...
> but then we could just do "touch FUNNY_NAME" and if we get an error
> message we will know usually...

I see your point, though `touch "whatever"` could fail
due to permissions for example, so generally it's nice
to be able to check a path name before use, even on the
current system. But you're right that pathchk is testing
limits rather than portability when no options are specified,
so we should mention that it checks validity at least.

> mainly we want to know if a file is
> portable to a foreign systems that we have no access to. OK, whatever.
> Do mention Windows...

As mentioned above I'm not sure we should.

> Also note that it writes to stderr, not stdout.

true

> Also mention that for each filename it bails out on the first error,

To document this accurately one would have to say
which error takes precedence. I think the existing text
is fine in that it says 1 message is printed, though
the ordering of the 3 -p checks doesn't match the code,
which we should probably change.

I'll push the attached patch in a day or 2.

cheers,
Pádraig.

>From fbe9201e5e2812bfc112ea05c317b194c98bb4f9 Mon Sep 17 00:00:00 2001
From: =?utf-8?q?P=C3=A1draig=20Brady?= <address@hidden>
Date: Sun, 4 Jan 2009 01:06:10 +0000
Subject: [PATCH] doc: pathchk description enhancements

* doc/coreutils.text (pathchk invocation): Mention pathchk
checks validity (for current system) as well as portability.
Say messages go to stderr, and reorder description of checks
done for the -p option, to match that done in code.
* src/pathchk.c (usage): Mention pathchk checks name validity.
Suggested clarifications were from Dan Jacobson.
---
 doc/coreutils.texi |   24 ++++++++++++------------
 src/pathchk.c      |    2 +-
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index e3e99b6..16f0aaf 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -376,7 +376,7 @@ File name manipulation
 
 * basename invocation::          Strip directory and suffix from a file name
 * dirname invocation::           Strip non-directory suffix from a file name
-* pathchk invocation::           Check file name portability
+* pathchk invocation::           Check file name validity and portability
 
 Working context
 
@@ -11572,7 +11572,7 @@ This section describes commands that manipulate file 
names.
 @menu
 * basename invocation::         Strip directory and suffix from a file name.
 * dirname invocation::          Strip non-directory suffix from a file name.
-* pathchk invocation::          Check file name portability.
+* pathchk invocation::          Check file name validity and portability.
 @end menu
 
 
@@ -11672,20 +11672,20 @@ dirname stdio.h
 
 
 @node pathchk invocation
address@hidden @command{pathchk}: Check file name portability
address@hidden @command{pathchk}: Check file name validity and portability
 
 @pindex pathchk
 @cindex file names, checking validity and portability
 @cindex valid file names, checking for
 @cindex portable file names, checking for
 
address@hidden checks portability of file names.  Synopsis:
address@hidden checks validity and portability of file names.  Synopsis:
 
 @example
 pathchk address@hidden@dots{} @address@hidden
 @end example
 
-For each @var{name}, @command{pathchk} prints a message if any of
+For each @var{name}, @command{pathchk} prints an error message if any of
 these conditions is true:
 
 @enumerate
@@ -11711,30 +11711,30 @@ Options must precede operands.
 @item -p
 @opindex -p
 Instead of performing checks based on the underlying file system,
-print a message if any of these conditions is true:
+print an error message if any of these conditions is true:
 
 @enumerate
 @item
 A file name is empty.
 
 @item
-The length of a file name or one of its components exceeds the
address@hidden minimum limits for portability.
-
address@hidden
 A file name contains a character outside the portable file name
 character set, namely, the ASCII letters and digits, @samp{-},
 @samp{.}, @samp{/}, and @samp{_}.
+
address@hidden
+The length of a file name or one of its components exceeds the
address@hidden minimum limits for portability.
 @end enumerate
 
 @item -P
 @opindex -P
-Print a message if a file name is empty, or if it contains a component
+Print an error message if a file name is empty, or if it contains a component
 that begins with @samp{-}.
 
 @item --portability
 @opindex --portability
-Print a message if a file name is not portable to all @acronym{POSIX}
+Print an error message if a file name is not portable to all @acronym{POSIX}
 hosts.  This option is equivalent to @samp{-p -P}.
 
 @end table
diff --git a/src/pathchk.c b/src/pathchk.c
index 3b2bd46..5dbc7da 100644
--- a/src/pathchk.c
+++ b/src/pathchk.c
@@ -96,7 +96,7 @@ usage (int status)
     {
       printf (_("Usage: %s [OPTION]... NAME...\n"), program_name);
       fputs (_("\
-Diagnose unportable constructs in NAME.\n\
+Diagnose invalid or unportable file names.\n\
 \n\
   -p                  check for most POSIX systems\n\
   -P                  check for empty names and leading \"-\"\n\
-- 
1.5.3.6