@@ -280,10 +280,77 @@ Implementation can be just a `Reader` monad producing something like text
280280builder. The context of `Reader` can store current indentation and
281281configuration options.
282282
283−As a pretty-printing library we can use [`Outputable`][outputable] (and
284−`SDoc`) from the [`ghc`][ghc] package itself. The benefit is that AST
285−components that we'll want to print are already instances of `Outputable`,
286−so we'll get correct renderings for free.
283+As the pretty-printing library we can use [`Outputable`][outputable] (and
284+`SDoc`) from the [`ghc`][ghc] package itself (at least for pretty-printing
285+basic things like floating point literals and the like). The benefit is that
286+AST components that we'll want to print are already instances of
287+`Outputable`, so we'll get correct renderings for free.
288+
289+The pretty-printing code can be in entirely in control of every formatting
290+choice, except for two, which are left to the programmer:
291+
292+1. location of comments (comments are going to be attached to specific
293+ syntactic entities, so moving an entity will move its comment too),
294+2. line breaking.
295+
296+Regarding (2), the idea is that given any syntactic entity, the programmer
297+has a choice:
298+
299+1. write it on one line, or
300+2. write it on two lines or more.
301+
302+If (1), then everything is kept one line. If (2), i.e. a line break appears
303+somewhere in the concrete syntax tree (CST), then additional line breaks are
304+introduced everywhere possible in parent nodes, *but not in any sibling or
305+children nodes*.
306+
307+Examples:
308+
309+```haskell
310+-- Stays as is.
311+data T = A | B
312+
313+data T
314+ = A | B
315+-- Is reformatted to:
316+data T
317+ = A
318+ | B
319+
320+-- Stays as is.
321+map :: (a -> b) -> [a] -> [b]
322+
323+foldr :: (a -> b -> b) ->
324+ b -> [a] -> [b]
325+-- Is reformatted to:
326+foldr
327+ :: (a -> b -> b)
328+ -> b
329+ -> [a]
330+ -> [b]
331+
332+t = let x = foo bar
333+ baz
334+ in foo bar baz
335+-- Is reformatted to:
336+t =
337+ let x =
338+ foo
339+ bar
340+ baz
341+ in foo far baz
342+```
343+
344+Crucially, no effort is made to fit within reasonable line lengths. That's
345+up to the programmer. Style will still be consistent for everyone in every
346+other aspect, and that's what counts.
347+
348+Not having to worry about line lengths is a huge simplification. Worrying
349+about them is why Hindent can run in time exponential to the size of the
350+input: it tries two variants at each node of the CST, to see whether one of
351+them fits on one 80-character line (and selects that one if so). If your CST
352+is even just somewhat deep, then you’re going to be waiting on your
353+formatter for a while.
287354
288355### Configuration
289356