groff_www(7)

📦
version 1.24.2 · 18 versions
, in alpine 3.24

✨ NAME ✨

groff_www — GNU roff macros for authoring web pages 🕸️💖

(also hi, this is from the Miscellaneous Information Manual, which is giving very "odds and ends drawer but make it chic" energy 🎀)

🌸 SYNOPSIS 🌸

groff -m www [option ...] [file ...]

🦋 DESCRIPTION 🦋

Okay bestie, so this is the manual page for the GNU www macro package, which is literally part of the groff(7) document formatting system. Iconic. 👑

Here's the tea: this macro file gets loaded automatically by the default troffrc file whenever the formatter (usually groff(1)) is called with either of the options -T html or -T xhtml. No cap, it just shows up. ✨

Heads up though: the HTML output driver grohtml(1) is in a beta state. groff distributes these macros to encourage its testing — so like, please test it, that's the whole point 🫶

Here's the full macro cast list, main-character energy only:

  • JOBNAME — split output into multiple files
  • HX — automatic heading level cut-off
  • BCL — specify colours on a web page
  • BGIMG — specify background image
  • URL — create a URL using two parameters
  • MTO — create an HTML email address
  • TAG — generate an HTML name
  • IMG — include an image file
  • PIMG — include PNG image
  • MPIMG — place PNG on the margin and wrap text around it
  • HnS — begin heading
  • HnE — end heading
  • LK — emit automatically collected links
  • HR — produce a horizontal rule
  • NHR — suppress automatic generation of rules
  • HTL — record document title as HTML metadata only
  • HEAD — add data to <head> block
  • ULS — unordered list begin
  • ULE — unordered list end
  • OLS — ordered list begin
  • OLE — ordered list end
  • DLS — definition list begin
  • DLE — definition list end
  • LI — insert a list item
  • DC — generate a drop capital
  • HTML — transmit raw HTML to output driver
  • CDS — code example begin
  • CDE — code example end
  • ALN — place links on left of main text
  • LNS — start two-column table with links on the left
  • LNE — end two-column table started with .LNS
  • LINKSTYLE — initialize default URL attributes

💅 MACROS 💅

🌟 JOBNAME file-name-stem

Split output into multiple HTML files. In ms documents, a file is split whenever an .SH or .NH 1 call is encountered. Its argument is the file name stem used for output files. This option is equivalent to grohtml's -j option. Slay, file splitting unlocked ✂️✨

🌟 HX n

Set the section heading level above which grohtml is not to automatically generate links to n. Example time: when used with the groff_ms(7) package, .HX 2 causes grohtml to generate a list of links for ms macro calls .NH 1 and .NH 2 but not for .NH 3 — whereas .HX 0 generates no hyperlinks to section headings at all. And if you give groff the option -P -l, that disables automatic heading linkage entirely. iykyk 🎯

🌟 BCL foreground background active not-visited visited

Configure the colours used for page foreground, page background, active hypertext link, hypertext links not yet visited, and visited hypertext links. Five slots, all the aesthetics 🎨

🌟 BGIMG file

Set the background image to file. Vibe check: passed 🌈

🌟 URL url [link-text [post]]

Generate a hyperlink to url with optional link-text followed immediately by non-linked text post.

If link-text is absent, url is formatted as the link text. Hyphenation is disabled while formatting a URL — so insert explicit break points with the \: escape sequence. Literally do not forget this one 🔗

🌟 MTO address [link-text [post]]

Generate an email hyperlink to address with optional link-text followed immediately by non-linked text post.

If link-text is absent, address is formatted as the link text. Hyphenation is disabled while formatting a URL — again, insert explicit break points with the \: escape sequence. Same rules, email edition 📧💌

🌟 TAG name

Generate an anchor name marking its location in the document as a target for hyperlinks. It's giving "you are here" but make it HTML 📍

🌟 IMG file-name [-C|-L|-R] [width [height]]

Insert graphical image file-name. The optional second argument aligns the image to the center (-C, the default), left (-L), or right (-R). The optional width defaults to 100 units (in the context of the HTML renderer) and the optional height to the same measurement as width. Center is the default, so no pressure 🖼️

🌟 PIMG [-C|-L|-R] file-name [width [height]]

Insert graphical image file-name, assumed to be in PNG format. Compared to IMG, this macro has the advantage of working with both PostScript and HTML devices, since it converts file-name into EPS format using pngtopnm(1), pnmcrop(1), and pnmtops(1). Bestie it does the whole pipeline for you, obsessed 💖

height and width may be given as percentages (of the line length \n[.l] and page length \n[.p], respectively).

Real talk: if the document isn't processed with -T html or -T xhtml, you must use groff(1)'s -U option. Not optional. Not a suggestion. 🚨

🌟 MPIMG [-L|-R] [-G gap] file-name [width [height]]

As PIMG, but place the image at a margin and wrap text around it. The image is aligned to the left (-L, default) or right (-R) margin. -G gap imposes horizontal space of gap pixels between the picture and the text that wraps around it. The default gap is zero. Text-wrapping around a PNG? That's main character behavior, fr fr 🦋

🌟 HnS n

Begin heading at level n. Go off, heading 👑

🌟 HnE

End heading text. That's a wrap 🎬

🌟 LK

Direct grohtml to emit the list of automatically generated hyperlinks at this location. You pick the spot, it drops the links 🫶

🌟 HR

Generate a full-width horizontal rule when used with -T html or -T xhtml. A little divider of your very own ➖

🌟 NHR

Suppress the horizontal rules at the document's top and bottom that grohtml emits by default. Sometimes less is more, lowkey 🚫

🌟 HTL

Generate an HTML title only. This differs from groff_ms(7)'s TL macro, which generates both an HTML title and an <H1> heading. Use it to provide an HTML title as document metadata but not as formatted text. The title ends when vertical space (.sp) or a break (.br) is seen. Metadata title only, zero formatting drama ✨

Add arbitrary data to the HTML <head> element. Ignored if not processed with -T html or -T xhtml. Your <head> your rules 🎀

🌟 HTML

All text after this macro is treated as raw HTML. Ignored if not processed with -T html or -T xhtml. Raw HTML, no filter, straight through — chaotic and I respect it 💀

🌟 DC L text [color]

Format a "drop cap" — a large character L (usually a capital letter) at a larger size and with a lower text baseline than the following text, such that the cap-heights of L and text align, in the specified color (default: black). Very fairy-tale-chapter-opening of you 🧚📖

🌟 CDS

Begin code display; a monospaced font is selected and filling is disabled. Code mode: activated 💻

🌟 CDE

End code display. Code mode: deactivated, we're back ✨

🌟 ALN [color [width-percentage]]

Enable a "navigation pane" containing links to section headings, aligned to the left of running text, and configure its rendering parameters. Columnation is achieved with an HTML table. color indicates an HTML background color to be used in the navigation column; the default is #eeeeee. width-percentage allocates the given percentage of the navigation pane's table column; the default is 30.

Call this macro at most once, at the beginning of the document. Seriously, once. Not twice, bestie 🙈

🌟 LNS

Begin text indexed by the navigation pane configured by ALN. Let the nav do its thing 🧭

🌟 LNE

End text indexed by navigation pane started by LNS. Nav text: closed out 🎀

🌟 LINKSTYLE color [font-style [open-glyph close-glyph]]

Configure rendering of formatted hyperlink targets for devices other than html and xhtml; render targets in color (default: blue) using the typeface font-style (default: CR) bracketed with open-glyph and close-glyph (defaults: \[la] and \[ra], respectively). Zebra-striping your links, I see you 💙

By default, grohtml generates links to all section headings and places these at the top of the HTML document. Configure this behavior with HX and/or LK. Your page, your navigation, your rules ⭐

😭 LIMITATIONS OF GROHTML 😭

Okay, real talk time. Here's what grohtml can't do (yet):

  • tbl(1) tables are rendered as PNG images. Yeah. Images. Of tables. 💀
  • All URLs currently are treated as consuming no textual space in groff. This could be considered as a bug since it causes some problems. To circumvent this, www.tmac inserts a zero-width character which expands to a harmless space (only if run with -Thtml or -Txhtml). Sneaky little workaround, we love a hack 🫶
  • Some of the macros, like ALN, LNS, and LNE, are integrated only with the groff_ms(7) package. ms girlies only for those 🙈

🍓 FILES 🍓

  • /usr/share/groff/1.24.2/tmac/www.tmac

That's the file, right there, in all its glory ✨

👑 AUTHORS 👑

The www macro package was written by Gaius Mulley, with additions by Werner Lemberg and Bernd Warken. Legends, all of them 🌟

🦋 SEE ALSO 🦋

Go read them, bestie, they're literally right there 📚💖

okay that's the whole page, mwah 💋 — this was groff 1.24.2, dated 2026-10-01, from the groff_www(7) page. Now go build a web page with roff like the absolute icon you are 🎀✨

📦 where this page comes from