groff_www(7) — Linux manual page

Name | Synopsis | Description | Macros | Section heading links | Limitations of grohtml | Files | Authors | See also | COLOPHON

groff_www(7)        Miscellaneous Information Manual        groff_www(7)

Name         top

       groff_www - GNU roff macros for authoring web pages

Synopsis         top

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

Description         top

       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         top

       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 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         top

       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         top

       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         top

       /usr/local/share/groff/1.23.0/tmac/www.tmac

Authors         top

       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         top

       groff(1), troff(1), grohtml(1), netpbm(1)

COLOPHON         top

       This page is part of the groff (GNU troff) project.  Information
       about the project can be found at 
       ⟨http://www.gnu.org/software/groff/⟩.  If you have a bug report
       for this manual page, see ⟨http://www.gnu.org/software/groff/⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-06-10.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

groff 1.23.0.453-330f9-d... 23 September 2023               groff_www(7)