Add Renderers/HTML

Renderers%2FHTML.md

@@ -0,0 +1,82 @@
+HTML renderer
+=============
+
+HTML renderer does exactly what it says on the tin - renders markdown to HTML.
+It offers the ability to modify the way output is generated, as well as tags
+which are used for every block.
+
+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 '"linewrap": 65' ...
+```
+
+Following global options can be provided:
+
+- `linewrap` - line wrapping, in number of text columns (80 by default)
+- `init_level` - initial indent level of generated text (2 by default)
+- `indent` - number of spaces per indent (2 by default)
+- `nowrap` - do not output wrapping code, only direct translations of
+   markdown elements (false by default)
+- `head` - array of head elements to add to the default template
+  output ([] by default)
+- `preambule` - text contents to embed before the translation output
+  (part of template containing head element by default)
+- `postambule` - text contents to embed after the translation output
+  (part of template by default)
+
+Per-class overrides
+-------------------
+
+Applying a per-class override via command line options works like this:
+```
+# see the following paragraph for all known block classes
+$ mmmdpp -o '"mapping"."Block::ClassName".override: <value, in JSON element form>' ...
+
+# i.e.
+$ mmmdpp -o '"mapping"."PointBlank::DOM::Paragraph".inline: true' ...
+```
+
+For library usage, these options roughly translate to the following hash, passed
+as the second argument to object initializer:
+```
+{
+    "mapping" => {
+        "PointBlank::DOM::Paragraph" => {
+            inline: true
+        }
+    }
+}
+```
+
+Following options can be applied to every class element:
+
+- `tag` - name of the tag this class should be mapped to. (i.e.
+  'PointBlank::DOM::Paragraph' => 'p', 'PointBlank::DOM::InlineEmphasis' =>
+  'em')      
+- `sanitize` - sanitize entities in text. shouldn't really be used anywhere
+  outside of text
+- `inline` - the tag should be considered self-closing
+- `codeblock` - special case. disables wordwrap, makes the block uninlined
+  regardless of containing tags.
+- `figcaption` - wrap tag into a `<figure>` tag. text contained in the tag is
+  copied into a caption.
+- `outer` - hash of parameters for an outer wrapping tag. can be defined
+  recursively. all options in this list apply.
+- `href` - add a href attribute. works only on links and classes containing
+  a `:uri` attribute
+- `title` - add a title attribute. works only on classes that have a
+  `:title` attribute
+- `style` - define an inline CSS style to embed into the tag.
+- `src` - add an src attribute. works only on images and classes containing
+  a `:uri` attribute
+- `alt` - add an alt attribute. works only on classes that have a
+  `:title` attribute