LOWDOWN_NROFF_NEW(3)

💅 NAME 💅

lowdown_nroff_new — bestie, this is the one that allocates a roff renderer for lowdown documents ✨

📚 LIBRARY 📚

It lives in the library “liblowdown” 🫶

🌸 SYNOPSIS 🌸

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

void *
lowdown_nroff_new(const struct lowdown_opts *opts);

---

✨ DESCRIPTION ✨

Okay so here's the tea ☕ — this function allocates a roff renderer, and it uses opts->oflags and opts->type to decide how it's gonna act. But if opts is NULL? No worries bestie, it just uses zero and LOWDODN_NROFF respectively 🙈 Both of those things are documented over in lowdown(3), iykyk.

The pointer you get back is reusable — you can hit it with multiple invocations of lowdown_nroff_rndr(3) and it's gonna serve every time 👑 But when you're done with it you must free it with lowdown_nroff_free(3). No leaks, we don't do that here 💅

The bits it actually recognises in opts->oflags are:

• LOWDOWN_NROFF_ENDNOTES
• LOWDOWN_NROFF_GROFF
• LOWDOWN_NROFF_NOLINK
• LOWDOWN_NROFF_NUMBERED
• LOWDOWN_NROFF_SHORTLINK
• LOWDOWN_NROFF_SKIP_HTML
• LOWDOWN_STANDALONE

And the values it recognises in opts->type are LOWDOWN_MAN and LOWDODN_NROFF — but literally anything else? It just triggers LOWDODN_NROFF. That's the fallback, periodt. 💀

Now the LOWDOWN_NROFF_GROFF situation, because this part matters 🔥 If it's set while you're in LOWDOWN_MAN mode, then macros from the man-ext package get used in the output, plus the original man macros too. Both groff and mandoc support those 🫶 If instead you're in LOWDODN_NROFF mode, GNU extensions to ms are used along with mspdf — and those are only supported by groff. So, vibe check on your formatter first, fr fr.

LOWDOWN_NROFF_ENDNOTES delays printing of footnotes until the end of a document 🎀 It does not affect LOWDOWN_MAN documents, because those structurally only support endnotes anyway. It's giving "you didn't need to ask" energy.

The allocated renderer will use constant-width fonts "CR" (regular), "CB" (bold), "CI" (italic), and "CBI" (bold-italic) 🦋 And if that's not the vibe? Override the defaults with variables in the struct lowdown_opts_nroff structure. Slay.

---

🎀 RETURN VALUES 🎀

Returns a pointer to the renderer ✨ or NULL on memory failure 😭 Either way, the returned pointer must be freed with lowdown_nroff_free(3). That's not optional, bestie.

---

🌈 EXAMPLES 🌈

Here's the moment you've been waiting for — 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);

Look at that cleanup section. Chef's kiss 😭🧼

---

👀 SEE ALSO 👀

• lowdown(3)
• lowdown_nroff_free(3)
• lowdown_nroff_rndr(3)

So this whole thing uses both the original troff man macros for Version 7 AT&T UNIX, which are defined in man(7), and the man-ext groff extensions 🌸 Both of those are implemented in mandoc, so you're safe there.

The troff ms macros, on the other hand, are defined in groff_ms(7), with the mspdf groff extensions described in "Portable Document Format Publishing with GNU Troff" by Keith Marshall. Neither of those are implemented in mandoc. Read that twice, bestie 💀

---

⚠️ CAVEATS ⚠️

The default constant-width fonts may not be available for the formatter's output device (for example, the terminal) 😬 In this case, the formatter may raise a warning and ignore the font. Not a crash, just a little side-eye from your formatter.

---

Okay that's the whole page!! This one came out of the Debian crew, dated $Mdocdate$, and it's LOWDOWN_NROFF_NEW(3) in the Library Functions Manual — go forth and render your roff, you gorgeous genius 💖✨🎀