NAME

       lowdown_nroff_new — allocate a roff renderer for lowdown documents

LIBRARY

       library “liblowdown”

SYNOPSIS

       #include <sys/queue.h>
       #include <stdio.h>
       #include <lowdown.h>

       void *
       lowdown_nroff_new(const struct lowdown_opts *opts);

DESCRIPTION

       Allocates  a roff renderer using opts->oflags and opts->type, or zero and LOWDODN_NROFF, respectively, if
       opts is NULL.  These are documented in lowdown(3).  The  returned  pointer  may  be  used  with  multiple
       invocations of lowdown_nroff_rndr(3) and must be freed with lowdown_nroff_free(3).

       The    bits    recognised    in    opts->oflags    are    LOWDOWN_NROFF_ENDNOTES,    LOWDOWN_NROFF_GROFF,
       LOWDOWN_NROFF_NOLINK,  LOWDOWN_NROFF_NUMBERED,  LOWDOWN_NROFF_SHORTLINK,   LOWDOWN_NROFF_SKIP_HTML,   and
       LOWDOWN_STANDALONE.

       The   values  recognised  in  opts->type  are  LOWDOWN_MAN  and  LOWDODN_NROFF:  anything  else  triggers
       LOWDODN_NROFF.

       If LOWDOWN_NROFF_GROFF is set in LOWDOWN_MAN mode, macros  from  the  man-ext  package  as  well  as  the
       original  man  are  used  in  output.  These are supported by both groff and mandoc.  If in LOWDODN_NROFF
       mode, GNU extensions to ms are used along with mspdf.  These are only supported by groff.

       LOWDOWN_NROFF_ENDNOTES delays printing of footnotes until  the  end  of  a  document.   Does  not  affect
       LOWDOWN_MAN documents, which structurally only supports endnotes.

       The  allocated  rendered  will  use  constant-width fonts "CR" (regular), "CB" (bold), "CI" (italic), and
       "CBI" (bold-italic).  Override the defaults with variables in the struct lowdown_opts_nroff structure.

RETURN VALUES

       Returns a pointer to the renderer or NULL on memory failure.  The returned pointer  must  be  freed  with
       lowdown_nroff_free(3).

EXAMPLES

       The following parses b of length bsz and outputs in groff_ms(7) format.

             struct lowdown_buf *out;
             struct lowdown_doc *doc;
             struct lowdown_node *n;
             void *rndr;

             if ((doc = lowdown_doc_new(NULL)) == NULL)
                     err(1, NULL);
             if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
                     err(1, NULL);
             if ((out = lowdown_buf_new(256)) == NULL)
                     err(1, NULL);
             if ((rndr = lowdown_nroff_new(NULL)) == NULL)
                     err(1, NULL);
             if (!lowdown_nroff_rndr(out, rndr, n))
                     err(1, NULL);

             fwrite(out->data, 1, out->size, stdout);

             lowdown_nroff_free(rndr);
             lowdown_buf_free(out);
             lowdown_node_free(n);
             lowdown_doc_free(doc);

SEE ALSO

       lowdown(3), lowdown_nroff_free(3), lowdown_nroff_rndr(3),

       This  uses both the original troff man macros for Version 7 AT&T UNIX, defined in man(7), and the man-ext
       groff extensions.  Both are implemented in mandoc.

       The troff ms macros are defined in groff_ms(7), with the mspdf groff extensions  described  in  "Portable
       Document Format Publishing with GNU Troff" by Keith Marshall.  Neither are implemented in mandoc.

CAVEATS

       The  default  constant-width  fonts may not available for the formatter's output device (for example, the
       terminal).  In this case, the formatter may raise a warning and ignore the font.

Debian                                             $Mdocdate$                               LOWDOWN_NROFF_NEW(3)