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.
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
Perltidy -html reads a Perl script and writes an a copy suitable for viewing with a web browser.
The short EXAMPLES section should help you get started quickly.
The OPTIONS section describes all of the command line parameters.
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.
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.
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.
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.
perltidy(1)
This man page documents perltidy version 20010406.
Steven L. Hancock email: perltidy at users.sourceforge.net http://perltidy.sourceforge.net
Bug reports and suggestions for new features are always welcome.
Copyright (c) 2000, 2001 by Steven L. Hancock
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.
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.