.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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
.    \}
.\}
.\"
.\" 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 "SVN::Notify::HTML 3pm"
.TH SVN::Notify::HTML 3pm "2018-07-03" "perl v5.26.2" "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"
.IX Header "Name"
SVN::Notify::HTML \- Subversion activity \s-1HTML\s0 notification
.SH "Synopsis"
.IX Header "Synopsis"
Use \fIsvnnotify\fR in \fIpost-commit\fR:
.PP
.Vb 2
\&  svnnotify \-\-repos\-path "$1" \-\-revision "$2" \e
\&    \-\-to developers@example.com \-\-handler HTML [options]
.Ve
.PP
Use the class in a custom script:
.PP
.Vb 1
\&  use SVN::Notify::HTML;
\&
\&  my $notifier = SVN::Notify::HTML\->new(%params);
\&  $notifier\->prepare;
\&  $notifier\->execute;
.Ve
.SH "Description"
.IX Header "Description"
This subclass of SVN::Notify sends \s-1HTML\s0 formatted email
messages for Subversion activity, rather than the default plain text.
.SH "Prerequisites"
.IX Header "Prerequisites"
In addition to the modules required by SVN::Notify, this class requires:
.IP "HTML::Entities" 4
.IX Item "HTML::Entities"
.SH "Usage"
.IX Header "Usage"
To use SVN::Notify::HTML, simply follow the instructions
in SVN::Notify, but when using \fIsvnnotify\fR, specify \f(CW\*(C`\-\-handler HTML\*(C'\fR.
.SH "Class Interface"
.IX Header "Class Interface"
.SS "Constructor"
.IX Subsection "Constructor"
\fInew\fR
.IX Subsection "new"
.PP
.Vb 1
\&  my $notifier = SVN::Notify::HTML\->new(%params);
.Ve
.PP
Constructs and returns a new SVN::Notify object. All parameters supported by
SVN::Notity are supported here, but SVN::Notify::HTML supports a few
additional parameters:
.IP "linkize" 4
.IX Item "linkize"
.Vb 1
\&  svnnotify \-\-linkize
.Ve
.Sp
A boolean attribute to specify whether or not to \*(L"linkize\*(R" the \s-1SVN\s0 log
message\*(--that is, to turn any URLs or email addresses in the log message into
links.
.IP "css_url" 4
.IX Item "css_url"
.Vb 1
\&  svnnotify \-\-css\-url http://example.com/svnnotify.css
.Ve
.Sp
\&\s-1URL\s0 for a \s-1CSS\s0 file that will can style the \s-1HTML\s0 output by SVN::Notify::HTML or
its subclasses. Note that the \s-1URL\s0 will be added to the output via a
\&\f(CW\*(C`<link rel="stylesheet">\*(C'\fR tag \fIafter\fR the \s-1CSS\s0 generated by
SVN::Notify::HTML or its subclasses. What that means is that the \s-1CSS\s0 file
specified by \f(CW\*(C`css_url\*(C'\fR need not completely style the \s-1HTML,\s0 but simply
override the default settings. This approach nicely takes advantage of the
\&\*(L"cascading\*(R" abilities of \s-1CSS.\s0
.IP "ticket_map" 4
.IX Item "ticket_map"
.Vb 1
\&  svnnotify \-\-ticket\-map \*(Aq(BUG\-(\ed+))=http://bugs.example.com/?show=%s\*(Aq
.Ve
.Sp
This attribute is inherited from SVN::Notify, but its semantics
are slightly different: the regular expression passed as the regular
expression used for the key should return \fItwo\fR matches instead of one: the
text to link and the ticket \s-1ID\s0 itself. For example, '(\s-1BUG\-\s0(\ed+))' will match
\&\*(L"\s-1BUG\-1234567\*(R",\s0 and \*(L"\s-1BUG\-1234567\*(R"\s0 will be used for the link text, while
\&\*(L"1234567\*(R" will be used to fill in the \f(CW\*(C`ticket_url\*(C'\fR format string. The first
set of parentheses capture the whole string, while the parentheses around
\&\f(CW\*(C`\ed+\*(C'\fR match the number only. Also note that it is wise to use \*(L"\eb\*(R" on either
side of the regular expression to insure that you don't get spurious matches.
So a better version would be '\eb(\s-1BUG\-\s0(\ed+))\eb'.
.Sp
As a fallback, if your regular expression returns only a single match string,
it will be used both for the link text and for the the ticket \s-1URL\s0 generated
from \f(CW\*(C`ticket_url\*(C'\fR. For example, '\ebBUG\-(\ed+)\eb' would make a link only of the
number in '\s-1BUG\-1234567\s0', as only the number has been captured by the regular
expression. But two matches are of course recommended (and likely to work
better, as well).
.Sp
You can use more complicated regular expressions if commit messages are likely
to format ticket numbers in various ways. For example, this regular
expression:
.Sp
.Vb 1
\&  \eb\e[?\es*(Ticket\es*#\es*(\ed+))\es*\e]?\eb\*(Aq
.Ve
.Sp
Will match:
.Sp
.Vb 6
\&   String Matched           Link Text        Ticket Number
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&   [Ticket#1234]         [Ticket#1234]       1234
\&   [ Ticket # 1234 ]     [ Ticket # 1234 ]   1234
\&   Ticket #1234          Ticket #1234        1234
\&   Ticket # 1234         Ticket  #1234       1234
.Ve
.Sp
In any of these cases, you can see that the match is successful, properly
creates the link text (simply using the text as typed in by the committer, and
correctly extracts the ticket number for use in the \s-1URL.\s0
.Sp
To learn more about the power of Regular expressions, I highly recommend
_Mastering Regular Expressions, Second Edition_, by Jeffrey Friedl.
.IP "wrap_log" 4
.IX Item "wrap_log"
.Vb 1
\&  svnnotify \-\-wrap\-log
.Ve
.Sp
A boolean attribute to specify whether or not to wrap the log message in the
output \s-1HTML.\s0 By default, log messages are \fInot\fR wrapped, on the assumption
that they should appear exactly as typed. But if that's not the case, specify
this option to wrap the log message.
.SS "Class Methods"
.IX Subsection "Class Methods"
\fIcontent_type\fR
.IX Subsection "content_type"
.PP
Returns the content type of the notification message, \*(L"text/html\*(R". Used to set
the Content-Type header for the message.
.SH "Instance Interface"
.IX Header "Instance Interface"
.SS "Instance Methods"
.IX Subsection "Instance Methods"
\fIstart_html\fR
.IX Subsection "start_html"
.PP
.Vb 1
\&  $notifier\->start_html($file_handle);
.Ve
.PP
This method starts the \s-1HTML\s0 of the notification message. It outputs the
opening \f(CW\*(C`<html>\*(C'\fR, \f(CW\*(C`<head>\*(C'\fR, and \f(CW\*(C`<body>\*(C'\fR tags. Note that if the
\&\f(CW\*(C`language\*(C'\fR attribute is set to a value, it will be specified in the
 \f(CW\*(C`<html>\*(C'\fR tag.
.PP
All of the \s-1HTML\s0 will be passed to any \*(L"start_html\*(R" output filters. See
Writing Output Filters for details on
filters.
.PP
\fIstart_body\fR
.IX Subsection "start_body"
.PP
This method starts the body of the \s-1HTML\s0 notification message. It first calls
\&\f(CW\*(C`start_html()\*(C'\fR, and then outputs the \f(CW\*(C`<style>\*(C'\fR tag, calling
\&\f(CW\*(C`output_css()\*(C'\fR between them. It then outputs an opening \f(CW\*(C`<div>\*(C'\fR tag.
.PP
If the \f(CW\*(C`header\*(C'\fR attribute is set, \f(CW\*(C`start_body()\*(C'\fR outputs it between
\&\f(CW\*(C`<div>\*(C'\fR tags with the \s-1ID\s0 \*(L"header\*(R". Furthermore, if the header happens to
start with the character \*(L"<\*(R", \f(CW\*(C`start_body()\*(C'\fR assumes that it contains
valid \s-1HTML\s0 and therefore will not escape it.
.PP
If a \*(L"start_body\*(R" output filter has been specified, it will be passed the
lines with the \f(CW\*(C`<div>\*(C'\fR tag and the header. To filter the \s-1CSS,\s0 use a \*(L"css\*(R"
filter, and to filter the declaration of the \s-1HTML\s0 document and its \f(CW\*(C`<head>\*(C'\fR section, use a \*(L"start_html\*(R" filter. See Writing Output
Filters for details on filters.
.PP
\fIoutput_css\fR
.IX Subsection "output_css"
.PP
.Vb 1
\&  $notifier\->output_css($file_handle);
.Ve
.PP
This method starts outputs the \s-1CSS\s0 for the \s-1HTML\s0 message. It is called by
\&\f(CW\*(C`start_body()\*(C'\fR, and which wraps the output of \f(CW\*(C`output_css()\*(C'\fR in the
appropriate \f(CW\*(C`<style>\*(C'\fR tags.
.PP
An output filter named \*(L"css\*(R" may be added to modify the output of \s-1CSS.\s0 The
filter subroutine name should be \f(CW\*(C`css\*(C'\fR and expect an array reference of lines
of \s-1CSS.\s0 See Writing Output Filters for
details on filters.
.PP
\fIoutput_metadata\fR
.IX Subsection "output_metadata"
.PP
.Vb 1
\&  $notifier\->output_metadata($file_handle);
.Ve
.PP
This method outputs a definition list containing the meta data of the commit,
including the revision number, author (user), and date of the revision. If the
\&\f(CW\*(C`revision_url\*(C'\fR attribute has been set, then the appropriate \s-1URL\s0 for the
revision will be used to turn the revision number into a link.
.PP
If there are any \f(CW\*(C`log_message\*(C'\fR filters, this method will do no \s-1HTML\s0
formatting, but redispatch to
SVN::Notify::output_metadata. See Writing
Output Filters for details on filters.
.PP
\fIoutput_log_message\fR
.IX Subsection "output_log_message"
.PP
.Vb 1
\&  $notifier\->output_log_message($file_handle);
.Ve
.PP
Outputs the commit log message in \f(CW\*(C`<pre>\*(C'\fR tags, and the label \*(L"Log
Message\*(R" in \f(CW\*(C`<h3>\*(C'\fR tags. If the \f(CW\*(C`bugzilla_url\*(C'\fR attribute is set, then
any strings like \*(L"Bug 2\*(R" or \*(L"bug # 567\*(R" will be turned into links.
.PP
If there are any \f(CW\*(C`log_message\*(C'\fR filters, the filters will be assumed to escape
the \s-1HTML,\s0 create inline links, and link ticket URLs. Otherwise, this method
will do those things. See Writing Output Filters for details on filters.
.PP
\fIoutput_file_lists\fR
.IX Subsection "output_file_lists"
.PP
.Vb 1
\&  $notifier\->output_log_message($file_handle);
.Ve
.PP
Outputs the lists of modified, added, deleted, files, as well as the list of
files for which properties were changed as unordered lists. The labels used
for each group are pulled in from the \f(CW\*(C`file_label_map()\*(C'\fR class method and
output in \f(CW\*(C`<h3>\*(C'\fR tags.
.PP
If there are any \f(CW\*(C`file_lists\*(C'\fR filters, this method will do no \s-1HTML\s0
formatting, but redispatch to
SVN::Notify::output_file_lists. See
Writing Output Filters for details on
filters.
.PP
\fIend_body\fR
.IX Subsection "end_body"
.PP
.Vb 1
\&  $notifier\->end_body($file_handle);
.Ve
.PP
Closes out the body of the email by outputting the closing \f(CW\*(C`</body>\*(C'\fR and
\&\f(CW\*(C`</html>\*(C'\fR tags. Designed to be called when the body of the message is
complete, and before any call to \f(CW\*(C`output_attached_diff()\*(C'\fR.
.PP
If the \f(CW\*(C`footer\*(C'\fR attribute is set, \f(CW\*(C`end_body()\*(C'\fR outputs it between
\&\f(CW\*(C`<div>\*(C'\fR tags with the \s-1ID\s0 \*(L"footer\*(R". Furthermore, if the footer happens to
end with the character \*(L"<\*(R", \f(CW\*(C`end_body()\*(C'\fR assumes that it contains valid
\&\s-1HTML\s0 and therefore will not escape it.
.PP
All of the \s-1HTML\s0 will be passed to any \*(L"end_body\*(R" output filters. See Writing
Output Filters for details on filters.
.PP
\fIoutput_diff\fR
.IX Subsection "output_diff"
.PP
.Vb 1
\&  $notifier\->output_diff($out_file_handle, $diff_file_handle);
.Ve
.PP
Sends the output of \f(CW\*(C`svnlook diff\*(C'\fR to the specified file handle for inclusion
in the notification message. The diff is output between \f(CW\*(C`<pre>\*(C'\fR tags, and
Each line of the diff file is escaped by \f(CW\*(C`HTML::Entities::encode_entities()\*(C'\fR.
The diff data will be read from \f(CW$diff_file_handle\fR and printed to
\&\f(CW$out_file_handle\fR.
.PP
If there are any \f(CW\*(C`diff\*(C'\fR filters, this method will do no \s-1HTML\s0 formatting, but
redispatch to SVN::Notify::output_diff. See
Writing Output Filters for details on
filters.
.SS "Accessors"
.IX Subsection "Accessors"
In addition to those supported by SVN::Notify,
SVN::Notify::HTML supports the following accessors:
.PP
\fIlinkize\fR
.IX Subsection "linkize"
.PP
.Vb 2
\&  my $linkize = $notifier\->linkize;
\&  $notifier = $notifier\->linkize($linkize);
.Ve
.PP
Gets or sets the value of the \f(CW\*(C`linkize\*(C'\fR attribute.
.PP
\fIcss_url\fR
.IX Subsection "css_url"
.PP
.Vb 2
\&  my $css_url = $notifier\->css_url;
\&  $notifier = $notifier\->css_url($css_url);
.Ve
.PP
Gets or sets the value of the \f(CW\*(C`css_url\*(C'\fR attribute.
.SH "See Also"
.IX Header "See Also"
.IP "SVN::Notify" 4
.IX Item "SVN::Notify"
.SH "Author"
.IX Header "Author"
David E. Wheeler <david@justatheory.com>
.SH "Copyright and License"
.IX Header "Copyright and License"
Copyright (c) 2004\-2018 David E. Wheeler. Some Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.