[dragonfly.git] / contrib / groff / tmac / groff_www.man

.TH GROFF_WWW @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
.\" Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009
.\" Free Software Foundation, Inc.
.\"      Written by Gaius Mulley (gaius@glam.ac.uk)
.\"
.\" This file is part of groff.
.\"
.\" groff is free software; you can redistribute it and/or modify it under
.\" the terms of the GNU General Public License as published by the Free
.\" Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" groff is distributed in the hope that it will be useful, but WITHOUT ANY
.\" WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.\" user level guide to using the -mwww macroset
.\"
.
.do nr groff_www_C \n[.C]
.cp 0
.
.do mso www.tmac
.
.\" we need the .LK here as we use it in the middle as an example --
.\" once the user requests .LK then the automatic generation of links
.\" at the top of the document is suppressed.
.LK
.
.
.SH NAME
groff_www \- groff macros for authoring web pages
.HR
.
.
.SH SYNOPSIS
.B "groff \-mwww"
[ options ]
file ...
.
.
.SH 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
.RB ( \%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
.B troffrc
file) if you use
.B \-Thtml
or
.BR \-Txhtml .
.PP
To see the hyperlinks in action, please format this man page with the
.B \%grohtml
device.
.PP
Here is a summary of the functions found in this macro set.
.TS
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 a html email address
\&.FTP@create an ftp reference
\&.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 generate 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.
.TE
.PP
Output of the
.BR pic ,
.BR eqn ,
.BR refer ,
and
.B tbl
preprocessors is acceptable as input.
.
.
.SH REQUESTS
.TP
.B .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
.BR \%grohtml 's
.B \-j
option.
.TP
.B .HX n
Specify the cut off depth when generating links from section headings.
For example, a parameter of\~2 would cause
.B \%grohtml
to generate a list of links for
.B .NH\ 1
and
.B .NH\ 2
but not for
.BR .NH\ 3 .
Whereas
.RS
.IP
.nf
.B .HX 0
.fi
.RE
.IP
tells
.B \%grohtml
that no heading links should be created at all.
Another method for turning automatic headings off is by issuing the
the command line switch
.B \-P\-l
to
.BR groff .
.
.TP
.B .BCL foreground background active not-visited visited
This macro takes five parameters: foreground, background, active hypertext
link, hypertext link not yet visited, and visited hypertext link colour.
.
.TP
.B .BGIMG imagefile
the only parameter to this macro is the background image file.
.
.TP
.B .URL url [description] [after]
generates
.TAG URL
a URL using either one, two or three arguments.
The first parameter is the actual URL, the second is the name of the link,
and the third is optional stuff to be printed immediately afterwards.
If
.B description
and
.B after
are absent then the
.B url
becomes the anchor text.
Hyphenation is disabled while printing the actual URL;
explicit breakpoints
should be inserted with the
.B \[rs]:
escape.
Here is how to encode
.URL http://\:foo.\:org/ "foo" :
.RS
.IP
.B .URL http://\[rs]:foo.\[rs]:org/ "foo" :
.RE
.IP
If this is processed by a device other than 
.B \-Thtml
or
.B \-Txhtml
it appears as:
.RS
.IP
foo \[la]\f[C]http://foo.org\f[]\[ra]:
.RE
.IP
The URL macro can be of any type; for example we can reference
.URL pic.html "Eric Raymond's pic guide" 
by:
.RS
.IP
.B .URL pic.html \[dq]Eric Raymond's pic guide\[dq]
.RE
.
.TP
.B .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,
.B address
is used instead.
An optional third argument is stuff printed immediately afterwards.
Hyphenation is disabled while printing the actual email address.
For example, 
.MTO joe@user.org "Joe User"
was achieved by the following macro:
.RS
.IP
.B .MTO joe@user.org \[dq]Joe User\[dq]
.RE
.IP
Note that all the URLs actually are treated as consuming no textual space
in groff.
This could be considered as a bug since it causes some problems.
To circumvent this,
.B www.tmac
inserts a zero-width character which expands to a harmless space (only if
run with
.B \-Thtml
or
.BR \-Txhtml ).
.
.TP
.B .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.
Hyphenation is disabled while printing the actual URL.
As an example, here the location of the
.FTP ftp://\:ftp.gnu.org/ "GNU ftp server" .
The macro example above was specified by:
.RS
.IP
.B .FTP ftp://\[rs]:ftp.gnu.org/ \[dq]GNU ftp server\[dq] .
.RE
.
.TP
.B .TAG name
Generates an html name tag from its argument.
This can then be referenced using the
.URL #URL URL
macro.
As you can see, you must precede the tag name with
.B #
since it is a local reference.
This link was achieved via placing a TAG in the URL description above;
the source looks like this:
.RS
.IP
.nf
.ft B
\&.TP
\&.B URL
generates
\&.TAG URL
a URL using either two or three arguments.
\&.\|.\|.
.fi
.ft P
.RE
.
.TP
.B .IMG [-R|-L|-C] filename [width] [height]
Include a picture into the document.
The first argument is the horizontal location: right, left, or center
.RB ( \-R ,
.BR \-L ,
or
.BR \-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
.B PIMG
macro.
.
.TP
.B .PIMG [-R|-L|-C] filename [width [height]]
Include an image in PNG format.
This macro takes exactly the same parameters as the
.B 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
.B netpbm
package:
.BR pngtopnm ,
.BR pnmcrop ,
and
.BR pnmtops .
If the document isn't processed with
.B \-Thtml
or
.B \-Txhtml
it is necessary to use the
.B \-U
option of groff.
.
.TP
.B .MPIMG [-R|-L] [-G gap] filename [width [height]]
Place a PNG image on the margin and wrap text around it.
The first parameters are optional.
The alignment: left or right
.RB ( \-L
or
.BR \-R )
specifies the margin where the picture is placed at.
The default alignment is left
.RB ( -L ).
Optionally,
.BI \-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.
.br
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:
.RS
.IP
.nf
.ft B
\&.MPIMG -L -G 2c foo.png 3c 1.5c
.ft P
.fi
.RE
.IP
The height and width may also be given as percentages. The PostScript
device calculates the width from the
.B .l
register and the height from the
.B .p
register. For example:
.RS
.IP
.nf
.ft B
\&.MPIMG -L -G 2c foo.png 15%
.ft P
.fi
.RE
.
.TP
.B .HnS n
Begin heading.
The numeric heading level
.I n
is specified by the first parameter.
Use this macro if your headings contain URL, FTP or MTO macros.
Example:
.RS
.IP
.nf
.ft B
\&.HnS 1
\&.HR
GNU Troff
\&.URL http://groff.ffii.org (Groff) 
\&\(em a
\&.URL http://www.gnu.org/ GNU
\&project.
\&Hosted by
\&.URL http://ffii.org/ FFII .
\&.HR
\&.HnE
.ft P
.fi
.RE
.IP
In this case you might wish to
disable automatic links to headings.
This can be done via
.B \-P\-l
from the command line.
.\" or by using a call to `.HX 0'.

.
.TP
.B .HnE
End heading.
.
.TP
.B .LK
.TAG LK
Force \%grohtml to place the automatically generated links at this position.
If this manual page has been processed with
.B \-Thtml
or
.B \-Txhtml
those links can be seen right here.
.
.LK
.
.TP
.B .HR
Generate a full-width horizontal rule for
.B \-Thtml
and
.BR \-Txhtml .
No effect for all other devices.
.
.TP
.B .NHR
Suppress generation of the top and bottom rules which \%grohtml emits
by default.
.
.TP
.B .HTL
Generate an HTML title only.
This differs from the 
.B TL
macro of the
.B 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).
.
.TP
.B .HEAD
Add arbitrary HTML data to the <head> block.
Ignored if not processed with
.B \-Thtml
or
.BR \-Txhtml .
Example:
.RS
.IP
.nf
.B ".HEAD" "\[dq]<link \[rs]"
.B "  rel=\[dq]\[dq]icon\[dq]\[dq] \[rs]"
.B "  type=\[dq]\[dq]image/png\[dq]\[dq] \[rs]"
.B "  href=\[dq]\[dq]http://foo.org//bar.png\[dq]\[dq]/>\[dq]"
.fi
.ft P
.RE
.
.TP
.B .HTML
All text after this macro is treated as raw html.
If the document is processed without
.B \-Thtml
or
.B \-Txhtml
then the macro is ignored.
Internally, this macro is used as a building block for other higher-level
macros.
.IP
For example, the
.B BGIMG
macro is defined as
.RS
.IP
.nf
.ft B
\&.de BGIMG
\&.   HTML <body background=\[rs]$1>
\&..
.ft P
.fi
.RE
.
.TP
.B .DC l text [color]
Produce a drop capital.
The first parameter is the letter to be dropped and enlarged, the second
parameter
.B text
is the ajoining text whose height the first letter should not exceed.
The optional third parameter is the color of the dropped letter.
It defaults to black.
.
.TP
.B ".CDS"
Start displaying a code section in constant width font.
.
.TP
.B ".CDE"
End code display
.
.TP
.B ".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 indicates 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.
.
.TP
.B ".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.
.
.TP
.B ".LNE"
End a two-column table.
This should be called at the end of the document if .ALN was used.
.
.TP
.B ".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
.RS
.IP
.nf
.ft B
\&.LINKSTYLE blue C \e[la] \e[ra]
.ft P
.fi
.RE
.IP
but these values will be superseded by a user call to LINKSTYLE.
.
.SH SECTION HEADING LINKS
By default
.B \%grohtml
generates links to all section headings and places these at the top of the
html document. (See
.URL #LK LINKS
for details of how to switch this off or alter the position).
.
.
.SH LIMITATIONS OF GROHTML
.LP
.B tbl
information is currently rendered as a PNG image.
.
.
.SH FILES
@MACRODIR@/www.tmac
.
.
.SH "SEE ALSO"
.BR groff (@MAN1EXT@),
.BR @g@troff (@MAN1EXT@)
.BR \%grohtml (@MAN1EXT@),
.BR netpbm (1)
.
.
.SH AUTHOR
.B \%grohtml
was written by
.MTO gaius@glam.ac.uk "Gaius Mulley"
.
.
.SH BUGS
Report bugs to the
.MTO bug-groff@\:gnu.org "Groff Bug Mailing List" .
Include a complete, self-contained example that will allow the bug to be
reproduced, and say which version of groff you are using.
.
.cp \n[groff_www_C]
.
.\" Local Variables:
.\" mode: nroff
.\" End:
Commit	Line	Data
92d0a6a6	1	.TH GROFF_WWW @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
4d3e9548	2	.\" Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009
465b256c	3	.\" Free Software Foundation, Inc.
92d0a6a6 JR	4	.\" Written by Gaius Mulley (gaius@glam.ac.uk)
	5	.\"
	6	.\" This file is part of groff.
	7	.\"
	8	.\" groff is free software; you can redistribute it and/or modify it under
	9	.\" the terms of the GNU General Public License as published by the Free
4d3e9548 JL	10	.\" Software Foundation, either version 3 of the License, or
4d3e9548 JL	11	.\" (at your option) any later version.
92d0a6a6 JR	12	.\"
	13	.\" groff is distributed in the hope that it will be useful, but WITHOUT ANY
	14	.\" WARRANTY; without even the implied warranty of MERCHANTABILITY or
	15	.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	16	.\" for more details.
	17	.\"
4d3e9548 JL	18	.\" You should have received a copy of the GNU General Public License
4d3e9548 JL	19	.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
92d0a6a6 JR	20	.\"
	21	.\" user level guide to using the -mwww macroset
	22	.\"
	23	.
	24	.do nr groff_www_C \n[.C]
	25	.cp 0
	26	.
	27	.do mso www.tmac
	28	.
	29	.\" we need the .LK here as we use it in the middle as an example --
	30	.\" once the user requests .LK then the automatic generation of links
	31	.\" at the top of the document is suppressed.
	32	.LK
	33	.
	34	.
	35	.SH NAME
	36	groff_www \- groff macros for authoring web pages
	37	.HR
465b256c JR	38	.
465b256c JR	39	.
92d0a6a6 JR	40	.SH SYNOPSIS
	41	.B "groff \-mwww"
	42	[ options ]
	43	file ...
	44	.
	45	.
	46	.SH DESCRIPTION
	47	This manual page describes the GNU \-mwww macro package, which is part of
	48	the groff document formatting system.
	49	The manual page is very a basic guide, and the html device driver
	50	.RB ( \%grohtml )
	51	has been completely rewritten but still remains as in an alpha state.
	52	It has been included into the distribution so that a lot of people have a
	53	chance to test it.
4d3e9548	54	Note that this macro file is automatically called (via the
92d0a6a6 JR	55	.B troffrc
92d0a6a6 JR	56	file) if you use
4d3e9548 JL	57	.B \-Thtml
	58	or
	59	.BR \-Txhtml .
92d0a6a6 JR	60	.PP
	61	To see the hyperlinks in action, please format this man page with the
	62	.B \%grohtml
	63	device.
	64	.PP
	65	Here is a summary of the functions found in this macro set.
4d3e9548 JL	66	.TS
	67	tab(@);
	68	l l.
	69	\&.JOBNAME@split output into multiple files
	70	\&.HX@automatic heading level cut off
	71	\&.BCL@specify colours on a web page
	72	\&.BGIMG@specify background image
	73	\&.URL@create a url using two parameters
	74	\&.FTP@create an ftp reference
	75	\&.MTO@create a html email address
	76	\&.FTP@create an ftp reference
	77	\&.TAG@generate an html name
	78	\&.IMG@include an image file
	79	\&.PIMG@include png image
	80	\&.MPIMG@place png on the margin and wrap text around it
	81	\&.HnS@begin heading
	82	\&.HnE@end heading
	83	\&.LK@emit automatically collected links.
	84	\&.HR@produce a horizontal rule
	85	\&.NHR@suppress automatic generation of rules.
	86	\&.HTL@only generate HTML title
	87	\&.HEAD@add data to <head> block
	88	\&.ULS@unorder list begin
	89	\&.ULE@unorder list end
	90	\&.OLS@ordered list begin
	91	\&.OLE@ordered list end
	92	\&.DLS@definition list begin
	93	\&.DLE@definition list end
	94	\&.LI@insert a list item
	95	\&.DC@generate a drop capital
	96	\&.HTML@pass an html raw request to the device driver
	97	\&.CDS@code example begin
	98	\&.CDE@code example end
	99	\&.ALN@place links on left of main text.
	100	\&.LNS@start a new two-column table with links in the left.
	101	\&.LNE@end the two-column table.
	102	\&.LINKSTYLE@initialize default url attributes.
	103	.TE
92d0a6a6 JR	104	.PP
	105	Output of the
	106	.BR pic ,
	107	.BR eqn ,
	108	.BR refer ,
	109	and
	110	.B tbl
	111	preprocessors is acceptable as input.
	112	.
	113	.
	114	.SH REQUESTS
	115	.TP
465b256c JR	116	.B .JOBNAME filename
	117	Split output into multiple HTML files.
	118	A file is split whenever a .SH or .NH\ 1 is encountered.
92d0a6a6 JR	119	Its argument is the file stem name for future output files.
	120	This option is equivalent to
	121	.BR \%grohtml 's
	122	.B \-j
	123	option.
	124	.TP
465b256c	125	.B .HX n
92d0a6a6 JR	126	Specify the cut off depth when generating links from section headings.
	127	For example, a parameter of\~2 would cause
	128	.B \%grohtml
	129	to generate a list of links for
	130	.B .NH\ 1
	131	and
	132	.B .NH\ 2
	133	but not for
	134	.BR .NH\ 3 .
	135	Whereas
	136	.RS
	137	.IP
	138	.nf
	139	.B .HX 0
	140	.fi
	141	.RE
	142	.IP
4d3e9548	143	tells
92d0a6a6 JR	144	.B \%grohtml
	145	that no heading links should be created at all.
	146	Another method for turning automatic headings off is by issuing the
	147	the command line switch
	148	.B \-P\-l
	149	to
	150	.BR groff .
	151	.
	152	.TP
465b256c	153	.B .BCL foreground background active not-visited visited
92d0a6a6 JR	154	This macro takes five parameters: foreground, background, active hypertext
	155	link, hypertext link not yet visited, and visited hypertext link colour.
	156	.
	157	.TP
465b256c	158	.B .BGIMG imagefile
92d0a6a6 JR	159	the only parameter to this macro is the background image file.
	160	.
	161	.TP
465b256c	162	.B .URL url [description] [after]
92d0a6a6 JR	163	generates
92d0a6a6 JR	164	.TAG URL
465b256c	165	a URL using either one, two or three arguments.
92d0a6a6 JR	166	The first parameter is the actual URL, the second is the name of the link,
92d0a6a6 JR	167	and the third is optional stuff to be printed immediately afterwards.
465b256c JR	168	If
	169	.B description
	170	and
	171	.B after
	172	are absent then the
	173	.B url
	174	becomes the anchor text.
	175	Hyphenation is disabled while printing the actual URL;
	176	explicit breakpoints
92d0a6a6 JR	177	should be inserted with the
	178	.B \[rs]:
	179	escape.
	180	Here is how to encode
	181	.URL http://\:foo.\:org/ "foo" :
	182	.RS
	183	.IP
	184	.B .URL http://\[rs]:foo.\[rs]:org/ "foo" :
	185	.RE
	186	.IP
	187	If this is processed by a device other than
	188	.B \-Thtml
4d3e9548 JL	189	or
4d3e9548 JL	190	.B \-Txhtml
92d0a6a6 JR	191	it appears as:
	192	.RS
	193	.IP
4d3e9548	194	foo \[la]\f[C]http://foo.org\f[]\[ra]:
92d0a6a6 JR	195	.RE
	196	.IP
	197	The URL macro can be of any type; for example we can reference
	198	.URL pic.html "Eric Raymond's pic guide"
	199	by:
	200	.RS
	201	.IP
	202	.B .URL pic.html \[dq]Eric Raymond's pic guide\[dq]
	203	.RE
	204	.
	205	.TP
465b256c	206	.B .MTO address [description] [after]
92d0a6a6 JR	207	Generate an email html reference.
92d0a6a6 JR	208	The first argument is mandatory as the email address.
465b256c JR	209	The optional second argument is the text you see in your browser
	210	If an empty argument is given,
	211	.B address
	212	is used instead.
	213	An optional third argument is stuff printed immediately afterwards.
92d0a6a6 JR	214	Hyphenation is disabled while printing the actual email address.
	215	For example,
	216	.MTO joe@user.org "Joe User"
	217	was achieved by the following macro:
	218	.RS
	219	.IP
	220	.B .MTO joe@user.org \[dq]Joe User\[dq]
	221	.RE
	222	.IP
	223	Note that all the URLs actually are treated as consuming no textual space
	224	in groff.
	225	This could be considered as a bug since it causes some problems.
	226	To circumvent this,
	227	.B www.tmac
	228	inserts a zero-width character which expands to a harmless space (only if
	229	run with
4d3e9548 JL	230	.B \-Thtml
	231	or
	232	.BR \-Txhtml ).
92d0a6a6 JR	233	.
92d0a6a6 JR	234	.TP
465b256c	235	.B .FTP url [description] [after]
92d0a6a6 JR	236	indicates that data can be obtained via ftp.
	237	The first argument is the url and the second is the browser text.
	238	A third argument, similar to the macros above, is intended for stuff printed
	239	immediately afterwards.
	240	The second and the third parameter are optional.
	241	Hyphenation is disabled while printing the actual URL.
	242	As an example, here the location of the
	243	.FTP ftp://\:ftp.gnu.org/ "GNU ftp server" .
	244	The macro example above was specified by:
	245	.RS
	246	.IP
	247	.B .FTP ftp://\[rs]:ftp.gnu.org/ \[dq]GNU ftp server\[dq] .
	248	.RE
	249	.
	250	.TP
465b256c	251	.B .TAG name
92d0a6a6 JR	252	Generates an html name tag from its argument.
	253	This can then be referenced using the
	254	.URL #URL URL
	255	macro.
	256	As you can see, you must precede the tag name with
	257	.B #
	258	since it is a local reference.
	259	This link was achieved via placing a TAG in the URL description above;
	260	the source looks like this:
	261	.RS
	262	.IP
	263	.nf
	264	.ft B
	265	\&.TP
	266	\&.B URL
	267	generates
	268	\&.TAG URL
	269	a URL using either two or three arguments.
	270	\&.\\|.\\|.
	271	.fi
	272	.ft P
	273	.RE
	274	.
	275	.TP
465b256c	276	.B .IMG [-R\|-L\|-C] filename [width] [height]
92d0a6a6 JR	277	Include a picture into the document.
	278	The first argument is the horizontal location: right, left, or center
	279	.RB ( \-R ,
	280	.BR \-L ,
	281	or
	282	.BR \-C ).
465b256c	283	Alignment is centered by default (-C).
92d0a6a6 JR	284	The second argument is the filename.
	285	The optional third and fourth arguments are the width and height.
	286	If the width is absent it defaults to 1\~inch.
	287	If the height is absent it defaults to the width.
	288	This maps onto an html img tag.
	289	If you are including a png image then it is advisable to use the
	290	.B PIMG
	291	macro.
	292	.
	293	.TP
465b256c	294	.B .PIMG [-R\|-L\|-C] filename [width [height]]
92d0a6a6 JR	295	Include an image in PNG format.
	296	This macro takes exactly the same parameters as the
	297	.B IMG
	298	macro; it has the advantage of working with postscript and html devices
	299	also since it can automatically convert the image into the EPS format,
	300	using the following programs
	301	of the
	302	.B netpbm
	303	package:
	304	.BR pngtopnm ,
	305	.BR pnmcrop ,
	306	and
	307	.BR pnmtops .
	308	If the document isn't processed with
	309	.B \-Thtml
4d3e9548 JL	310	or
4d3e9548 JL	311	.B \-Txhtml
92d0a6a6 JR	312	it is necessary to use the
	313	.B \-U
	314	option of groff.
	315	.
	316	.TP
465b256c	317	.B .MPIMG [-R\|-L] [-G gap] filename [width [height]]
92d0a6a6	318	Place a PNG image on the margin and wrap text around it.
465b256c JR	319	The first parameters are optional.
465b256c JR	320	The alignment: left or right
92d0a6a6 JR	321	.RB ( \-L
92d0a6a6 JR	322	or
465b256c JR	323	.BR \-R )
	324	specifies the margin where the picture is placed at.
	325	The default alignment is left
	326	.RB ( -L ).
	327	Optionally,
	328	.BI \-G \~gap
	329	can be used to arrange a gap between the picture
	330	and the text that wraps around it.
	331	The default gap width is zero.
	332	.br
	333	The first non-optional argument is the filename.
	334	The optional following arguments are the width and height.
92d0a6a6 JR	335	If the width is absent it defaults to 1\~inch.
92d0a6a6 JR	336	If the height is absent it defaults to the width.
465b256c JR	337	Example:
	338	.RS
	339	.IP
	340	.nf
	341	.ft B
	342	\&.MPIMG -L -G 2c foo.png 3c 1.5c
	343	.ft P
	344	.fi
	345	.RE
	346	.IP
	347	The height and width may also be given as percentages. The PostScript
	348	device calculates the width from the
	349	.B .l
	350	register and the height from the
	351	.B .p
	352	register. For example:
	353	.RS
	354	.IP
	355	.nf
	356	.ft B
	357	\&.MPIMG -L -G 2c foo.png 15%
	358	.ft P
	359	.fi
	360	.RE
92d0a6a6 JR	361	.
92d0a6a6 JR	362	.TP
465b256c	363	.B .HnS n
92d0a6a6	364	Begin heading.
465b256c JR	365	The numeric heading level
	366	.I n
	367	is specified by the first parameter.
	368	Use this macro if your headings contain URL, FTP or MTO macros.
92d0a6a6 JR	369	Example:
	370	.RS
	371	.IP
	372	.nf
	373	.ft B
	374	\&.HnS 1
	375	\&.HR
	376	GNU Troff
	377	\&.URL http://groff.ffii.org (Groff)
	378	\&\(em a
	379	\&.URL http://www.gnu.org/ GNU
	380	\&project.
	381	\&Hosted by
	382	\&.URL http://ffii.org/ FFII .
	383	\&.HR
	384	\&.HnE
	385	.ft P
	386	.fi
	387	.RE
465b256c JR	388	.IP
	389	In this case you might wish to
	390	disable automatic links to headings.
	391	This can be done via
	392	.B \-P\-l
	393	from the command line.
	394	.\" or by using a call to `.HX 0'.
	395
92d0a6a6 JR	396	.
92d0a6a6 JR	397	.TP
465b256c	398	.B .HnE
92d0a6a6 JR	399	End heading.
	400	.
	401	.TP
465b256c	402	.B .LK
92d0a6a6 JR	403	.TAG LK
	404	Force \%grohtml to place the automatically generated links at this position.
	405	If this manual page has been processed with
	406	.B \-Thtml
4d3e9548 JL	407	or
4d3e9548 JL	408	.B \-Txhtml
92d0a6a6 JR	409	those links can be seen right here.
	410	.
	411	.LK
	412	.
92d0a6a6	413	.TP
465b256c JR	414	.B .HR
465b256c JR	415	Generate a full-width horizontal rule for
4d3e9548 JL	416	.B \-Thtml
	417	and
	418	.BR \-Txhtml .
465b256c	419	No effect for all other devices.
92d0a6a6 JR	420	.
92d0a6a6 JR	421	.TP
465b256c	422	.B .NHR
92d0a6a6 JR	423	Suppress generation of the top and bottom rules which \%grohtml emits
	424	by default.
	425	.
	426	.TP
465b256c	427	.B .HTL
92d0a6a6 JR	428	Generate an HTML title only.
	429	This differs from the
	430	.B TL
	431	macro of the
	432	.B ms
465b256c	433	macro package which generates both an HTML title and an <H1> heading.
92d0a6a6 JR	434	Use it to provide an HTML title as search engine fodder but a graphic title
92d0a6a6 JR	435	in the document.
465b256c	436	The macro terminates when a space or break is seen (.sp, .br).
92d0a6a6 JR	437	.
92d0a6a6 JR	438	.TP
465b256c JR	439	.B .HEAD
	440	Add arbitrary HTML data to the <head> block.
	441	Ignored if not processed with
4d3e9548 JL	442	.B \-Thtml
	443	or
	444	.BR \-Txhtml .
465b256c JR	445	Example:
	446	.RS
	447	.IP
	448	.nf
	449	.B ".HEAD" "\[dq]<link \[rs]"
	450	.B " rel=\[dq]\[dq]icon\[dq]\[dq] \[rs]"
	451	.B " type=\[dq]\[dq]image/png\[dq]\[dq] \[rs]"
	452	.B " href=\[dq]\[dq]http://foo.org//bar.png\[dq]\[dq]/>\[dq]"
	453	.fi
	454	.ft P
	455	.RE
	456	.
	457	.TP
	458	.B .HTML
92d0a6a6 JR	459	All text after this macro is treated as raw html.
	460	If the document is processed without
	461	.B \-Thtml
4d3e9548 JL	462	or
4d3e9548 JL	463	.B \-Txhtml
92d0a6a6 JR	464	then the macro is ignored.
	465	Internally, this macro is used as a building block for other higher-level
	466	macros.
	467	.IP
	468	For example, the
	469	.B BGIMG
	470	macro is defined as
	471	.RS
	472	.IP
	473	.nf
	474	.ft B
	475	\&.de BGIMG
	476	\&. HTML <body background=\[rs]$1>
	477	\&..
	478	.ft P
	479	.fi
	480	.RE
	481	.
	482	.TP
465b256c	483	.B .DC l text [color]
92d0a6a6 JR	484	Produce a drop capital.
92d0a6a6 JR	485	The first parameter is the letter to be dropped and enlarged, the second
465b256c JR	486	parameter
	487	.B text
	488	is the ajoining text whose height the first letter should not exceed.
92d0a6a6	489	The optional third parameter is the color of the dropped letter.
465b256c JR	490	It defaults to black.
	491	.
	492	.TP
	493	.B ".CDS"
	494	Start displaying a code section in constant width font.
	495	.
	496	.TP
	497	.B ".CDE"
	498	End code display
	499	.
4d3e9548 JL	500	.TP
	501	.B ".ALN [color] [percentage]"
	502	Place section heading links automatically to the left of the main text.
	503	The color argument is optional and if present indicates which HTML
	504	background color is to be used under the links.
	505	The optional percentage indicates the amount of width to devote to
	506	displaying the links.
	507	The default values are #eeeeee and 30 for color and percentage width,
	508	respectively.
	509	This macro should only be called once at the beginning of the document.
	510	After calling this macro each section heading emits an HTML table consisting
	511	of the links in the left and the section text on the right.
	512	.
	513	.TP
	514	.B ".LNS"
	515	Start a new two-column table with links in the left column.
	516	This can be called if the document has text before the first .SH and if .ALN
	517	is used.
	518	Typically this is called just before the first paragraph and after the main
	519	title as it indicates that text after this point should be positioned to the
	520	right of the left-hand navigational links.
	521	.
	522	.TP
	523	.B ".LNE"
	524	End a two-column table.
	525	This should be called at the end of the document if .ALN was used.
	526	.
	527	.TP
	528	.B ".LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ]"
	529	Initialize default url attributes to be used if this macro set is not used
	530	with the HTML device.
	531	The macro set initializes itself with the following call
	532	.RS
	533	.IP
	534	.nf
	535	.ft B
	536	\&.LINKSTYLE blue C \e[la] \e[ra]
	537	.ft P
	538	.fi
	539	.RE
	540	.IP
	541	but these values will be superseded by a user call to LINKSTYLE.
	542	.
465b256c JR	543	.SH SECTION HEADING LINKS
	544	By default
	545	.B \%grohtml
	546	generates links to all section headings and places these at the top of the
	547	html document. (See
	548	.URL #LK LINKS
	549	for details of how to switch this off or alter the position).
92d0a6a6 JR	550	.
	551	.
	552	.SH LIMITATIONS OF GROHTML
	553	.LP
	554	.B tbl
	555	information is currently rendered as a PNG image.
	556	.
	557	.
	558	.SH FILES
	559	@MACRODIR@/www.tmac
	560	.
	561	.
	562	.SH "SEE ALSO"
	563	.BR groff (@MAN1EXT@),
	564	.BR @g@troff (@MAN1EXT@)
	565	.BR \%grohtml (@MAN1EXT@),
	566	.BR netpbm (1)
	567	.
	568	.
	569	.SH AUTHOR
	570	.B \%grohtml
	571	was written by
	572	.MTO gaius@glam.ac.uk "Gaius Mulley"
	573	.
	574	.
	575	.SH BUGS
	576	Report bugs to the
	577	.MTO bug-groff@\:gnu.org "Groff Bug Mailing List" .
	578	Include a complete, self-contained example that will allow the bug to be
	579	reproduced, and say which version of groff you are using.
	580	.
	581	.cp \n[groff_www_C]
	582	.
	583	.\" Local Variables:
	584	.\" mode: nroff
	585	.\" End: