.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "HTML::Stream 3pm"
.TH HTML::Stream 3pm "2016-11-27" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::Stream \- HTML output stream class, and some markup utilities
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Here's small sample of some of the non-OO ways you can use this module:
.PP
.Vb 1
\&      use HTML::Stream qw(:funcs);
\&      
\&      print html_tag(\*(AqA\*(Aq, HREF=>$link);     
\&      print html_escape("<<Hello & welcome!>>");
.Ve
.PP
And some of the \s-1OO\s0 ways as well:
.PP
.Vb 2
\&      use HTML::Stream;
\&      $HTML = new HTML::Stream \e*STDOUT;
\&      
\&      # The vanilla interface...
\&      $HTML\->tag(\*(AqA\*(Aq, HREF=>"$href");
\&      $HTML\->tag(\*(AqIMG\*(Aq, SRC=>"logo.gif", ALT=>"LOGO");
\&      $HTML\->text($copyright);
\&      $HTML\->tag(\*(Aq_A\*(Aq);
\&      
\&      # The chocolate interface...
\&      $HTML \-> A(HREF=>"$href");
\&      $HTML \-> IMG(SRC=>"logo.gif", ALT=>"LOGO");
\&      $HTML \-> t($caption);
\&      $HTML \-> _A;
\&       
\&      # The chocolate interface, with whipped cream...
\&      $HTML \-> A(HREF=>"$href")
\&            \-> IMG(SRC=>"logo.gif", ALT=>"LOGO")
\&            \-> t($caption)
\&            \-> _A;
\&
\&      # The strawberry interface...
\&      output $HTML [A, HREF=>"$href"], 
\&                   [IMG, SRC=>"logo.gif", ALT=>"LOGO"],
\&                   $caption,
\&                   [_A];
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBHTML::Stream\fR module provides you with an object-oriented
(and subclassable) way of outputting \s-1HTML. \s0 Basically, you open up 
an \*(L"\s-1HTML\s0 stream\*(R" on an existing filehandle, and then do all of your  
output to the \s-1HTML\s0 stream.  You can intermix HTML-stream-output and 
ordinary-print-output, if you like.
.PP
There's even a small built-in subclass, \fBHTML::Stream::Latin1\fR, which can
handle Latin\-1 input right out of the box.   But all in good time...
.SH "INTRODUCTION (the Neapolitan dessert special)"
.IX Header "INTRODUCTION (the Neapolitan dessert special)"
.SS "Function interface"
.IX Subsection "Function interface"
Let's start out with the simple stuff.
This module provides a collection of non-OO utility functions
for escaping \s-1HTML\s0 text and producing \s-1HTML\s0 tags, like this:
.PP
.Vb 1
\&    use HTML::Stream qw(:funcs);        # imports functions from @EXPORT_OK
\&    
\&    print html_tag(A, HREF=>$url);
\&    print \*(Aq&copy; 1996 by\*(Aq, html_escape($myname), \*(Aq!\*(Aq;
\&    print html_tag(\*(Aq/A\*(Aq);
.Ve
.PP
By the way: that last line could be rewritten as:
.PP
.Vb 1
\&    print html_tag(_A);
.Ve
.PP
And if you need to get a parameter in your tag that doesn't have an
associated value, supply the \fIundefined\fR value (\fInot\fR the empty string!):
.PP
.Vb 1
\&    print html_tag(TD, NOWRAP=>undef, ALIGN=>\*(AqLEFT\*(Aq);
\&    
\&         <TD NOWRAP ALIGN=LEFT>
\&    
\&    print html_tag(IMG, SRC=>\*(Aqlogo.gif\*(Aq, ALT=>\*(Aq\*(Aq);
\&    
\&         <IMG SRC="logo.gif" ALT="">
.Ve
.PP
There are also some routines for reversing the process, like:
.PP
.Vb 2
\&    $text = "This <i>isn\*(Aqt</i> &quot;fun&quot;...";    
\&    print html_unmarkup($text);
\&       
\&         This isn\*(Aqt &quot;fun&quot;...
\&      
\&    print html_unescape($text);
\&       
\&         This isn\*(Aqt "fun"...
.Ve
.PP
\&\fIYeah, yeah, yeah\fR, I hear you cry.  \fIWe've seen this stuff before.\fR
But wait!  There's more...
.SS "\s-1OO\s0 interface, vanilla"
.IX Subsection "OO interface, vanilla"
Using the function interface can be tedious... so we also
provide an \fB\*(L"\s-1HTML\s0 output stream\*(R"\fR class.  Messages to an instance of
that class generally tell that stream to output some \s-1HTML. \s0 Here's the
above example, rewritten using \s-1HTML\s0 streams:
.PP
.Vb 2
\&    use HTML::Stream;
\&    $HTML = new HTML::Stream \e*STDOUT;
\&    
\&    $HTML\->tag(A, HREF=>$url);
\&    $HTML\->ent(\*(Aqcopy\*(Aq);
\&    $HTML\->text(" 1996 by $myname!");
\&    $HTML\->tag(_A);
.Ve
.PP
As you've probably guessed:
.PP
.Vb 1
\&    text()   Outputs some text, which will be HTML\-escaped.
\&    
\&    tag()    Outputs an ordinary tag, like <A>, possibly with parameters.
\&             The parameters will all be HTML\-escaped automatically.
\&     
\&    ent()    Outputs an HTML entity, like the &copy; or &lt; .
\&             You mostly don\*(Aqt need to use it; you can often just put the 
\&             Latin\-1 representation of the character in the text().
.Ve
.PP
You might prefer to use \f(CW\*(C`t()\*(C'\fR and \f(CW\*(C`e()\*(C'\fR instead of \f(CW\*(C`text()\*(C'\fR 
and \f(CW\*(C`ent()\*(C'\fR: they're absolutely identical, and easier to type:
.PP
.Vb 4
\&    $HTML \-> tag(A, HREF=>$url);
\&    $HTML \-> e(\*(Aqcopy\*(Aq);
\&    $HTML \-> t(" 1996 by $myname!");
\&    $HTML \-> tag(_A);
.Ve
.PP
Now, it wouldn't be nice to give you those \f(CW\*(C`text()\*(C'\fR and \f(CW\*(C`ent()\*(C'\fR shortcuts
without giving you one for \f(CW\*(C`tag()\*(C'\fR, would it?  Of course not...
.SS "\s-1OO\s0 interface, chocolate"
.IX Subsection "OO interface, chocolate"
The known \s-1HTML\s0 tags are even given their own \fBtag-methods,\fR compiled on 
demand.  The above code could be written even more compactly as:
.PP
.Vb 4
\&    $HTML \-> A(HREF=>$url);
\&    $HTML \-> e(\*(Aqcopy\*(Aq);
\&    $HTML \-> t(" 1996 by $myname!");
\&    $HTML \-> _A;
.Ve
.PP
As you've probably guessed:
.PP
.Vb 2
\&    A(HREF=>$url)   ==   tag(A, HREF=>$url)   ==   <A HREF="/the/url">
\&    _A              ==   tag(_A)              ==   </A>
.Ve
.PP
All of the autoloaded \*(L"tag-methods\*(R" use the tagname in \fIall-uppercase\fR.
A \f(CW"_"\fR prefix on any tag-method means that an end-tag is desired.
The \f(CW"_"\fR was chosen for several reasons: 
(1) it's short and easy to type,
(2) it doesn't produce much visual clutter to look at,
(3) \f(CW\*(C`_TAG\*(C'\fR looks a little like \f(CW\*(C`/TAG\*(C'\fR because of the straight line.
.IP "\(bu" 4
\&\fII know, I know... it looks like a private method.
You get used to it.  Really.\fR
.PP
I should stress that this module will only auto-create tag methods
for \fBknown\fR \s-1HTML\s0 tags.  So you're protected from typos like this
(which will cause a fatal exception at run-time):
.PP
.Vb 1
\&    $HTML \-> IMGG(SRC=>$src);
.Ve
.PP
(You're not yet protected from illegal tag parameters, but it's a start, 
ain't it?)
.PP
If you need to make a tag known (sorry, but this is currently a 
\&\fIglobal\fR operation, and not stream-specific), do this:
.PP
.Vb 1
\&    accept_tag HTML::Stream \*(AqMARQUEE\*(Aq;       # for you MSIE fans...
.Ve
.PP
\&\fBNote: there is no corresponding \*(L"reject_tag\*(R".\fR  I thought and thought
about it, and could not convince myself that such a method would 
do anything more useful than cause other people's modules to suddenly
stop working because some bozo function decided to reject the \f(CW\*(C`FONT\*(C'\fR tag.
.SS "\s-1OO\s0 interface, with whipped cream"
.IX Subsection "OO interface, with whipped cream"
In the grand tradition of \*(C+, output method chaining is supported
in both the Vanilla Interface and the Chocolate Interface.  
So you can (and probably should) write the above code as:
.PP
.Vb 3
\&    $HTML \-> A(HREF=>$url) 
\&          \-> e(\*(Aqcopy\*(Aq) \-> t(" 1996 by $myname!") 
\&          \-> _A;
.Ve
.PP
\&\fIBut wait!  Neapolitan ice cream has one more flavor...\fR
.SS "\s-1OO\s0 interface, strawberry"
.IX Subsection "OO interface, strawberry"
I was jealous of the compact syntax of HTML::AsSubs, but I didn't
want to worry about clogging the namespace with a lot of functions
like p(), a(), etc. (especially when markup-functions like \fItr()\fR conflict
with existing Perl functions).  So I came up with this:
.PP
.Vb 1
\&    output $HTML [A, HREF=>$url], "Here\*(Aqs my $caption", [_A];
.Ve
.PP
Conceptually, arrayrefs are sent to \f(CW\*(C`html_tag()\*(C'\fR, and strings to 
\&\f(CW\*(C`html_escape()\*(C'\fR.
.SH "ADVANCED TOPICS"
.IX Header "ADVANCED TOPICS"
.SS "Auto-formatting and inserting newlines"
.IX Subsection "Auto-formatting and inserting newlines"
\&\fIAuto-formatting\fR is the name I give to the Chocolate Interface feature
whereby newlines (and maybe, in the future, other things)
are inserted before or after the tags you output in order to make 
your \s-1HTML\s0 more readable.  So, by default, this:
.PP
.Vb 5
\&    $HTML \-> HTML 
\&          \-> HEAD  
\&          \-> TITLE \-> t("Hello!") \-> _TITLE 
\&          \-> _HEAD
\&          \-> BODY(BGCOLOR=>\*(Aq#808080\*(Aq);
.Ve
.PP
Actually produces this:
.PP
.Vb 5
\&    <HTML><HTML>
\&    <HEAD>
\&    <TITLE>Hello!</TITLE>
\&    </HEAD>
\&    <BODY BGCOLOR="#808080">
.Ve
.PP
\&\fBTo turn off autoformatting altogether\fR on a given HTML::Stream object,
use the \f(CW\*(C`auto_format()\*(C'\fR method:
.PP
.Vb 1
\&    $HTML\->auto_format(0);        # stop autoformatting!
.Ve
.PP
\&\fBTo change whether a newline is automatically output\fR before/after the 
begin/end form of a tag at a \fBglobal\fR level, use \f(CW\*(C`set_tag()\*(C'\fR:
.PP
.Vb 2
\&    HTML::Stream\->set_tag(\*(AqB\*(Aq, Newlines=>15);   # 15 means "\en<B>\en \en</B>\en"
\&    HTML::Stream\->set_tag(\*(AqI\*(Aq, Newlines=>7);    # 7 means  "\en<I>\en \en</I>  "
.Ve
.PP
\&\fBTo change whether a newline is automatically output\fR before/after the 
begin/end form of a tag \fBfor a given stream\fR level, give the stream
its own private \*(L"tag info\*(R" table, and then use \f(CW\*(C`set_tag()\*(C'\fR:
.PP
.Vb 2
\&    $HTML\->private_tags;
\&    $HTML\->set_tag(\*(AqB\*(Aq, Newlines=>0);     # won\*(Aqt affect anyone else!
.Ve
.PP
\&\fBTo output newlines explicitly\fR, just use the special \f(CW\*(C`nl\*(C'\fR method
in the Chocolate Interface:
.PP
.Vb 2
\&    $HTML\->nl;     # one newline
\&    $HTML\->nl(6);  # six newlines
.Ve
.PP
I am sometimes asked, \*(L"why don't you put more newlines in automatically?\*(R"
Well, mostly because...
.IP "\(bu" 4
Sometimes you'll be outputting stuff inside a \f(CW\*(C`PRE\*(C'\fR environment.
.IP "\(bu" 4
Sometimes you really do want to jam things (like images, or table
cell delimiters and the things they contain) right up against each other.
.PP
So I've stuck to outputting newlines in places where it's most likely
to be harmless.
.SS "Entities"
.IX Subsection "Entities"
As shown above, You can use the \f(CW\*(C`ent()\*(C'\fR (or \f(CW\*(C`e()\*(C'\fR) method to output 
an entity:
.PP
.Vb 1
\&    $HTML\->t(\*(AqCopyright \*(Aq)\->e(\*(Aqcopy\*(Aq)\->t(\*(Aq 1996 by Me!\*(Aq);
.Ve
.PP
But this can be a pain, particularly for generating output with
non-ASCII characters:
.PP
.Vb 3
\&    $HTML \-> t(\*(AqCopyright \*(Aq) 
\&          \-> e(\*(Aqcopy\*(Aq) 
\&          \-> t(\*(Aq 1996 by Fran\*(Aq) \-> e(\*(Aqccedil\*(Aq) \-> t(\*(Aqois, Inc.!\*(Aq);
.Ve
.PP
Granted, Europeans can always type the 8\-bit characters directly in
their Perl code, and just have this:
.PP
.Vb 1
\&    $HTML \-> t("Copyright \e251 1996 by Fran\e347ois, Inc.!\*(Aq);
.Ve
.PP
But folks without 8\-bit text editors can find this kind of output
cumbersome to generate.  Sooooooooo...
.SS "Auto-escaping: changing the way text is escaped"
.IX Subsection "Auto-escaping: changing the way text is escaped"
\&\fIAuto-escaping\fR is the name I give to the act of taking an \*(L"unsafe\*(R"
string (one with \*(L">\*(R", \*(L"&\*(R", etc.), and magically outputting \*(L"safe\*(R" \s-1HTML.\s0
.PP
The default \*(L"auto-escape\*(R" behavior of an \s-1HTML\s0 stream can be a drag if
you've got a lot character entities that you want to output, or if 
you're using the Latin\-1 character set, or some other input encoding.  
Fortunately, you can use the \f(CW\*(C`auto_escape()\*(C'\fR method to change the 
way a particular HTML::Stream works at any time.
.PP
First, here's a couple of special invocations:
.PP
.Vb 4
\&    $HTML\->auto_escape(\*(AqALL\*(Aq);      # Default; escapes [<>"&] and 8\-bit chars.
\&    $HTML\->auto_escape(\*(AqLATIN_1\*(Aq);  # Like ALL, but uses Latin\-1 entities
\&                                    #   instead of decimal equivalents.
\&    $HTML\->auto_escape(\*(AqNON_ENT\*(Aq);  # Like ALL, but leaves "&" alone.
.Ve
.PP
You can also install your own auto-escape function (note
that you might very well want to install it for just a little bit
only, and then de-install it):
.PP
.Vb 7
\&    sub my_auto_escape {
\&        my $text = shift;
\&        HTML::Entities::encode($text);     # start with default
\&        $text =~ s/\e(c\e)/&copy;/ig;        # (C) becomes copyright
\&        $text =~ s/\e\e,(c)/\e&$1cedil;/ig;   # \e,c becomes a cedilla
\&        $text;
\&    }
\&    
\&    # Start using my auto\-escape:
\&    my $old_esc = $HTML\->auto_escape(\e&my_auto_escape);  
\&    
\&    # Output some stuff:
\&    $HTML\-> IMG(SRC=>\*(Aqlogo.gif\*(Aq, ALT=>\*(AqFran\e,cois, Inc\*(Aq);
\&    output $HTML \*(AqCopyright (C) 1996 by Fran\e,cois, Inc.!\*(Aq;
\&    
\&    # Stop using my auto\-escape:
\&    $HTML\->auto_escape($old_esc);
.Ve
.PP
If you find yourself in a situation where you're doing this a lot,
a better way is to create a \fBsubclass\fR of HTML::Stream which installs
your custom function when constructed.  For an example, see the 
\&\fBHTML::Stream::Latin1\fR subclass in this module.
.SS "Outputting \s-1HTML\s0 to things besides filehandles"
.IX Subsection "Outputting HTML to things besides filehandles"
As of Revision 1.21, you no longer need to supply \f(CW\*(C`new()\*(C'\fR with a 
filehandle: \fIany object that responds to a \fIprint()\fI method will do\fR.
Of course, this includes \fBblessed\fR FileHandles, and IO::Handles.
.PP
If you supply a \s-1GLOB\s0 reference (like \f(CW\*(C`\e*STDOUT\*(C'\fR) or a string (like
\&\f(CW"Module::FH"\fR), HTML::Stream will automatically create an invisible
object for talking to that filehandle (I don't dare bless it into a
FileHandle, since the underlying descriptor would get closed when 
the HTML::Stream is destroyed, and you might not want that).
.PP
You say you want to print to a string?  For kicks and giggles, try this:
.PP
.Vb 9
\&    package StringHandle;
\&    sub new {
\&        my $self = \*(Aq\*(Aq;
\&        bless \e$self, shift;
\&    }
\&    sub print {
\&        my $self = shift;
\&        $$self .= join(\*(Aq\*(Aq, @_);
\&    }
\&    
\&  
\&    package main;
\&    use HTML::Stream;
\&    
\&    my $SH = new StringHandle;
\&    my $HTML = new HTML::Stream $SH;
\&    $HTML \-> H1 \-> t("Hello & <<welcome>>!") \-> _H1;
\&    print "PRINTED STRING: ", $$SH, "\en";
.Ve
.SS "Subclassing"
.IX Subsection "Subclassing"
This is where you can make your application-specific HTML-generating code
\&\fImuch\fR easier to look at.  Consider this:
.PP
.Vb 2
\&    package MY::HTML;
\&    @ISA = qw(HTML::Stream);
\&     
\&    sub Aside {
\&        $_[0] \-> FONT(SIZE=>\-1) \-> I;
\&    }
\&    sub _Aside {
\&        $_[0] \-> _I \-> _FONT;
\&    }
.Ve
.PP
Now, you can do this:
.PP
.Vb 1
\&    my $HTML = new MY::HTML \e*STDOUT;
\&    
\&    $HTML \-> Aside
\&          \-> t("Don\*(Aqt drink the milk, it\*(Aqs spoiled... pass it on...")
\&          \-> _Aside;
.Ve
.PP
If you're defining these markup-like, chocolate-interface-style functions,
I recommend using mixed case with a leading capital.  You probably 
shouldn't use all-uppercase, since that's what this module uses for
real \s-1HTML\s0 tags.
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.SS "Functions"
.IX Subsection "Functions"
.IP "html_escape \s-1TEXT\s0" 4
.IX Item "html_escape TEXT"
Given a \s-1TEXT\s0 string, turn the text into valid \s-1HTML\s0 by escaping \*(L"unsafe\*(R" 
characters.  Currently, the \*(L"unsafe\*(R" characters are 8\-bit characters plus:
.Sp
.Vb 1
\&    <  >  =  &
.Ve
.Sp
\&\fBNote:\fR provided for convenience and backwards-compatibility only.
You may want to use the more-powerful \fBHTML::Entities::encode\fR
function instead.
.IP "html_tag \s-1TAG\s0 [, PARAM=>\s-1VALUE, ...\s0]" 4
.IX Item "html_tag TAG [, PARAM=>VALUE, ...]"
Return the text for a given \s-1TAG,\s0 possibly with parameters.
As an efficiency hack, only the values are HTML-escaped currently:
it is assumed that the tag and parameters will already be safe.
.Sp
For convenience and readability, you can say \f(CW\*(C`_A\*(C'\fR instead of \f(CW"/A"\fR
for the first tag, if you're into barewords.
.IP "html_unescape \s-1TEXT\s0" 4
.IX Item "html_unescape TEXT"
Remove angle-tag markup, and convert the standard ampersand-escapes
(\f(CW\*(C`lt\*(C'\fR, \f(CW\*(C`gt\*(C'\fR, \f(CW\*(C`amp\*(C'\fR, \f(CW\*(C`quot\*(C'\fR, and \f(CW\*(C`#ddd\*(C'\fR) into \s-1ASCII\s0 characters.
.Sp
\&\fBNote:\fR provided for convenience and backwards-compatibility only.
You may want to use the more-powerful \fBHTML::Entities::decode\fR
function instead: unlike this function, it can collapse entities
like \f(CW\*(C`copy\*(C'\fR and \f(CW\*(C`ccedil\*(C'\fR into their Latin\-1 byte values.
.IP "html_unmarkup \s-1TEXT\s0" 4
.IX Item "html_unmarkup TEXT"
Remove angle-tag markup from \s-1TEXT,\s0 but do not convert ampersand-escapes.  
Cheesy, but theoretically useful if you want to, say, incorporate
externally-provided \s-1HTML\s0 into a page you're generating, and are worried
that the \s-1HTML\s0 might contain undesirable markup.
.SS "Vanilla"
.IX Subsection "Vanilla"
.IP "new [\s-1PRINTABLE\s0]" 4
.IX Item "new [PRINTABLE]"
\&\fIClass method.\fR
Create a new \s-1HTML\s0 output stream.
.Sp
The \s-1PRINTABLE\s0 may be a FileHandle, a glob reference, or any object
that responds to a \f(CW\*(C`print()\*(C'\fR message.
If no \s-1PRINTABLE\s0 is given, does a \fIselect()\fR and uses that.
.IP "auto_escape [NAME|SUBREF]" 4
.IX Item "auto_escape [NAME|SUBREF]"
\&\fIInstance method.\fR
Set the auto-escape function for this \s-1HTML\s0 stream.
.Sp
If the argument is a subroutine reference \s-1SUBREF,\s0 then that subroutine 
will be used.  Declare such subroutines like this:
.Sp
.Vb 5
\&    sub my_escape {
\&        my $text = shift;     # it\*(Aqs passed in the first argument
\&        ...
\&        $text;
\&    }
.Ve
.Sp
If a textual \s-1NAME\s0 is given, then one of the appropriate built-in 
functions is used.  Possible values are:
.RS 4
.IP "\s-1ALL\s0" 4
.IX Item "ALL"
Default for HTML::Stream objects.  This escapes angle brackets, 
ampersands, double-quotes, and 8\-bit characters.  8\-bit characters 
are escaped using decimal entity codes (like \f(CW\*(C`#123\*(C'\fR).
.IP "\s-1LATIN_1\s0" 4
.IX Item "LATIN_1"
Like \f(CW"ALL"\fR, but uses Latin\-1 entity names (like \f(CW\*(C`ccedil\*(C'\fR) instead of
decimal entity codes to escape characters.  This makes the \s-1HTML\s0 more readable
but it is currently not advised, as \*(L"older\*(R" browsers (like Netscape 2.0)
do not recognize many of the \s-1ISO\-8859\-1\s0 entity names (like \f(CW\*(C`deg\*(C'\fR).
.Sp
\&\fBWarning:\fR If you specify this option, you'll find that it attempts
to \*(L"require\*(R" \fBHTML::Entities\fR at run time.  That's because I didn't want 
to \fIforce\fR you to have that module just to use the rest of HTML::Stream.
To pick up problems at compile time, you are advised to say:
.Sp
.Vb 2
\&    use HTML::Stream;
\&    use HTML::Entities;
.Ve
.Sp
in your source code.
.IP "\s-1NON_ENT\s0" 4
.IX Item "NON_ENT"
Like \f(CW"ALL"\fR, except that ampersands (&) are \fInot\fR escaped.
This allows you to use &\-entities in your text strings, while having
everything else safely escaped:
.Sp
.Vb 1
\&    output $HTML "If A is an acute angle, then A > 90&deg;";
.Ve
.RE
.RS 4
.Sp
Returns the previously-installed function, in the manner of \f(CW\*(C`select()\*(C'\fR.
No arguments just returns the currently-installed function.
.RE
.IP "auto_format \s-1ONOFF\s0" 4
.IX Item "auto_format ONOFF"
\&\fIInstance method.\fR
Set the auto-formatting characteristics for this \s-1HTML\s0 stream.
Currently, all you can do is supply a single defined boolean
argument, which turns auto-formatting \s-1ON \\fIs0\fR\|(1) or \s-1OFF \\fIs0\fR\|(0). 
The self object is returned.
.Sp
Please use no other values; they are reserved for future use.
.IP "comment \s-1COMMENT\s0" 4
.IX Item "comment COMMENT"
\&\fIInstance method.\fR
Output an \s-1HTML\s0 comment.
As of 1.29, a newline is automatically appended.
.IP "ent \s-1ENTITY\s0" 4
.IX Item "ent ENTITY"
\&\fIInstance method.\fR
Output an \s-1HTML\s0 entity.  For example, here's how you'd output a 
non-breaking space:
.Sp
.Vb 1
\&      $html\->ent(\*(Aqnbsp\*(Aq);
.Ve
.Sp
You may abbreviate this method name as \f(CW\*(C`e\*(C'\fR:
.Sp
.Vb 1
\&      $html\->e(\*(Aqnbsp\*(Aq);
.Ve
.Sp
\&\fBWarning:\fR this function assumes that the entity argument is legal.
.IP "io" 4
.IX Item "io"
Return the underlying output handle for this \s-1HTML\s0 stream.
All you can depend upon is that it is some kind of object
which responds to a \fIprint()\fR message:
.Sp
.Vb 1
\&    $HTML\->io\->print("This is not auto\-escaped or nuthin!");
.Ve
.IP "nl [\s-1COUNT\s0]" 4
.IX Item "nl [COUNT]"
\&\fIInstance method.\fR
Output \s-1COUNT\s0 newlines.  If undefined, \s-1COUNT\s0 defaults to 1.
.IP "tag \s-1TAGNAME\s0 [, PARAM=>\s-1VALUE, ...\s0]" 4
.IX Item "tag TAGNAME [, PARAM=>VALUE, ...]"
\&\fIInstance method.\fR
Output a tag.  Returns the self object, to allow method chaining.
You can say \f(CW\*(C`_A\*(C'\fR instead of \f(CW"/A"\fR, if you're into barewords.
.IP "text \s-1TEXT...\s0" 4
.IX Item "text TEXT..."
\&\fIInstance method.\fR
Output some text.  You may abbreviate this method name as \f(CW\*(C`t\*(C'\fR:
.Sp
.Vb 1
\&      $html\->t(\*(AqHi there, \*(Aq, $yournamehere, \*(Aq!\*(Aq);
.Ve
.Sp
Returns the self object, to allow method chaining.
.IP "text_nbsp \s-1TEXT...\s0" 4
.IX Item "text_nbsp TEXT..."
\&\fIInstance method.\fR
Output some text, but with all spaces output as non-breaking-space
characters:
.Sp
.Vb 2
\&      $html\->t("To list your home directory, type: ")
\&           \->text_nbsp("ls \-l ~yourname.")
.Ve
.Sp
Returns the self object, to allow method chaining.
.SS "Strawberry"
.IX Subsection "Strawberry"
.IP "output \s-1ITEM,...,ITEM\s0" 4
.IX Item "output ITEM,...,ITEM"
\&\fIInstance method.\fR
Go through the items.  If an item is an arrayref, treat it like
the array argument to \fIhtml_tag()\fR and output the result.  If an item
is a text string, escape the text and output the result.  Like this:
.Sp
.Vb 1
\&     output $HTML [A, HREF=>$url], "Here\*(Aqs my $caption!", [_A];
.Ve
.SS "Chocolate"
.IX Subsection "Chocolate"
.IP "accept_tag \s-1TAG\s0" 4
.IX Item "accept_tag TAG"
\&\fIClass method.\fR
Declares that the tag is to be accepted as valid \s-1HTML \s0(if it isn't already).
For example, this...
.Sp
.Vb 2
\&     # Make sure methods MARQUEE and _MARQUEE are compiled on demand:
\&     HTML::Stream\->accept_tag(\*(AqMARQUEE\*(Aq);
.Ve
.Sp
\&...gives the Chocolate Interface permission to create (via \s-1AUTOLOAD\s0)
definitions for the \s-1MARQUEE\s0 and _MARQUEE methods, so you can then say:
.Sp
.Vb 1
\&     $HTML \-> MARQUEE \-> t("Hi!") \-> _MARQUEE;
.Ve
.Sp
If you want to set the default attribute of the tag as well, you can
do so via the \fIset_tag()\fR method instead; it will effectively do an
\&\fIaccept_tag()\fR as well.
.Sp
.Vb 3
\&     # Make sure methods MARQUEE and _MARQUEE are compiled on demand,
\&     #   *and*, set the characteristics of that tag.
\&     HTML::Stream\->set_tag(\*(AqMARQUEE\*(Aq, Newlines=>9);
.Ve
.IP "private_tags" 4
.IX Item "private_tags"
\&\fIInstance method.\fR
Normally, \s-1HTML\s0 streams use a reference to a global table of tag
information to determine how to do such things as auto-formatting,
and modifications made to that table by \f(CW\*(C`set_tag\*(C'\fR will
affect everyone.
.Sp
However, if you want an \s-1HTML\s0 stream to have a private copy of that
table to munge with, just send it this message after creating it.  
Like this:
.Sp
.Vb 2
\&    my $HTML = new HTML::Stream \e*STDOUT;
\&    $HTML\->private_tags;
.Ve
.Sp
Then, you can say stuff like:
.Sp
.Vb 2
\&    $HTML\->set_tag(\*(AqPRE\*(Aq,   Newlines=>0);
\&    $HTML\->set_tag(\*(AqBLINK\*(Aq, Newlines=>9);
.Ve
.Sp
And it won't affect anyone else's \fIauto-formatting\fR (although they will 
possibly be able to use the \s-1BLINK\s0 tag method without a fatal
exception \f(CW\*(C`:\-(\*(C'\fR ).
.Sp
Returns the self object.
.IP "set_tag \s-1TAG,\s0 [\s-1TAGINFO...\s0]" 4
.IX Item "set_tag TAG, [TAGINFO...]"
\&\fIClass/instance method.\fR
Accept the given \s-1TAG\s0 in the Chocolate Interface, and (if \s-1TAGINFO\s0
is given) alter its characteristics when being output.
.RS 4
.IP "\(bu" 4
\&\fBIf invoked as a class method,\fR this alters the \*(L"master tag table\*(R",
and allows a new tag to be supported via an autoloaded method:
.Sp
.Vb 1
\&     HTML::Stream\->set_tag(\*(AqMARQUEE\*(Aq, Newlines=>9);
.Ve
.Sp
Once you do this, \fIall\fR \s-1HTML\s0 streams you open from then on 
will allow that tag to be output in the chocolate interface.
.IP "\(bu" 4
\&\fBIf invoked as an instance method,\fR this alters the \*(L"tag table\*(R" referenced
by that \s-1HTML\s0 stream, usually for the purpose of affecting things like
the auto-formatting on that \s-1HTML\s0 stream.
.Sp
\&\fBWarning:\fR by default, an \s-1HTML\s0 stream just references the \*(L"master tag table\*(R" 
(this makes \f(CW\*(C`new()\*(C'\fR more efficient), so \fIby default, the 
instance method will behave exactly like the class method.\fR
.Sp
.Vb 2
\&     my $HTML = new HTML::Stream \e*STDOUT;
\&     $HTML\->set_tag(\*(AqBLINK\*(Aq, Newlines=>0);  # changes it for others!
.Ve
.Sp
If you want to diddle with \fIone\fR stream's auto-formatting \fIonly,\fR 
you'll need to give that stream its own \fIprivate\fR tag table.  Like this:
.Sp
.Vb 3
\&     my $HTML = new HTML::Stream \e*STDOUT;
\&     $HTML\->private_tags;
\&     $HTML\->set_tag(\*(AqBLINK\*(Aq, Newlines=>0);  # doesn\*(Aqt affect other streams
.Ve
.Sp
\&\fBNote:\fR this will still force an default entry for \s-1BLINK\s0 in the \fImaster\fR 
tag table: otherwise, we'd never know that it was legal to \s-1AUTOLOAD\s0 a 
\&\s-1BLINK\s0 method.   However, it will only alter the \fIcharacteristics\fR of the 
\&\s-1BLINK\s0 tag (like auto-formatting) in the \fIobject's\fR tag table.
.RE
.RS 4
.Sp
The \s-1TAGINFO,\s0 if given, is a set of key=>value pairs with the following 
possible keys:
.IP "Newlines" 4
.IX Item "Newlines"
Assumed to be a number which encodes how newlines are to be output 
before/after a tag.   The value is the logical \s-1OR \s0(or sum) of a set of flags:
.Sp
.Vb 4
\&     0x01    newline before <TAG>         .<TAG>.     .</TAG>.    
\&     0x02    newline after <TAG>          |     |     |      |
\&     0x04    newline before </TAG>        1     2     4      8
\&     0x08    newline after </TAG>
.Ve
.Sp
Hence, to output \s-1BLINK\s0 environments which are preceded/followed by newlines:
.Sp
.Vb 1
\&     set_tag HTML::Stream \*(AqBLINK\*(Aq, Newlines=>9;
.Ve
.RE
.RS 4
.Sp
Returns the self object on success.
.RE
.IP "tags" 4
.IX Item "tags"
\&\fIClass/instance method.\fR
Returns an unsorted list of all tags in the class/instance tag table 
(see \f(CW\*(C`set_tag\*(C'\fR for class/instance method differences).
.SH "SUBCLASSES"
.IX Header "SUBCLASSES"
.SS "HTML::Stream::Latin1"
.IX Subsection "HTML::Stream::Latin1"
A small, public package for outputting Latin\-1 markup.  Its
default auto-escape function is \f(CW\*(C`LATIN_1\*(C'\fR, which tries to output
the mnemonic entity markup (e.g., \f(CW\*(C`&ccedil;\*(C'\fR) for \s-1ISO\-8859\-1\s0 characters.
.PP
So using HTML::Stream::Latin1 like this:
.PP
.Vb 1
\&    use HTML::Stream;
\&    
\&    $HTML = new HTML::Stream::Latin1 \e*STDOUT;
\&    output $HTML "\e253A right angle is 90\e260, \e277No?\e273\en";
.Ve
.PP
Prints this:
.PP
.Vb 1
\&    &laquo;A right angle is 90&deg;, &iquest;No?&raquo;
.Ve
.PP
Instead of what HTML::Stream would print, which is this:
.PP
.Vb 1
\&    &#171;A right angle is 90&#176;, &#191;No?&#187;
.Ve
.PP
\&\fBWarning:\fR a lot of Latin\-1 \s-1HTML\s0 markup is not recognized by older 
browsers (e.g., Netscape 2.0).  Consider using HTML::Stream; it will output 
the decimal entities which currently seem to be more \*(L"portable\*(R".
.PP
\&\fBNote:\fR using this class \*(L"requires\*(R" that you have HTML::Entities.
.SH "PERFORMANCE"
.IX Header "PERFORMANCE"
Slower than I'd like.  Both the \fIoutput()\fR method and the various \*(L"tag\*(R" 
methods seem to run about 5 times slower than the old 
just-hardcode-the-darn stuff approach.  That is, in general, this:
.PP
.Vb 6
\&    ### Approach #1...
\&    tag  $HTML \*(AqA\*(Aq, HREF=>"$href";
\&    tag  $HTML \*(AqIMG\*(Aq, SRC=>"logo.gif", ALT=>"LOGO";
\&    text $HTML $caption;
\&    tag  $HTML \*(Aq_A\*(Aq;
\&    text $HTML $a_lot_of_text;
.Ve
.PP
And this:
.PP
.Vb 6
\&    ### Approach #2...
\&    output $HTML [A, HREF=>"$href"], 
\&                 [IMG, SRC=>"logo.gif", ALT=>"LOGO"],
\&                 $caption,
\&                 [_A];
\&    output $HTML $a_lot_of_text;
.Ve
.PP
And this:
.PP
.Vb 6
\&    ### Approach #3...
\&    $HTML \-> A(HREF=>"$href")
\&          \-> IMG(SRC=>"logo.gif", ALT=>"LOGO")
\&          \-> t($caption)
\&          \-> _A
\&          \-> t($a_lot_of_text);
.Ve
.PP
Each run about 5x slower than this:
.PP
.Vb 6
\&    ### Approach #4...
\&    print \*(Aq<A HREF="\*(Aq, html_escape($href), \*(Aq>\*(Aq,
\&          \*(Aq<IMG SRC="logo.gif" ALT="LOGO">\*(Aq,
\&          html_escape($caption),
\&          \*(Aq</A>\*(Aq;
\&    print html_escape($a_lot_of_text);
.Ve
.PP
Of course, I'd much rather use any of first three \fI(especially #3)\fR 
if I had to get something done right in a hurry.  Or did you not notice
the typo in approach #4?  \f(CW\*(C`;\-)\*(C'\fR
.PP
(\s-1BTW,\s0 thanks to Benchmark:: for allowing me to... er... benchmark stuff.)
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR Stream.pm,v 1.60 2008/08/06 dstaal Exp $
.SH "CHANGE LOG"
.IX Header "CHANGE LOG"
.IP "Version 1.60   (2008/08/06)" 4
.IX Item "Version 1.60 (2008/08/06)"
Fixed up the tests some more, updated changelog.  (Which I'd forgotten 
about...)
.IP "Version 1.59   (2008/06/01)" 4
.IX Item "Version 1.59 (2008/06/01)"
Better tests, better Meta.yml.
.IP "Version 1.58   (2008/05/28)" 4
.IX Item "Version 1.58 (2008/05/28)"
Another attempt at cleanup, as well expanding the Meta.yml file.
.IP "Version 1.57   (2008/05/28)" 4
.IX Item "Version 1.57 (2008/05/28)"
Cleaned up the Mac-specific files that were getting created in the archive.
.IP "Version 1.56   (2008/05/27)" 4
.IX Item "Version 1.56 (2008/05/27)"
Added the start of a testing suite.  In the process, I found an error:
\&\s-1HTML\s0 defines the tag '\s-1NOFRAMES\s0', not '\s-1NOFRAME\s0'.  Both are currently in
the tag list, but consider '\s-1NOFRAME\s0' depriciated.
.Sp
The test suite requires Test::More and Test::Output.
.IP "Version 1.55   (2003/10/28)" 4
.IX Item "Version 1.55 (2003/10/28)"
New maintainer: Daniel T. Staal.  No major changes in the code, except
to complete the tag list to \s-1HTML 4.01\s0 specifications. (With the
exception of the 'S' tag, which I want to test, and is depreciated
anyway.  Note that the \s-1DOCTYPE\s0 is not actually a \s-1HTML\s0 tag, and is not
currently included.)
.IP "Version 1.54   (2001/08/20)" 4
.IX Item "Version 1.54 (2001/08/20)"
The terms-of-use have been placed in the distribution file \*(L"\s-1COPYING\*(R".  \s0
Also, small documentation tweaks were made.
.IP "Version 1.51   (2001/08/16)" 4
.IX Item "Version 1.51 (2001/08/16)"
No real changes to code; just improved documentation,
and removed HTML::Entities and HTML::Parser from ./etc
at \s-1CPAN\s0's request.
.IP "Version 1.47   (2000/06/10)" 4
.IX Item "Version 1.47 (2000/06/10)"
No real changes to code; just improved documentation.
.IP "Version 1.45   (1999/02/09)" 4
.IX Item "Version 1.45 (1999/02/09)"
Cleanup for Perl 5.005: removed duplicate typeglob assignments.
.IP "Version 1.44   (1998/01/14)" 4
.IX Item "Version 1.44 (1998/01/14)"
Win95 install (5.004) now works.
Added \s-1SYNOPSIS\s0 to \s-1POD.\s0
.IP "Version 1.41   (1998/01/02)" 4
.IX Item "Version 1.41 (1998/01/02)"
Removed $& for efficiency.
\&\fIThanks, Andreas!\fR
.Sp
Added support for \s-1OPTION,\s0 and default now puts newlines after \s-1SELECT \s0
and /SELECT.  Also altered \*(L"\s-1TELEM\*(R"\s0 syntax to put newline after end-tags 
of list element tags (like /OPTION, /LI, etc.).  In theory, this change
could produce undesirable results for folks who embed lists inside of \s-1PRE \s0
environments... however, that kind of stuff was done in the days before 
TABLEs; also, you can always turn it off if you really need to.
\&\fIThanks to John D Groenveld for these patches.\fR
.Sp
Added \fItext_nbsp()\fR.
\&\fIThanks to John D Groenveld for the patch.\fR
This method may also be invoked as \fInbsp_text()\fR as in the original patch, 
but that's sort of a private tip-of-the-hat to the patch author, and the 
synonym may go away in the future.
.IP "Version 1.37   (1997/02/09)" 4
.IX Item "Version 1.37 (1997/02/09)"
No real change; just trying to make \s-1CPAN\s0.pm happier.
.IP "Version 1.32   (1997/01/12)" 4
.IX Item "Version 1.32 (1997/01/12)"
\&\fB\s-1NEW TOOL\s0 for generating Perl code which uses HTML::Stream!\fR 
Check your toolkit for \fBhtml2perlstream\fR.
.Sp
Added built-in support for escaping 8\-bit characters.
.Sp
Added \f(CW\*(C`LATIN_1\*(C'\fR auto-escape, which uses HTML::Entities to generate
mnemonic entities.  This is now the default method for HTML::Stream::Latin1.
.Sp
Added \f(CW\*(C`auto_format(),\*(C'\fR 
so you can now turn auto-formatting off/on.
.Sp
Added \f(CW\*(C`private_tags()\*(C'\fR, 
so it is now possible for \s-1HTML\s0 streams to each have their own \*(L"private\*(R"
copy of the \f(CW%Tags\fR table, for use by \f(CW\*(C`set_tag()\*(C'\fR.
.Sp
Added \f(CW\*(C`set_tag()\*(C'\fR.  The tags tables may now be modified dynamically so 
as to change how formatting is done on-the-fly.  This will hopefully not
compromise the efficiency of the chocolate interface (until now,
the formatting was compiled into the method itself), and \fIwill\fR add
greater flexibility for more-complex programs.
.Sp
Added \s-1POD\s0 documentation for all subroutines in the public interface.
.IP "Version 1.29   (1996/12/10)" 4
.IX Item "Version 1.29 (1996/12/10)"
Added terminating newline to \fIcomment()\fR.
\&\fIThanks to John D Groenveld for the suggestion and the patch.\fR
.IP "Version 1.27   (1996/12/10)" 4
.IX Item "Version 1.27 (1996/12/10)"
Added built-in HTML::Stream::Latin1, which does a very simple encoding
of all characters above \s-1ASCII 127.\s0
.Sp
Fixed bug in \fIaccept_tag()\fR, where 'my' variable was shadowing argument.
\&\fIThanks to John D Groenveld for the bug report and the patch.\fR
.IP "Version 1.26   (1996/09/27)" 4
.IX Item "Version 1.26 (1996/09/27)"
Start of history.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This program is free software.  You may copy or redistribute it under
the same terms as Perl itself.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Warmest thanks to...
.PP
.Vb 1
\&    Eryq                   For writing the original version of this module.
\&
\&    John Buckman           For suggesting that I write an "html2perlstream",
\&                           and inspiring me to look at supporting Latin\-1.
\&    Tony Cebzanov          For suggesting that I write an "html2perlstream"
\&    John D Groenveld       Bug reports, patches, and suggestions
\&    B. K. Oxley (binkley)  For suggesting the support of "writing to strings"
\&                           which became the "printable" interface.
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel T. Staal (\fIDStaal@usa.net\fR).
.PP
Enjoy.  Yell if it breaks.