theory
2008-02-23 16:49:35 -0700 (Sat, 23 Feb 2008)
4298
= Trac-Style Log Message Formatting =

This "commit" demonstrates how log messages look when they are written in [http://trac.edgewall.org/wiki/WikiFormatting Trac wiki syntax] and converted to HTML by `[http://search.cpan.org/perldoc?Text::Trac Text::Trac]` via the `[http://search.cpan.org/perldoc?SVN::Notify::Filter::Trac SVN::Notify::Filter::Trac]` filter. All of the various features of that syntax are demonstrated here.

I expect that there will soon be filters for [http://daringfireball.net/projects/markdown/ Markdown], [http://www.textism.com/tools/textile/ Textile], [http://search.cpan.org/perldoc?perlpod POD], and other formatting paradigms. Hopefully, most of the HTML generated by parsing those other syntaxes into HTML will look just as good, mainly because I'm not doing anything special: this is just plain 'ole HTML. But if I've missed something, do [https://rt.cpan.org/Ticket/Create.html?Queue=SVN-Notify let me know].

These three paragraphs, by the way, demostrate how paragraphs look.

== Type Styles ==

Here are the various typographic styles supported by the Trac format:

 * '''bold'''
 * ''italic''
 * '''''bold italic'''''
 * __underline__
 * `monospace`
 * ~~strike-through~~
 * ^superscript^ 
 * ,,subscript,,

== Headings ==

Trac supports three levels of headings:

= Heading =
== Subheading ==
=== Sub-Subheading ===

== Lists ==

Lists can be nested, of course:

 * Item 1
   * Item 1.1
      * Item 1.1.1
      * Item 1.1.2
      * Item 1.1.3
   * Item 1.2
 * Item 2

 1. Item 1
   a. Item 1.a
   a. Item 1.b
      i. Item 1.b.i
      i. Item 1.b.ii
 1. Item 2
 3. Item 3

== Definition Lists ==

I've styled definition lists so that the terms are followed by a colon (:), and the definitions preceded by a closing angle quotation mark (»).

 camel::
   One lump, or two?

 python::
   My hovercraft is full of eels.

 elephant::
   Um, I don't remember.

== Preformatted Text ==

Usually used for blocks of code and the like.

{{{
package SVN::Notify::Filter::Trac;

SVN::Notify->register_attributes( trac_url => 'trac-url=s' );

sub log_message {
    my ($notify, $lines) = @_;
    return $lines unless $notify->content_type eq 'text/html';
    my $trac = Text::Trac->new( trac_url => $notify->trac_url );
    return [ $trac->parse( join $/, @{ $lines } ) ];
}
}}}

== Blockquotes ==

Unlike the official Trac format (see ticket #6887 for the details), `[http://search.cpan.org/perldoc?Text::Trac Text::Trac]` 0.09 nicely includes multiple indented paragraphs in a single block:

  Ask not what your country can do for you. Ask what you can do for your country.
  
  —John F. Kennedy

== Discussion Citations ==

As of version 0.09 of `[http://search.cpan.org/perldoc?Text::Trac Text::Trac]`, citations are supported. These are the style of citation that's supposed to look kind of like email:

>>>> This is some deeply buried original text, in which the poster was going on and on, ad naseum. Make it stop!
>>> This is the reply to the ad naseum comment. This poster, too, went on and on, saying nothing useful, as you might expect. It's usenet, after all!
>> This is slightly more relevant, or a pile-on, as you might expect.
> The last quoted bit from someone else attempting to add a bit of sanity to the discussion.
This bit would be, of course, an application of [http://en.wikipedia.org/wiki/Godwin's_law Godwin's law]. ;-P

== Tables ==

I borrowed this example table, as well its style, from [http://fluidmind.org/test/css/tables.html Styling Tables with CSS].

||'''Browser'''||'''2000'''||'''2001'''||'''2002'''||'''2003'''||'''2004'''||
||MSIE 6.x||—||—||23||52||74||
||MSIE 5.x||45||72||64||39||18||
||MSIE 4.x||30||12||4||1||< 1||
||Netscape 6+/Mozilla||—||—||< 1||< 1||< 2||
||Netscape 4-||18||10||4||1||< 1||
||Opera||< 1||< 1||< 1||< 1||1||

== Links ==

 * External link: [http://search.cpan.org/dist/SVN-Notify/ SVN::Notify on CPAN]
 * Long wiki link: [wiki:TracProject Trac open source project]
 * Short wiki link: TracProject
 * Ticket: #1
 * Report: {1}
 * Changeset: r1

== Escaping Links and !WikiPageNames ==

This paragraph has what appears to be a !TracLink, because of the camel-casing of "TracLink", but it's not a link, is it?

== Horizontal Rules ==

This is exactly what you'd think it is:

----

And that's it!

