Package: dash
Version: 0.5.12-6
Severity: minor
Tags: patch upstream
tl;dr: This patch restores the ability to search manpages for text
containing ASCII hyphens, like "-V" or ">&-", using pagers like "less".
nroff can render 4 distinct dash characters, if non-ASCII output is
supported (as in modern Debian, unless suppressed with, e.g.,
"export MANOPT=-Eascii"):
\- ASCII hyphen.
Use: Any place one would type a literal ASCII hyphen:
"ls \-F", "$((OPTIND \- 1))", "chdir \-"
- non-ASCII hyphen
Use: Phrases like "POSIX-compliant", "human-readable", "built-in".
Also used by nroff to break a word of text across 2 lines.
\(en en dash (the width of "n").
Use: Very rare. I think it's a mathematical minus sign, but of
course it's not used in $(( )) shell expressions.
\(em em dash (traditionally, the width of lowercase "m").
Use: To break up grammatical phrases: "the shell executes the
command asynchronously \(em that is, the shell does not wait for
the command to finish"
The - vs. \- distinction especially matters, because if you search for
"<<-" by typing "/<<-" into "less", but nroff has used a non-ASCII
hyphen there, it will not find it.
(Also, some older X11 fonts don't have the non-ASCII dash chars. Though
that has an easy workaround, "MANOPT=-Eascii".)
Thanks,
Peter
From: Peter Samuelson <pet...@p12n.org>
Date: Tue, 19 Sep 2023 11:53:05 -0500
Subject: Fix manpage dashes (ASCII '-' / hyphen / en dash / em dash)
Directs nroff to use ASCII "-" to document the shell's uses of "-".
This ensures that expressions like "-V" and ">&-" are searchable using
pagers like "less".
(Also changes some \(en to \(em for correctness, but that is purely
cosmetic.)
--- a/src/dash.1
+++ b/src/dash.1
@@ -124,7 +124,7 @@ An interactive shell generally prompts b
programming and command errors differently (as described below).
When first starting,
the shell inspects argument 0, and if it begins with a dash
-.Sq - ,
+.Sq \- ,
the shell is also considered
a login shell.
This is normally done automatically by the system
@@ -176,7 +176,7 @@ The set
name is provided next to the single letter option in
the description below.
Specifying a dash
-.Dq -
+.Dq \-
turns the option on, while using a plus
.Dq +
disables the option.
@@ -270,7 +270,7 @@ Following is a list of operators:
.It "Control operators:"
.Dl & && \&( \&) \&; ;; | || \*[Lt]newline\*[Gt]
.It "Redirection operators:"
-.Dl \*[Lt] \*[Gt] \*[Gt]| \*[Lt]\*[Lt] \*[Gt]\*[Gt] \*[Lt]& \*[Gt]&
\*[Lt]\*[Lt]- \*[Lt]\*[Gt]
+.Dl \*[Lt] \*[Gt] \*[Gt]| \*[Lt]\*[Lt] \*[Gt]\*[Gt] \*[Lt]& \*[Gt]&
\*[Lt]\*[Lt]\- \*[Lt]\*[Gt]
.El
.Ss Quoting
Quoting is used to remove the special meaning of certain characters or
@@ -323,14 +323,14 @@ If it does, it replaces it in the input
For example, if there is an alias called
.Dq lf
with the value
-.Dq "ls -F" ,
+.Dq "ls \-F" ,
then the input:
.Pp
.Dl lf foobar Aq return
.Pp
would become
.Pp
-.Dl ls -F foobar Aq return
+.Dl ls \-F foobar Aq return
.Pp
Aliases provide a convenient way for naive users to create shorthands for
commands without having to learn how to create functions with arguments.
@@ -404,12 +404,12 @@ Redirect standard input (or n) from file
.It [n1] Ns \*[Lt]& Ns n2
Copy file descriptor n2 as stdout (or fd n1).
fd n2.
-.It [n] Ns \*[Lt]&-
+.It [n] Ns \*[Lt]&\-
Close standard input (or n).
.It [n1] Ns \*[Gt]& Ns n2
Copy file descriptor n2 as stdin (or fd n1).
fd n2.
-.It [n] Ns \*[Gt]&-
+.It [n] Ns \*[Gt]&\-
Close standard output (or n).
.It [n] Ns \*[Lt]\*[Gt] file
Open file for reading and writing on standard input (or n).
@@ -433,13 +433,13 @@ subjected to parameter expansion, comman
expansion (as described in the section on
.Dq Expansions ) .
If the operator is
-.Dq \*[Lt]\*[Lt]-
+.Dq \*[Lt]\*[Lt]\-
instead of
.Dq \*[Lt]\*[Lt] ,
then leading tabs in the here-doc-text are stripped.
.Ss Search and Execution
There are three types of commands: shell functions, builtin commands, and
-normal programs \(en and the command is searched for (by name) in that order.
+normal programs \(em and the command is searched for (by name) in that order.
They each are executed in a different way.
.Pp
When a shell function is executed, all of the shell positional parameters
@@ -578,11 +578,11 @@ the preceding AND-OR-list.
.Pp
Note that unlike some other shells, each process in the pipeline is a
child of the invoking shell (unless it is a shell builtin, in which case
-it executes in the current shell \(en but any effect it has on the
+it executes in the current shell \(em but any effect it has on the
environment is wiped).
-.Ss Background Commands \(en &
+.Ss Background Commands \(em &
If a command is terminated by the control operator ampersand (&), the
-shell executes the command asynchronously \(en that is, the shell does not
+shell executes the command asynchronously \(em that is, the shell does not
wait for the command to finish before executing the next command.
.Pp
The format for running a command in background is:
@@ -592,7 +592,7 @@ The format for running a command in back
If the shell is not interactive, the standard input of an asynchronous
command is set to
.Pa /dev/null .
-.Ss Lists \(en Generally Speaking
+.Ss Lists \(em Generally Speaking
A list is a sequence of zero or more commands separated by newlines,
semicolons, or ampersands, and optionally terminated by one of these three
characters.
@@ -615,7 +615,7 @@ of the first command is nonzero.
and
.Dq ||
both have the same priority.
-.Ss Flow-Control Constructs \(en if, while, for, case
+.Ss Flow-Control Constructs \(em if, while, for, case
The syntax of the if command is
.Bd -literal -offset indent
if list
@@ -720,7 +720,7 @@ Variables may be declared to be local to
command.
This should appear as the first statement of a function, and the syntax is
.Pp
-.Dl local [ variable | - ] ...
+.Dl local [ variable | \- ] ...
.Pp
Local is implemented as a builtin command.
.Pp
@@ -734,9 +734,9 @@ inside g will refer to the variable x de
variable named x.
.Pp
The only special parameter that can be made local is
-.Dq - .
+.Dq \- .
Making
-.Dq -
+.Dq \-
local any shell options that are changed via the set command inside the
function to be restored to their original values when the function
returns.
@@ -757,7 +757,7 @@ New variables can be set using the form
.Dl name=value
.Pp
Variables set by the user must have a name consisting solely of
-alphabetics, numerics, and underscores - the first of which must not be
+alphabetics, numerics, and underscores \(em the first of which must not be
numeric.
A parameter can also be denoted by a number or a special
character as explained below.
@@ -809,7 +809,7 @@ the two arguments:
Expands to the number of positional parameters.
.It ?
Expands to the exit status of the most recent pipeline.
-.It - (Hyphen.)
+.It \- (Hyphen.)
Expands to the current option flags (the single-letter
option names concatenated into a string) as specified on
invocation, by the set builtin command, or implicitly
@@ -904,7 +904,7 @@ expansion, with the exception of @.
In addition, a parameter expansion can be modified by using one of the
following formats.
.Bl -tag -width aaparameterwordaaaaa
-.It ${parameter:-word}
+.It ${parameter:\-word}
Use Default Values.
If parameter is unset or null, the expansion of word
is substituted; otherwise, the value of parameter is substituted.
@@ -1145,7 +1145,7 @@ Do not execute the command but
search for the command and print the absolute pathname
of utilities, the name for builtins or the expansion of aliases.
.El
-.It cd|chdir Ar -
+.It cd|chdir Ar \-
.It Xo cd|chdir Op Fl LP
.Op Ar directory
.Xc
@@ -1300,7 +1300,7 @@ the first and last operands, as affected
.Fl r ,
with each command preceded by the command number.
.It Fl n
-Suppress command numbers when listing with -l.
+Suppress command numbers when listing with \-l.
.It Fl r
Reverse the order of the commands listed (with
.Fl l )
@@ -1439,7 +1439,7 @@ do
\\?) echo $USAGE; exit 1;;
esac
done
-shift $((OPTIND - 1))
+shift $((OPTIND \- 1))
.Ed
.Pp
This code will accept any of the following as equivalent:
@@ -1447,7 +1447,7 @@ This code will accept any of the followi
.Bd -literal -offset indent
cmd \-acarg file file
cmd \-a \-c arg file file
-cmd \-carg -a file file
+cmd \-carg \-a file file
cmd \-a \-carg \-\- file file
.Ed
.It hash Op Ar command ...
@@ -1477,7 +1477,7 @@ Display the status of all, or just the s
.Bl -tag -compact -offset 5n -width "By default"
.It By default
display the job number, currency
-.Pq Sy +-
+.Pq Sy +\-
status, if any, the job state, and its shell command.
.It Fl l
also output the PID of the group leader, and just the PID and shell commands
@@ -1816,7 +1816,7 @@ a field; padding takes place only if the
the actual width.
.It Xo set
.Oo {
-.Fl options | Cm +options | Cm -- }
+.Fl options | Cm +options | Cm \-\- }
.Oc Ar arg ...
.Xc
The
@@ -1828,9 +1828,9 @@ With no arguments, it lists the values o
If options are given, it sets the specified option
flags, or clears them as described in the section called
.Sx Argument List Processing .
-As a special case, if the option is -o or +o and no argument is
+As a special case, if the option is \-o or +o and no argument is
supplied, the shell prints the settings of all its options.
-If the option is -o,
+If the option is \-o,
the settings are printed in a human-readable format;
if the option is +o,
the settings are printed in a format suitable for
@@ -1840,7 +1840,7 @@ The third use of the set command is to s
positional parameters to the specified args.
To change the positional
parameters without changing any options, use
-.Dq --
+.Dq \-\-
as the first argument to set.
If no args are present, the set command
will clear all the positional parameters (equivalent to executing
@@ -2130,7 +2130,7 @@ may be empty
which causes the specified signals to be ignored.
With
.Ar action
-omitted or set to `-' the specified signals are set to their default action.
+omitted or set to `\-' the specified signals are set to their default action.
When the shell forks off a subshell, it resets trapped (but not ignored)
signals to the default action.
The
@@ -2279,7 +2279,7 @@ can be edited using vi-mode command-line
This mode uses commands, described below,
similar to a subset of those described in the vi man page.
The command
-.Ql set -o vi
+.Ql set \-o vi
enables vi-mode editing and places sh into vi insert mode.
With vi-mode
enabled, sh can be switched between insert mode and command mode.
@@ -2342,7 +2342,7 @@ unless you are the superuser, in which c
The secondary prompt string, which defaults to
.Dq \*[Gt]\ .
.It Ev PS4
-Output before each line when execution trace (set -x) is enabled,
+Output before each line when execution trace (set \-x) is enabled,
defaults to
.Dq +\ .
.It Ev IFS
