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 -mwww [ options ] 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 a html email address
33       .FTP         create an ftp reference
34       .TAG         generate an html name
35       .IMG         include an image file
36       .PIMG        include png image
37       .MPIMG       place png on the margin and wrap text around it
38       .HnS         begin heading
39       .HnE         end heading
40       .LK          emit automatically collected links.
41       .HR          produce a horizontal rule
42       .NHR         suppress automatic generation of rules.
43       .HTL         only generate HTML title
44       .HEAD        add data to <head> block
45       .ULS         unorder list begin
46       .ULE         unorder list end
47       .OLS         ordered list begin
48       .OLE         ordered list end
49       .DLS         definition list begin
50       .DLE         definition list end
51       .LI          insert a list item
52       .DC          generate a drop capital
53       .HTML        pass an html raw request to the device driver
54       .CDS         code example begin
55       .CDE         code example end
56       .ALN         place links on left of main text.
57       .LNS         start a new two-column table with links in the left.
58       .LNE         end the two-column table.
59       .LINKSTYLE   initialize default url attributes.
60
61       Output of the pic, eqn, refer, and tbl preprocessors is  acceptable  as
62       input.
63

REQUESTS

65       .JOBNAME filename
66              Split output into multiple HTML files.  A file is split whenever
67              a .SH or .NH 1 is encountered.  Its argument is  the  file  stem
68              name  for  future  output  files.   This option is equivalent to
69              grohtml's -j option.
70
71       .HX n  Specify the cut off depth when  generating  links  from  section
72              headings.   For example, a parameter of 2 would cause grohtml to
73              generate a list of links for .NH 1 and .NH 2 but not for  .NH 3.
74              Whereas
75
76                     .HX 0
77
78              tells  grohtml  that  no heading links should be created at all.
79              Another method for turning automatic headings off is by  issuing
80              the the command line switch -P-l to groff.
81
82       .BCL foreground background active not-visited visited
83              This macro takes five parameters: foreground, background, active
84              hypertext link, hypertext link  not  yet  visited,  and  visited
85              hypertext link colour.
86
87       .BGIMG imagefile
88              the only parameter to this macro is the background image file.
89
90       .URL url [description] [after]
91              generates  a  URL using either one, two or three arguments.  The
92              first parameter is the actual URL, the second is the name of the
93              link,  and the third is optional stuff to be printed immediately
94              afterwards.  If description and after are absent  then  the  url
95              becomes the anchor text.  Hyphenation is disabled while printing
96              the actual URL; explicit breakpoints should be inserted with the
97              \: escape.  Here is how to encode foo ⟨http://foo.org/⟩:
98
99                     .URL http://\:foo.\:org/ foo :
100
101              If this is processed by a device other than -Thtml or -Txhtml it
102              appears as:
103
104                     foo ⟨http://foo.org⟩:
105
106              The URL macro can be of any type; for example we can reference
107              Eric Raymond's pic guide ⟨pic.html⟩ by:
108
109                     .URL pic.html "Eric Raymond's pic guide"
110
111       .MTO address [description] [after]
112              Generate  an email html reference.  The first argument is manda‐
113              tory as the email address.  The optional second argument is  the
114              text  you  see  in your browser.  If an empty argument is given,
115              address is used instead.  An optional third  argument  is  stuff
116              printed  immediately  afterwards.  Hyphenation is disabled while
117              printing the  actual  email  address.   For  example,  Joe  User
118              ⟨joe@user.org⟩ was achieved by the following macro:
119
120                     .MTO joe@user.org "Joe User"
121
122              Note that all the URLs actually are treated as consuming no tex‐
123              tual space in groff.  This could be considered as a bug since it
124              causes  some  problems.   To circumvent this, www.tmac inserts a
125              zero-width character which expands to a harmless space (only  if
126              run with -Thtml or -Txhtml).
127
128       .FTP url [description] [after]
129              indicates that data can be obtained via ftp.  The first argument
130              is the url and the second is the browser text.   A  third  argu‐
131              ment, similar to the macros above, is intended for stuff printed
132              immediately afterwards.  The second and the third parameter  are
133              optional.   Hyphenation  is  disabled  while printing the actual
134              URL.  As an example, here the location of the GNU ftp server
135              ⟨ftp://ftp.gnu.org/⟩.  The macro example above was specified by:
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 ⟨0⟩ 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
182              defaults 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
252              optional 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
284              itself with the following call
285
286                     .LINKSTYLE blue C \[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 ⟨0⟩ 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.3/tmac/www.tmac
300

BUGS

302       Report bugs to the Groff Bug Mailing List ⟨bug-groff@gnu.org⟩.  Include
303       a complete, self-contained example that will allow the bug to be repro‐
304       duced, and say which version of groff you are using.
305

SEE ALSO

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

COPYING

310       Copyright © 2000-2014 Free Software Foundation, Inc.
311
312       This file is part of groff.
313
314       groff is free software; you can redistribute it and/or modify it  under
315       the  terms  of  the GNU General Public License as published by the Free
316       Software Foundation, either version 3  of  the  License,  or  (at  your
317       option) any later version.
318
319       groff  is  distributed  in the hope that it will be useful, but WITHOUT
320       ANY WARRANTY; without even the implied warranty of  MERCHANTABILITY  or
321       FITNESS  FOR  A PARTICULAR PURPOSE.  See the GNU General Public License
322       for more details.
323
324       You should have received a copy of the GNU General Public License along
325       with this program. If not, see GPLs ⟨http://www.gnu.org/licenses/⟩.
326

AUTHORS

328       grohtml was written by Gaius Mulley ⟨gaius@glam.ac.uk⟩
329
330
331
332Groff Version 1.22.3            4 November 2014                   GROFF_WWW(7)
Impressum