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

NAME

8       groff_www - groff macros for authoring web pages
9
10

SYNOPSIS

12       groff -mwww [ options ] file ...
13

DESCRIPTION

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

REQUESTS

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

LIMITATIONS OF GROHTML

299       tbl information is currently rendered as a PNG image.
300

FILES

302       /usr/share/groff/1.22.2/tmac/www.tmac
303

SEE ALSO

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

AUTHOR

308       grohtml was written by Gaius Mulley ⟨gaius@glam.ac.uk⟩
309

BUGS

311       Report bugs to the Groff Bug Mailing List ⟨bug-groff@gnu.org⟩.  Include
312       a complete, self-contained example that will allow the bug to be repro‐
313       duced, and say which version of groff you are using.
314
315
316
317Groff Version 1.22.2            7 February 2013                   GROFF_WWW(7)
Impressum