1GROFF_WWW(7)           Miscellaneous Information Manual           GROFF_WWW(7)
2
3
4

NAME

6       groff_www - groff macros for authoring web pages
7
8

SYNOPSIS

10       groff -m www [option ...] [input-file ...]
11

DESCRIPTION

13       This manual page describes the GNU -mwww macro package, which is part
14       of the groff document formatting system.  The manual page is very a
15       basic guide, and the HTML device driver (grohtml) has been completely
16       rewritten but still remains as in an alpha state.  It has been included
17       into the distribution so that a lot of people have a chance to test it.
18       Note that this macro file is automatically called (via the troffrc
19       file) if you use -Thtml or -Txhtml.
20
21       To see the hyperlinks in action, please format this man page with the
22       grohtml device.
23
24       Here is a summary of the functions found in this macro set.
25
26       .JOBNAME     split output into multiple files
27       .HX          automatic heading level cut off
28       .BCL         specify colours on a web page
29       .BGIMG       specify background image
30       .URL         create a URL using two parameters
31       .FTP         create an FTP reference
32       .MTO         create an HTML email address
33       .TAG         generate an HTML name
34       .IMG         include an image file
35       .PIMG        include PNG image
36       .MPIMG       place PNG on the margin and wrap text around it
37       .HnS         begin heading
38       .HnE         end heading
39       .LK          emit automatically collected links.
40       .HR          produce a horizontal rule
41       .NHR         suppress automatic generation of rules.
42       .HTL         only generate HTML title
43       .HEAD        add data to <head> block
44       .ULS         unorder list begin
45       .ULE         unorder list end
46       .OLS         ordered list begin
47       .OLE         ordered list end
48       .DLS         definition list begin
49       .DLE         definition list end
50       .LI          insert a list item
51       .DC          generate a drop capital
52       .HTML        pass an HTML raw request to the device driver
53       .CDS         code example begin
54       .CDE         code example end
55       .ALN         place links on left of main text.
56       .LNS         start a new two-column table with links in the left.
57       .LNE         end the two-column table.
58       .LINKSTYLE   initialize default URL attributes.
59
60       Output of the pic, eqn, refer, and tbl preprocessors is acceptable as
61       input.
62

REQUESTS

64       .JOBNAME filename
65              Split output into multiple HTML files.  A file is split whenever
66              a .SH or .NH 1 is encountered.  Its argument is the file stem
67              name for future output files.  This option is equivalent to
68              grohtml's -j option.
69
70       .HX n  Specify the cut off depth when generating links from section
71              headings.  For example, a parameter of 2 would cause grohtml to
72              generate a list of links for .NH 1 and .NH 2 but not for .NH 3.
73              Whereas
74
75                     .HX 0
76
77              tells grohtml that no heading links should be created at all.
78              Another method for turning automatic headings off is by issuing
79              the command-line switch -P-l to groff.
80
81       .BCL foreground background active not-visited visited
82              This macro takes five parameters: foreground, background, active
83              hypertext link, hypertext link not yet visited, and visited
84              hypertext link colour.
85
86       .BGIMG imagefile
87              the only parameter to this macro is the background image file.
88
89       .URL url [description] [after]
90              generates a URL using either one, two or three arguments.  The
91              first parameter is the actual URL, the second is the name of the
92              link, and the third is optional stuff to be printed immediately
93              afterwards.  If description and after are absent then the URL
94              becomes the anchor text.  Hyphenation is disabled while printing
95              the actual URL; explicit breakpoints should be inserted with the
96              \: escape.  Here is how to encode foo ⟨http://foo.org/⟩:
97
98                     .URL http://\:foo.\:org/ foo :
99
100              If this is processed by a device other than -Thtml or -Txhtml it
101              appears as:
102
103                     foo ⟨http://foo.org⟩:
104
105              The URL macro can be of any type; for example we can reference
106              Eric Raymond's pic guide ⟨pic.html⟩ by:
107
108                     .URL pic.html "Eric Raymond's pic guide"
109
110       .MTO address [description] [after]
111              Generate an email HTML reference.  The first argument is manda‐
112              tory as the email address.  The optional second argument is the
113              text you see in your browser.  If an empty argument is given,
114              address is used instead.  An optional third argument is stuff
115              printed immediately afterwards.  Hyphenation is disabled while
116              printing the actual email address.  For example, Joe User
117              ⟨joe@user.org⟩ can be achieved by the following macro:
118
119                     .MTO joe@user.org "Joe User"
120
121              Note that all the URLs actually are treated as consuming no tex‐
122              tual space in groff.  This could be considered as a bug since it
123              causes some problems.  To circumvent this, www.tmac inserts a
124              zero-width character which expands to a harmless space (only if
125              run with -Thtml or -Txhtml).
126
127       .FTP url [description] [after]
128              indicates that data can be obtained via FTP.  The first argument
129              is the URL and the second is the browser text.  A third argu‐
130              ment, similar to the macros above, is intended for stuff printed
131              immediately afterwards.  The second and the third parameter are
132              optional.  Hyphenation is disabled while printing the actual
133              URL.  As an example, here is the location of the GNU FTP server
134              ⟨ftp://ftp.gnu.org/⟩.  The macro example above can be specified
135              as:
136
137                     .FTP ftp://\:ftp.gnu.org/ "GNU FTP server" .
138
139       .TAG name
140              Generates an HTML name tag from its argument.  This can then be
141              referenced using the URL ⟨#URL⟩ macro.  As you can see, you must
142              precede the tag name with # since it is a local reference.  This
143              link was achieved via placing a TAG in the URL description
144              above; the source looks like this:
145
146                     .TP
147                     .B URL
148                     generates
149                     .TAG URL
150                     a URL using either two or three arguments.
151                     ...
152
153       .IMG [-R|-L|-C] filename [width] [height]
154              Include a picture into the document.  The first argument is the
155              horizontal location: right, left, or center (-R, -L, or -C).
156              Alignment is centered by default (-C).  The second argument is
157              the filename.  The optional third and fourth arguments are the
158              width and height.  If the width is absent it defaults to 1 inch.
159              If the height is absent it defaults to the width.  This maps
160              onto an HTML img tag.  If you are including a PNG image then it
161              is advisable to use the PIMG macro.
162
163       .PIMG [-R|-L|-C] filename [width [height]]
164              Include an image in PNG format.  This macro takes exactly the
165              same parameters as the IMG macro; it has the advantage of work‐
166              ing with PostScript and HTML devices also since it can automati‐
167              cally convert the image into the EPS format, using the following
168              programs of the netpbm package: pngtopnm, pnmcrop, and pnmtops.
169              If the document isn't processed with -Thtml or -Txhtml it is
170              necessary to use the -U option of groff.
171
172       .MPIMG [-R|-L] [-G gap] filename [width [height]]
173              Place a PNG image on the margin and wrap text around it.  The
174              first parameters are optional.  The alignment: left or right (-L
175              or -R) specifies the margin where the picture is placed at.  The
176              default alignment is left (-L).  Optionally, -G gap can be used
177              to arrange a gap between the picture and the text that wraps
178              around it.  The default gap width is zero.
179              The first non-optional argument is the filename.  The optional
180              following arguments are the width and height.  If the width is
181              absent it defaults to 1 inch.  If the height is absent it de‐
182              faults to the width.  Example:
183
184                     .MPIMG -L -G 2c foo.png 3c 1.5c
185
186              The height and width may also be given as percentages.  The
187              PostScript device calculates the width from the .l register and
188              the height from the .p register.  For example:
189
190                     .MPIMG -L -G 2c foo.png 15%
191
192       .HnS n Begin heading.  The numeric heading level n is specified by the
193              first parameter.  Use this macro if your headings contain URL,
194              FTP or MTO macros.  Example:
195
196                     .HnS 1
197                     .HR
198                     GNU Troff
199                     .URL http://groff.ffii.org (Groff)
200                     — a
201                     .URL http://www.gnu.org/ GNU
202                     project.
203                     Hosted by
204                     .URL http://ffii.org/ FFII .
205                     .HR
206                     .HnE
207
208              In this case you might wish to disable automatic links to head‐
209              ings.  This can be done via -P-l from the command line.
210
211       .HnE   End heading.
212
213       .LK    Force grohtml to place the automatically generated links at this
214              position.  If this manual page has been processed with -Thtml or
215              -Txhtml those links can be seen right here.
216
217       .HR    Generate a full-width horizontal rule for -Thtml and -Txhtml.
218              No effect for all other devices.
219
220       .NHR   Suppress generation of the top and bottom rules which grohtml
221              emits by default.
222
223       .HTL   Generate an HTML title only.  This differs from the TL macro of
224              the ms macro package which generates both an HTML title and an
225              <H1> heading.  Use it to provide an HTML title as search engine
226              fodder but a graphic title in the document.  The macro termi‐
227              nates when a space or break is seen (.sp, .br).
228
229       .HEAD  Add arbitrary HTML data to the <head> block.  Ignored if not
230              processed with -Thtml or -Txhtml.  Example:
231
232                     .HEAD "<link \
233                       rel=""icon"" \
234                       type=""image/png"" \
235                       href=""http://foo.org//bar.png""/>"
236
237       .HTML  All text after this macro is treated as raw HTML.  If the docu‐
238              ment is processed without -Thtml or -Txhtml then the macro is
239              ignored.  Internally, this macro is used as a building block for
240              other higher-level macros.
241
242              For example, the BGIMG macro is defined as
243
244                     .de BGIMG
245                     .   HTML <body background=\\$1>
246                     ..
247
248       .DC l text [color]
249              Produce a drop capital.  The first parameter is the letter to be
250              dropped and enlarged, the second parameter text is the adjoining
251              text whose height the first letter should not exceed.  The op‐
252              tional third parameter is the color of the dropped letter.  It
253              defaults to black.
254
255       .CDS   Start displaying a code section in constant width font.
256
257       .CDE   End code display
258
259       .ALN [color] [percentage]
260              Place section heading links automatically to the left of the
261              main text.  The color argument is optional and if present indi‐
262              cates which HTML background color is to be used under the links.
263              The optional percentage indicates the amount of width to devote
264              to displaying the links.  The default values are #eeeeee and 30
265              for color and percentage width, respectively.  This macro should
266              only be called once at the beginning of the document.  After
267              calling this macro each section heading emits an HTML table con‐
268              sisting of the links in the left and the section text on the
269              right.
270
271       .LNS   Start a new two-column table with links in the left column.
272              This can be called if the document has text before the first .SH
273              and if .ALN is used.  Typically this is called just before the
274              first paragraph and after the main title as it indicates that
275              text after this point should be positioned to the right of the
276              left-hand navigational links.
277
278       .LNE   End a two-column table.  This should be called at the end of the
279              document if .ALN was used.
280
281       .LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ]
282              Initialize default URL attributes to be used if this macro set
283              is not used with the HTML device.  The macro set initializes it‐
284              self with the following call
285
286                     .LINKSTYLE blue CR \[la] \[ra]
287
288              but these values will be superseded by a user call to LINKSTYLE.
289
291       By default grohtml generates links to all section headings and places
292       these at the top of the HTML document.  (See LINKS ⟨#LK⟩ for details of
293       how to switch this off or alter the position).
294

LIMITATIONS OF GROHTML

296       tbl information is currently rendered as a PNG image.
297

FILES

299       /usr/share/groff/1.22.4/tmac/www.tmac
300

AUTHORS

302       The www macro package was written by Gaius Mulley ⟨gaius@glam.ac.uk⟩,
303       with additions by Werner Lemberg ⟨wl@gnu.org⟩ and Bernd Warken
304       ⟨groff-bernd.warken-72@web.de⟩.
305

SEE ALSO

307       groff(1), troff(1), grohtml(1), netpbm(1)
308
309
310
311groff 1.22.4                     17 March 2021                    GROFF_WWW(7)
Impressum