From: Andre Noll <maan@tuebingen.mpg.de>
Date: Thu, 2 Jun 2016 12:43:54 +0000 (+0200)
Subject: manual: Improve documentation of --output.
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=4884395952589ec5310ad6220928d4bd25ab10cb;p=adu.git

manual: Improve documentation of --output.

The three redirection features of --output are useless for select
mode since these redirections can also be created by the shell.

This commit adds a paragraph which clarifies this. We use the
opportunity to reword the remaining text for the option slightly.
---

diff --git a/select.ggo b/select.ggo
index d966095..d7f8c93 100644
--- a/select.ggo
+++ b/select.ggo
@@ -134,28 +134,32 @@ string typestr="path"
 optional
 default="-"
 details="
-	If empty, or not given, use stdout. The following conventions
-	cause the output to be written differently:
-
-	An output file name of \"-\" means stdout.
-
-	\"path\" may be prepended by '>' which instructs adu to
-	truncate the output file to length zero.  If \"path\" does
-	not start with '>' and \"path\" already exists, the select
-	query is being aborted. Otherwise, \"path\" is created and
-	output is written to \"path\".
-
-	If the first two characters of \"path\" are '>', the output
-	file (given by removing the leading \">>\" from \"path\")
-	is being opened in append mode. It is no error if the output
-	file does not exist but, as above, the output file name \">>\"
-	is considered invalid.
-
-	If the first character of \"path\" is '|', a pipe is created
-	and the rest of \"path\" is being executed with its standard in
-	redirected to the reading end of the pipe. The output of adu
-	is written to the writing end of the pipe. Again, specifying
-	only \"|\" is considered invalid and causes an error.
+	This option is only useful in interactive mode. If stdin is redirected
+	from a script, and the script contains several queries one can use
+	this option to let each query write its output to a different file.
+
+	If the option is not given, or its argument is either \"-\" or the
+	empty string, stdout is assumed. The following conventions cause the
+	output to be written in a different way:
+
+	\"path\" may be prepended by '>' which instructs adu to truncate
+	the output file to length zero. If \"path\" does not start with
+	'>' and \"path\" already exists, the query is aborted. Otherwise,
+	the file is created and truncated. The output file name \">\" is
+	considered invalid.
+
+	If the first two characters of \"path\" are '>', the output file
+	(given by removing the leading \">>\" from \"path\") is opened in
+	append mode. It is no error if the output file does not exist. However,
+	as above the output file name \">>\" is considered invalid.
+
+	If the first character of \"path\" is '|', a pipe is created and the
+	rest of \"path\" is executed with stdin redirected to the reading
+	end of the pipe while the query output is written to the writing end
+	of the pipe. Again, specifying only \"|\" is considered invalid and
+	causes an error.
+
+	See the manual page for examples.
 "
 
 option "user-summary-sort" -