PERLTIDY HTML DOCUMENTATION
    This document explains perltidy options available for outputting perl
    scripts in html format. For other perltidy options, see the perltidy man
    page, or go to the home page at http://perltidy.sourceforge.net.

    Please note that the -html flag is the "master switch" which tells
    perltidy to write output in html; without it, the html formatting
    parameters described here will all be ignored. Also please note that at
    present perltidy is either in "html mode" or "beautification mode", but
    not both, so it does not do any beautification when the -html option is
    used. This means that any beautification must be done in a preliminary
    separate run without the -html switch.

    This documentation has been split from the rest of the perltidy
    documentation because it is expected that the perltidy -html capability
    will eventually be spun off into a new, independent program, to allow it
    to grow more easily.

SYNOPSIS
        perltidy -html [ other options ] file1 file2 file3 ...
                (output goes to file1.html, file2.html, file3.html, ...)
        perltidy -html [ other options ] file1 -o outfile
        perltidy -html [ options ] file1 -st >outfile
        perltidy -html [ options ] <infile >outfile

DESCRIPTION
    Perltidy -html reads a Perl script and writes an a copy suitable for
    viewing with a web browser.

    The short the section on "EXAMPLES" section should help you get started
    quickly.

    The the section on "OPTIONS" section describes all of the command line
    parameters.

EXAMPLES
      perltidy -html somefile.pl

    This will produce a file somefile.pl.html containing the script with
    html markup. The output file will contain an embedded style sheet in the
    <HEAD> section which may be edited to change the appearance.

      perltidy -html -css=mystyle.css somefile.pl

    This will produce a file somefile.pl.html containing the script with
    html markup. This output file will contain a link to a separate style
    sheet file mystyle.css. If the file mystyle.css does not exist, it will
    be created. If it exists, it will not be overwritten.

      perltidy -html -pre somefile.pl

    Write an html snippet with only the PRE section to somefile.pl.html.
    This is useful when code snippets are being formatted for inclusion in a
    larger web page. No style sheet will be written in this case.

      perltidy -html -ss >mystyle.css

    Write a style sheet to mystyle.css and exit.

OPTIONS
    The -html master switch
        The flag -html causes perltidy to write an html file with extension
        .html. So, for example, the following command

                perltidy -html somefile.pl

        will produce a syntax-colored html file named somefile.pl.html which
        may be viewed with a browser.

        Please Note: In this case, perltidy does not do any formatting to
        the input file, and it does not write a formatted file with
        extension .tdy. This means that two perltidy runs are required to
        create a fully reformatted, html copy of a script.

    The -pre flag for code snippets
        When the -pre flag is given, only the pre-formatted section, within
        the <PRE> and </PRE> tags, will be output. This simplifies inclusion
        of the output in other files. The default is to output a complete
        web page.

    The -nnn flag for line numbering
        When the -nnn flag is given, the output lines will be numbered.

    Style Sheets
        Style sheets make it very convenient to control and adjust the
        appearance of html pages. The default behavior is to write a page of
        html with an embedded style sheet.

        An alternative to an embedded style sheet is to create a page with a
        link to an external style sheet. This is indicated with the
        -css=filename, where the external style sheet is filename. The
        external style sheet filename will be created if and only if it does
        not exist. This option is useful for controlling multiple pages from
        a single style sheet.

        To cause perltidy to write a style sheet to standard output and
        exit, use the -ss, or --stylesheet, flag. This is useful if the
        style sheet could not be written for some reason, such as if the
        -pre flag was used. Thus, for example,

          perltidy -html -ss >mystyle.css

        will write a style sheet with the default properties to file
        mystyle.css.

        The use of style sheets is encouraged, but a web page without a
        style sheets can be created with the flag -nss. Use this option if
        you must to be sure that older browsers (roughly speaking, versions
        prior to 4.0 of Netscape Navigator and Internet Explorer) can
        display the syntax-coloring of the html files.

    Controlling HTML properties
        Syntax colors may be changed from their default values by flags of
        the either the long form, -html-color-xxxxxx=n, or more conveniently
        the short form, -hcx=n, where xxxxxx is one of the following words,
        and x is the corresponding abbreviation:

              Token Type             xxxxxx           x 
              ----------             --------         --
              comment                comment          c
              number                 numeric          n
              identifier             identifier       i
              bareword, function     bareword         w
              keyword                keyword          k
              quite, pattern         quote            q
              here doc text          here-doc-text    h
              here doc target        here-doc-target  hh
              punctuation            punctuation      pu
              parentheses            paren            p
              structural braces      structural       s
              semicolon              semicolon        sc
              colon                  colon            co
              comma                  comma            cm
              label                  label            j

        A default set of colors has been defined, but they may be changed by
        providing values to any of the following parameters, where n is
        either a 6 digit hex RGB color value or an ascii name for a color,
        such as 'red'.

        To illustrate, the following command will produce an html file
        somefile.pl.html with "aqua" keywords:

                perltidy -html -hck=00ffff somefile.pl

        and this should be equivalent for most browsers:

                perltidy -html -hck=aqua somefile.pl

        Perltidy merely writes any non-hex names that it sees in the html
        file. The following 16 color names are defined in the HTML 3.2
        standard:

                black   => 000000,
                silver  => c0c0c0,
                gray    => 808080,
                white   => ffffff,
                maroon  => 800000,
                red     => ff0000,
                purple  => 800080,
                fuchsia => ff00ff,
                green   => 008000,
                lime    => 00ff00,
                olive   => 808000,
                yellow  => ffff00
                navy    => 000080,
                blue    => 0000ff,
                teal    => 008080,
                aqua    => 00ffff,

        Many more names are supported in specific browsers, but it is safest
        to use the hex codes for other colors. Helpful color tables can be
        located with an internet search for "HTML color tables".

        Besides color, two other character attributes may be set: bold, and
        italics. To set a token type to use bold, use the flag
        -html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
        names from the above table.

        Likewise, to set a token type to use an italic font, use the flag
        -html-italic-xxxxxx or -hix, where again xxxxxx or x are the long or
        short names from the above table. For example, to use bold braces
        and lime, bold, italics keywords the following command would be
        used:

                perltidy -html -hbs -hck=00FF00 -hik -hbk somefile.pl

        The background color can be specified with -html-color-background=n,
        or -hcbg=n for short, where n is a 6 character hex RGB value. The
        default color of text is the value given to punctuation, which is
        black as a default.

        Here are some notes and hints:

        1. If you find a preferred set of these parameters, you may want to
        create a .perltidyrc file containing them. See the perltidy man page
        for an explanation.

        2. Rather than specifying values for these parameters, it may be
        easier to accept the defaults and then edit a style sheet. The style
        sheet contains helpful comments which should make this easy.

        3. The syntax-colored html files can be very large, so it may be
        best to split large files into smaller pieces to improve download
        times.

        4. The list of token types is expected to evolve over time as
        further tokenizer improvements allow a refinement in the available
        token types, so you should occasionally check for updates to this
        program if you use it frequently.

SEE ALSO
    perltidy(1)

VERSION
    This man page documents perltidy version 20010328.

AUTHOR
      Steven L. Hancock
      email: perltidy at users.sourceforge.net
      http://perltidy.sourceforge.net

    Bug reports and suggestions for new features are always welcome.

COPYRIGHT
    Copyright (c) 2000, 2001 by Steven L. Hancock

LICENSE
    This package is free software; you can redistribute it and/or modify it
    under the terms of the "GNU General Public License".

    Please refer to the file "COPYING" for details.

DISCLAIMER
    This package 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.

