Skip to content

Commit

Permalink
Straighten markup. (#21)
Browse files Browse the repository at this point in the history
* Straighten markup.

* Indent paragraphs inside a numbered list by 3 spaces, so that they are seen as being inside the item.
* Break the twoth list _(the three goals of the class)_ away from the first _(the definition of the class)_.

* Indent by 4 spaces.

As requested by maintainers. Should have no effect on formatting.
  • Loading branch information
kindaro authored Feb 6, 2022
1 parent 046965c commit e4ffaaf
Showing 1 changed file with 13 additions and 12 deletions.
25 changes: 13 additions & 12 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,20 +51,21 @@ type Display :: * -> Constraint
```

1. This is the class definition, with its methods.
* `displayBuilder` produces a `Builder` value out of an `a`.
This is the most common way to implement `Display` when you just need to render something for an end-user.

* `displayList` produces a `Builder` value out of a list of `a`.
This method has a default implementation provided by the library, but it may be overloaded in case you
wish to render the list of a particular type in a certain way, like how `[Char]` is rendered to `"this nice user-readable string"` instead of something `['l', 'i', 'k', 'e', ' ', 't', 'h', 'i', 's']`.

* `displayPrec` takes a precedence value with the value to be transformed, and produces a `Builder`.
It has a more advanced target audience in mind, and is used when printing nested datatypes calls for a clarification of operator and constructor precedence.
If the precedence is not set, we cannot say that we want parentheses surrounding an inner value, like `"Just (Just 5)"`, and indeed, may find ourselves
with a result like `"Just Just 5"`, which is unacceptable.
* `displayBuilder` produces a `Builder` value out of an `a`.
This is the most common way to implement `Display` when you just need to render something for an end-user.
* `displayList` produces a `Builder` value out of a list of `a`.
This method has a default implementation provided by the library, but it may be overloaded in case you
wish to render the list of a particular type in a certain way, like how `[Char]` is rendered to `"this nice user-readable string"` instead of something `['l', 'i', 'k', 'e', ' ', 't', 'h', 'i', 's']`.
* `displayPrec` takes a precedence value with the value to be transformed, and produces a `Builder`.
It has a more advanced target audience in mind, and is used when printing nested datatypes calls for a clarification of operator and constructor precedence.
If the precedence is not set, we cannot say that we want parentheses surrounding an inner value, like `"Just (Just 5)"`, and indeed, may find ourselves
with a result like `"Just Just 5"`, which is unacceptable.

2. This is the minimal implementation a user of the library must provide in order to implement `Display` for
their datatype.
their datatype.

You will notice that `display` itself is not part of the Typeclass. And indeed, we wanted the typeclass to:

1. Internally use a `Builder` type for efficient production of textual data;
Expand Down

0 comments on commit e4ffaaf

Please # to comment.