.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" 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 "MKDoc::XML::Tagger 3pm"
.TH MKDoc::XML::Tagger 3pm "2005-03-10" "perl v5.10.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"
MKDoc::XML::Tagger \- Adds XML markup to XML / XHTML content.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  use MKDoc::XML::Tagger;
\&  print MKDoc::XML::Tagger\->process_data (
\&      "<p>Hello, World!</p>",
\&      { _expr => \*(AqWorld\*(Aq, _tag => \*(Aqstrong\*(Aq, class => \*(AqsuperFort\*(Aq }
\&  );
.Ve
.PP
Should print:
.PP
.Vb 1
\&  <p>Hello, <strong class="superFort">World</strong>!</p>
.Ve
.SH "SUMMARY"
.IX Header "SUMMARY"
MKDoc::XML::Tagger is a class which lets you specify a set of tag and attributes associated
with expressions which you want to mark up. This module will then stuff any \s-1XML\s0 you send out
with the extra expressions.
.PP
For example, let's say that you have a document which has the term 'Microsoft Windows' several
times in it. You could wish to surround any instance of the term with a <trademark> tag.
MKDoc::XML::Tagger lets you do exactly that.
.PP
In MKDoc, this is used so that editors can enter hyperlinks separately from the content.
It allows them to enter content without having to worry about the annoying <a href=\*(L"...\*(R">
syntax. It also has the added benefit from preventing bad information architecture such as
the 'click here' syndrome.
.PP
We also have plans to use it for automatically linking glossary words, abbreviation tags,
etc.
.PP
MKDoc::XML::Tagger is also probably a very good tool if you are building some kind of Wiki
system in which you want expressions to be automagically hyperlinked.
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
\&\fBThis module does low level \s-1XML\s0 manipulation. It will somehow parse even broken \s-1XML\s0
and try to do something with it. Do not use it unless you know what you're doing.\fR
.SH "API"
.IX Header "API"
The \s-1API\s0 is very simple.
.ie n .SS "my $result = MKDoc::XML::Tagger\->process_data ($xml, @expressions);"
.el .SS "my \f(CW$result\fP = MKDoc::XML::Tagger\->process_data ($xml, \f(CW@expressions\fP);"
.IX Subsection "my $result = MKDoc::XML::Tagger->process_data ($xml, @expressions);"
Tags \f(CW$xml\fR with the \f(CW@expressions\fR list.
.PP
Each element of \f(CW@expressions\fR is a hash reference looking like this:
.PP
.Vb 6
\&  {
\&      _expr      => \*(AqSome Expression\*(Aq,
\&      _tag       => \*(Aqfoo\*(Aq,
\&      attribute1 => \*(Aqbar\*(Aq
\&      attribute2 => \*(Aqbaz\*(Aq
\&  }
.Ve
.PP
Which will try to turn anything which looks like:
.PP
.Vb 3
\&  Some Expression
\&  sOmE ExPrEssIoN
\&  (etcetera)
.Ve
.PP
Into:
.PP
.Vb 3
\&  <foo attr1="bar" attr2="baz">Some Expression</foo>
\&  <foo attr1="bar" attr2="baz">sOmE ExPrEssIoN</foo>
\&  <foo attr1="bar" attr2="baz">(etcetera)</foo>
.Ve
.PP
You can have multiple expressions, in which case longest expressions
are processed first.
.ie n .SS "my $result = MKDoc::XML::Tagger\->process_file ('some/file.xml', @expressions);"
.el .SS "my \f(CW$result\fP = MKDoc::XML::Tagger\->process_file ('some/file.xml', \f(CW@expressions\fP);"
.IX Subsection "my $result = MKDoc::XML::Tagger->process_file ('some/file.xml', @expressions);"
Same as \fIprocess_data()\fR, except it takes its data from 'some/file.xml'.
.SH "NOTES"
.IX Header "NOTES"
MKDoc::XML::Tagger does not really parse the \s-1XML\s0 file you're giving to it
nor does it care if the \s-1XML\s0 is well-formed or not. It uses MKDoc::XML::Tokenizer
to turn the \s-1XML\s0 / \s-1XHTML\s0 file into a series of MKDoc::XML::Token objects
and strictly operates on a list of tokens.
.PP
For this same reason MKDoc::XML::Tagger does not support namespaces.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright 2003 \- MKDoc Holdings Ltd.
.PP
Author: Jean-Michel Hiver
.PP
This module is free software and is distributed under the same license as Perl
itself. Use it at your own risk.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
MKDoc::XML::Tokenizer
MKDoc::XML::Token