Add Renderers/Plainterm

Renderers%2FPlainterm.md

@@ -0,0 +1,131 @@
+Plainterm renderer
+==================
+
+Plainterm renderer renders markdown documents into a prettier format for reading
+in the terminal. It uses certain control codes to make it work. Styles applied
+to various elements can be changed.
+
+Applicable global options
+-------------------------
+
+Global options are applied to the root of the configuration hash for the
+renderer. They can be applied using the following pattern via command
+line:
+
+```
+$ mmmdpp -o '"nameOfGlobalOption": <value, in JSON element form>' ...
+
+# i.e.
+$ mmmdpp -o '"hsize": 65' ...
+```
+
+- `style` - override the style of certain elements. See "Style overrides"
+- `hsize` - horizontal size to align the contents to. Automatically
+   set to the width of the current terminal by default, or, if unavailable,
+   to 80 columns.
+
+Style overrides
+---------------
+
+Style overrides provide per-class overrides for element style. It's essentially
+a stylesheet applied to the element.
+
+Applying a style override via command line options works like this:
+```
+# see the following paragraph for all known block classes
+$ mmmdpp -o '"style"."Block::ClassName".override: <value, in JSON element form>' ...
+
+# i.e.
+$ mmmdpp -o '"style"."PointBlank::DOM::Paragraph".indent: false' ...
+```
+
+For library usage, these options roughly translate to the following hash, passed
+as the second argument to object initializer:
+```
+{
+    "style" => {
+        "PointBlank::DOM::Paragraph" => {
+            indent: false
+        }
+    }
+}
+```
+
+Applicable style overrides:
+- `indent` (boolean) - increase indentation
+- `increase_level` (boolean) - decrease horizontal space occupied (needed with
+  indent)
+- `center` (boolean) - center text
+- `bold` (boolean) - render text in bold
+- `italics` (boolean) - render text in italics
+- `strikethrough` (boolean) - render text with strikethrough
+- `bg` (text, #RGB) - set color background
+- `fg` (text, #RGB) - set color foreground
+- `box` (boolean) - render contents in an ascii box
+- `rjust` (boolean) - right-justify text
+- `extra_newlines` (boolean) - add extra newlines around the text block
+- `underline_block` (boolean) - underline text block, from left visual boundary
+  of text to right visual boundary of text
+- `underline_full_block` (boolean) - underline text block, from left border to
+  right border
+- `bullet` (boolean) - add bullet to block, used for bullet lists
+- `numbered` (boolean) - add numbered point to block, used for ordered lists
+- `leftline` (boolean) - draw a line on the left side of the block, top to
+  bottom
+
+Style defaults
+--------------
+
+These are the defaults applied to each class of text block
+
+- `PointBlank::DOM::Paragraph`:
+  - `indent`
+  - `increase_level`
+- `PointBlank::DOM::Text`:
+  - none applied by default
+- `PointBlank::DOM::SetextHeading1` (underline style of heading in markdown,
+  level 1)
+  - `center`
+  - `bold`
+  - `extra_newlines`
+  - `underline_full_block`
+- `PointBlank::DOM::SetextHeading2` (underline style of heading in markdown,
+  level 2)
+  - `center`
+  - `underline_block`
+- `PointBlank::DOM::ATXHeading1` (hash-symbol prefix style of heading,
+  level 1)
+  - (same as SetextHeading1)
+- `PointBlank::DOM::ATXHeading2` (hash-symbol heading, level 2)
+  - (same as SetextHeading2)
+- `PointBlank::DOM::ATXHeading3` (hash-symbol heading, level 3)
+  - `underline`
+  - `bold`
+- `PointBlank::DOM::ATXHeading4` (hash-symbol heading, level 4)
+  - `bold`
+  - `underline`
+- `PointBlank::DOM::ATXHeading5` (hash-symbol heading, level 5)
+  - `underline`
+- `PointBlank::DOM::ATXHeading6` (hash-symbol heading, level 6)
+  - `underline`
+- `PointBlank::DOM::InlineImage` (image link)
+  - `underline`
+- `PointBlank::DOM::InlineLink` (link)
+  - `underline`
+- `PointBlank::DOM::InlinePre` (inline code)
+  - none by default
+- `PointBlank::DOM::InlineEmphasis`
+  - `italics`
+- `PointBlank::DOM::InlineStrong` (strong emphasis)
+  - `bold`
+- `PointBlank::DOM::ULListElement` (element of an unordered list)
+  - `bullet`
+  - `increase_level`
+- `PointBlank::DOM::OLListElement` (element of an ordered list)
+  - `numbered`
+  - `increase_level`
+- `PointBlank::DOM::QuoteBlock`
+  - `leftline`
+  - `increase_level`
+- `PointBlank::DOM::HorizontalRule`
+  - `hrule`