ensure tests work when `stdout` is not the console

ensure this case is continuously tested on travis.

Update documentation on implicit output,
invite to not rely on implicit output in scripts.

4 files changed, 18 insertions, 18 deletions

diff --git a/.travis.yml b/.travis.yml
index 301d294..2065478 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -8,7 +8,7 @@ matrix:
       os: osx
       compiler: clang
       script:
-        - make -C tests test-lz4 MOREFLAGS='-Werror -Wconversion -Wno-sign-conversion'
+        - make -C tests test-lz4 MOREFLAGS='-Werror -Wconversion -Wno-sign-conversion' | tee # test scenario where `stdout` is not the console
         - CFLAGS=-m32 make -C tests clean test-lz4-contentSize
 
     # Container-based 12.04 LTS Server Edition 64 bit (doesn't support 32-bit includes)
diff --git a/programs/lz4.1.md b/programs/lz4.1.md
index 10449a0..ffda3ff 100644
--- a/programs/lz4.1.md
+++ b/programs/lz4.1.md
@@ -31,29 +31,29 @@ The native file format is the `.lz4` format.
 `lz4` supports a command line syntax similar _but not identical_ to `gzip(1)`.
 Differences are :
 
-  * `lz4` preserves original files
   * `lz4` compresses a single file by default (see `-m` for multiple files)
   * `lz4 file1 file2` means : compress file1 _into_ file2
   * `lz4 file.lz4` will default to decompression (use `-z` to force compression)
+  * `lz4` preserves original files
   * `lz4` shows real-time notification statistics
      during compression or decompression of a single file
      (use `-q` to silence them)
-  * If no destination name is provided, result is sent to `stdout`
-    _except if stdout is the console_.
-  * If no destination name is provided, __and__ if `stdout` is the console,
-    `file` is compressed into `file.lz4`.
-  * As a consequence of previous rules, note the following example :
-    `lz4 file | consumer` sends compressed data to `consumer` through `stdout`,
-    hence it does _not_ create `file.lz4`.
-  * Another consequence of those rules is that to run `lz4` under `nohup`,
-    you should provide a destination file: `nohup lz4 file file.lz4`,
-    because `nohup` writes the specified command's output to a file.
+  * When no destination is specified, result is sent on implicit output,
+    which depends on `stdout` status.
+    When `stdout` _is Not the console_, it becomes the implicit output.
+    Otherwise, if `stdout` is the console, the implicit output is `filename.lz4`.
+  * It is considered bad practice to rely on implicit output in scripts.
+    because the script's environment may change.
+    Always use explicit output in scripts.
+    `-c` ensures that output will be `stdout`.
+    Conversely, providing a destination name, or using `-m`
+    ensures that the output will be either the specified name, or `filename.lz4` respectively.
 
 Default behaviors can be modified by opt-in commands, detailed below.
 
   * `lz4 -m` makes it possible to provide multiple input filenames,
     which will be compressed into files using suffix `.lz4`.
-    Progress notifications are also disabled by default (use `-v` to enable them).
+    Progress notifications become disabled by default (use `-v` to enable them).
     This mode has a behavior which more closely mimics `gzip` command line,
     with the main remaining difference being that source files are preserved by default.
   * Similarly, `lz4 -m -d` can decompress multiple `*.lz4` files.
@@ -81,8 +81,7 @@ In some cases, some options can be expressed using short command `-x`
 or long command `--long-word`.
 Short commands can be concatenated together.
 For example, `-d -c` is equivalent to `-dc`.
-Long commands cannot be concatenated.
-They must be clearly separated by a space.
+Long commands cannot be concatenated. They must be clearly separated by a space.
 
 ### Multiple commands
 
diff --git a/programs/lz4cli.c b/programs/lz4cli.c
index 279aaf1..82f2fac 100644
--- a/programs/lz4cli.c
+++ b/programs/lz4cli.c
@@ -655,8 +655,9 @@ int main(int argc, const char** argv)
 
         if (!IS_CONSOLE(stdout)) {
             /* Default to stdout whenever stdout is not the console.
-             * Note : this policy is likely to change in the future, don't rely on it !
-             * prefer using an explicit `-c` flag */
+             * Note : this policy may change in the future, therefore don't rely on it !
+             * To ensure `stdout` is explicitly selected, use `-c` command flag.
+             * Conversely, to ensure output will not become `stdout`, use `-m` command flag */
             DISPLAYLEVEL(1, "Warning : using stdout as default output. Do not rely on this behavior: use explicit `-c` instead ! \n");
             output_filename=stdoutmark;
             break;
diff --git a/tests/Makefile b/tests/Makefile
index 209a530..ddc6d1e 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -317,7 +317,7 @@ test-lz4-basic: lz4 datagen unlz4 lz4cat
 	! $(LZ4) -c --fast=-1 tmp-tlb-dg20K # lz4 should fail when fast=-1
 	# Test for #596
 	@echo "TEST" > tmp-tlb-test
-	$(LZ4) tmp-tlb-test
+	$(LZ4) -m tmp-tlb-test
 	$(LZ4) tmp-tlb-test.lz4 tmp-tlb-test2
 	$(DIFF) -q tmp-tlb-test tmp-tlb-test2
 	@$(RM) tmp-tlb*