README [skip ci]

doc/io-flags.md

@@ -6,7 +6,8 @@ which binds `*input*` to a lazy seq of lines of text. If you want to read
 multiple EDN values, use the `-I` flag. The `-o` option prints the result as
 lines of text. The `-O` option prints the result as lines of EDN values.
 
-> **Note:** `*input*` is only available in the `user` namespace, on other namespaces use `*in*`.
+> **Note:** `*input*` is only available in the `user` namespace, designed for
+> one-liners. For writing scripts, see [scripts](#scripts).
 
 The following table illustrates the combination of options for commands of the form
 
@@ -28,11 +29,13 @@ $ echo '{:a 1} {:a 2}' | bb --stream '*input*'
 {:a 2}
 ```
 
-When writing Clojure scripts that should be fully portable with the JVM, it is
-not recommended to use in- and output flags and `*input*` since those are not
-available in standard Clojure. Here is how you can rewrite:
+## Scripts
 
-## EDN input
+When writing scripts instead of one-liners on the command line, it is not
+recommended to use `*input*`. Here is how you can rewrite to standard Clojure
+code.
+
+### EDN input
 
 Reading a single EDN value from stdin:
 
@@ -54,7 +57,7 @@ Reading multiple EDN values from stdin (the `-I` flag):
   (take-while #(not (identical? ::eof %)) (repeatedly #(edn/read {:eof ::eof} reader))))
 ```
 
-## Text input
+### Text input
 
 Reading text from stdin can be done with `(slurp *in*)`. To get a lazy seq of
 lines (the `-i` flag), you can use:
@@ -66,6 +69,6 @@ lines (the `-i` flag), you can use:
 (line-seq (io/reader *in*))
 ```
 
-## Output
+### Output
 
 To print to stdout, use `println` for text and `prn` for EDN values.