tmac/groff_www.man

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