diff --git a/Renderers%2FPlainterm.md b/Renderers%2FPlainterm.md new file mode 100644 index 0000000..7c06c50 --- /dev/null +++ b/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": ' ... + +# 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: ' ... + +# 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`