% Discount -- a C implementation of the Markdown markup language -- documentation % Jessica L. Parsons (orc@pell.portland.or.us) % #Discount ###API reference There are 17 public functions in the [markdown][] library, broken into three categories: ####Input functions 1. `MMIOT *mkd_in(FILE *f, mkd_flag_t *flags)` reads a markdown input file and returns a MMIOT containing the preprocessed document. (which is then fed to `markdown()` for final formatting.) 2. `MMIOT *mkd_string(char *bfr, int size, mkd_flag_t *flags)` reads the markdown input file that's been written into `bfr` and returns a preprocessed blob suitable for feeding to `markdown()`. This function exists because [annotations][] uses `mmap()` to access message files instead of traditional file i/o. (If you're going to port Markdown to an AS/400, this function *is* the droid you've been looking for.) ####"Big Picture"-style processing functions 1. `int markdown(MMIOT *doc, FILE *out, mkd_flag_t *flags)` formats a document (created with `mkd_in()` or `mkd_string()`) and writes the resulting HTML document to `out`. 2. `int mkd_line(char *bfr, int size, char **out, mkd_flag_t *flags)` allocates a buffer, then formats the text string into that buffer. text string, allocates a buffer, The differences from `markdown()` are it doesn't support quoting, footnotes ("reference links",) multiple paragraphs, lists, code sections, or pure html sections. 3. `int mkd_generateline(char*bfr, int size, FILE *out, mkd_flag_t *flags)` formats the text string and writes the resulting HTML fragment to `out`. It is exactly like `mkd_line()` except that it writes the output to a `FILE*`. ####Fine-grained access to the internals 1. `int mkd_compile(MMIOT *doc, mkd_flag_t *flags)` takes a document created by `mkd_in()` or `mkd_string()` and compiles it into a tree of block elements. 2. `int mkd_generatehtml(MMIOT *doc, FILE *out)` generates html from a compiled document. 2. `int mkd_document(MMIOT *doc, char **text)` returns (in `text`) a pointer to the compiled html document, and (in the return code) the size of that document. 2. `int mkd_css(MMIOT *doc, char **out)` allocates a buffer and populates it with any style blocks found in the document. 2. `int mkd_generatecss(MMIOT *doc, FILE *out)` prints any style blocks in the document. 3. `int mkd_toc(MMIOT *doc, char **out)` allocates a buffer, populates it with a table of contents, assigns it to out, and returns the length of the buffer. To get a table of contents, you must `compile()` the document with the `MKD_TOC` flag (described below) 3. `int mkd_generatetoc(MMIOT *doc, FILE *out)` writes a table of contents to _out_; other than writing to a `FILE*`, it operates exactly like `mkd_toc()` 3. `int mkd_dump(MMIOT *doc, FILE *f, mkd_flag_t *flags, char *title)` prints a block structure diagram of a compiled document. 4. `void mkd_cleanup(MMIOT *doc)` releases the MMIOT allocated for the document. ####[Document header](id:document-header) access functions 1. `char *mkd_doc_title(MMIOT *doc)` returns the `% title` line. 2. `char *mkd_doc_author(MMIOT *doc)` returns the `% author(s)` line. 3. `char *mkd_doc_date(MMIOT *doc)` returns the `% date` line. ####[Url callback](id:callback) functions 1. `void mkd_e_url(MMIOT*, char* (callback)(char*,int,void*))` sets up a callback function that is called whenever [discount] processes a `[]()` or `` construct. The callback function is passed a pointer to the url, the size of the url, and a data pointer (null or supplied by `mkd_e_data()`) 2. `void mkd_e_flags(MMIOT*, char *(callback)(char*,int,void*))` sets up a callback to provide additional arguments to the tags generated by `[]()` and `` constructs. If, for instance, you wanted to add `target="_blank"` to every generated url, you could just make a callback function that returned that string. 3. `void mkd_e_code(MMIOT*, char *(callback)(char*,int,void*))' sets up a callback to format the contents of a code block. 3. `void mkd_e_free(char *, void*)` is called to free any allocated memory returned by the url or flags callbacks. 4. `void mkd_e_data(MMIOT*, void*)` assigns a callback data area to the url & flags callbacks. ####[Flag handling](id:flags) 1. `mkd_flag_t *mkd_flags()' initializes a flag structure and returns a pointer to it. 2. `void mkd_free_flags(mkd_flag *)` deletes a flag structure 3. `mkd_flag_t *mkd_copy(mkd_flag_t *)` copies flags and returns a pointer to the copy. 4. `int mkd_flag_isset(mkd_flag_t *, int)` checks if a flag is set. 5. `char *mkd_set_flag_string(mkd_flag_t *, char*)` sets flags from a comma-separated list of flags; returns NULL if it was able to set all the flags, a pointer to the flag it couldn't set otherwise. This function destroys the input string, so be aware! 6. `void mkd_set_flag_num(mkd_flag_t*, int)` sets a specific flag. 7. `void mkd_clr_flag_num(mkd_flag_t*, int)` clears a specific flag. [Flag](id:mkd_flags) | Action ------------------------|------------------------------------------ MKD_NOLINKS | don't do link processing, block tags MKD_NOIMAGE | don't do image processing, block MKD_NOPANTS | don't run smartypants() MKD_NOHTML | don't allow raw html through AT ALL MKD_NORMAL_LISTITEM | disable github-style checkbox lists MKD_TAGTEXT | process text inside an html tag MKD_NO_EXT | don't allow pseudo-protocols MKD_EXPLICITLIST | don't combine numbered/bulletted lists MKD_CDATA | generate code for xml ![CDATA[...]] MKD_NOSUPERSCRIPT | no A^B MKD_STRICT | conform to Markdown standard as implemented in Markdown.pl MKD_NOTABLES | disallow tables MKD_NOSTRIKETHROUGH | forbid ~~strikethrough~~ MKD_1_COMPAT | compatibility with MarkdownTest_1.0 MKD_TOC | do table-of-contents processing MKD_AUTOLINK | make http://foo.com link even without <>s MKD_NOHEADER | don't process header blocks MKD_TABSTOP | expand tabs to 4 spaces MKD_SAFELINK | paranoid check for link protocol MKD_NODIVQUOTE | forbid >%class% blocks MKD_NOALPHALIST | forbid alphabetic lists MKD_EXTRA_FOOTNOTE | enable markdown extra-style footnotes MKD_NOSTYLE | don't extract `