* NEWS: Updated.

* tmac/groff_www.man: Revised and updated.

1 files changed, 73 insertions, 38 deletions

diff --git a/tmac/groff_www.man b/tmac/groff_www.man
index e52ea38d..503e03d6 100644
--- a/tmac/groff_www.man
+++ b/tmac/groff_www.man
@@ -87,6 +87,8 @@ Here is a summary of the functions found in this macro set.
 \&.DC	generate a drop capital
 \&.HTML	pass an html raw request to the
 	device driver
+\&.CDS	code example begin
+\&.CDE	code example end
 .fi
 .PP
 Output of the
@@ -100,15 +102,16 @@ preprocessors is acceptable as input.
 .
 .SH REQUESTS
 .TP
-.B JOBNAME
-Split output into multiple files.
+.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
+.B .HX n
 Specify the cut off depth when generating links from section headings.
 For example, a parameter of\~2 would cause
 .B \%grohtml
@@ -136,22 +139,30 @@ to
 .BR groff .
 .
 .TP
-.B BCL
+.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
+.B .BGIMG imagefile
 the only parameter to this macro is the background image file.
 .
 .TP
-.B URL
+.B .URL url [description] [after]
 generates
 .TAG URL
-a URL using either two or three arguments.
+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.
-Hyphenation is disabled while printing the actual URL; explicit breakpoints
+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.
@@ -179,11 +190,14 @@ by:
 .RE
 .
 .TP
-.B MTO
+.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, and
-an optional third argument is stuff printed immediately afterwards.
+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"
@@ -203,7 +217,7 @@ run with
 .BR \-Thtml ).
 .
 .TP
-.B FTP
+.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
@@ -219,7 +233,7 @@ The macro example above was specified by:
 .RE
 .
 .TP
-.B TAG
+.B .TAG name
 Generates an html name tag from its argument.
 This can then be referenced using the
 .URL #URL URL
@@ -244,13 +258,14 @@ a URL using either two or three arguments.
 .RE
 .
 .TP
-.B IMG
+.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.
@@ -261,7 +276,7 @@ If you are including a png image then it is advisable to use the
 macro.
 .
 .TP
-.B PIMG
+.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
@@ -282,7 +297,7 @@ it is necessary to use the
 option of groff.
 .
 .TP
-.B MPIMG
+.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
@@ -313,10 +328,12 @@ Example:
 .RE
 .
 .TP
-.B HnS
+.B .HnS n
 Begin heading.
-The heading level is specified by the first parameter.
-Use this macro of your headings contain URLs.
+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
@@ -336,13 +353,21 @@ GNU Troff
 .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
+.B .HnE
 End heading.
 .
 .TP
-.B LK
+.B .LK
 .TAG LK
 Force \%grohtml to place the automatically generated links at this position.
 If this manual page has been processed with
@@ -351,37 +376,29 @@ those links can be seen right here.
 .
 .LK
 .
-.
-.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).
-.
 .TP
-.B HR
+.B .HR
 Generate a full-width horizontal rule.
 .
 .TP
-.B NHR
+.B .NHR
 Suppress generation of the top and bottom rules which \%grohtml emits
 by default.
 .
 .TP
-.B HTL
+.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.
+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 HTML
+.B .HTML
 All text after this macro is treated as raw html.
 If the document is processed without
 .B \-Thtml
@@ -404,12 +421,30 @@ macro is defined as
 .RE
 .
 .TP
-.B DC
+.B .DC l text [color]
 Produce a drop capital.
 The first parameter is the letter to be dropped and enlarged, the second
-parameter is the ajoining text whose height the first letter should not
-exceed.
+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
+.
+.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