LOWDOWN_ROFF_NEW(3)

📦 version 3.2.1, in alpine 3.24, arch rolling, nixpkgs unstable, ubuntu stonking

🌸 NAME 🌸

lowdown_roff_new — allocate a roff renderer for lowdown documents 💅🦋

okay so first things first: hi bestie, welcome to the Library Functions Manual section 3, this is the lowdown_roff_new(3) page, and it is literally the page where you make a brand new roff renderer. the whole thing lives in the library called “liblowdown”. let's get into it ✨

🎀 LIBRARY 🎀

it's chillin in the library “liblowdown” — that's the one 🫶

✨ SYNOPSIS ✨

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

void *
lowdown_roff_new(const struct lowdown_opts *opts);

💖 DESCRIPTION 💖

okay so what this does is allocate a roff renderer using opts->oflags and opts->type — and if opts is NULL?? then it just uses zero and LOWDODN_MS respectively, no big deal, it's fine, she's flexible 😌. those two things are documented in lowdown(3), so go read that if you want the full lore.

the pointer you get back? you can use it with multiple invocations of lowdown_roff_rndr(3) — like, she's not a one-time-use girlie, she's reusable 💅 — and you must free her with lowdown_roff_free(3) when you're done. no leaks, bestie, that's not the vibe.

the bits that get recognized in opts->oflags are:

  • LOWDOWN_ROFF_ENDNOTES
  • LOWDOWN_ROFF_GROFF
  • LOWDOWN_NOLINK
  • LOWDOWN_NORELLINK
  • LOWDOWN_ROFF_NUMBERED
  • LOWDOWN_SHORTLINK
  • LOWDOWN_SKIP_HTML
  • LOWDOWN_ROFF_MANPAGE
  • LOWDOWN_STANDALONE

and the values that get recognized in opts->type are LOWDOWN_MAN, LOWDOWN_MDOC, and LOWDODN_MS — and literally anything else triggers LOWDODN_MS. she said "default it is, periodt 💀"

🌈 the GROFF situation 🌈

if LOWDOWN_ROFF_GROFF is set while you're in LOWDOWN_MAN mode, then macros from the man-ext package as well as the original man are used in the output. and good news: those are supported by both groff and mandoc 🎉.

but if you're in LOWDODN_MS mode instead? then GNU extensions to ms get used, along with mspdf. and those are only supported by groff. mandoc said no thanks 🙈

📌 ENDNOTES 📌

LOWDOWN_ROFF_ENDNOTES delays printing of footnotes until the end of a document. and just so you know, this does not affect LOWDOWN_MAN and LOWDOWN_MDOC documents, because those structurally only support endnotes anyway — they were already doing that, iconic behavior honestly 👑

🎨 the fonts 🎨

the renderer you allocate will use constant-width fonts "CR" (regular), "CB" (bold), "CI" (italic), and "CBI" (bold-italic). want to override the defaults? do it with variables in the struct lowdown_opts_nroff structure. customize her, she loves that 💖

also a lil historical tea ☕: this function used to be called lowdown_nroff_new(). glow-up. rebrand. we love to see it ✨

🫶 RETURN VALUES 🫶

returns a pointer to the renderer — or NULL on memory failure 😭 (rip). and whichever one you get (well, the non-NULL one), the returned pointer must be freed with lowdown_roff_free(3). don't forget. i will know.

🌟 EXAMPLES 🌟

the following parses b of length bsz and outputs in groff_ms(7) format. she ate this one, fr fr 🔥

      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_roff_new(NULL)) == NULL)
              err(1, NULL);
      if (!lowdown_roff_rndr(out, rndr, n))
              err(1, NULL);

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

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

see how she cleans up after herself?? every single free. no cap. that's the standard 🧚

👀 SEE ALSO 👀

so, more context on the format situation 🌸: this uses both the original troff man macros for Version 7 AT&T UNIX — those are defined in man(7) — and the man-ext groff extensions. both of them are implemented in mandoc 💪

the mdoc macros are defined in mdoc(7).

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. and ngl, neither of those are implemented in mandoc 😭

💀 CAVEATS 💀

the default constant-width fonts may not available for the formatter's output device (for example, the terminal). in that case, the formatter may raise a warning and ignore the font. so like… she might just shrug and move on 🙈 that's it, that's the caveat.

and that's the page bestie!! this one came from Debian, dated $Mdocdate$, and it's LOWDOWN_ROFF_NEW(3) — go make something cute, and remember to lowdown_roff_free(3) her when you're done 💖✨🎀🦋

📦 where this page comes from