view release on metacpan or  search on metacpan

bin/changelog2x  view on Meta::CPAN

child-element (which is also assigned a distinct class from the similar
elements used within the change-blocks). This stylesheet also includes some
diagnostic information as an XML/XHTML comment, but does not include it in
any visible elements.

=item dl

As with the previous two stylesheets, this produces an XHTML fragment for
inclusion in other documents. In this case, the outermost container element is
a C<< <dl> >>. The structure of this template's output is also somewhat
different: where the previous two rendered each release-block in the same
manner as the whole-document stylesheet, this stylesheet moves the
pseudo-heading line that contains the word "Version" followed by the release's
version number into the C<< <dt> >> element, and renders the remainder of the
release block in the C<< <dd> >> element. As with the others, the stylesheet
also includes some diagnostic information as an XML/XHTML comment, but does
not include it in any visible elements.

=item htmlnewest

This is a special variation of the C<div> stylesheet, that contains exactly
one release-block, that of the most-recent release (as sorted by date). The
outermost container is a C<< <div> >> element whose CSS class dfaults to the
same class used for the top-most container in the other templates.  However,
the user may specify a different CSS class with the C<class> stylesheet
parameter (see L</"Stylesheet Options">), if they wish to have this XHTML
fragment adhere to styles defined in a different CSS stylesheet. Diagnostic
information is included within a comment.

=item htmlversion

This is similar to the previous stylesheet, but only renders a single
C<< <span> >> tag containing the version-string of the newest release (as
sorted by date). The element is assigned a CSS class whose name fits within
the general naming scheme of other CSS classes used in these templates. As
with the previous, the class can be specified by the user via the C<class>
parameter.

=back

For all varieties of XHTML output, any elements in C<< <description> >> blocks
that belong to the namespace set aside by the W3C for XHTML
(C<http://www.w3.org/1999/xhtml>) are copied into the output verbatim, except
that a C<class> attribute is added to allow the user to include CSS style
information with the rest of the changelog-related CSS declarations. If the
element already has a C<class> attribute, it is copied over and the new class
name added at the end of the existing content.  The new class name is created
by appending the tag name to the string C<changelog-html->. Thus, an element
C<p> gets the class C<changelog-html-p>.  For example (assuming that the
C<xhtml> prefix has been declared to reference the XHTML namespace), the
following content:

    <xhtml:a href="http://perl.org">perl.org</xhtml:a>

yields this output:

    <a href="http://perl.org" class="changelog-html-a">perl.org</a>

The following content (which already has a C<class> attribute):

    <xhtml:span class="bold">Bold Span</xhtml:span>

yields:

    <span class="bold changelog-html-span">Bold Span</span>

No other foreign XML tags are copied over, at present. Allowance has been
made for future extension with information such as version-control system
specification, hosting information, Dublin Core metadata, etc.

=head3 Text templates

These templates produce plain-text output:

=over 4

=item text

This template produces output that comes very close to the de-facto standard
plain-text "Changelog" so familiar to open-source projects. After the project
name and in-set description (formatted like a document abstract, left-justified
and centered with regards to an 80-column page), the releases are presented
in the sorted order (possibly filtered by the C<versions> parameter).

Each release starts with a line like this:

    0.19    Monday October 20, 2008, 02:00:00 AM -0700

The version string is left-justified, followed by a single tab-stop character
and the formatted date (see the C<format> application option to control the
formatting of the dates).

Following the "header" for a release, each C<< <change> >> element is presented
(in order) in a format roughly like this:

            [ <transaction-revision number> ]
            * FILE-1 [ <revision number> [, <action label> ] ]
            ...
            Change <description> text

If the change-block contains a C<< <fileset> >> that itself has a C<revision>
attribute, the first line in the example above is produced, identifying this
as the revision identifier for the transaction as a whole (similar to how
systems like Subversion group commits of multiple files at once into a
"transaction"). Then, all the files listed in the change are enumerated as
a bulleted-list. For each file, if there is a C<revision> attribute on the
C<< <file> >> element, it is displayed after the path. If the file has an
C<action> attribute, a parenthetical action-label is further appended. Once
all files have been listed, the contents of the C<< <description> >> element
are displayed, indented 8 spaces and word-wrapped to a width of 70 columns.

At the end of the output, several lines are added with C<# > in the first
two columns (pseudo-comment notation) that identify the revision of the
XSLT stylesheet used, the date/time when it was processed, and the tools used
to do the processing.

=item textnewest

This template is similar to the C<htmlnewest> listed earlier, except that it
generates plain-text. It outputs the newest revision as a single block, using
the same format and layout as described above for C<text>. However, it does
not output the pseudo-comments at the end.

=item textversion