.\" Automatically generated by Pod::Man version 1.16
.\" Sat Oct 20 13:28:17 2001
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.bd B 3
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "PERL2WEB 1"
.TH PERL2WEB 1 "perl v5.6.1" "2001-10-20" "User Contributed Perl Documentation"
.UC
.SH "PERLTIDY HTML DOCUMENTATION"
.IX Header "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.
.PP
Please note that the \fB\-html\fR flag is the \*(L"master switch\*(R" 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 \*(L"html mode\*(R" or \*(L"beautification mode\*(R", but
not both, so it does not do any indentation or formatting when the
\&\fB\-html\fR option is used.  The input file is decorated with \s-1HTML\s0 tags but
otherwise left unchanged.  Therefore any indenting or reformatting must
be done in a preliminary separate run without the \fB\-html\fR switch.
.PP
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.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Perltidy \-html reads a Perl script and writes an a copy suitable for
viewing with a web browser.
.PP
For a quick introduction, see the section on "EXAMPLES". 
.PP
For a complete description of the command line parameters, see the section on "OPTIONS". 
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 1
\&  perltidy -html somefile.pl
.Ve
This will produce a file \fIsomefile.pl.html\fR containing the script with
html markup.  The output file will contain an embedded style sheet in
the <\s-1HEAD\s0> section which may be edited to change the appearance.
.PP
.Vb 1
\&  perltidy -html -css=mystyle.css somefile.pl
.Ve
This will produce a file \fIsomefile.pl.html\fR containing the script with
html markup.  This output file will contain a link to a separate style
sheet file \fImystyle.css\fR.  If the file \fImystyle.css\fR does not exist,
it will be created.  If it exists, it will not be overwritten.
.PP
.Vb 1
\&  perltidy -html -pre somefile.pl
.Ve
Write an html snippet with only the \s-1PRE\s0 section to \fIsomefile.pl.html\fR.
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.  
.PP
.Vb 1
\&  perltidy -html -ss >mystyle.css
.Ve
Write a style sheet to \fImystyle.css\fR and exit.
.SH "OPTIONS"
.IX Header "OPTIONS"
.Ip "The \fB\-html\fR master switch" 4
.IX Item "The -html master switch"
The flag \fB\-html\fR causes perltidy to write an html file with extension
\&\fI.html\fR.  So, for example, the following command
.Sp
.Vb 1
\&        perltidy -html somefile.pl
.Ve
will produce a syntax-colored html file named \fIsomefile.pl.html\fR
which may be viewed with a browser.
.Sp
\&\fBPlease Note\fR: In this case, perltidy does not do any formatting to the
input file, and it does not write a formatted file with extension
\&\fI.tdy\fR.  This means that two perltidy runs are required to create a
fully reformatted, html copy of a script.  
.Ip "The \fB\-pre\fR flag for code snippets" 4
.IX Item "The -pre flag for code snippets"
When the \fB\-pre\fR flag is given, only the pre-formatted section, within
the <\s-1PRE\s0> and </PRE> tags, will be output.  This simplifies inclusion
of the output in other files.  The default is to output a complete
web page.
.Ip "The \fB\-nnn\fR flag for line numbering" 4
.IX Item "The -nnn flag for line numbering"
When the \fB\-nnn\fR flag is given, the output lines will be numbered.
.Ip "Style Sheets" 4
.IX Item "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.
.Sp
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
\&\fB\-css=filename\fR,  where the external style sheet is \fIfilename\fR.  The
external style sheet \fIfilename\fR will be created if and only if it does
not exist.  This option is useful for controlling multiple pages from a
single style sheet.
.Sp
To cause perltidy to write a style sheet to standard output and exit,
use the \fB\-ss\fR, or \fB\*(--stylesheet\fR, flag.  This is useful if the style
sheet could not be written for some reason, such as if the \fB\-pre\fR flag
was used.  Thus, for example,
.Sp
.Vb 1
\&  perltidy -html -ss >mystyle.css
.Ve
will write a style sheet with the default properties to file
\&\fImystyle.css\fR.
.Sp
The use of style sheets is encouraged, but a web page without a style
sheets can be created with the flag \fB\-nss\fR.  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.
.Ip "Controlling \s-1HTML\s0 properties" 4
.IX Item "Controlling HTML properties"
Syntax colors may be changed from their default values by flags of the either
the long form, \fB\-html-color-xxxxxx=n\fR, or more conveniently the short form,
\&\fB\-hcx=n\fR, where \fBxxxxxx\fR is one of the following words, and \fBx\fR is the
corresponding abbreviation:
.Sp
.Vb 19
\&      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      structure        s
\&      semicolon              semicolon        sc
\&      colon                  colon            co
\&      comma                  comma            cm
\&      label                  label            j
\&      sub definition name    subroutine       m
\&      pod text               pod-text         pd
.Ve
A default set of colors has been defined, but they may be changed by providing
values to any of the following parameters, where \fBn\fR is either a 6 digit 
hex \s-1RGB\s0 color value or an ascii name for a color, such as 'red'.
.Sp
To illustrate, the following command will produce an html 
file \fIsomefile.pl.html\fR with \*(L"aqua\*(R" keywords:
.Sp
.Vb 1
\&        perltidy -html -hck=00ffff somefile.pl
.Ve
and this should be equivalent for most browsers:
.Sp
.Vb 1
\&        perltidy -html -hck=aqua somefile.pl
.Ve
Perltidy merely writes any non-hex names that it sees in the html file.
The following 16 color names are defined in the \s-1HTML\s0 3.2 standard:
.Sp
.Vb 16
\&        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,
.Ve
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 \*(L"\s-1HTML\s0 color tables\*(R". 
.Sp
Besides color, two other character attributes may be set: bold, and italics.
To set a token type to use bold, use the flag
\&\fB\-html-bold-xxxxxx\fR or \fB\-hbx\fR, where \fBxxxxxx\fR or \fBx\fR are the long
or short names from the above table.  Conversely, to set a token type to 
\&\s-1NOT\s0 use bold, use \fB\-nohtml-bold-xxxxxx\fR or \fB\-nhbx\fR.
.Sp
Likewise, to set a token type to use an italic font, use the flag
\&\fB\-html-italic-xxxxxx\fR or \fB\-hix\fR, where again \fBxxxxxx\fR or \fBx\fR are the
long or short names from the above table.  And to set a token type to
\&\s-1NOT\s0 use italics, use \fB\-nohtml-italic-xxxxxx\fR or \fB\-nhix\fR.
.Sp
For example, to use bold braces and lime color, non-bold, italics keywords the
following command would be used:
.Sp
.Vb 1
\&        perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
.Ve
The background color can be specified with \fB\-html-color-background=n\fR,
or \fB\-hcbg=n\fR for short, where n is a 6 character hex \s-1RGB\s0 value.  The
default color of text is the value given to \fBpunctuation\fR, which is
black as a default.
.Sp
Here are some notes and hints:
.Sp
1. If you find a preferred set of these parameters, you may want
to create a \fI.perltidyrc\fR file containing them.  See the perltidy man
page for an explanation.
.Sp
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.
.Sp
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.
.Sp
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperltidy\fR\|(1)
.SH "VERSION"
.IX Header "VERSION"
This man page documents perltidy version 20011020.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 3
\&  Steven L. Hancock
\&  email: perltidy at users.sourceforge.net
\&  http://perltidy.sourceforge.net
.Ve
Bug reports and suggestions for new features are always welcome.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2000, 2001 by Steven L. Hancock
.SH "LICENSE"
.IX Header "LICENSE"
This package is free software; you can redistribute it and/or modify it
under the terms of the \*(L"\s-1GNU\s0 General Public License\*(R".
.PP
Please refer to the file \*(L"\s-1COPYING\s0\*(R" for details.
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
This package is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.
.PP
See the \*(L"\s-1GNU\s0 General Public License\*(R" for more details.