Re: Proposed doc updates

[Ralf Wildenhues]

* Eric Blake wrote on Mon, Jan 24, 2005 at 02:22:04PM CET:
> 
> My assignment is not yet on file, but I would like comments on my proposed
> portability patches below.  I welcome any stylistic corrections (this is
> my first time writing in texinfo), technical corrections, or additional
> comments that should be added.  I did a visual check of the patch using
> `make html'.

You can try `make dvi' as well, it's usually quite helpful.

Couple of nits: (nice work, btw!)

> @@ -9503,11 +9503,12 @@ have evolved over the years, but to prev
>  advantage of features that were added after Unix version 7, circa
>  1977 (@pxref{Systemology}).
>  
> -You should not use shell functions, aliases, negated character
> -classes, or other features that are not found in all Bourne-compatible
> -shells; restrict yourself to the lowest common denominator.  Even
> address@hidden is not supported by all shells!  Also, include a space
> -after the exclamation point in interpreter specifications, like this:
> +You should use shell functions with care, and should avoid aliases,
> +negated character classes, or other features that are not found in all
> +Bourne-compatible shells; restrict yourself to the lowest common
> +denominator.  Even @code{unset} is not supported by all shells!  Also,
> +include a space after the exclamation point in interpreter
> +specifications, like this:

You could also mention that with some shells, functions and variables
share a namespace.

>  @example
>  #! /usr/bin/perl

*snip*
> @@ -10607,21 +10673,27 @@ PS2='> '
>  PS4='+ '
>  @end example
>  
> address@hidden PWD
> address@hidden PWD
> -Posix 1003.1-2001 requires that @command{cd} and
> address@hidden must update the @env{PWD} environment variable to point
> -to the logical name of the current directory, but traditional shells
> -do not support this.  This can cause confusion if one shell instance
> -maintains @env{PWD} but a subsidiary and different shell does not know
> -about @env{PWD} and executes @command{cd}; in this case @env{PWD} will
> -point to the wrong directory.  Use @samp{`pwd`} rather than
> address@hidden
> -
> address@hidden status
> address@hidden status
> -This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
> -hence read-only.  Do not use it.
> address@hidden PATH
> address@hidden PATH
> +Not all @env{PATH} names are portable.  This is particularly noticeable
> +in a default Cygwin installation, where @env{PATH} is inherited from the
> address@hidden path, and typically includes directory components with
> +spaces, such as @code{Program Files} or @code{Documents and Settings}.
> +When handling a @code{$PATH} from a user, quote the variable to avoid
> +inadvertant word splitting or other unexpected behavior.
> +
> address@hidden
> +$ @kbd{echo $PATH}
> +/usr/bin:/cygdrive/c/windows:/cygdrive/c/program files/program
> +$ @kbd{eval PATH=/bin:$PATH}
> address@hidden: files/program: command not found
> address@hidden example
> +
> +Remember that Posix requires that a leading or trailing
> address@hidden in a @env{PATH} implies the current directory.
> +This applies to other @env{PATH}-like variables as well, such as
> address@hidden  Therefore, if you do not want to add @samp{.} to
> +a search path, first check that the path variable is not empty.

Maybe add
  LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}/added/path
?  Also, could people have the impression that use of LD_LIBRARY_PATH is
portable?

>  @item PATH_SEPARATOR
>  @evindex PATH_SEPARATOR
*snip*
> @@ -10696,6 +10785,26 @@ More generally, one can always rewrite @
>  if @var{command}; then (exit 1); else :; fi
>  @end example
>  
> address@hidden @command{alias}
> address@hidden ------------------
> address@hidden @command{alias}
> +Even though Posix requires it, Ash does not support aliases, and some
> +shells only support @command{alias} in interactive mode.  Portable
> +scripts should not use aliases.  See @command{unalias} if you are
> +worried about existing aliases affecting your script.
> +
> +Most of the time, a Posix function can do everything that an alias can,
> +and more.  However, in shells that support both, it is worth remembering
> +that alias expansion occurs before filename expansion, leading to this
> +useful alias from
> address@hidden://lists.debian.org/debian-user/2003/06/msg01038.html)} that

s/)//

> +supresses filename expansion for the duration of the find command:
> +
> address@hidden
> +$ @kbd{alias find='_find() @{ find "$@@"; set +f; unset _find; @}; set -f; 
> _find'}
> address@hidden example
> +
> +
>  @item @command{break}
>  @c ------------------
>  @prindex @command{break}
*snip*
> @@ -11044,12 +11186,14 @@ set x $my_list; shift
>  
>  Some shells have the "opposite" problem of not recognizing all options
>  (e.g., @samp{set -e -x} assigns @samp{-x} to the command line).  It is
> -better to elide these:
> +better to combine these:
>  
>  @example
>  set -ex
>  @end example
>  
> +Ash does not recognize @samp{set -h} or @samp{set -o nolog}.
> +

You could add that some shells reset `-x' upon function entry.
(I did not check whether they reset any other options).

>  @item @command{shift}
>  @c ------------------

Regards,
Ralf