--- name: "groff_www" section: "7" platform: "linux" package: "groff" version: "1.24.2-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/groff_www" --- # groff\_www(7) GNU roff macros for authoring web pages ## Name groff\_www - GNU *roff* macros for authoring web pages ## Synopsis **groff -m www** \[*option* ...\] \[*file* ...\] ## Description This manual page describes the GNU *www* macro package, which is part of the [*groff*(7)](/groff/7.md) document formatting system. This macro file is automatically loaded by the default *troffrc* file when the formatter (usually [*groff*(1)](/groff/1.md)) is called with either of the options “**-T html**” or “**-T xhtml**”. The HTML output driver [*grohtml*(1)](/grohtml/1.md) is in a beta state; *groff* distributes these macros to encourage its testing. | | | | --- | --- | | Macro | Meaning | | **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 \ 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. - **HX** *n* Set section heading level above which *grohtml* is not to automatically generate links to *n.* For example, when used with the [*groff\_ms*(7)](/groff_ms/7.md) 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. Giving *groff* the option “**-P -l**” disables automatic heading linkage. - **BCL** *foreground background active not-visited visited* Configure colours used for page foreground, page background, active hypertext link, hypertext links not yet visited, and visited hypertext links. - **BGIMG** *file* Set the background image to *file.* - **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; insert explicit break points with the **\\:** escape sequence. - **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; insert explicit break points with the **\\:** escape sequence. - **TAG** *name* Generate an anchor *name* marking its location in the document as a target for hyperlinks. - **IMG** *file-name* \[**-C**\|**-L**\|**-R**\] \[*width* \[*height*\]\] Insert graphical image *file-name.* The optional second argument aligns the image to the center (**-C**; 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 .* - **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)](/pngtopnm/1.md), [*pnmcrop*(1)](/pnmcrop/1.md), and [*pnmtops*(1)](/pnmtops/1.md). *height* and *width* may be given as percentages (of the line length **\\n\[.l\]** and page length **\\n\[.p\]**, respectively). - If the document isn't processed with “**-T html**” or “**-T xhtml**”, you must use [*groff*(1)](/groff/1.md)'s **-U** option. - **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 the 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. - **HnS** *n* Begin heading at level *n.* - **HnE** End heading text. - **LK** Direct *grohtml* to emit the list of automatically generated hyperlinks at this location. - **HR** Generate a full-width horizontal rule when used with “**-T html**” or “**-T xhtml**”. - **NHR** Suppress the horizontal rules at the document's top and bottom that *grohtml* emits by default. - **HTL** Generate an HTML title only. This differs from [*groff\_ms*(7)](/groff_ms/7.md)'s **TL** macro, which generates both an HTML title and an \ 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. - **HEAD** Add arbitrary data to the HTML \ element. Ignored if not processed with “**-T html**” or “**-T xhtml**”. - **HTML** All text after this macro is treated as raw HTML. Ignored if not processed with “**-T html**” or “**-T xhtml**”. - **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). - **CDS** Begin code display; a monospaced font is selected and filling is disabled. - **CDE** End code display. - **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. - **LNS** Begin text indexed by the navigation pane configured by **ALN**. - **LNE** End text indexed by navigation pane started by **LNS**. - **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). ## Section heading links 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**. ## Limitations of *grohtml* [*tbl*(1)](/tbl/1.md) tables are rendered as PNG images. 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**). Some of the macros, like **ALN**, **LNS**, and **LNE**, are integrated only with the [*groff\_ms*(7)](/groff_ms/7.md) package. ## Files */usr/share/groff/1.24.2/tmac/www.tmac* ## Authors The *www* macro package was written by Gaius Mulley ⟨gaius@\\:glam\\:.ac\\:.uk⟩, with additions by Werner Lemberg ⟨wl@\\:gnu\\:.org⟩ and Bernd Warken ⟨groff\\-bernd\\:.warken\\-72@\\:web\\:.de⟩. ## See also [*groff*(1)](/groff/1.md), [*troff*(1)](/troff/1.md), [*grohtml*(1)](/grohtml/1.md), [*netpbm*(1)](/netpbm/1.md)