1LOWDOWN_NROFF_NEW(3)     BSD Library Functions Manual     LOWDOWN_NROFF_NEW(3)
2

NAME

4     lowdown_nroff_new — allocate a roff renderer for lowdown documents
5

LIBRARY

7     library “liblowdown”
8

SYNOPSIS

10     #include <sys/queue.h>
11     #include <stdio.h>
12     #include <lowdown.h>
13
14     void *
15     lowdown_nroff_new(const struct lowdown_opts *opts);
16

DESCRIPTION

18     Allocates a roff renderer using opts->oflags and opts->type, or zero and
19     LOWDODN_NROFF, respectively, if opts is NULL.  These are documented in
20     lowdown(3).  The returned pointer may be used with multiple invocations
21     of lowdown_nroff_rndr(3) and must be freed with lowdown_nroff_free(3).
22
23     The bits recognised in opts->oflags are LOWDOWN_NROFF_GROFF,
24     LOWDOWN_NROFF_NOLINK, LOWDOWN_NROFF_NUMBERED, LOWDOWN_NROFF_SHORTLINK,
25     LOWDOWN_NROFF_SKIP_HTML, and LOWDOWN_STANDALONE.
26
27     The values recognised in opts->type are LOWDOWN_MAN and LOWDODN_NROFF:
28     anything else triggers LOWDODN_NROFF.
29
30     If LOWDOWN_NROFF_GROFF is set in LOWDOWN_MAN mode, macros from the
31     man-ext package as well as the original man are used in output.  These
32     are supported by both groff and mandoc.  If in LOWDODN_NROFF mode, GNU
33     extensions to ms are used along with mspdf.  These are only supported by
34     groff.
35

RETURN VALUES

37     Returns a pointer to the renderer or NULL on memory failure.  The re‐
38     turned pointer must be freed with lowdown_nroff_free(3).
39

EXAMPLES

41     The following parses b of length bsz and outputs in groff_ms(7) format.
42
43           struct lowdown_buf *out;
44           struct lowdown_doc *doc;
45           struct lowdown_node *n;
46           void *rndr;
47
48           if ((doc = lowdown_doc_new(NULL)) == NULL)
49                   err(1, NULL);
50           if ((n = lowdown_doc_parse(doc, NULL, b, bsz, NULL)) == NULL)
51                   err(1, NULL);
52           if ((out = lowdown_buf_new(256)) == NULL)
53                   err(1, NULL);
54           if ((rndr = lowdown_nroff_new(NULL)) == NULL)
55                   err(1, NULL);
56           if (!lowdown_nroff_rndr(out, rndr, n))
57                   err(1, NULL);
58
59           fwrite(out->data, 1, out->size, stdout);
60
61           lowdown_nroff_free(rndr);
62           lowdown_buf_free(out);
63           lowdown_node_free(n);
64           lowdown_doc_free(doc);
65

SEE ALSO

67     lowdown(3), lowdown_nroff_free(3), lowdown_nroff_rndr(3),
68
69     This uses both the original troff man macros for Version 7 AT&T UNIX, de‐
70     fined in man(7), and the man-ext groff extensions.  Both are implemented
71     in mandoc.
72
73     The troff ms macros are defined in groff_ms(7), with the mspdf groff ex‐
74     tensions described in "Portable Document Format Publishing with GNU
75     Troff" by Keith Marshall.  Neither are implemented in mandoc.
76
77BSD                            December 17, 2023                           BSD
Impressum