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_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.

       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)