Provided by: libsoldout1-dev_1.3-6_amd64 
NAME
markdown - markdown documents parsing
SYNOPSIS
#PACKAGE#
#include <markdown.h>
void markdown ( struct buf *ob,
struct buf *ib,
const struct mkd_renderer *rndr);
DESCRIPTION
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:
http://daringfireball.net/projects/markdown/
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:
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 */ };
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.
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.
`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`.
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.
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.
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.
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 `'"'`.
The `normal_text` callback should also perform whatever escape is needed to have the output looking like
the input data.
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:
- `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`.
The input format to describe tables is taken from PHP-Markdown, and looks like this:
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: |
Each row of the input text is a single row in the output, except the header rule, which is purely
syntactic.
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.
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.
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.
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`).
A column-wise default alignment can be specified with the same syntax on the header rule.
RENDERER EXAMPLES
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.
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 />`).
STANDARD MARKDOWN RENDERER
`mkd_html` and `mkd_xhtml` implement standard Markdown to (X)HTML translation without any extension.
DISCOUNT-ISH
`discount_html` and `discount_xhtml` implement on top of the standard markdown *some* of the extensions
found in Discount.
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.
Here is a list of all extensions included in these renderers:
- 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).
NATASHA'S OWN EXTENSIONS
`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.
Here is a list of these extensions :
- 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 `|`
Follows an example use of all of them:
###atx_id#ID was chosen to look nice in atx-style headers ###
setext_id#Though it will also work in setext-style headers
----------------------------------------------------------
Here is a paragraph with --deleted-- and ++inserted++ text.
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:
(verse)|And on the pedestal these words appear:|
|"My name is Ozymandias, king of kings:|
|Look on my works, ye Mighty, and despair!"|
COPYRIGHT
Copyright © 2009 Natasha Porte' <natbsd@instinctive.eu>
SEE ALSO
John Gruber's website http://daringfireball.net/projects/markdown/
Natacha Porté website http://fossil.instinctive.eu/
2009 MARKDOWN(3)