granicus.if.org Git - imagemagick/blob - scripts/format_c_api_docs

   1 #!/usr/bin/perl -w
   2 #
   3 # Format ImageMagick comments into POD-format or HTML format
   4 # documentation
   5 # Produces *.pod or *.html files corresponding to *.c files
   6 #
   7 # Written by Bob Friesenhahn, April 1997
   8 #
   9
  10 $opt_format='html';
  11 $opt_srcdir='';
  12 $opt_outdir='';
  13
  14 use Getopt::Long;
  15 if ( ! GetOptions(
  16                   'format=s'    => \$opt_format,
  17                   'srcdir=s'    => \$opt_srcdir,
  18                   'outdir=s'    => \$opt_outdir,
  19                  )
  20    ) {
  21   print("Usage: fmtdocs [-srcdir srcdir] [-outdir outdir] [-format format] \n");
  22   exit(1);
  23 }
  24
  25 #
  26 # Source files to use
  27 #
  28 @srcs = ('animate.c',
  29          'annotate.c',
  30          'attribute.c',
  31          'blob.c',
  32          'cache.c',
  33          'cache-view.c',
  34          'color.c',
  35          'colorspace.c',
  36          'compare.c',
  37          'composite.c',
  38          'constitute.c',
  39          'decorate.c',
  40    'deprecate.c',
  41          'draw.c',
  42          'drawing-wand.c',
  43          'display.c',
  44          'effect.c',
  45          'enhance.c',
  46          'exception.c',
  47          'fx.c',
  48          'image.c',
  49          'list.c',
  50          'magick.c',
  51          'magick-wand.c',
  52          'memory.c',
  53          'monitor.c',
  54          'montage.c',
  55    'paint.c',
  56          'pixel-iterator.c',
  57          'pixel-wand.c',
  58          'profile.c',
  59          'quantize.c',
  60          'registry.c',
  61    'resource.c',
  62          'segment.c',
  63          'shear.c',
  64          'signature.c',
  65          'stream.c',
  66          'transform.c',
  67          'resize.c',
  68    'version.c');
  69
  70 $tmpname_pre_format = "/tmp/fmtdocs_pre.$$";
  71 $tmpname_pod = "/tmp/fmtdocs_pod.$$";
  72 $tmpname_html = "/tmp/fmtdocs_html.$$";
  73
  74 #@srcs = ('draw.c');
  75
  76 #
  77 # What is for source files
  78 #
  79 %whatis =
  80 (
  81  'animate',     'Interactively Animate an Image Sequence',
  82  'annotate',    'Annotate an Image',
  83  'attribute',   'Set Text Attributes',
  84  'blob',        'Read or Write Binary Large OBjects',
  85  'color',       'Count the Colors in an Image',
  86  'colorspace',  'Dealing with Image Colorspaces',
  87  'compare',     'Compare an Image to a Reconstructed Image',
  88  'constitute',  'Constitute an Image',
  89  'composite',   'Composite an Image',
  90  'decorate',    'Decorate an Image',
  91  'deprecate',   'Deprecated Methods',
  92  'display',     'Interactively Display and Edit an Image',
  93  'draw',        'Draw on an Image',
  94  'drawing_wand',        'Image Vector Drawing',
  95  'effect',      'Add an Effect',
  96  'fx',          'Add a Special Effect',
  97  'enhance',     'Enhance an Image',
  98  'exception',   'Dealing with Exceptions',
  99  'image',       'Image Methods',
 100  'list',        'Working with Image Lists',
 101  'cache',       'Get or Set Image Pixels',
 102  'cache_view',  'Working with Cache Views',
 103  'magick',      'Read or List Image formats',
 104  'magick_wand', 'Magick Wand',
 105  'memory',      'Memory Allocation',
 106  'monitor',     'Monitor the Progress of an Image Operation',
 107  'montage',     'Create an Image Thumbnail',
 108  'paint',       'Paint on an Image',
 109  'pixel_iterator',      'Pixel Iterator',
 110  'pixel_wand',  'Pixel Wand',
 111  'profile',     'Dealing with Image Profiles',
 112  'quantize',    'Reduce the Number of Unique Colors in an Image',
 113  'registry',    'The Registry',
 114  'resource',    'Minitor or Limit Resource Consumption',
 115  'segment',     'Segment an Image with Thresholding Fuzzy c-Means',
 116  'shear',       'Shear or Rotate an Image by an Arbitrary Angle',
 117  'signature',   'Compute a Digital Signature for an Image',
 118  'stream',      'The Pixel FIFO',
 119  'transform',   'Transform an Image',
 120  'resize',      'Resize an Image',
 121  'version',     'Get Version and Copyright',
 122 );
 123
 124 #
 125 # Key words to replace with HTML links
 126 #
 127 my %keywords =
 128   (
 129    AffineMatrix         => 'types.html#AffineMatrix',
 130    BlobInfo             => 'types.html#BlobInfo',
 131    Cache                => 'types.html#Cache',
 132    ChannelType          => 'types.html#ChannelType',
 133    ChromaticityInfo     => 'types.html#ChromaticityInfo',
 134    ClassType            => 'types.html#ClassType',
 135    ClipPathUnits        => 'types.html#ClipPathUnits',
 136    ColorPacket          => 'types.html#ColorPacket',
 137    ColorspaceType       => 'types.html#ColorspaceType',
 138    ComplianceType       => 'types.html#ComplianceType',
 139    CompositeOperator    => 'types.html#CompositeOperator',
 140    CompressionType      => 'types.html#CompressionType',
 141    DecorationType       => 'types.html#DecorationType',
 142    DrawContext          => 'types.html#DrawContext',
 143    DrawInfo             => 'types.html#DrawInfo',
 144    ErrorHandler         => 'types.html#ErrorHandler',
 145    ExceptionInfo        => 'types.html#ExceptionInfo',
 146    ExceptionType        => 'types.html#ExceptionType',
 147    FillRule             => 'types.html#FillRule',
 148    FilterTypes          => 'types.html#FilterTypes',
 149    FrameInfo            => 'types.html#FrameInfo',
 150    GravityType          => 'types.html#GravityType',
 151    Image                => 'types.html#Image',
 152    ImageInfo            => 'types.html#ImageInfo',
 153    ImageType            => 'types.html#ImageType',
 154    InterlaceType        => 'types.html#InterlaceType',
 155    LayerType            => 'types.html#LayerType',
 156    MagickInfo           => 'types.html#MagickInfo',
 157    MonitorHandler       => 'types.html#MonitorHandler',
 158    MontageInfo          => 'types.html#MontageInfo',
 159    NoiseType            => 'types.html#NoiseType',
 160    PaintMethod          => 'types.html#PaintMethod',
 161    PixelPacket          => 'types.html#PixelPacket',
 162    PointInfo            => 'types.html#PointInfo',
 163    ProfileInfo          => 'types.html#ProfileInfo',
 164    QuantizeInfo         => 'types.html#QuantizeInfo',
 165    Quantum              => 'types.html#Quantum',
 166    QuantumType          => 'types.html#QuantumType',
 167    RectangleInfo        => 'types.html#RectangleInfo',
 168    RegistryType         => 'types.html#RegistryType',
 169    RenderingIntent      => 'types.html#RenderingIntent',
 170    ResolutionType       => 'types.html#ResolutionType',
 171    ResourceType         => 'types.html#ResourceType',
 172    SegmentInfo          => 'types.html#SegmentInfo',
 173    SignatureInfo        => 'types.html#SignatureInfo',
 174    StorageType          => 'types.html#StorageType',
 175    StreamHandler        => 'types.html#StreamHandler',
 176    StretchType          => 'types.html#StretchType',
 177    StyleType            => 'types.html#StyleType',
 178    TypeMetric           => 'types.html#TypeMetric',
 179    CacheView            => 'types.html#CacheView',
 180    VirtualPixelMethod   => 'types.html#VirtualPixelMethod',
 181    XResourceInfo        => 'types.html#XResourceInfo',
 182 );
 183
 184
 185 foreach $src (@srcs) {
 186
 187   my($out,$command);
 188
 189   # Compute POD name
 190   ($base = $src) =~ s/\.[^\.]*$//g;
 191
 192   $out = "${base}.${opt_format}";
 193   if ("${opt_outdir}" ne "") {
 194     $out = "${opt_outdir}/${base}.${opt_format}";
 195   }
 196
 197   if ("${opt_srcdir}" ne "") {
 198     $src = "${opt_srcdir}/${src}";
 199   }
 200
 201   $command='pod2html -netscape';
 202   if ( $opt_format eq 'html' ) {
 203     $command='pod2html -netscape';
 204   } elsif ( $opt_format eq 'latex' ) {
 205     $command='pod2latex';
 206   } elsif ( $opt_format eq 'man' ) {
 207     $command='pod2man';
 208   } elsif ( $opt_format eq 'text' ) {
 209     $command='pod2text';
 210   } elsif ( $opt_format eq 'pod' ) {
 211     $command='cat';
 212   }
 213
 214   print( "Processing $src -> $out\n" );
 215
 216   pre_format($src, $tmpname_pre_format);                # Make easily parsed
 217   format_to_pod($tmpname_pre_format, $tmpname_pod);     # Format to pod.
 218
 219   if ( $opt_format eq 'html' ) {
 220     system("$command $tmpname_pod > \"$tmpname_html\"");
 221     reformat_html($tmpname_html,$out);
 222   } else {
 223     system("$command $tmpname_pod > \"$out\"");
 224   }
 225   unlink($tmpname_pre_format);
 226   unlink($tmpname_pod);
 227   unlink($tmpname_html);
 228 }
 229
 230 #unlink($tmpname_pre_format);
 231 exit(0);
 232
 233 #
 234 # Reformat pod2html-generated HTML into nicer form.
 235 #
 236 sub reformat_html {
 237   my($infile, $outfile) = @_;
 238
 239   open( IN, "<$infile" ) || die("Failed to open \"$infile\" for read\n" );
 240   open( OUT, ">$outfile" ) || die("Failed to open \"$outfile\" for write\n" );
 241
 242  INPUT:
 243   while(<IN>) {
 244     s|<\!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">|<\!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 245   "http://www.w3.org/TR/html4/loose.dtd">|;
 246     s|<HEAD>|<HEAD>
 247 <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
 248 <STYLE>
 249 <!--
 250 \@page { size: 8.5in 11in }
 251 TD P { color: #000000; font-family: "Verdana", "Arial", "Helvetica", sans-serif; font-size: 12pt }
 252 P { color: #000000; font-family: "Verdana", "Arial", "Helvetica", sans-serif; font-size: 12pt }
 253 H2 { color: #000000 }
 254 A:link { color: #0085c0 }
 255 A:visited { color: #800080 }
 256 -->
 257 </STYLE>
 258 |;
 259     s|<link rev="made" href="mailto:root\@localhost" />|<link rel="stylesheet" type="text/css" href="../magick.css">|;
 260     s|<body style="background-color: white">|<body marginheight="1" marginwidth="1" topmargin="1" leftmargin="1">
 261 <a name="top"></a>
 262 <table border="0" cellpadding="0" cellspacing="0" summary="Masthead" width="100%">
 263 <tbody>
 264 <tr>
 265 <td bgcolor="#003399" width="25%" height="118" background="../../images/background.gif"><a href="http://www.imagemagick.org/"><img src="../../images/script.gif" width="278" height="118" border="0" alt="" /></a></td>
 266 <td bgcolor="#003399" width="60%" height="118" background="../../images/background.gif"><a href="http://www.networkeleven.com/direct.php?magick_all"><img src="../../images/promote.png" border="0" width="186" height="52" vspace="29" alt="Powered by NetworkEleven" /></a></td>
 267 <td bgcolor="#003399" width="114" height="118" align="right"><img src="../../images/sprite.png" width="114" height="118" alt="" /></td>
 268 <td bgcolor="#003399" width="114" height="118" align="right"><a href="http://www.imagemagick.net"><img src="../../images/logo.png" width="114" height="118" border="0" alt="ImageMagick logo" /></a></td>
 269 </tr></tbody></table>
 270 <table align="left" border="0" cellpadding="2" cellspacing="2" summary="Navigation buttons" width="20%">
 271 <tr>
 272 <td>
 273 <form target="_self" action="../../index.html"><input type="submit" title="ImageMagick Home" value=" Home" style="background-color: #1947A3; background-image:url('../../../images/background.gif'); color:#fbc713; font-weight:bold"></form></td>
 274 <td>
 275 <form target="_self" action="../../www/apis.html"><input type="submit" title="ImageMagick API" value=" API " style="background-color: #1947A3; background-image:url('../../../images/background.gif'); color:#fbc713; font-weight:bold"></form></td>
 276 <td>
 277 <form target="_self" action="../../www/download.html"><input type="submit" title="ImageMagick Download" value="Download" style="background-color: #1947A3; background-image:url('../../../images/background.gif'); color:#fbc713; font-weight:bold"></form></td></tr></table>
 278 <div align="right" style="margin-top:3px; padding-right:4px">
 279 <form action="http://studio.imagemagick.org/Sage/scripts/Sage.cgi"><input type="TEXT" name="query" size="32" maxlength="255"> <input type="SUBMIT" name="sa" value="Search" style="background-color: #1947A3; background-image:url('../../../images/background.gif'); bgcolor:#003399; color:#fbc713; font-weight:bold"></form></div>
 280 <table align="left" border="0" cellpadding="10" cellspacing="0" style="margin-top:-17px" width="100%">
 281 <tr>
 282 <td>
 283 |;
 284     s|</body>|
 285 <HR>
 286
 287 <a href="#top"><img src="../../../images/top.gif" border=0 width="35" height="46" align="right" alt="Top of page"></a>
 288 <form action="http://studio.imagemagick.org/magick/" style="margin-top:5px">
 289 <input type="submit" title="Help!" value="Help!" style="background-image:url('../../../images/background.gif'); color:#fbc713; font-weight:bold">
 290   <small>&quot;Image manipulation software that works like magick&quot;</small>
 291 </form></td>
 292 </tr></table>
 293
 294 </body>
 295 |;
 296     s|<FONT SIZE=-1>||g;
 297     s|</FONT>||g;
 298
 299     s|<H2>|<H3>|g;
 300     s|</H2>|</H3>|g;
 301
 302     s|<H1>|<H2>|g;
 303     s|</H1>|</H2>|g;
 304
 305     s|<DT>|<DD><P></P><DT>|g;
 306     s|<DL>|<DL><DT><DD><DL>|g;
 307     s|</DL>|</DL></DL>|g;
 308     s|<dd>|<DD>|g;
 309     s|<p>|<P>|g;
 310     s|</p>|</P>|g;
 311     s|</LI>||g;
 312     s|>o |>|g;
 313     s|unsignedint|unsigned int|g;
 314     print( OUT $_ );
 315   }
 316   close( TMP );
 317   close( IN );
 318 }
 319
 320 #
 321 # Pre-process file into intermediate form
 322 #
 323 # Initializes globals:
 324 #
 325 #  @functions   - Function names
 326 #  %synopsis    - Function synopsis
 327 #
 328 sub pre_format {
 329   my($infile, $tmpfile) = @_;
 330
 331   my $inpara = 0;       # Set to 1 if in paragraph
 332   my $inlist = 0;       # Set to 1 if in list-item paragraph
 333
 334   # Open C source file
 335   open( IN, "<$infile" ) || die("Failed to open \"$infile\" for read\n" );
 336
 337   # Open TMP file
 338   open( TMP, ">$tmpfile" ) || die("Failed to open \"$tmpfile\" for write\n" );
 339
 340   undef @functions;
 341   undef %synopsis;
 342
 343   # Skip past first form feed
 344   while(<IN>) {
 345     last if m/\014/;
 346   }
 347
 348 LINE:
 349   while(<IN>) {
 350     if (m/^\+/) {
 351       while(<IN>) {
 352         last unless m/^%/;
 353       }
 354       next;
 355     }
 356     next unless m/^%/ ;
 357     chop;
 358
 359     # Extract and save function title
 360     if (m/^%\s+((\w )+)\s+%/) {
 361       ($ftitle = $1) =~ s/ //g;
 362       push(@functions, $ftitle);
 363       print( TMP "===$ftitle\n" );
 364       next;
 365     }
 366
 367     # Zap text we don't want
 368     next if ( m/^%.+%/ );       # "%*%
 369     s/^%\s{0,2}//;
 370
 371     # Extract and save synopsis info
 372     if (m /\(\)/ ) {
 373       # nothing
 374       ;
 375     }
 376     elsif ( m/${ftitle}\(.*\)$/ ) {
 377       s/,/ , /g;
 378       s/\(/ ( /g;
 379       s/\)/ ) /g;
 380       s/\*/ * /g;
 381       s/\s+/ /g;
 382
 383       s/\(\s+\*/(*/g;
 384       s/ ,/,/g;
 385       s/ \(/(/g;
 386       s/\) /)/g;
 387       s/ \* / */g;
 388
 389       s/^\s*//;
 390       $synopsis{$ftitle} = $_ . ';'; # Append semi-colon, prototype style
 391       print ( TMP " " . $synopsis{$ftitle} . "\n" );
 392       next LINE;
 393      }
 394      elsif ( m/${ftitle}\(.*/ ) {
 395       $synopsis{$ftitle} = $_;
 396       do {
 397         $_ = <IN>;
 398         chop;
 399         # Zap text we don't want
 400         next if m/^%.+%/;       # "%*%
 401         s/^%\s{0,2}//;
 402         $synopsis{$ftitle} .= $_;
 403       } until m/^\s*$/;
 404       $_ = $synopsis{$ftitle};
 405
 406       s/,/ , /g;
 407       s/\(/ ( /g;
 408       s/\)/ ) /g;
 409       s/\*/ * /g;
 410       s/\s+/ /g;
 411
 412       s/\(\s+\*/(*/g;
 413       s/ ,/,/g;
 414       s/ \(/(/g;
 415       s/\) /)/g;
 416       s/ \* / */g;
 417
 418       s/^\s*//;
 419       $synopsis{$ftitle} = $_ . ';'; # Append semi-colon, prototype style
 420       print ( TMP " " . $synopsis{$ftitle} . "\n" );
 421       next LINE;
 422     }
 423
 424   # Keep track of paragraphing
 425   if( ! m/^$/ ) {
 426     if ( $inpara == 0 ) {
 427       $inpara = 1;      # Start of paragraph
 428       $para = "$_";     # Start paragraph string
 429     } else {
 430       # Inside paragraph
 431       $para .= " $_";   # Add line to paragraph
 432     }
 433   }
 434   # Keep track of list items so they can
 435   # be wrapped as a paragraph
 436   if( m/^\s+(o[^:]+:|o|[0-9]\.)\s(.*)/ ) {
 437     $inlist = 1;
 438   }
 439
 440   if ( $inpara == 1 ) {
 441     if( $para =~ m/^\s+\S+/ && ! $inlist ) {
 442       # Lines that start with a space shouldn't be munged
 443       $inpara = 0;      # End of paragraph
 444       $inlist = 0;
 445       $para .= "";      # Terminate paragraph
 446       print( TMP "$para\n" );
 447     }
 448     elsif( m/^$/ ) {
 449       # End of paragraph
 450       $inpara = 0;      # End of paragraph
 451       $inlist = 0;
 452       $para .= "";      # Terminate paragraph
 453       $para =~ s/^\s+//g;               # Eliminate any leading space
 454       $para =~ s/\s+/ /g;               # Canonicalize whitespace
 455       $para =~ s/ $//;          # Trim final space
 456       $para =~ s/([a-zA-Z0-9][.!?][)'"]*) /$1  /g; #' Fix sentance ends
 457                   print( TMP "\n$para\n\n" );
 458                 }
 459     }
 460   }
 461
 462   close( TMP );
 463   close( IN );
 464 }
 465
 466 #
 467 # Second pass
 468 # Process into formatted form
 469 #
 470 sub format_to_pod {
 471     my($infile, $outfile) = @_;
 472
 473     my $func;
 474
 475     my $inlist = 0;             # Set to one if in indented list
 476
 477     # Open input file
 478     open( IN, "<$infile" ) || die("Failed to open \"$infile\" for read\n" );
 479
 480     # Open output file
 481     open( OUT, ">$outfile" ) || die("Failed to open \"$outfile\" for write\n" );
 482
 483     # Name field
 484     print( OUT head1("NAME") );
 485     if (!defined($whatis{$base})) {
 486       print("Whatis definition missing for \"$base\"!\n");
 487       print( OUT "${base} - Unknown\n\n" );
 488     } else {
 489       print( OUT "${base} - $whatis{$base}\n\n" );
 490     }
 491
 492     # Synopsis field (function signatures)
 493     print( OUT head1("SYNOPSIS") );
 494     foreach $func (sort( @functions )) {
 495       if (defined $synopsis{$func} ) {
 496         $_ = $synopsis{$func};
 497         s/$func/ B<$func>/;
 498         s/^\s*//;
 499         my $synopsis = $_;
 500         print( OUT $synopsis, "\n\n" );
 501       }
 502     }
 503
 504     # Description field
 505     print( OUT head1("FUNCTION DESCRIPTIONS") );
 506
 507     while(<IN>){
 508         chop;
 509         next if m/^$/;
 510
 511         # Match list element
 512         if( m/^(o[^:]+:|o|[0-9]\.?)\s(.*)/ ) {
 513             my $bullet = $1;
 514             my $bullet_text = $2;
 515
 516             print( OUT startlist() ) unless $inlist;
 517             $inlist = 1;
 518             print( OUT item($bullet), "$bullet_text\n\n" );
 519             next;
 520         } else {
 521             print( OUT endlist() ) if $inlist;
 522             $inlist = 0;
 523         }
 524
 525         # Match synopsis item
 526         if( defined $func && m/$func\s*\(.*\)/ ) {
 527           # Split all words with spaces to aid with tokenization
 528           s/,/ , /g;
 529           s/\(/ ( /g;
 530           s/\)/ ) /g;
 531           s/\*/ * /g;
 532
 533           my $html = '';
 534
 535           # Replace tokens matching keywords with HTML links.
 536 TOKEN:    foreach $token ( split(' ', $_ ) ) {
 537             foreach $keyword ( %keywords ) {
 538               if ( $token eq $keyword ) {
 539                 $html .= linked( $keyword, $keywords{$keyword} );
 540                 $html .= " ";
 541                 next TOKEN;
 542               }
 543             }
 544             $html .= "$token ";
 545           }
 546           $_ = $html;
 547           # Remove excess spaces
 548           s/\s+/ /g;
 549           s/ ,/,/g;
 550           s/\* /*/g;
 551           s/\)\s*\;/);/;
 552           s/^\s*//;
 553           s/ \( *\)/\(\)/;
 554
 555           # This is very poor because text is output specifically
 556           # for HTML so the text isn't output at all for other target
 557           # formats.
 558           print( OUT html("<blockquote>$_</blockquote>") );
 559             next;
 560         }
 561
 562         # Match function title
 563         if( m/===([a-zA-Z0-9]+)/ ) {
 564             $func = $1;
 565             print( OUT head2($func) );
 566             next;
 567         }
 568
 569         print( OUT "\n") if /^[^ ]/;
 570         print( OUT "$_\n") ;
 571         print( OUT "\n") if /^[^ ]/;
 572     }
 573
 574     close( OUT );
 575     close( IN );
 576 }
 577
 578 #
 579 # Return level 1 heading
 580 # Similar to: <H1>heading</H1>
 581 #
 582 sub head1 {
 583     my($heading) = @_;
 584     return( "=head1 $heading\n\n" );
 585 }
 586
 587 #
 588 # Return level 2 heading
 589 # Similar to: <H2>heading</H2>
 590 #
 591 sub head2 {
 592     my($heading) = @_;
 593     return( "=head2 $heading\n\n" );
 594 }
 595
 596
 597 #
 598 # Return item
 599 # Simlar to: <I>
 600 #
 601 sub item {
 602     my($item) = @_;
 603     return( "=item $item\n\n" );
 604 }
 605
 606
 607 #
 608 # Start list
 609 # Similar to: <UL>
 610 #
 611 sub startlist {
 612     return( "=over 4\n\n" )
 613 }
 614
 615 #
 616 # End list
 617 # Similar to: </UL>
 618 #
 619 sub endlist {
 620     return( "=back\n\n" );
 621 }
 622
 623 #
 624 # Preformatted text
 625 # Similar to <PRE></PRE>
 626 #
 627 sub formated {
 628     my($text) = @_;
 629     return( " $text\n\n" );
 630 }
 631
 632 #
 633 # Raw HTML paragraph
 634 #
 635 sub html {
 636   my($html) = @_;
 637   return return( "=for html $html\n\n" );
 638 }
 639
 640 #
 641 # HTML Link
 642 # Similar to: <A HREF="url">description</A>
 643 #
 644 sub linked {
 645   local($description, $url) = @_;
 646   return( "<A HREF=\"" . $url . "\">" . $description . "</A>" );
 647 }