www.LinuxHowtos.org

groff_www

Section: Environments, Tables, and Troff Macros (7)
Updated: 202-0-28
Index Return to Main Contents

Name

groff_www - GNU roff macros for authoring web pages
.nr d-fallback 1
.nr d-fallback 1

Synopsis

[option~...] [file~...]

Description

This manual page describes the GNU www macro package, which is part of the document formatting system. This macro file is automatically loaded by the default troffrc file when the formatter (usually is called with either of the options [lq]-T~html[rq] or [lq]-T~xhtml[rq]. The HTML output driver 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 cu-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 tw-column table with links on the left
LNE	end tw-column table started with .LNS
LINKSTYLE	initialize default URL attributes

Macros

JOBNAME~fil-nam-stem: Split output into multiple HTML files. In ms documents, a file is split whenever an .SH or [lq].NH~1[rq] 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 package, [lq].HX~2[rq] causes grohtml to generate a list of links for ms macro calls [lq].NH~1[rq] and [lq].NH~2[rq] but not for [lq].NH~3[rq], whereas [lq].HX~0[rq] generates no hyperlinks to section headings. Giving groff the option [lq]-P~-l[rq] disables automatic heading linkage.
BCL~foreground background active no-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~: [lin-text~[post]] Generate a hyperlink to url with optional lin-text followed immediately by no-linked text post.
: If lin-text is absent, url is formatted as the link text. Hyphenation is disabled while formatting a URL; insert explicit break points with the [rs]: escape sequence.
MTO~address~: [lin-text~[post]] Generate an email hyperlink to address with optional lin-text followed immediately by no-linked text post.
: If lin-text is absent, address is formatted as the link text. Hyphenation is disabled while formatting a URL; insert explicit break points with the [rs]: escape sequence.
TAG~name: Generate an anchor name marking its location in the document as a target for hyperlinks.
IMG~fil-name~: [-C|-L|-R]~[width~[height]] Insert graphical image fil-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]~: fil-name~[width~[height]] Insert graphical image fil-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 fil-name into EPS format using and height and width may be given as percentages (of the line length [rs]n[.l] and page length [rs]n[.p], respectively).
: If the document isn't processed with [lq]-T~html[rq] or [lq]-T~xhtml[rq], you must use -U option.
MPIMG~[-L|-R]~[-G~: gap]~fil-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 ful-width horizontal rule when used with [lq]-T~html[rq] or [lq]-T~xhtml[rq].
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 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.
HEAD: Add arbitrary data to the HTML <head> element. Ignored if not processed with [lq]-T~html[rq] or [lq]-T~xhtml[rq].
HTML: All text after this macro is treated as raw HTML. Ignored if not processed with [lq]-T~html[rq] or [lq]-T~xhtml[rq].
DC~L text~: [color] Format a [lq]drop cap[rq][em]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 ca-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~[widt-percentage]] Enable a [lq]navigation pane[rq] 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. widt-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~: [fon-style~[ope-glyph clos-glyph]] Configure rendering of formatted hyperlink targets for devices other than html and xhtml; render targets in color (default: blue) using the typeface fon-style (default: CR) bracketed with ope-glyph and clos-glyph (defaults: [rs][la] and [rs][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 I]grohtml]

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 zer-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 package.

Files

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

Authors

The www macro package was written by Gaius Mulley with additions by Werner Lemberg and Bernd Warken