Rename chapter 12 and fix a bunch of errors in that chapter

Chapter 12 was called just "IO" but explained both how to do IO in Elixir as
well as how to interact with files and the file system (the File and Path
modules). The new title - "IO and the file system" - reflects
exactly that.

Author: whatyouhide

_layouts/getting_started.html

@@ -21,7 +21,7 @@ <h3 class="widget-title">Getting Started</h3>
       <li><a class="spec" href="/getting_started/9.html">Recursion</a></li>
       <li><a class="spec" href="/getting_started/10.html">Enumerables and streams</a></li>
       <li><a class="spec" href="/getting_started/11.html">Processes</a></li>
-      <li><a class="spec" href="/getting_started/12.html">IO</a></li>
+      <li><a class="spec" href="/getting_started/12.html">IO and the file system</a></li>
       <li><a class="spec" href="/getting_started/13.html">alias, require and import</a></li>
       <li><a class="spec" href="/getting_started/14.html">Module attributes</a></li>
       <li><a class="spec" href="/getting_started/15.html">Structs</a></li>

getting_started/12.markdown

@@ -1,20 +1,20 @@
 ---
 layout: getting_started
-title: 12 IO
+title: 12 IO and the file system
 guide: 12
 ---
 
 # {{ page.title }}
 
 {% include toc.html %}
 
-This chapter is a quick introduction to input/output mechanisms in Elixir and related modules, like [`IO`](/docs/stable/elixir/IO.html), [`File`](/docs/stable/elixir/File.html) and [`Path`](/docs/stable/elixir/Path.html).
+This chapter is a quick introduction to input/output mechanisms and file-system-related tasks, as well as to related modules like [`IO`](/docs/stable/elixir/IO.html), [`File`](/docs/stable/elixir/File.html) and [`Path`](/docs/stable/elixir/Path.html).
 
 We had originally sketched this chapter to come much earlier in the getting started guide. However, we noticed the IO system provides a great opportunity to shed some light on some philosophies and curiosities of Elixir and the VM.
 
-## 12.1 The IO module
+## 12.1 The `IO` module
 
-The `IO` module in Elixir is the main mechanism for reading and writing to the standard io (`:stdio`), standard error (`:stderr`), files and other IO devices. Usage of the module is pretty straight-forward:
+The `IO` module is the main mechanism in Elixir for reading and writing to standard input/output (`:stdio`), standard error (`:stderr`), files and other IO devices. Usage of the module is pretty straightforward:
 
 ```iex
 iex> IO.puts "hello world"
@@ -25,17 +25,17 @@ yes or no? yes
 "yes\n"
 ```
 
-By default, the functions in the IO module use the standard input and output. We can pass the `:stderr` as argument to write to the standard error device:
+By default, functions in the IO module read from the standard input and write to the standard output. We can change that by passing, for example, `:stderr` as an argument (in order to write to the standard error device):
 
 ```iex
 iex> IO.puts :stderr, "hello world"
 hello world
 :ok
 ```
 
-## 12.2 The File module
+## 12.2 The `File` module
 
-The [`File`](/docs/stable/elixir/File.html) module contains functions that allows us to open files as IO devices. By default, files are opened in binary mode, which requires developers to use the specific `IO.binread/2` and `IO.binwrite/2` functions from the `IO` module:
+The [`File`](/docs/stable/elixir/File.html) module contains functions that allow us to open files as IO devices. By default, files are opened in binary mode, which requires developers to use the specific `IO.binread/2` and `IO.binwrite/2` functions from the `IO` module:
 
 ```iex
 iex> {:ok, file} = File.open "hello", [:write]
@@ -48,16 +48,11 @@ iex> File.read "hello"
 {:ok, "world"}
 ```
 
-A file can also be opened with `:utf8` encoding which allows the remaining functions in the `IO` module to be used:
+A file can also be opened with `:utf8` encoding, which tells the `File` module to interpret the bytes read from the file as UTF-8-encoded bytes.
 
-```iex
-iex> {:ok, file} = File.open "another", [:write, :utf8]
-{:ok, #PID<0.48.0>}
-```
-
-Besides functions for opening, reading and writing files, the `File` module has many functions that work on the file system. Those functions are named after their UNIX equivalents. For example, `File.rm/1` can be used to remove files, `File.mkdir/1` to create directories, `File.mkdir_p/1` creates directories guaranteeing their parents exists and there is even `File.cp_r/2` and `File.rm_rf/2` which copy and remove files and directories recursively.
+Besides functions for opening, reading and writing files, the `File` module has many functions to work with the file system. Those functions are named after their UNIX equivalents. For example, `File.rm/1` can be used to remove files, `File.mkdir/1` to create directories, `File.mkdir_p/1` to create directories and all their parent chain. There are even `File.cp_r/2` and `File.rm_rf/2` to respectively copy and remove files and directories recursively (i.e., copying and removing the contents of the directories too).
 
-You will also notice that functions in the `File` module have two variants, one with `!` (bang) in its name and others without. For example, when we read the "hello" file above, we have used the one without `!`. Let's try some new examples:
+You will also notice that functions in the `File` module have two variants: one "regular" variant and another variant which has the same name as the regular version but with a trailing bang (`!`). For example, when we read the `"hello"` file in the example above, we use `File.read/1`. Alternatively, we can use `File.read!/1`:
 
 ```iex
 iex> File.read "hello"
@@ -70,30 +65,28 @@ iex> File.read! "unknown"
 ** (File.Error) could not read file unknown: no such file or directory
 ```
 
-Notice that when the file does not exist, the version with `!` raises an error. That said, the version without `!` is preferred when you want to handle different outcomes with pattern matching. However, if you expect the file to be there, the bang variation is more useful as it raises a meaningful error message. That said, never write:
-
-```elixir
-{:ok, body} = File.read(file)
-```
-
-Instead write:
+Notice that when the file does not exist, the version with `!` raises an error. The version without `!` is preferred when you want to handle different outcomes using pattern matching:
 
 ```elixir
 case File.read(file) do
-  {:ok, body} -> # handle ok
-  {:error, r} -> # handle error
+  {:ok, body}      -> # do something with the `body`
+  {:error, reason} -> # handle the error caused by `reason`
 end
 ```
 
-or
+However, if you expect the file to be there, the bang variation is more useful as it raises a meaningful error message. Avoid writing:
 
 ```elixir
-File.read!(file)
+{:ok, body} = File.read(file)
 ```
 
+as, in case of an error, `File.read/1` will return `{:error, reason}` and the pattern matching will fail. You will still get the desired result (a raised error), but the message will be about the pattern which doesn't match (thus being cryptic in respect to what the error actually is about).
+
+If you don't want to handle a possible error (i.e., you want it to bubble up), prefer using `File.read!/1`.
+
 ## 12.3 The Path module
 
-The majority of the functions in the File module expects paths as arguments. Most commonly, those paths will be binaries and they can be manipulated with the [`Path`](/docs/stable/elixir/Path.html) module:
+The majority of the functions in the `File` module expect paths as arguments. Most commonly, those paths will be regular binaries. The [`Path`](/docs/stable/elixir/Path.html) module provides facilities for working with such paths:
 
 ```iex
 iex> Path.join("foo", "bar")
@@ -102,18 +95,20 @@ iex> Path.expand("~/hello")
 "/Users/jose/hello"
 ```
 
-With this we have covered the main modules for doing IO and interacting with the file system. Next we will discuss some curiosities and advanced topics regarding IO. Those sections are not necessary to write Elixir code, so feel free to skip them, but they do provide an overview of how the IO system is implemented in the VM and other curiosities.
+Using functions from the `Path` module as opposed to just manipulating binaries is preferred since the `Path` module takes care of different operating systems transparently. For example, `Path.join/2` joins a path with slashes (`/`) on Unix-like systems and with backslashes (`\\`) on Windows.
+
+With this we have covered the main modules that Elixir provides for dealing with IO and interacting with the file system. In the next sections, we will discuss some advanced topics regarding IO. Those sections are not necessary in order to write Elixir code, so feel free to skip them, but they do provide a nice overview of how the IO system is implemented in the VM and other curiosities.
 
 ## 12.4 Processes and group leaders
 
-You may have noticed that `File.open/2` returned a tuple containing a PID:
+You may have noticed that `File.open/2` returns a tuple like `{:ok, pid}`:
 
 ```iex
 iex> {:ok, file} = File.open "hello", [:write]
 {:ok, #PID<0.47.0>}
 ```
 
-That's because the IO module actually works with processes. When you say `IO.write(pid, binary)`, the IO module will send a message to the process with the desired operation. Let's see what happens if we use our own process:
+That happens because the `IO` module actually works with processes (see [chapter 11](/getting_started/11.html)). When you write `IO.write(pid, binary)`, the `IO` module will send a message to the process identified by `pid` with the desired operation. Let's see what happens if we use our own process:
 
 ```iex
 iex> pid = spawn fn ->
@@ -125,9 +120,9 @@ iex> IO.write(pid, "hello")
 ** (ErlangError) erlang error: :terminated
 ```
 
-After `IO.write/2`, we can see the request sent by the IO module printed, which then fails since the IO module expected some kind of result that we did not supply.
+After `IO.write/2`, we can see the request sent by the `IO` module (a four-elements tuple) printed out. Soon after that, we see that it fails since the `IO` module expected some kind of result that we did not supply.
 
-The [`StringIO`](/docs/stable/elixir/StringIO.html) module provides an implementation of the IO device messages on top of a string:
+The [`StringIO`](/docs/stable/elixir/StringIO.html) module provides an implementation of the `IO` device messages on top of strings:
 
 ```iex
 iex> {:ok, pid} = StringIO.open("hello")
@@ -136,9 +131,9 @@ iex> IO.read(pid, 2)
 "he"
 ```
 
-By modelling IO devices with processes, the Erlang VM allows different nodes in the same network to exchange file processes to read/write files in between nodes. Of all IO devices, there is one that is special to each process, called group leader.
+By modelling IO devices with processes, the Erlang VM allows different nodes in the same network to exchange file processes in order to read/write files in between nodes. Of all IO devices, there is one that is special to each process: the **group leader**.
 
-When you write to `:stdio`, you are actually sending a message to the group leader, which writes to STDIO file descriptor:
+When you write to `:stdio`, you are actually sending a message to the group leader, which writes to the standard-input file descriptor:
 
 ```iex
 iex> IO.puts :stdio, "hello"
@@ -153,7 +148,7 @@ The group leader can be configured per process and is used in different situatio
 
 ## 12.5 `iodata` and `chardata`
 
-In all examples above, we have used binaries/strings when writing to files. In the chapter "Binaries, strings and char lists", we mentioned how strings are simply bytes while char lists are lists with code points.
+In all of the examples above, we used binaries when writing to files. In the chapter ["Binaries, strings and char lists"](/getting_started/6.html), we mentioned how strings are simply bytes while char lists are lists with code points.
 
 The functions in `IO` and `File` also allow lists to be given as arguments. Not only that, they also allow a mixed list of lists, integers and binaries to be given:
 
@@ -166,10 +161,10 @@ hello world
 :ok
 ```
 
-However, this requires some attention. A list may represent either a bunch of bytes or a bunch of characters and which one to use depends on the encoding of the IO device. If the file is opened without encoding, the file is expected to be in raw mode, and the functions in the `IO` module starting with `bin*` must be used. Those functions expect an `iodata` as argument, i.e. it expects a list of integers representing bytes and binaries to be given.
+However, this requires some attention. A list may represent either a bunch of bytes or a bunch of characters and which one to use depends on the encoding of the IO device. If the file is opened without encoding, the file is expected to be in raw mode, and the functions in the `IO` module starting with `bin*` must be used. Those functions expect an `iodata` as argument; i.e., they expect a list of integers representing bytes and binaries to be given.
 
-On the other hand, `:stdio` and files opened with `:utf8` encoding work with the remaining functions in the `IO` module and those expect a `char_data` as argument, i.e. they expect a list of characters or strings to be given.
+On the other hand, `:stdio` and files opened with `:utf8` encoding work with the remaining functions in the `IO` module. Those functions expect a `char_data` as argument, that is, a list of characters or strings.
 
 Although this is a subtle difference, you only need to worry about those details if you intend to pass lists to those functions. Binaries are already represented by the underlying bytes and as such their representation is always raw.
 
-This finishes our tour of IO devices and IO related functionality. We have learned about four Elixir modules, [`IO`](/docs/stable/elixir/IO.html), [`File`](/docs/stable/elixir/File.html), [`Path`](/docs/stable/elixir/Path.html) and [`StringIO`](/docs/stable/elixir/StringIO.html), as well as how the VM uses processes for the underlying IO mechanisms and how to use (char and io) data for IO operations.
+This finishes our tour of IO devices and IO related functionality. We have learned about four Elixir modules - [`IO`](/docs/stable/elixir/IO.html), [`File`](/docs/stable/elixir/File.html), [`Path`](/docs/stable/elixir/Path.html) and [`StringIO`](/docs/stable/elixir/StringIO.html) - as well as how the VM uses processes for the underlying IO mechanisms and how to use `chardata` and `iodata` for IO operations.