Manpage tweaks to clarify nameref behavior

[Jeffrey S. Haemer]

Configuration Information [Automatically generated, do not change]:
Machine: x86_64
OS: linux-gnu
Compiler: gcc
Compilation CFLAGS:  -DPROGRAM='bash' -DCONF_HOSTTYPE='x86_64'
-DCONF_OSTYPE='linux-gnu' -DCONF_MACHTYPE='x86_64-pc-linux-gnu'
-DCONF_VENDOR='pc' -DLOCALEDIR='/usr/share/locale' -DPACKAGE='bash' -DSHELL
-DHAVE_CONFIG_H   -I.  -I../. -I.././include -I.././lib
 -D_FORTIFY_SOURCE=2 -g -O2 -fstack-protector --param=ssp-buffer-size=4
-Wformat -Werror=format-security -Wall
uname output: Linux jhaemer-ThinkPad-T420 3.13.0-24-generic #46-Ubuntu SMP
Thu Apr 10 19:11:08 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux
Machine Type: x86_64-pc-linux-gnu

Bash Version: 4.3
Patch Level: 11
Release Status: release

Description:
  The shell's behavior when exporting nameref variables isn't described
clearly enough
  -- at least, to me -- by the manpage.

Repeat-By:

  #!/bin/bash

  comment() {
    printf '\n== %s\n' "$@"
  }

  report() {
    echo "foo is '$foo' bar is '$bar'"
  }

  demo() {
    comment "$@"
    printf 'Shell: '
    report
    printf 'Subshell: '
    bash -c report
  }


  # don't export anything

  export -f report
  foo=bar; bar=69;

  export -n foo bar
  demo 'At first, export nothing'

  export foo
  demo 'Export only foo'

  export bar
  demo 'Export both variables'

  declare -n foo
  demo 'Make foo a nameref'

  unset foo bar
  demo 'Unset foo, then bar'
  comment '** Note: if I had unset bar first, then they would both be
unset. **'

  declare +nx foo bar
  unset foo bar
  demo 'Reset everything from scratch'

  declare -n foo
  foo=bar; bar=69
  demo 'Make foo a nameref to bar before exporting'

  export foo
  demo 'Export only foo'
  comment '** Note: The man page tweak is meant to describe this behavior.
**'

  exit 0

Fix:

  - Under PARAMETERS, change this

    Whenever the nameref variable is referenced or assigned to, the
    operation is actually performed on the variable specified by the
    nameref variable's value.

  to this

    Whenever the nameref variable is referenced, assigned to, or exported,
    the operation is actually performed on the variable specified by the
    nameref variable's value.

  - Further on, change this

    References and assignments to ref are treated as references and
    assignments to the variable whose name was passed as $1.

  to this

    Exports, references, and assignments to ref are treated as exports,
    references and assignments to the variable whose name was passed
    as $1.

  (Yeah, I don't like the preposition either. If you can word it better,
  great!)

  - A third fix needs to be made, in SHELL BUILTIN COMMANDS, to the
description
  of the "-n" option to "declare/typeset" .

-- 
Jeffrey Haemer <jeffrey.haemer@gmail.com>
720-837-8908 [cell], http://seejeffrun.blogspot.com [blog],
http://www.youtube.com/user/goyishekop [vlog]
*פרייהייט? דאס איז יאַנג דינען וואָרט.*