# groff_www

## 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) document formatting system.  This macro file
           is automatically loaded by the default _troffrc_ file when the
           formatter (usually _groff_(1)) is called with either of the options
           “**-T html** ” or “**-T xhtml** ”.  The HTML output driver _grohtml_(1) 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 <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.
    
           **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) 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),
                  _pnmcrop_(1), and _pnmtops_(1).  _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)'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)'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.
    
           **HEAD** Add arbitrary data to the HTML <head> 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) tables are rendered as PNG images.  Paul DuBois's approach
           with _tblcvt_(1), part of the _troffcvt_ distribution 
           ⟨http://www.snake.net/software/troffcvt/⟩, should be explored.
    
           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) package.
    


## Files



           _/usr/local/share/groff/1.23.0/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), _troff_(1), _grohtml_(1), _netpbm_(1)
    


* * *