App-Changelog2x
view release on metacpan or search on metacpan
bin/changelog2x view on Meta::CPAN
snippets that are conformant and should be easily included in larger
documents:
=over 4
=item html
This is the default stylesheet, which generates a complete XHTML document.
The C<< <body> >> tag and all its children will have a CSS classes associated
with them that indicate the hierarchy to some extent, and allow for
comprehensive styling via CSS.
The structure of the document is basically:
HEAD
headcontent parameter
<title>
CSS parameters
javascript parameter
BODY
bodycontent parameter
<h1> containing same text as <title>
<div> containing abstract (top-most <description> block)
ToC-style links
<hr>
<div> containing one or more release blocks:
<div> wrapping one release:
<span> containing subproject name (if release is from a subproject)
<span> containing version number
<span> containing release date
<p> containing release-level <description>, if present
<div> containing one or more change blocks:
<div> wrapping one change:
<span> containing transaction revision, if any
<ul> containing one or more files:
<li> containing one file, possibly with revision
and/or action information
<p> containing the change-level <description>
<hr>
<div> containing diagnostics/credits data
This doesn't include most of the viewer-visible content that doesn't come
directly from the input file (things like labels, etc.), except for the two
horizontal-rule elements, which contribute to the overall visual structure.
Every element referred to above (and some that are implied, but not explicitly
listed) is given a CSS class name. See L</"CSS Class Hierarchy"> for details
on the class names and where they are used.
=item div
This stylesheet renders a structure similar to the above, except that it only
produces the C<< <div >> element that contains the release blocks. Referring
to the structure above, this is the C<< <div> >> that immediately follows the
first C<< <hr> >>. An XML comment is included with some information on the
version of the stylesheet used, as well as tools. However, no visible content
is included (i.e., no "footer" as follows the second C<< <hr> >> in the layout
above).
=item ul
Like the previous stylesheet, this produces an XHTML fragment suitable for
inclusion in a larger document. However, it differs in that the outermost
container is not a C<< <div> >>, but instead a C<< <ul> >>. The containing
C<< <ul> >> is assigned a different CSS class than the C<< <ul> >> containers
used for change-blocks. Each release-block is rendered within one C<< <li> >>
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
( run in 0.706 second using v1.01-cache-2.11-cpan-b16cb0d3907 )