I’ve had a number of bug reports regarding issues with character encodings. Particularly for folks working in Europe and Asia, but really for anyone using multibyte characters in their source code and log messages (and we all do nowadays, don’t we?), it has been difficult to find the proper incantation to get SVN::Notify to convert data from and to their proper encodings. Using a patch from Toshikazu Kinkoh as a starting-point, and with a lot of reading and experimentation, as well as regular and patient tests on Toshikazu’s and Martin Lindhe’s production systems, I think I’ve finally got it nailed down.
Now you can use the --encoding (formerly --charset), --svn-encoding, and --diff-encoding options—as well as --language—to get SVN::Notify to do the right thing. As long as your Subversion server’s OS supports an appropriate locale, you should be golden (mine is old, with no UTF-8 locales :\). And if all else fails, you can still set the $LANG environment variable before executing svnnotify.
There is actually a fair bit to know about encodings to get it to work properly, but if you use UTF-8 throughout and your OS supports UTF-8 locales, you shouldn’t have to do anything. You might have to set --language in order to get it to use the proper locale. See the new documentation of the encoding support for all the details. And if you still have problems, please do let me know.
Much sexier is the addition of output filtering in SVN::Notify 2.70. I got pretty tired of getting feature requests for what are essentially formatting modifications, such as this one requesting support for KDE-style keyword support. I myself was using Trac wiki syntax in commit messages on a recent project and wanted to see them converted to HTML for messages output by SVN::Notify::HTML::ColorDiff.
So I finally sat down and gave some though on how to implement a simple plugin architecture for SVN::Notify. When I realized that it was generally just formatting that people wanted, it became simpler: I just needed a way to allow folks to write simple output filters. The solution I came up with was to just use Perl. Output filters are simply subroutines named for the kind of output they filter. They live in perl packages. That’s it.
For example, say that your developers write their commit log messages in Textile, and rather than receive them stuck inside <pre> tags, you’d like them converted to HTML. It’s simple. Just put this code in a Perl module file:
package SVN::Notify::Filter::Textile;
use Text::Textile ();
sub log_message {
my ($notifier, $lines) = @_;
return $lines unless $notify->content_type eq 'text/html';
return [ Text::Textile->new->process( join $/, @$lines ) ];
}
Put the file, SVN/Notify/Filter/Textile.pm somewhere in a Perl library directory. Then use the new --filter option to svnnotify to put it to work:
svnnotify -p "$1" -r "$2" --handler HTML::ColorDiff --filter Textile
Yep, that’s it! SVN::Notify will find the filter module, load it, register its filtering subroutine, and then call it at the appropriate time. Of course, there are a lot of things you can filter; consult the complete documentation for all of the details. But hopefully this gives you a flavor for how easy it is to write new filters for SVN::Notify. I’m hoping that all those folks who want featurs can now stop bugging me and writing their own filters to do the job, and uploading them to CPAN for all to share!
To get things started, I scratched my own itch, writing a Trac filter myself. The filter is almost as simple as the Textile example above, but I also spent quite a bit of time tweaking the CSS so that most of the Trac-generated HTML looks good. You can see an example right here. Thanks to a number of bug fixes in Text::Trac, as well as Trac-specific CSS added via a filter on CSS output, it works beautifully. If I’m feeling motivated in the next week or so, I’ll create a separate CPAN distribution with just a Markdown filter and upload it. That will create a nice distriution example for folks to copy to creat their own. Or maybe someone on the Lazy Web Will do it for me! Maybe you?
I wish I’d thought to do this from the beginning; it would have saved me from having to add so many features/cruft to SVN::Notify over the years. Here’s a quick list of the features that likely could have been implemented via filters instead of added to the core:
--user-domain: Combine the SVN username with a domain for the Fromheader.
--add-header: Add a header to the message.--reply-to: Add a specific header to the message.--subject-prefix:: Modify the message subject.--subject-cx: Add the commit context to the subject.--strip-cx-regex: More subject context modification.--no-first-line: Another subject filter.--max-sub-length: Yet another!--max-diff-length: A filter could truncate the diff, although this might be tricky with the HTML formatting.--author-url: Modify the metadata section to add a link to the author URL.--revision-url: Ditto for the revision URL.--ticket-map: Filter the log message for various ticketing system strings to convert to URLs. This also encompasses the old --rt-url, --bugzilla-url, --gnats-url, and --jira-url options.--header: Filter the beginning of the message.--footer: Filter the end of the message.--linkize: Filter the log message to convert URLs to links for HTML messages.--css-url: Filter the CSS to modify it, or filter the start of the HTML to add a link to an external CSS URL.--wrap-log: Reformat the log message for HTML.Yes, really! That’s about half the functionality right there. I’m glad that I won’t have to add any more like that; filters are a much better way to go.
So download it, install it, write some filters, get your multibyte characters output properly, and enjoy! And as usual, send me your bug reports, but implement your own improvements using filters!
]]>open() on Windows, i.e., open FH, "$cmd|" instead of open FH, "-|"; exec($cmd);. It’s silly, really, but it works. It really makes me wonder why -| and |- haven’t been emulated on Windows. Whatever.
’Course the other thing I realized, after I made this change and all the tests pass, was that there is no equivalent of sendmail on Windows. So I added the —smtp option, so that now email can be sent to an SMTP server rather than to a local sendmail. I tested it out, and it seems to work, but I’d be especially interested to hear from folks using wide characters in their repositories: do they get printed properly to Net::SMTP’s connection?
The whole list of changes in 2.57 (the output remains the same as in 2.56):
—smtp option to enable sending messages to an SMTP server
rather than to the local sendmail application. This is essential for
Windows support.—io-layer to the usage statement in svnnotify.Enjoy!
]]>The change I’m most pleased with in 2.56 is the addition of SVN::Notify::Alternative, based on a submission from Jukka Zitting. This new subclass allows you to actually combine a number of other subclasses into a single activity notification message. Why? Well, mainly because, though you might like to get HTML messages with colorized diffs, some mail clients might not care for the HTML. They would much prefer the plain text version.
SVN::Notify::Alternative allows you to have your cake and eat it too: send a single message with multipart/alternative sections for both HTML output and plain text. Plain text will always be used; to use HTML::ColorDiff with it, just do this:
svnnotify —repos-path "$1" —revision "$2" \ —to developers@example.com —handler Alternative \ —alternative HTML::ColorDiff —with-diff
This incantation will send an email with both the plain text and HTML::ColorDiff formats. If you look at it in Mail.app, you’ll see the nice colorized format, and if you look at it in pine, you’ll see the plain text.
For the curious, here are all of the changes since 2.50:
diff_handle()
method.diff_handle() in the output() method.output() to optionally suppress the
output of the email headers. This argument is used by the new
Alternative subclass.use_ok() tests that weren’t running at all.—with-diff has been specified.multipart/mixed content-type header generation from
output_headers() to output_content_type(), not only because this makes
more sense, but also because it makes attachments behave better when
using SVN::Notify::Alternative.io-layer option to specify an alternate IO layer. Will be
most useful for those with repositories containing text in multiple
encodings, where it should be set to raw.
—subject-cx option
so that it’s smarter about determining the longest common path.
Reported by Max Horn.to_regex_map hash, so as not
to mess with folks who might be passing it as a hash to more than one
call to new(). Reported by Darby Felton.meta http-equiv="content-type" tag to HTML output that
includes the character set to help some clients in the proper display
of the characters in an HTML email. I’m not sure if any clients
actually need this help, but it certainly can’t hurt!—css-url option to specify an alternate style sheet for
HTML emails. SVN::Notify::HTML’s own CSS is left in the email, as
well, so the specified style sheet can just override the default,
rather than have to style everything itself. Yes, it takes advantage
of the cascadingfeature of cascading style sheets! Based on a suggestion by Steve James.
—max-diff-length option. Patch from David Burley/SourceForge.header and footer attributes and command-line options to
specify text to be put at the head and foot of each message. For HTML
messages, the text will be escaped, unless it starts with <, in which case it will be assumed to be valid HTML and will therefore not be escaped. Either way, it will be output between
<div> tags with the
IDs headeror
footeras appropriate. Based on a patch from David Burley/SourceForge.
.exeto the name of the executable being searched for if
$^O eq 'MSWin32'.charset attribute. CPAN # 16050,
reported by Michael Zehrer.encode_entities() in
SVN::Notify::HTML and SVN::Notify::HTML::ColorDiff so that only '>'.
'<', '&', and '"' are escaped._find_exe() function that was attempting to modify
a constant variable. Patch from John Peacock._find_exe() function into the find_exe() class method,
since subclasses (such as SVN::Notify::Mirror) might want to use it.File::Spec->path to search for a validate sendmail or svnlook
when they’re not specified via their respective command-line options or
environment variables. Suggested by Andreas Koenig. Not that they
should probably be explicitly set anyway, as the $PATH environment
variable tends to be non-existent when running under Apache.Enjoy!
]]>—ticket-url and —ticket-regex
options to be used by those who want to match ticket identifers for
systems other than RT, Bugzilla, GNATS, and JIRA. Based on a patch
from Andrew O’Brien.use lib line put
into Makefile.PL by a prerelease version of Module::Build.'or
', since HTML::Entities can be configured differently on different systems.
—to-regex-map option works correctly when it is used
only once on the command-line.<span class="add"> and
<span class="rem">
to <ins> and <del> elements in
SVN::Notify::HTML::ColorDiff in order to make the markup more
semantic.—svnweb-url option. Based on a patch from
Ricardo Signes.Copiedfiles to HTML::ColorDiff so that they display properly.
—strip-cx-regex option to strip out parts of the
context from the subject. Useful for removing parts of the file names
you might not be interested in seeing in every commit message.—no-first-line option to omit the first sentence
or line of the log message from the subject. Useful in combination
with the —subject-cx option.Filesto
Pathsin hash returned by
file_label_map() since directories can be listed as well
as files.Enjoy!
]]>The biggest change is that I’ve moved the Request Tracker, Bugzilla, and JIRA support from SVN::Notify::HTML to SVN::Notify. I realized, after the release of 2.30, that it might be cool to add links to the text-only email message generated by SVN::Notify, too. So I’ve done that, including for ViewCVS links. Unlike in SVN::Notify::HTML, the links won’t be inline in the message (that doesn’t work too well in plain text, IMO), but will come in their own sections after the message. So you’ll get something like this (extreme example):
Log Message:
-----------
Let’s try a few links to other applications. First, we have
A Bugzilla Bug # 709. Then we have a JIRA key, TST-1608. And
finally, we have an RT link to Ticket # 4321.
Hey, we could add one to ViewCVS for a Subversion Revision
#606, too!
ViewCVS Links:
-------------
http://viewsvn.bricolage.cc/?rev=606&view=rev
Bugzilla Links:
--------------
http://bugzilla.mozilla.org/show_bug.cgi?id=709
RT Links:
--------
http://rt.cpan.org/NoAuth/Bugs.html?id=4321
JIRA Links:
----------
http://jira.atlassian.com/secure/ViewIssue.jspa?key=TST-1608
The nice thing is that, for many mail clients, these will be turned into clickable links. You’ll also notice that the text that creates the ViewCVS link is split over two lines. This is new in this release, and works for SVN::Notify::HTML, too. I made a few other tweaks to the regular expressions, as well. Here’s a complete list of changes:
register_attributes() but a subclass are
created in the subclass’ package instead of in SVN::Notify.JIRA-followed by a number. Reported by Garrett Rooney.
humbug 12don’t match.
rev 12as well as
revision 12.
RT-Ticket: 23as well as
Ticket 1234. Suggested by Jesse Vincent.
binary, and using the same CSS as is used for the
propsetclass.
delfileclass to properly wrap it in a border like the other files in the diff.
Modified,
Added,
Deleted, or
Property changes).
rt_url, bugzilla_url, and jira_url parameters from
SVN::Notify::HTML to SVN::Notify, where they are used to add URLs
to the text version of log messages.Enjoy!
]]>—rt-url, —bugzilla-url, and —jira-url options have an effect much like the parallel feature in CVSspam: pass in a string with the spot for the ID represented by %s, such as http://rt.cpan.org/NoAuth/Bugs.html?id=%s for RT or http://bugzilla.mozilla.org/show_bug.cgi?id=%s for Bugzilla. SVN::Notify::HTML will then look for the appropriate strings (such as Ticket # 1234for RT or
Bug # 4321for Bugzilla) and turn them into URLs.
This functionality has been extended to the old —viewcvs-url option, to. For the sake of consistency, it now also requires a URL of the same form (although if SVN::Notify doesn’t see %s in the string, it will append a default and emit a warning), and will be used to create links for strings like Revision 654
in the log message.
SVN::Notify::HTML has an additional new option, —linkize, that will force any email addresses or URLs it finds in the log message to be turned into links. Again, this works like it does for CVSspam; I’m grateful to Jeffrey Friedl’s Mastering Regular Expressions, Second Edition for the excellent regular expressions for matching URLs and email addresses.
All of this was made possible by moving the processing of options from svnnotify to SVN::Notify->get_options and adding a new class method, SVN::Notify->register_attributes. This second method allows Bricolage subclasses to easily add new attributes; register_attributes() will create accessor methods and add command-line option processing for each new attribute required by a subclass. Then, when you execute svnnotify —handler HTML, SVN::Notify->get_options processes the default options, loads the SVN::Notify::Handler subclass, and then processes any options specified by the subclass. The short story is that all of this is the detail-oriented way of saying that it is easier to subclass SVN::Notify and be able to automatically load the necessary options and attributes via the same executable, svnnotify.
This change was motivated not only by my desire to add the new features to SVN::Notify::HTML, but also by Autrijus’ new modules, SVN::Notify::Snapshot and SVN::Notify::Config. Thanks Autrijus!
I’ll try to get a nice example of all this functionality up in the next few days; if anyone else creates one first, send it to me! But in the meantime, enjoy!
]]>Grab the new version from CPAN now
]]>Update: And now I’ve released SVN::Notify 2.21 with a few minor fixes, including XHTML 1.1 compliance.
]]>The result SVN::Notify 2.10. To simplify the move to a subclass for the HTML notifications, I broke up the old send() method into a large number of other methods that affect various parts of the composition of the email, such as headers, starting the message, outputting the log message, the file list, and outputting or attaching the diff. Then I just overrode the few methods that need different behavior in the subclass, and it all worked!
I realized, as I worked on it, I also realized that I was following the same principals that Ovid has written about with regard to the use of if. I was able to remove quite a few of them by moving HTML to a subclass. Of course, there are still some to enable diffs to be either included in an email or attached, but I didn’t want to split things up too much, or I’d have a geometric explosion of subclasses!
The svnnotify script, in the meantime, remains largely unmodified. The only change is the deprecation of the —format option in favor of a new option, —handler. Use this option to specify what subclass of SVN::Notify should handle the notification. So far, there’s just one, —format HTML, but I’m sure that Autrijus will soon add —format Jabber, and I’d like to add —format HTML::ColorDiff, myself. I might have to move the processing of command-line arguments out of svnnotify and into SVN::Notify, instead, so that subclasses can add new options. We’ll see what comes up.
Other changes to SVN::Notify include:
send() method to execute() to better reflect
its generalized use as the method that executes actions in
response to Subversion activity.Enjoy!
]]>These are the major changes, but SVN::Notify also features a number of smaller improvements over its activitymail ancestor, including character set support, user domain support for the From
header, explicit specification of a From
header, properly escaped content when sending HTML-formatted notifications, and a maximum subject length configuration.
So what did it lose? Just a few things:
svnlook diff to generate a diff. Support for other diffs could be added in a future version, if people really need it.Not too much, eh? Let me know what you think, and send feedback!
]]>