GROFF_WWW(7)           (9 September 2021)            GROFF_WWW(7)

     NAME
          groff_www - groff macros for authoring web pages

     SYNOPSIS
          [option ...] [input-file ...]

     DESCRIPTION
          This manual page describes the GNU -mwww macro package,
          which is part of the groff document formatting system.  The
          manual page is very a basic guide, and the HTML device
          driver (grohtml) has been completely rewritten but still
          remains as in an alpha state.  It has been included into the
          distribution so that a lot of people have a chance to test
          it.  Note that this macro file is automatically called (via
          the troffrc file) if you use -Thtml or -Txhtml.

          To see the hyperlinks in action, please format this man page
          with the grohtml device.

          Here is a summary of the functions found in this macro set.
          tab(@); l l.  .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 .FTP@create an FTP reference
          .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@only gen-
          erate HTML title .HEAD@add data to <head> block .ULS@unorder
          list begin .ULE@unorder 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@pass an HTML raw request to the device
          driver .CDS@code example begin .CDE@code example end
          .ALN@place links on left of main text.  .LNS@start a new
          two-column table with links in the left.  .LNE@end the two-
          column table.  .LINKSTYLE@initialize default URL attributes.

          Output of the pic, eqn, refer, and tbl preprocessors is
          acceptable as input.

     REQUESTS
          .JOBNAME filename
               Split output into multiple HTML files.  A file is split
               whenever a .SH or .NH 1 is encountered.  Its argument
               is the file stem name for future output files.  This
               option is equivalent to grohtml's -j option.

     Page 1                    groff 1.22.4          (printed 5/22/22)

     GROFF_WWW(7)           (9 September 2021)            GROFF_WWW(7)

          .HX n
               Specify the cut off depth when generating links from
               section headings.  For example, a parameter of~2 would
               cause grohtml to generate a list of links for .NH 1 and
               .NH 2 but not for .NH 3.  Whereas

                    .HX 0

               tells grohtml that no heading links should be created
               at all.  Another method for turning automatic headings
               off is by issuing the command-line switch -P-l to
               groff.

          .BCL foreground background active not-visited visited
               This macro takes five parameters: foreground, back-
               ground, active hypertext link, hypertext link not yet
               visited, and visited hypertext link colour.

          .BGIMG imagefile
               the only parameter to this macro is the background
               image file.

          .URL url [description] [after]
               generates a URL using either one, two or three argu-
               ments.  The first parameter is the actual URL, the sec-
               ond is the name of the link, and the third is optional
               stuff to be printed immediately afterwards.  If
               description and after are absent then the URL becomes
               the anchor text.  Hyphenation is disabled while print-
               ing the actual URL; explicit breakpoints should be
               inserted with the [rs]: escape.  Here is how to encode
               foo

                    .URL http://[rs]:foo.[rs]:org/ foo :

               If this is processed by a device other than -Thtml or
               -Txhtml it appears as:

                    foo [la]CR]http://foo.org][ra]:

               The URL macro can be of any type; for example we can
               reference Eric Raymond's pic guide by:

                    .URL pic.html [dq]Eric Raymond's pic guide[dq]

          .MTO address [description] [after]
               Generate an email HTML reference.  The first argument
               is mandatory as the email address.  The optional second
               argument is the text you see in your browser.  If an
               empty argument is given, address is used instead.  An
               optional third argument is stuff printed immediately
               afterwards.  Hyphenation is disabled while printing the

     Page 2                    groff 1.22.4          (printed 5/22/22)

     GROFF_WWW(7)           (9 September 2021)            GROFF_WWW(7)

               actual email address.  For example, Joe User can be
               achieved by the following macro:

                    .MTO joe@user.org [dq]Joe User[dq]

               Note that all the URLs actually are treated as consum-
               ing no textual space in groff.  This could be consid-
               ered as a bug since it causes some problems.  To cir-
               cumvent this, www.tmac inserts a zero-width character
               which expands to a harmless space (only if run with
               -Thtml or -Txhtml).

          .FTP url [description] [after]
               indicates that data can be obtained via FTP.  The first
               argument is the URL and the second is the browser text.
               A third argument, similar to the macros above, is
               intended for stuff printed immediately afterwards.  The
               second and the third parameter are optional.  Hyphen-
               ation is disabled while printing the actual URL.  As an
               example, here is the location of the GNU FTP server The
               macro example above can be specified as:

                    .FTP ftp://[rs]:ftp.gnu.org/ [dq]GNU FTP
                    server[dq] .

          .TAG name
               Generates an HTML name tag from its argument.  This can
               then be referenced using the URL macro.  As you can
               see, you must precede the tag name with # since it is a
               local reference.  This link was achieved via placing a
               TAG in the URL description above; the source looks like
               this:

                    .TP
                    .B URL
                    generates
                    .TAG URL
                    a URL using either two or three arguments.
                    ...

          .IMG [-R|-L|-C] filename [width] [height]
               Include a picture into the document.  The first argu-
               ment is the horizontal location: right, left, or center
               (-R, -L, or -C).  Alignment is centered by default
               (-C).  The second argument is the filename.  The
               optional third and fourth arguments are the width and
               height.  If the width is absent it defaults to 1~inch.
               If the height is absent it defaults to the width.  This
               maps onto an HTML img tag.  If you are including a PNG
               image then it is advisable to use the PIMG macro.

          .PIMG [-R|-L|-C] filename [width [height]]

     Page 3                    groff 1.22.4          (printed 5/22/22)

     GROFF_WWW(7)           (9 September 2021)            GROFF_WWW(7)

               Include an image in PNG format.  This macro takes
               exactly the same parameters as the IMG macro; it has
               the advantage of working with PostScript and HTML
               devices also since it can automatically convert the
               image into the EPS format, using the following programs
               of the netpbm package: pngtopnm, pnmcrop, and pnmtops.
               If the document isn't processed with -Thtml or -Txhtml
               it is necessary to use the -U option of groff.

          .MPIMG [-R|-L] [-G gap] filename [width
               Place a PNG image on the margin and wrap text around
               it.  The first parameters are optional.  The alignment:
               left or right (-L or -R) specifies the margin where the
               picture is placed at.  The default alignment is left
               (-L).  Optionally, -G~gap can be used to arrange a gap
               between the picture and the text that wraps around it.
               The default gap width is zero.
               The first non-optional argument is the filename.  The
               optional following arguments are the width and height.
               If the width is absent it defaults to 1~inch.  If the
               height is absent it defaults to the width.  Example:

                    .MPIMG -L -G 2c foo.png 3c 1.5c

               The height and width may also be given as percentages.
               The PostScript device calculates the width from the .l
               register and the height from the .p register.  For
               example:

                    .MPIMG -L -G 2c foo.png 15%

          .HnS n
               Begin heading.  The numeric heading level n is speci-
               fied by the first parameter.  Use this macro if your
               headings contain URL, FTP or MTO macros.  Example:

                    .HnS 1
                    .HR
                    GNU Troff
                    .URL http://groff.ffii.org (Groff)
                    - a
                    .URL http://www.gnu.org/ GNU
                    project.
                    Hosted by
                    .URL http://ffii.org/ FFII .
                    .HR
                    .HnE

               In this case you might wish to disable automatic links
               to headings.  This can be done via -P-l from the com-
               mand line.

     Page 4                    groff 1.22.4          (printed 5/22/22)

     GROFF_WWW(7)           (9 September 2021)            GROFF_WWW(7)

          .HnE End heading.

          .LK  Force grohtml to place the automatically generated
               links at this position.  If this manual page has been
               processed with -Thtml or -Txhtml those links can be
               seen right here.

          .HR  Generate a full-width horizontal rule for -Thtml and
               -Txhtml.  No effect for all other devices.

          .NHR Suppress generation of the top and bottom rules which
               grohtml emits by default.

          .HTL Generate an HTML title only.  This differs from the TL
               macro of the ms macro package which generates both an
               HTML title and an <H1> heading.  Use it to provide an
               HTML title as search engine fodder but a graphic title
               in the document.  The macro terminates when a space or
               break is seen (.sp, .br).

          .HEAD
               Add arbitrary HTML data to the <head> block.  Ignored
               if not processed with -Thtml or -Txhtml.  Example:

                    .HEAD [dq]<link [rs]
                      rel=[dq][dq]icon[dq][dq] [rs]
                      type=[dq][dq]image/png[dq][dq] [rs]
                      href=[dq][dq]http://foo.org//bar.png[dq][dq]/>[dq]

          .HTML
               All text after this macro is treated as raw HTML.  If
               the document is processed without -Thtml or -Txhtml
               then the macro is ignored.  Internally, this macro is
               used as a building block for other higher-level macros.

               For example, the BGIMG macro is defined as

                    .de BGIMG
                    .   HTML <body background=[rs][rs]$1>
                    ..

          .DC l text [color]
               Produce a drop capital.  The first parameter is the
               letter to be dropped and enlarged, the second parameter
               text is the adjoining text whose height the first let-
               ter should not exceed.  The optional third parameter is
               the color of the dropped letter.  It defaults to black.

          .CDS Start displaying a code section in constant width font.

          .CDE End code display

     Page 5                    groff 1.22.4          (printed 5/22/22)

     GROFF_WWW(7)           (9 September 2021)            GROFF_WWW(7)

          .ALN [color] [percentage]
               Place section heading links automatically to the left
               of the main text.  The color argument is optional and
               if present indicates which HTML background color is to
               be used under the links.  The optional percentage indi-
               cates the amount of width to devote to displaying the
               links.  The default values are #eeeeee and 30 for color
               and percentage width, respectively.  This macro should
               only be called once at the beginning of the document.
               After calling this macro each section heading emits an
               HTML table consisting of the links in the left and the
               section text on the right.

          .LNS Start a new two-column table with links in the left
               column.  This can be called if the document has text
               before the first .SH and if .ALN is used.  Typically
               this is called just before the first paragraph and
               after the main title as it indicates that text after
               this point should be positioned to the right of the
               left-hand navigational links.

          .LNE End a two-column table.  This should be called at the
               end of the document if .ALN was used.

          .LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ]
               Initialize default URL attributes to be used if this
               macro set is not used with the HTML device.  The macro
               set initializes itself with the following call

                    .LINKSTYLE blue CR \[la] \[ra]

               but these values will be superseded by a user call to
               LINKSTYLE.

     SECTION HEADING LINKS
          By default grohtml generates links to all section headings
          and places these at the top of the HTML document.  (See
          LINKS for details of how to switch this off or alter the
          position).

     LIMITATIONS OF GROHTML
          tbl information is currently rendered as a PNG image.

     FILES
          /usr/:share/:groff/:1.22.4/:tmac/www.tmac

     AUTHORS
          The www macro package was written by Gaius Mulley with addi-
          tions by Werner Lemberg and Bernd Warken

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

     Page 6                    groff 1.22.4          (printed 5/22/22)