From 49b387bb53e76eecd2b6cf4f89f3146fc2198bd3 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Tue, 24 Nov 2020 17:56:57 +0000
Subject:  Fix chomping: only make it default on line-processing binaries

---
 doc/forstdin.html | 41 ++++++++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 13 deletions(-)

(limited to 'doc/forstdin.html')

diff --git a/doc/forstdin.html b/doc/forstdin.html
index 44939fe..74644b4 100644
--- a/doc/forstdin.html
+++ b/doc/forstdin.html
@@ -30,7 +30,7 @@ run another program.
 </p>
 
 <pre>
-     forstdin [ -p | -o <em>okcodes</em> | -x <em>breakcodes</em> ] [ -E firsteofcode ] [ -e eofcode ] [ -n ] [ -C | -c ] [ -0 | -d <em>delim</em> ] <em>variable</em> <em>loop...</em>
+     forstdin [ -p | -o <em>okcodes</em> | -x <em>breakcodes</em> ] [ -N | -n ] [ -C | -c ] [ -0 | -d <em>delim</em> ] <em>variable</em> <em>loop...</em>
 </pre>
 
 <ul>
@@ -50,9 +50,6 @@ and 1 if it hasn't read anything. </li>
 instance to finish before spawning the next one. forstdin will
 still wait for all instances of <em>loop</em> to terminate before
 exiting, though. </li>
- <li> <tt>-0</tt>&nbsp;: accept null characters on its stdin,
-using them as delimiters. If this option and a <tt>-d</tt> option are
-used simultaneously, the rightmost one wins. </li>
  <li> <tt>-o</tt>&nbsp;<em>okcodes</em>&nbsp;: <em>okcodes</em> must
 be a comma-separated list of exit codes. If the <tt>-p</tt> flag
 hasn't been given and <em>loop</em> exits with one of the codes in
@@ -64,15 +61,33 @@ not listed in <em>okcodes</em>, forstdin will exit immediately with an
 option, but with inverted meaning - the listed exit codes are codes
 that will make forstdin break the loop and exit, and the unlisted exit
 codes will make it keep looping. </li>
- <li> <tt>-E</tt>&nbsp;<em>firsteofcode</em>&nbsp;: if forstdin encounters
-EOF on its first attempt to read data, exit <em>firsteofcode</em>. Default is 1. </li>
- <li> <tt>-e</tt>&nbsp;<em>eofcode</em>&nbsp;: if forstdin has already
-read data, and encounters EOF, exit <em>eofcode</em>. Default is 0. </li>
- <li> Other options are used to <a href="el_transform.html">control
-the substitution mechanism</a> for every <em>x</em>. Of course, you can't
-split <em>x</em>. The default delimiter for <tt>forstdin</tt> is a
-newline; you need a <tt>-d</tt> option to split <em>x</em> around
-other values. </li>
+</ul>
+
+<p>
+ Other options are similar (in name and functionality) to the switches
+passed to <a href="el_transform.html">control a substitution mechanism</a>,
+on purpose; however, <tt>forstdin</tt> does not call the substitution
+mechanism and has its own semantics for those options.
+</p>
+
+<ul>
+ <li> <tt>-N</tt>&nbsp;: store the whole line in <em>variable</em>,
+including the terminating newline (or other delimiter). </li>
+ <li> <tt>-n</tt>&nbsp;: chomp a terminating delimiter from the line from
+stdin before storing it into <em>variable</em>. This is the default. </li>
+ <li> <tt>-C</tt>&nbsp;: crunch. If there is an empty line (i.e. that
+only contains a delimiter), do not call <em>loop</em>. If this option is
+given, <em>and</em> chomping is active, <em>and</em> the last line of stdin
+is not terminated by a delimiter, then this last line will not be processed. </li>
+ <li> <tt>-c</tt>&nbsp;: do not crunch, call <em>loop</em> even if
+the line is empty. This is the default. </li>
+ <li> <tt>-0</tt>&nbsp;: accept null characters on its stdin,
+using them as delimiters. If this option and a <tt>-d</tt> option are
+used simultaneously, the rightmost one wins. </li>
+ <li> <tt>-d&nbsp;<em>delim</em></tt>&nbsp;: use the characters in string
+<em>delim</em> as delimiters for a line. Default is "<tt>\n</tt>", meaning
+the input is only split on newlines. </li>
+ <li>
 </ul>
 
 <h2> Notes </h2>
-- 
cgit v1.2.3