perl2web - perltidy options for outputting Perl scripts in HTML format
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 indentation or formatting when the -html option is used. The input file is decorated with HTML tags but otherwise left unchanged. Therefore any indenting or reformatting 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.
For a quick introduction, see EXAMPLES.
For a complete description of the command line parameters, see OPTIONS.
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 structure s semicolon semicolon sc colon colon co comma comma cm label label j sub definition name subroutine m pod text pod-text pd
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. Conversely, to set a token type to NOT use bold, use -nohtml-bold-xxxxxx or -nhbx.
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. And to set a token type to NOT use italics, use -nohtml-italic-xxxxxx or -nhix.
For example, to use bold braces and lime color, non-bold, italics keywords the following command would be used:
perltidy -html -hbs -hck=00FF00 -nhbk -hik 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 20011020.
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.