Description: Adding libsoldout.3 man page 
 Adding man page to document the only public entry of libsoldout
Author: Massimo Manghi <mxmanghi@apache.org>
Reviewed-by: Natacha Porté <natbsd@instinctive.eu>
Last-Update: 2015-05-10
---
This patch header follows DEP-3: http://dep.debian.net/deps/dep3/

--- /dev/null
+++ b/libsoldout.3
@@ -0,0 +1,289 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.\" (C) Copyright 2009 Natacha Porté <natbsd@instinctive.eu>,
+.\"
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH MARKDOWN 3 "2009"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh        disable hyphenation
+.\" .hy        enable hyphenation
+.\" .ad l      left justify
+.\" .ad b      justify to both left and right margins
+.\" .nf        disable filling
+.\" .fi        enable filling
+.\" .br        insert line break
+.\" .sp <n>    insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.SH NAME
+markdown \- markdown documents parsing
+.SH SYNOPSIS
+.B #PACKAGE#
+    #include <markdown.h>
+.sp
+    void markdown ( struct buf *ob,
+                    struct buf *ib,
+                    const struct mkd_renderer *rndr);
+.sp
+.SH DESCRIPTION
+.sp
+is the only exported function in libsoldout and starts
+the parsing process of a markdown document. You can have
+more information about the markdown language from John
+Gruber's website:
+.sp
+http://daringfireball.net/projects/markdown/
+.sp
+Libsoldout only performs the parsing of markdown input, the
+construction of the output is left to a *renderer*, which is a
+set of callback functions called when markdown elements are
+encountered. Pointers to these functions are gathered into a
+`struct mkd_renderer` along with some renderer-related
+data. I think the struct declaration is pretty obvious:
+.sp
+struct mkd_renderer {
+    /* document level callbacks */
+    void (*prolog)(struct buf *ob, void *opaque);
+    void (*epilog)(struct buf *ob, void *opaque);
+
+    /* block level callbacks - NULL skips the block */
+    void (*blockcode)(struct buf *ob, struct buf *text, void *opaque);
+    void (*blockquote)(struct buf *ob, struct buf *text, void *opaque);
+    void (*blockhtml)(struct buf *ob, struct buf *text, void *opaque);
+    void (*header)(struct buf *ob, struct buf *text,
+                        int level, void *opaque);
+    void (*hrule)(struct buf *ob, void *opaque);
+    void (*list)(struct buf *ob, struct buf *text, int flags,
+                 void *opaque);
+    void (*listitem)(struct buf *ob, struct buf *text,
+                        int flags, void *opaque);
+    void (*paragraph)(struct buf *ob, struct buf *text, void *opaque);
+    void (*table)(struct buf *ob, struct buf *head_row,
+                        struct buf *rows,void *opaque);
+    void (*table_cell)(struct buf *ob, struct buf *text, int flags,
+                            void *opaque);
+    void (*table_row)(struct buf *ob, struct buf *cells, int flags,
+                            void *opaque);
+
+    /* span level callbacks - NULL or return 0
+       prints the span verbatim */
+    int (*autolink)(struct buf *ob, struct buf *link,
+                    enum mkd_autolink type, void *opaque);
+    int (*codespan)(struct buf *ob, struct buf *text, void *opaque);
+    int (*double_emphasis)(struct buf *ob, struct buf *text,
+                        char c, void *opaque);
+    int (*emphasis)(struct buf *ob, struct buf *text,
+                    char c, void*opaque);
+    int (*image)(struct buf *ob, struct buf *link, struct buf *title,
+                        struct buf *alt, void *opaque);
+    int (*linebreak)(struct buf *ob, void *opaque);
+    int (*link)(struct buf *ob, struct buf *link, struct buf *title,
+                    struct buf *content, void *opaque);
+    int (*raw_html_tag)(struct buf *ob, struct buf *tag, void *opaque);
+    int (*triple_emphasis)(struct buf *ob, struct buf *text,
+                        char c, void *opaque);
+
+    /* low level callbacks - NULL copies input directly
+       into the output */
+    void (*entity)(struct buf *ob, struct buf *entity, void *opaque);
+    void (*normal_text)(struct buf *ob, struct buf *text,
+                        void *opaque);
+
+    /* renderer data */
+    int max_work_stack; /* prevent arbitrary deep recursion */
+    const char *emph_chars; /* chars that trigger emphasis rendering */
+    void *opaque; /* opaque data send to every rendering callback */
+};
+.sp
+The first argument of a renderer function is always the output buffer,
+where the function is supposed to write its output. It's not necessarily
+related to the output buffer given to `markdown()` because in some cases
+render into a temporary buffer is needed.
+.sp
+The last argument of a renderer function is always an opaque pointer, which
+is equal to the `opaque` member of `struct mkd_renderer`. The name
+"opaque" might not be well-chosen, but it means a pointer *opaque for the
+parser, **not** for the renderer*. It means that my parser passes around
+blindy the pointer which contains data you know about, in case you need to
+store an internal state or whatever. I have not found anything to put in
+this pointer in my example renderers, so it is set to NULL in the structure
+and never look at in the callbacks.
+.sp
+`emph_chars` is a zero-terminated string which contains the set of
+characters that trigger emphasis. In regular markdown, emphasis is only
+triggered by '\\_' and '\\*', but in some extensions it might be useful to
+add other characters to this list. For example in my extension to handle
+`<ins>` and `<del>` spans, delimited respectively by "++" and "--", I have
+added '+' and '-' to `emph_chars`. The character that triggered the
+emphasis is then passed to `emphasis`, `double_emphasis` and
+`triple_emphasis` through the parameter `c`.
+.sp
+Function pointers in `struct mkd_renderer` can be NULL, but it has a
+different meaning whether the callback is block-level or span-level. A null
+block-level callback will make the corresponding block disappear from the
+output, as if the callback was an empty function. A null span-level
+callback will cause the corresponding element to be treated as normal
+characters, copied verbatim to the output.
+.sp
+So for example, to disable link and images (e.g. because you consider them
+as dangerous), just put a null pointer in `rndr.link` and `rndr.image` and
+the bracketed stuff will be present as-is in the output. While a null
+pointer in `header` will remove all header-looking blocks. If you want an
+otherwise standard markdown-to-XHTML conversion, you can take the example
+`mkd_xhtml` struct, copy it into your own `struct mkd_renderer` and then
+assign NULL to `link` and `image` members.
+.sp
+Moreover, span-level callbacks return an integer, which tells whether the
+renderer accepts to render the item (non-zero return value) or whether it
+should be copied verbatim (zero return value). This allows you to only
+accept some specific inputs. For example, my extension for `<ins>` and
+`<del>` spans asks *exactly* two '-' or '+' as delimiters, when `emphasis`
+and `triple_emphasis` are called with '-' or '+', they return 0.
+.sp
+Special care should be taken when writing `autolink`, `link` and `image`
+callbacks, because the arguments `link`, `title` and `alt` are unsanitized
+data taken directly from the input file. It is up to the renderer to escape
+whatever needs escaping to prevent bad things from happening. To help you
+writing renderers, the function `lus_attr_escape()` escapes all problematic
+characters in (X)HTML: `'<'`, `'>'`, `'&'` and `'"'`.
+.sp
+The `normal_text` callback should also perform whatever escape is needed to
+have the output looking like the input data.
+.sp
+.SH PHP-MARKDOWN-LIKE TABLES
+Tables are one of the few extensions that are quite difficult and/or hacky
+to implement using vanilla Markdown parser and a renderer. Thus a support
+has been introduced into the parser, using dedicated callbacks:
+.sp
+  - `table_cell`, which is called with the span-level contents of the cell;
+  - `table_row`, which is called with data returned by `table_cell`;
+  - `table`, which called with data returned by `table_row`.
+.sp
+The input format to describe tables is taken from PHP-Markdown, and looks
+like this:
+.sp
+    header 1    | header 2      | header 3      | header 4
+    ------------|:-------------:|--------------:|:--------------
+    first line  |   centered    | right-aligned | left-aligned
+    second line |   centered    |:   centered  :| left-aligned
+    third line  |: left-aglined | right-aligned | right-aligned :
+    column-separator | don't need | to be | aligned in the source
+    | extra speratators | are allowed | at both ends | of the line |
+    | correct number of cell per row is not enforced |
+    | pipe characters can be embedded in cell text by escaping it: \| |
+.sp
+Each row of the input text is a single row in the output, except the header
+rule, which is purely syntactic.
+.sp
+Each cell in a row is delimited by a pipe (`|`) character. Optionally, a
+pipe character can also be present at the beginning and/or at the end of
+the line. Column separator don't have to be aligned in the input, but it
+makes the input more readable.
+.sp
+There is no check of "squareness" of the table: `table_cell` is called once
+for each cell provided in the input, which can be a number of times
+different from one row to the other. If the output *has* to respect a given
+number of cell per row, it's up to the renderer to enforce it, using state
+transmitted through the `opaque` pointer.
+.sp
+The header rule is a line containing only horizontal blanks (space and
+tab), dashes (`-`), colons (`:`) and separator. Moreover, it *must* be the
+second line of the table. In case such a header rule is detected, the first
+line of the table is considered as a header, and passed as the `head_row`
+argument to `table` callback. Moreover `table_row` and `table_cell` are
+called for that specific row with `MKD_CELL_HEAD` flag.
+.sp
+Alignment is defined on a per-cell basis, and specified by a colon (`:`) at
+the very beginning of the input span (i.e. directly after the `|`
+separator, or as the first character on the line) and/or at the very end of
+it (i.e.  directly before the separator, or as the last character on the
+line). A cell with such a leading colon only is left-aligned
+(`MKD_CELL_ALIGN_LEFT`), one with a trailing colon only is right-aligned
+(`MKD_CELL_ALIGN_RIGHT`), and one with both is centered
+(`MKD_CELL_ALIGN_CENTER`).
+.sp
+A column-wise default alignment can be specified with the same syntax on
+the header rule.
+.SH RENDERER EXAMPLES
+.sp
+While libsoldout is designed to perform only the parsing of markdown files,
+and to let you provide the renderer callbacks, a few renderers have been
+included, both to illustrate how to write a set of renderer functions and
+to allow anybody who do not need special extensions to use libsoldout
+without hassle.
+.sp
+All the examples provided here comme with two flavors, `_html` producing
+HTML code (self-closing tags are rendered like this: `<hr>`), and `_xhtml`
+producing XHTML code (self-closing tags like `<hr />`).
+.sp
+.SH STANDARD MARKDOWN RENDERER
+`mkd_html` and `mkd_xhtml` implement standard Markdown to (X)HTML
+translation without any extension.
+.SH DISCOUNT-ISH
+.sp
+`discount_html` and `discount_xhtml` implement on top of the standard
+markdown *some* of the extensions found in Discount.
+.sp
+Actually, all Discount extensions that are not provided here cannot be
+easily implemented in libsoldout without touching to the parsing code,
+hence they do not belong strictly to the renderer realm. However some
+(maybe all, not sure about tables) extensions can be implemented fairly
+easily with libsoldout by using both a dedicated renderer and some
+preprocessing to make the extension look like something closer to the
+original markdown syntax.
+.sp
+Here is a list of all extensions included in these renderers:
+.sp
+ - image size specitication, by appending " =(width)x(height)" to
+   the link,
+ - pseudo-protocols in links:
+    * abbr:_description_ for `<abbr title="`_description_`">...</abbr>`
+    * class:_name_ for `<span class="`_name_`">...</span>`
+    * id:_name_ for `<a id="`_name_`>...</a>`
+    * raw:_text_ for verbatim unprocessed _text_ inclusion
+ - class blocks: blockquotes beginning with %_class_% will be
+    rendered as a `div` of the given class(es).
+.sp
+
+.SH NATASHA'S OWN EXTENSIONS
+.sp
+`nat_html` and `nat_xhtml` implement on top of Discount extensions some
+things that I need to convert losslessly my existing HTML into extended
+markdown.
+.sp
+Here is a list of these extensions :
+.sp
+ - id attribute for headers, using the syntax _id_#_Header text_
+ - class attribute for paragraphs, by putting class name(s) between
+   parenthesis at the very beginning of the paragraph
+ - `<ins>` and `<del>` spans, using respectively `++` and `--` as
+   delimiters (with emphasis-like restrictions, i.e. an opening
+   delimiter cannot be followed by a whitespace, and a closing
+   delimiter cannot be preceded by a whitespace).
+ - plain `<span>` without attribute, using emphasis-like delimiter `|`
+.sp
+Follows an example use of all of them:
+.sp
+    ###atx_id#ID was chosen to look nice in atx-style headers ###
+.sp
+    setext_id#Though it will also work in setext-style headers
+    ----------------------------------------------------------
+.sp
+    Here is a paragraph with --deleted-- and ++inserted++ text.
+.sp
+    I use CSS rules to render poetry and other verses, using a plain
+    `<span>` for each verse, and enclosing each group of verses in
+    a `<p class="verse">`. Here is how it would look like:
+.sp
+    (verse)|And on the pedestal these words appear:|
+    |"My name is Ozymandias, king of kings:|
+    |Look on my works, ye Mighty, and despair!"|
+.sp
+.PP
+.SH COPYRIGHT
+  Copyright \(co 2009 Natasha Porte' <natbsd@instinctive.eu>
+.SH SEE ALSO
+   John Gruber's website http://daringfireball.net/projects/markdown/
+   Natacha Porté website http://fossil.instinctive.eu/
