From 44be69112c71fe65784cc014995044c2a191a449 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sun, 14 Feb 2021 15:10:15 +0000
Subject:  Apply doc fixes by flexibeast and suggestions by Profpatsch&aranea

---
 doc/dieshdiedie.html      |  6 +++---
 doc/el_semicolon.html     |  2 +-
 doc/el_substitute.html    |  2 +-
 doc/elgetpositionals.html |  2 +-
 doc/execline-shell.html   |  4 ++--
 doc/execlineb.html        |  8 ++++----
 doc/exitcodes.html        |  6 +++---
 doc/export.html           |  2 +-
 doc/fdmove.html           | 11 ++++++++---
 doc/fdreserve.html        |  2 +-
 doc/getcwd.html           |  2 +-
 doc/getpid.html           |  2 +-
 doc/grammar.html          |  4 ++--
 doc/index.html            |  6 +++---
 doc/trap.html             |  2 +-
 15 files changed, 33 insertions(+), 28 deletions(-)

(limited to 'doc')

diff --git a/doc/dieshdiedie.html b/doc/dieshdiedie.html
index 34e4db4..383bcea 100644
--- a/doc/dieshdiedie.html
+++ b/doc/dieshdiedie.html
@@ -16,7 +16,7 @@
 <a href="//skarnet.org/">skarnet.org</a>
 </p>
 
-<h1> Why not just use <tt>/bin/sh</tt>&nbsp;? </h1>
+<h1> Why not just use <tt>/bin/sh</tt>? </h1>
 
 
 <a name="security">
@@ -175,9 +175,9 @@ genius to understand the simplicity", that's because incompetent people
 took advantage of the huge Unix flexibility to write insanely crappy or
 complex software. System administrators can only do a decent job when
 they understand how the programs they run are supposed to work. People
-are slowly starting to grasp this (or are they&nbsp;? We finally managed
+are slowly starting to grasp this (or are they? We finally managed
 to get rid of sendmail and BIND, but GNU/Linux users seem happy to
-welcome the era of D-Bus and systemd. Will we ever learn&nbsp;?) - but even
+welcome the era of D-Bus and systemd. Will we ever learn?) - but even
 <tt>sh</tt>, a seemingly simple and basic Unix program, is hard to
 understand when you lift the cover.
 </p>
diff --git a/doc/el_semicolon.html b/doc/el_semicolon.html
index 31446fe..6519faa 100644
--- a/doc/el_semicolon.html
+++ b/doc/el_semicolon.html
@@ -112,7 +112,7 @@ produce empty words, which may modify your script's execution flow.
 <p>
  You can use the <tt>EXECLINE_STRICT</tt> environment variable to
 check proper block quoting. If that variable contains <tt>1</tt>,
-commands that read blocks will print a warning message everytime
+commands that read blocks will print a warning message every time
 they find an unquoted argument inside a block. If that variable
 contains <tt>2</tt> or a bigger integer, commands will print an
 error message and die on unquoted arguments.
diff --git a/doc/el_substitute.html b/doc/el_substitute.html
index 3bb56a2..6e6decb 100644
--- a/doc/el_substitute.html
+++ b/doc/el_substitute.html
@@ -100,7 +100,7 @@ be substituted, or <em>don't</em> be substituted. </li>
  <li> The default (unquoted) action should be: substitute. </li>
  <li> A sequence that means "do not substitute" should be able
 to appear literally. The quote character should also be able to
-appear literally before a sequence that means "substitute". (Tricky, eh&nbsp;?) </li>
+appear literally before a sequence that means "substitute". (Tricky, eh?) </li>
  <li> There should be as few quote characters as possible, to avoid
 shell-like quoting nightmares. </li>
 </ul>
diff --git a/doc/elgetpositionals.html b/doc/elgetpositionals.html
index 494a69b..88e7b48 100644
--- a/doc/elgetpositionals.html
+++ b/doc/elgetpositionals.html
@@ -68,7 +68,7 @@ equivalent to having <tt>-P&nbsp;0</tt>. </li>
 
 <ul>
  <li> A typical argument-taking execline script will
-often begin that way:
+often begin this way:
 <pre>
  #!/command/execlineb
  elgetopt <em>optstring</em>
diff --git a/doc/execline-shell.html b/doc/execline-shell.html
index 80c52eb..92140c1 100644
--- a/doc/execline-shell.html
+++ b/doc/execline-shell.html
@@ -42,12 +42,12 @@ shell with <tt>$@</tt> as its argument. </li>
 
 <ul>
  <li> <tt>execline-shell</tt> is meant to be used as the <tt>SHELL</tt>
-environment variable value. It allows one to specify his favourite shell and
+environment variable value. It allows one to specify their favourite shell and
 shell configuration in any language, since the <tt>${HOME}/.execline-shell</tt>
 file can be any executable program. <tt>${HOME}/.execline-shell</tt> can be seen
 as a portable <tt>.<em>whatever</em>rc</tt> file. </li>
  <li> As an administrator-modifiable configuration file, <tt>execline-shell</tt>
-provided in execline's <tt>examples/etc/</tt> subdirectory, and should be copied by
+is provided in execline's <tt>examples/etc/</tt> subdirectory, and should be copied by
 the administrator to <tt>/etc</tt>. </li>
 </ul>
 
diff --git a/doc/execlineb.html b/doc/execlineb.html
index da20e4c..fe4f0d3 100644
--- a/doc/execlineb.html
+++ b/doc/execlineb.html
@@ -65,14 +65,14 @@ exits 0. </li>
 
 <ul>
  <li> <em>Pushing the current stack frame.</em> If none of the
-<tt>-p</tt>, <tt>-P</tt>, <tt>-S</tt> or <tt>-s</tt> options is set:
+<tt>-p</tt>, <tt>-P</tt>, <tt>-S</tt> or <tt>-s</tt> options are set:
 <tt>execlineb</tt> <a href="el_pushenv.html">pushes</a>
 the current positional parameters, i.e. environment variables that
 start with <tt>#</tt>, <tt>0</tt>, <tt>1</tt>, ..., <tt>9</tt>.
 To get the previous values back, use
 <a href="emptyenv.html"><tt>emptyenv&nbsp;-P</tt></a>. </li>
  <li> <em>Setting the new stack frame.</em> If none of the <tt>-P</tt>,
-<tt>-S</tt> or <tt>-s</tt> options is set:
+<tt>-S</tt> or <tt>-s</tt> options are set:
  <ul>
   <li> <tt>execlineb</tt> sets the <tt>#</tt> environment variable to
 the number <em>n</em> of <em>args</em> it is given. </li>
@@ -167,7 +167,7 @@ Quoted closing braces do not have that behaviour. </li>
 <em>blevel</em> goes below 0 during the parsing, or is not 0 at the end
 of the script), it exits 100 with an error message. </li>
  <li> <tt>execlineb</tt> automatically quotes
-<a href="el_semicolon.html">blocks</a>. Which means that everytime it
+<a href="el_semicolon.html">blocks</a>. Which means that every time it
 finds a word, it prepends it with <em>blevel</em> spaces. </li>
 </ul>
 
@@ -196,7 +196,7 @@ force it unset, set to 1, or set to 2 by giving respectively the
 
 <p>
  The <tt>EXECLINE_STRICT</tt> variable (as well as the <tt>-q</tt>,
-<tt>-w</tt> and <tt>-W</tt> options to <tt>execlineb</tt> will also modify
+<tt>-w</tt> and <tt>-W</tt> options to <tt>execlineb</tt>) will also modify
 the behaviour of the <tt>-S&nbsp;<em>nmin</em></tt> and <tt>-s&nbsp;<em>nmin</em></tt>
 options when <tt>execlineb</tt> is called with less than <em>nmin</em>
 positional parameters:
diff --git a/doc/exitcodes.html b/doc/exitcodes.html
index 619f5d3..c1fcd24 100644
--- a/doc/exitcodes.html
+++ b/doc/exitcodes.html
@@ -24,7 +24,7 @@
 Either <em>C</em> dies normally with an exit code from 0 to 255, or it is
 killed by a signal.
  How can we make sure that <em>P</em> reports to <em>G</em> what happened
-to <em>C</em>, with as much precision as possible&nbsp;?
+to <em>C</em>, with as much precision as possible?
 </p>
 
 <p>
@@ -33,7 +33,7 @@ structure filled in by
 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/waitpid.html">waitpid()</a>)
 than a process can report by
 simply exiting. <em>P</em> could exit with the same exit code as <em>C</em>,
-but then what should it do if C has been killed by a signal&nbsp;?
+but then what should it do if C has been killed by a signal?
 </p>
 
 <p>
@@ -42,7 +42,7 @@ but then what should it do if C has been killed by a signal&nbsp;?
 But that's actually not right, because <em>P</em> itself could be killed by a
 signal from another source, and G needs that information. "<em>P</em> has been
 killed by a signal" and "<em>C</em> has been killed by a signal" are two
-different informations, so they should not be reported in the same way.
+different pieces of information, so they should not be reported in the same way.
 </p>
 
 <p>
diff --git a/doc/export.html b/doc/export.html
index 1cf9127..06de067 100644
--- a/doc/export.html
+++ b/doc/export.html
@@ -36,7 +36,7 @@ its arguments.
 </p>
 
 <ul>
- <li> <em>var</em> must be given without a dollar&nbsp;! </li>
+ <li> <em>var</em> must be given without a dollar! </li>
  <li> <em>var</em> must not contain the character <tt>=</tt> . </li>
 </ul>
 
diff --git a/doc/fdmove.html b/doc/fdmove.html
index 39bdb2b..00a70f0 100644
--- a/doc/fdmove.html
+++ b/doc/fdmove.html
@@ -46,10 +46,15 @@ instead of moving it; do not close <em>fdfrom</em>. </li>
 <h2> Notes </h2>
 
 <ul>
- <li> <tt>fdmove -c <em>a</em> <em>b</em> prog...</tt> is roughly equivalent to
-<tt>sh -c 'exec prog... <em>a</em>&gt;&amp;<em>b</em>'</tt></li>
  <li> <tt>fdmove <em>a</em> <em>b</em> prog...</tt> is roughly equivalent to
-<tt>sh -c 'exec prog... <em>a</em>&gt;&amp;<em>b</em> <em>b</em>&lt;&amp;-'</tt></li>
+<tt>sh -c 'exec prog... <em>a</em>&gt;&amp;<em>b</em> <em>b</em>&lt;&amp;-'</tt>.
+It means: if you write to fd <em>a</em> now, it will have the same effect as writing
+to fd <em>b</em> beforehand, and you cannot write to fd <em>b</em> anymore. </li>
+ <li> <tt>fdmove -c <em>a</em> <em>b</em> prog...</tt> is roughly equivalent to
+<tt>sh -c 'exec prog... <em>a</em>&gt;&amp;<em>b</em>'</tt>. It means: you can
+now write to fd <em>a</em>, and also still write to fd <em>b</em>, and both will have
+the same effect as writing to fd <em>b</em> beforehand. </li>
+ <li> It also works with file descriptors that are open for reading! </li>
 </ul>
 
 </body>
diff --git a/doc/fdreserve.html b/doc/fdreserve.html
index 2412b5e..ab9cf59 100644
--- a/doc/fdreserve.html
+++ b/doc/fdreserve.html
@@ -52,7 +52,7 @@ use:
  {
    importas fdr FD0
    importas fdw FD1
-  }
+ }
  piperw $fdr $fdw
  <em>prog...</em>
 </pre>
diff --git a/doc/getcwd.html b/doc/getcwd.html
index d3e7e27..62701c6 100644
--- a/doc/getcwd.html
+++ b/doc/getcwd.html
@@ -50,7 +50,7 @@ line instead of putting it into the environment. </li>
 <h2> Notes </h2>
 
 <ul>
- <li> <em>var</em> must be given without a dollar&nbsp;! </li>
+ <li> <em>var</em> must be given without a dollar! </li>
  <li> <em>var</em> must not contain <tt>=</tt>. </li>
  <li> Unlike the
 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pwd.html">pwd</a>
diff --git a/doc/getpid.html b/doc/getpid.html
index 5a849e8..ef1410c 100644
--- a/doc/getpid.html
+++ b/doc/getpid.html
@@ -47,7 +47,7 @@ line instead of putting it into the environment. </li>
 <h2> Notes </h2>
 
 <ul>
- <li> <em>var</em> must be given without a dollar&nbsp;! </li>
+ <li> <em>var</em> must be given without a dollar! </li>
  <li> <em>var</em> must not contain <tt>=</tt>. </li>
 </ul>
 
diff --git a/doc/grammar.html b/doc/grammar.html
index 419c13e..74ee60f 100644
--- a/doc/grammar.html
+++ b/doc/grammar.html
@@ -69,10 +69,10 @@ and 128&nbsp;KB on Linux. </li>
 <p>
  Knowing that, and wanting lightweight and efficient scripts, I
 wondered: "Why should the interpreter stay in memory while the script
-is executing&nbsp;? Why not parse the script once and for all, put
+is executing? Why not parse the script once and for all, put
 it all into one <em>argv</em>, and just execute into that <em>argv</em>,
 relying on external commands (which will be called from within the
-script) to control the execution flow&nbsp;?"
+script) to control the execution flow?"
 </p>
 
 <p> <tt>execline</tt> was born. </p>
diff --git a/doc/index.html b/doc/index.html
index 8222a48..c3b647b 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -17,10 +17,10 @@
 
 <h1> execline </h1>
 
-<h2> What is it&nbsp;? </h2>
+<h2> What is it? </h2>
 
 <p>
- execline is a (non-interactive) scripting language, like <tt>sh</tt>&nbsp;;
+ execline is a (non-interactive) scripting language, like <tt>sh</tt> -
 but its syntax is quite different from a traditional shell syntax.
 The <tt>execlineb</tt> program is meant to be used as an interpreter for a
 text file; the other commands are essentially useful inside an
@@ -38,7 +38,7 @@ shell's syntax, and has no security issues.
 
 <ul>
 <li> <a href="grammar.html">The execline design and grammar</a></li>
-<li> <a href="dieshdiedie.html">Why not just use <tt>/bin/sh</tt>&nbsp;?</a></li>
+<li> <a href="dieshdiedie.html">Why not just use <tt>/bin/sh</tt>?</a></li>
 </ul>
 
 <hr />
diff --git a/doc/trap.html b/doc/trap.html
index 1a6e9df..9351c93 100644
--- a/doc/trap.html
+++ b/doc/trap.html
@@ -86,7 +86,7 @@ this option does nothing. </li>
 <code><a href="importas.html">importas</a> ! !</code> to retrieve the pid of
 <em>prog</em> in <tt>$!</tt>. If they need the signal number, which
 can be the case in <tt>default</tt> directives, they can for instance use
-<code><a href="multisubstitute.html">multisubstitute</a> { importas ! ! importas SIGNAL SIGNAL }<code>
+<code><a href="multisubstitute.html">multisubstitute</a> { importas ! ! importas SIGNAL SIGNAL }</code>
 to get both <tt>$!</tt> and <tt>$SIGNAL</tt> substitutions. </li>
  <li> The <tt>-x</tt> option is basically a shortcut for a <code>default {
 multisubstitute { importas ! ! importas SIGNAL SIGNAL } kill -$SIGNAL $! }</code> directive. </li>
-- 
cgit v1.3.1