   optimal formatting. To help better understand how to control the formatter,
   we describe in the next sections the cases where the formatter keeps the
   user encoding and how to control multiline expressions.
+
+  ## Line length
+
+  Another point about the formatter is that the `:line_length` configuration
+  is a guideline. In many cases, it is not possible for the formatter to break
+  your code apart, which means it will go over the line length. For example,
+  if you have a long string:
+
+      "this is a very long string that will go over the line length"
+
+  The formatter doesn't know how to break it apart without changing the
+  code underlying syntax representation, so it is up to you to step in:
+
+      "this is a very long string " <>
+         "that will go over the line length"
+
+  The string concatenation makes the code fit on a single line and also
+  gives more options to the formatter.
+
+  This may also appear in do/end blocks, where the `do` keyword (or `->`)
+  may go over the line lenth because there is no opportunity for the
+  formatter to introduce a line break in a readable way. For example,
+  if you do:
+
+      case very_long_expression() do
+
+  And only the `do` keyword is above the line length, Elixir **will not**
+  emit this:
+
+      case very_long_expression()
+      do
+
+  So it prefers to not touch the line at all and leave `do` above the
+  line limit.
 
   ## Keeping user's formatting
 

    * `:force_do_end_blocks` (since v1.9.0) - when `true`, converts all
      inline usages of `do: ...`,  `else: ...` and friends into `do/end`
      blocks. Defaults to `false`. Note that this option is convergent:
      once you set it to `true`, all keywords will be converted. If you
      set it to `false` later on, `do/end` blocks won't be converted
      back to keywords.

  ## Design principles



    * `:line_length` - the line length to aim for when formatting
      the document. Defaults to 98. Note this value is used as
      guideline but there are situations where it is not enforced.
      See the "Line length" section below for more information

    * `:locals_without_parens` - a keyword list of name and arity
      pairs that should be kept without parens whenever possible.
