From 15bbc2f632eddb12d15f3d797b94fc44f1c6b3a7 Mon Sep 17 00:00:00 2001 From: Martijn Dekker Date: Fri, 19 Nov 2021 02:49:28 +0100 Subject: [PATCH] manual: use consistent terminology The ksh manual page is one of the few places that calls globbing "file name generation". The mksh and zsh manuals use the same term. But every other shell's manual calls it "pathname expansion": bash, dash, yash, FreeBSD sh. So does ksh's built-in documentation (alias --man, export --man, readonly --man, set --man, typeset --man). What's more, the authoritative ksh reference, Bolsky & Korn's 1995 "The New Kornshell" book, also calls it "pathname expansion", and so does the POSIX standard. Similarly, "arithmetic substitution" should be called "arithmetic expansion" per Bolsky & Korn as well as POSIX. This commit has several other miscellaneous documentation tweaks as well. --- src/cmd/ksh93/COMPATIBILITY | 2 +- src/cmd/ksh93/DESIGN | 2 +- src/cmd/ksh93/PROMO.mm | 4 +- src/cmd/ksh93/README | 16 ++++++-- src/cmd/ksh93/data/testops.c | 4 +- src/cmd/ksh93/sh.1 | 76 +++++++++++++++++++----------------- 6 files changed, 59 insertions(+), 45 deletions(-) diff --git a/src/cmd/ksh93/COMPATIBILITY b/src/cmd/ksh93/COMPATIBILITY index a1394539c..87eeb5e52 100644 --- a/src/cmd/ksh93/COMPATIBILITY +++ b/src/cmd/ksh93/COMPATIBILITY @@ -14,7 +14,7 @@ For more details, see the NEWS file and for complete details, see the git log. 1. Bytecode compiled by shcomp 93u+m will not run on older ksh versions. (However, bytecode compiled by older shcomp will run on ksh 93u+m.) -2. File name generation (a.k.a. pathname expansion, a.k.a. globbing) now +2. Pathname expansion (a.k.a. filename generation, a.k.a. globbing) now never matches the special navigational names '.' (current directory) and '..' (parent directory). This change makes a pattern like .* useful; it now matches all hidden 'dotfiles' in the current directory. diff --git a/src/cmd/ksh93/DESIGN b/src/cmd/ksh93/DESIGN index 4a9a1ec33..022d6870e 100644 --- a/src/cmd/ksh93/DESIGN +++ b/src/cmd/ksh93/DESIGN @@ -109,7 +109,7 @@ sh directory: 5. deparse.c contains code to generate shell script from a parse tree. 6. expand.c contains code for file name expansion and - file name generation. + pathname expansion. 7. fault.c contains code for signal processing, trap handling and termination. 8. fcin.c contains code for reading and writing a character diff --git a/src/cmd/ksh93/PROMO.mm b/src/cmd/ksh93/PROMO.mm index f542dbdb8..ac0dfb018 100644 --- a/src/cmd/ksh93/PROMO.mm +++ b/src/cmd/ksh93/PROMO.mm @@ -95,7 +95,7 @@ way scripts are. Substring Capabilities: KSH-93 allows you to create a substring of any given string either by specifying the starting offset and length, or by stripping off leading -or trailing substrings during parameter substitution. +or trailing substrings during parameter expansion. You can also specify attributes, such as upper and lower case, field width, and justification to shell variables. .LI @@ -137,5 +137,5 @@ be embedded into an application to allow scripting. Documentation for KSH-93 consists of an "Introduction to KSH-93", "Compatibility with the Bourne Shell" and a manual page and a README file. In addition, the "New KornShell Command and Programming -Language," book is available from Prentice Hall. +Language" book is available from Prentice Hall. diff --git a/src/cmd/ksh93/README b/src/cmd/ksh93/README index 06831e6a6..d7229946d 100644 --- a/src/cmd/ksh93/README +++ b/src/cmd/ksh93/README @@ -39,7 +39,8 @@ The options have the following defaults and meanings: the job pid and $? is set to the job exit status at the beginning of the trap. - BRACEPAT on C-shell type abc{d,e}f style file generation + BRACEPAT on Brace expansion. Expands abc{d,e}f to abcdf abcef. + This feature was inspired by the C shell. CMDLIB_HDR "" The header in which you can provide a custom list of @@ -79,7 +80,7 @@ The options have the following defaults and meanings: fixed-size arrays NAME[N1][N2]... are also supported. GLOBCASEDET Adds the 'globcasedetect' shell option. When this shell - option is turned on, file name generation (globbing) + option is turned on, pathname expansion (globbing) and file name listing and completion automatically become case-insensitive on file systems where the difference between upper- and lowercase is ignored for file names. @@ -95,8 +96,15 @@ The options have the following defaults and meanings: MULTIBYTE on Multibyte character handling. Requires mblen() and mbctowc(). - NAMESPACE on Allows namespaces. This is experimental, incomplete - and undocumented. + NAMESPACE on Adds a 'namespace' reserved word that allows defining name + spaces. Variables and functions defined within a block like + namespace ExampleSpace { commandlist; } + all have their names automatically prefixed with + '.ExampleSpace.' when defining or using them, creating a + separate space of names unique to the block. Outside of + the namespace block, they can be accessed using + .ExampleSpace.function or ${.ExampleSpace.variable}. + Name spaces within name spaces are also supported. NOECHOE off Disable the '-e' option to the 'echo' command, unless SHOPT_ECHOPRINT is enabled. diff --git a/src/cmd/ksh93/data/testops.c b/src/cmd/ksh93/data/testops.c index 9c13d6845..2a7473abc 100644 --- a/src/cmd/ksh93/data/testops.c +++ b/src/cmd/ksh93/data/testops.c @@ -63,8 +63,8 @@ const char sh_opttest[] = "[+DESCRIPTION?\btest\b evaluates expressions and returns its result using the " "exit status. Option parsing is not performed; all arguments, " "including \b--\b, are processed as operands. It is essential to quote " - "expression arguments to suppress empty removal, field splitting, file " - "name generation, and constructs such as redirection. If the command " + "expression arguments to suppress empty removal, field splitting, " + "pathname expansion, and constructs such as redirection. If the command " "is invoked as \b[\b, a final \b]]\b argument is required and " "discarded. The evaluation of the expression depends on the number of " "operands, as follows:]" diff --git a/src/cmd/ksh93/sh.1 b/src/cmd/ksh93/sh.1 index 3b8553adc..5f91bcde3 100644 --- a/src/cmd/ksh93/sh.1 +++ b/src/cmd/ksh93/sh.1 @@ -416,8 +416,8 @@ that matches .IR word . The form of the patterns is the same as that used for -file name generation (see -.I "File Name Generation\^" +pathname expansion (see +.I "Pathname Expansion\^" below). The .B ;; @@ -706,7 +706,7 @@ value is not unset and the new values are appended to the current ones provided that the types are compatible. .PP The right hand side of a variable assignment undergoes all the expansion -listed below except word splitting, brace expansion, and file name generation. +listed below except word splitting, brace expansion, and pathname expansion. When the left hand side is an assignment is a compound variable and the right hand is the name of a compound variable, the compound variable on the right will be copied or appended to the compound variable on the left. @@ -911,7 +911,7 @@ side effects are possible. For the second form, the final .B } will be recognized as a reserved word after any token. -.SS Arithmetic Substitution. +.SS Arithmetic Expansion. An arithmetic expression enclosed in double parentheses preceded by a dollar sign ( .B $((\|)) @@ -1851,7 +1851,7 @@ will be turned on. .SM .B ENV If this variable is set, then -parameter expansion, command substitution, and arithmetic substitution +parameter expansion, command substitution, and arithmetic expansion are performed on the value to generate the pathname of the script that will be @@ -1966,7 +1966,7 @@ The first character of the variable is used to separate arguments for the .B "$*" -substitution (see +expansion (see .I Quoting below). Each single occurrence of @@ -2037,7 +2037,7 @@ collation information. This variable determines the locale category for character handling functions. It determines the character classes for pattern matching (see -.I "File Name Generation\^" +.I "Pathname Expansion\^" below). .TP .B @@ -2099,7 +2099,7 @@ Each file name can be followed by a .B ? and a message that will be printed. The message will undergo parameter expansion, command substitution, -and arithmetic substitution +and arithmetic expansion with the variable .B $_ defined as the name of the file that has changed. @@ -2125,7 +2125,7 @@ if executing under Every time a new command line is started on an interactive shell, the value of this variable is expanded to resolve backslash escaping, parameter expansion, command substitution, -and arithmetic substitution. +and arithmetic expansion. The result defines the primary prompt string for that command line. The default is .RB `` "$ \|\|\|" ''. @@ -2164,7 +2164,7 @@ loop, by default .SM .B PS4 The value of this variable is expanded for parameter evaluation, -command substitution, and arithmetic substitution +command substitution, and arithmetic expansion and precedes each line of an execution trace. By default, .SM @@ -2450,7 +2450,9 @@ expands to the 8 fields, .B z04bx and .BR z04cx . -.SS File Name Generation. +.SS Pathname Expansion. +This is also known as \f2globbing\fP +or sometimes \f2filename generation\fP. Following splitting, each field is scanned for the characters .BR * , .BR ? , @@ -2761,7 +2763,7 @@ This is the default. .TP .B N This is ignored. However, when it is the first letter and is -used with file name generation, and no matches occur, +used with pathname expansion, and no matches occur, the file pattern expands to the empty string. .TP .B X @@ -2911,13 +2913,17 @@ The recognition of function names or built-in command names listed below cannot be altered by quoting them. .SS Arithmetic Evaluation. The shell performs arithmetic evaluation for -arithmetic substitution, to evaluate an arithmetic command, +arithmetic expansion, to evaluate an arithmetic command, to evaluate an indexed array subscript, and to evaluate arguments to the built-in commands .B shift\^ and -.BR let . +.B let\^ +as well as arguments to numeric format specifiers given to +.B "print -f"\^ +and +.BR printf . Evaluations are performed using double precision floating point arithmetic or long double precision floating point for @@ -3059,7 +3065,7 @@ the shell prompts with the value of .SM .B PS1 after expanding it for parameter expansion, command substitution, and -arithmetic substitution, +arithmetic expansion, before reading a command. In addition, each single .B ! @@ -3081,7 +3087,7 @@ is used with the .B [[ compound command to test attributes of files and to compare strings. -Field splitting and file name generation are +Field splitting and pathname expansion are not performed on the words between .B [[ and @@ -3401,12 +3407,12 @@ and are .I not\^ passed on to the invoked command. Command substitution, parameter expansion, -and arithmetic substitution occur before +and arithmetic expansion occur before .I word\^ or .I digit\^ is used except as noted below. -File name generation +Pathname expansion occurs only if the shell is interactive and the pattern matches a single file. Field splitting is not performed. @@ -3497,8 +3503,8 @@ The shell input is read up to a line that is the same as .IR word after any quoting has been removed, or to an end-of-file. -No parameter substitution, command substitution, arithmetic substitution or -file name generation is performed on +No parameter expansion, command substitution, arithmetic expansion or +pathname expansion is performed on .IR word . The resulting document, called a @@ -3510,7 +3516,7 @@ If any character of is quoted, then no interpretation is placed upon the characters of the document; otherwise, parameter expansion, command substitution, and arithmetic -substitution occur, +expansion occur, .B \enew-line is ignored, and @@ -3541,7 +3547,7 @@ purposes of determining the indentation. A short form of here document in which \f2word\fP becomes the contents of the here-document after any parameter expansion, command substitution, and arithmetic -substitution occur. +expansion occur. .TP .BI <& digit The standard input is duplicated from file descriptor @@ -4211,7 +4217,7 @@ the .B trap built-in command below). .SS Execution. -Each time a command is read, the above substitutions +Each time a command is read, the above expansions and substitutions are carried out. If the command name matches one of the @@ -4984,7 +4990,7 @@ Same as .PP .TP 10 .B M-* -Attempt file name generation on the current word. +Attempt pathname expansion on the current word. An asterisk is appended if the word doesn't match any file or contain any special pattern characters. @@ -5443,7 +5449,7 @@ is omitted. .B * Causes an .B * -to be appended to the current word and file name generation attempted. +to be appended to the current word and pathname expansion attempted. If no match is found, it rings the bell. Otherwise, the word is replaced @@ -5604,7 +5610,7 @@ This means that tilde expansion is performed after the .B = sign, array assignments of the form \f2varname\^\fP\f3=(\fP\f2assign_list\^\fP\f3)\fP -are supported, and field splitting and file name generation are not +are supported, and field splitting and pathname expansion are not performed. .PD .TP @@ -7006,11 +7012,11 @@ Requires to truncate a file when turned on. .TP 8 .B \-G -Enables recursive file name generation. +Enables recursive pathname expansion. This adds the double-star pattern .B ** -to the file generation mechanism (see -.I "File Name Generation\^" +to the pathname expansion (see +.I "Pathname Expansion\^" above). By itself, it matches the recursive contents of the current directory, which is to say, all files and directories in the current directory @@ -7035,7 +7041,7 @@ itself and the recursive contents of Symbolic links to non-directories are not followed. Symbolic links to directories are followed if they are specified literally or match a pattern as described under -.IR "File Name Generation\^" , +.IR "Pathname Expansion\^" , but not if they result from a double-star pattern. .TP 8 .B \-H @@ -7071,7 +7077,7 @@ and exit. This mode is disabled while reading profiles. .TP 8 .B \-f -Disables file name generation. +Disables pathname expansion. .TP 8 .B \-h Each command @@ -7134,7 +7140,7 @@ Same as .TP 8 .B globcasedetect When this option is turned on, globbing (see -.I "File Name Generation\^" +.I "Pathname Expansion\^" above) and file name listing and completion (see .I "In-line Editing Options\^" @@ -7179,7 +7185,7 @@ command allows octal numbers starting with On by default if ksh is invoked as \fBsh\fR or \fBrsh\fR. .TP 8 .B markdirs -All directory names resulting from file name generation have a trailing +All directory names resulting from pathname expansion have a trailing .B / appended. .TP 8 @@ -7470,7 +7476,7 @@ not available. Instead, the \f3-a\fP and \f3-o\fP binary operators can be used, but they are fraught with pitfalls due to grammatical ambiguities and therefore deprecated in favor of invoking separate \f3test\fP commands. Most importantly, as \f3test\fP and \f3[\fP are simple regular commands, field -splitting and file name generation \f2are\fP performed on all their +splitting and pathname expansion \f2are\fP performed on all their arguments and all aspects of regular shell grammar (such as redirection) remain active. This is usually harmful, so care must be taken to quote arguments and expansions to avoid this. To avoid the many pitfalls @@ -8333,7 +8339,7 @@ the file named by .B ENV if the file exists, its name being determined by performing parameter expansion, command substitution, -and arithmetic substitution on +and arithmetic expansion on the value of that environment variable. If the .B \-s