doc: improve Examples (#7428)

1 files changed, 20 insertions, 8 deletions

diff --git a/docs/examples/unix_cat.md b/docs/examples/unix_cat.md
index efec9e3fb..f93d9c94d 100644
--- a/docs/examples/unix_cat.md
+++ b/docs/examples/unix_cat.md
@@ -1,9 +1,26 @@
-## An implementation of the unix "cat" program
+# An implementation of the unix "cat" program
+
+## Concepts
+
+- Use the Deno runtime API to output the contents of a file to the console
+- [Deno.args](https://doc.deno.land/builtin/stable#Deno.args) accesses the
+  command line arguments
+- [Deno.open](https://doc.deno.land/builtin/stable#Deno.open) is used to get a
+  handle to a file
+- [Deno.copy](https://doc.deno.land/builtin/stable#Deno.copy) is used to
+  transfer data from the file to the output stream
+- Files should be closed when you are finished with them
+- Modules can be run directly from remote URLs
+
+## Example
 
 In this program each command-line argument is assumed to be a filename, the file
-is opened, and printed to stdout.
+is opened, and printed to stdout (e.g. the console).
 
 ```ts
+/**
+ * cat.ts
+ */
 for (let i = 0; i < Deno.args.length; i++) {
   const filename = Deno.args[i];
   const file = await Deno.open(filename);
@@ -12,12 +29,7 @@ for (let i = 0; i < Deno.args.length; i++) {
 }
 ```
 
-The `copy()` function here actually makes no more than the necessary kernel ->
-userspace -> kernel copies. That is, the same memory from which data is read
-from the file, is written to stdout. This illustrates a general design goal for
-I/O streams in Deno.
-
-Try the program:
+To run the program:
 
 ```shell
 deno run --allow-read https://deno.land/std@$STD_VERSION/examples/cat.ts /etc/passwd