Initial pass at documentation
This commit is contained in:
Sam Ruby
parent
c684e112e6
commit
5966c45bce
116
docs/config.html
Normal file
116
docs/config.html
Normal file
@ -0,0 +1,116 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<script type="text/javascript" src="docs.js"></script>
|
||||
<link rel="stylesheet" type="text/css" href="docs.css"/>
|
||||
<title>Venus Configuration</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h2>Configuration</h2>
|
||||
<p>Configuration files are in <a href="http://docs.python.org/lib/module-
|
||||
ConfigParser.html">ConfigParser</a> format which basically means the same
|
||||
format as INI files, i.e., they consist of a series of
|
||||
<code>[sections]</code>, in square brackets, with each section containing a
|
||||
list of <code>name:value</code> pairs (or <code>name=value</code> pairs, if
|
||||
you prefer).</p>
|
||||
<p>You are welcome to place your entire configuration into one file.
|
||||
Alternately, you may factor out the templating into a "theme", and
|
||||
the list of subscriptions into one or more "reading lists".</p>
|
||||
<h3 id="planet"><code>[planet]</code></h3>
|
||||
<p>This is the only required section, which is a bit odd as none of the
|
||||
parameters listed below are required. Even so, you really do want to
|
||||
provide many of these, especially ones that identify your planet and
|
||||
either (or both) of <code>template_files</code> and <code>theme</code>.</p>
|
||||
<p>Below is a complete list of predefined planet configuration parameters,
|
||||
including <del>ones not (yet) implemented by Venus</del> and <ins>ones that
|
||||
are either new or implemented differently by Venus</ins>.</p>
|
||||
<blockquote>
|
||||
<dl class="compact code">
|
||||
<dt>name</dt>
|
||||
<dd>Your planet's name</dd>
|
||||
<dt>link</dt>
|
||||
<dd>Link to the main page</dd>
|
||||
<dt>owner_name</dt>
|
||||
<dd>Your name</dd>
|
||||
<dt>owner_email</dt>
|
||||
<dd>Your e-mail address</dd>
|
||||
<dt>cache_directory</dt>
|
||||
<dd>Where cached feeds are stored</dd>
|
||||
<dt>log_level</dt>
|
||||
<dd>One of <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code> or <code>CRITICAL</code></dd>
|
||||
<dt><ins>output_theme</ins></dt>
|
||||
<dd>Directory containing a <code>config.ini</code> file which is merged
|
||||
with this one. This is typically used to specify templating and bill of
|
||||
material information.</dd>
|
||||
<dt>output_dir</dt>
|
||||
<dd>Directory to place output files</dd>
|
||||
<dt>items_per_page</dt>
|
||||
<dd>How many items to put on each page. <ins>Whereas Planet 2.0 allows this to
|
||||
be overridden on a per template basis, Venus currently takes the maximum value
|
||||
for this across all templates.</ins></dd>
|
||||
<dt><del>days_per_page</del></dt>
|
||||
<dd>How many complete days of posts to put on each page This is the absolute, hard limit (over the item limit)</dd>
|
||||
<dt>date_format</dt>
|
||||
<dd><a href="http://docs.python.org/lib/module-time.html#l2h-2816">strftime</a> format for the default 'date' template variable</dd>
|
||||
<dt>new_date_format</dt>
|
||||
<dd><a href="http://docs.python.org/lib/module-time.html#l2h-2816">strftime</a> format for the 'new_date' template variable <ins>only applies to htmltmpl templates</ins></dd>
|
||||
<dt><del>encoding</del></dt>
|
||||
<dd>Output encoding for the file, Python 2.3+ users can use the special "xml" value to output ASCII with XML character references</dd>
|
||||
<dt><del>locale</del></dt>
|
||||
<dd>Locale to use for (e.g.) strings in dates, default is taken from your system</dd>
|
||||
<dt>feed_timeout</dt>
|
||||
<dd>Number of seconds to wait for any given feed</dd>
|
||||
<dt><del>new_feed_items</del></dt>
|
||||
<dd>Number of items to take from new feeds</dd>
|
||||
<dt>activity_threshold</dt>
|
||||
<dd>If non-zero, all feeds which have not been updated in the indicated
|
||||
number of days will be marked as inactive</dd>
|
||||
<dt>template_files</dt>
|
||||
<dd>Space-separated list of output template files</dd>
|
||||
<dt><ins>template_directories</ins></dt>
|
||||
<dd>Space-separated list of directories in which <code>template_files</code>
|
||||
can be found</dd>
|
||||
<dt><ins>bill_of_materials</ins></dt>
|
||||
<dd>Space-separated list of files to be copied as is directly from the <code>template_directories</code> to the <code>output_dir</code></dd>
|
||||
<dt><ins>filters</ins></dt>
|
||||
<dd>Space-separated list of filters to apply to each entry</dd>
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<h3 id="default"><code>[DEFAULT]</code></h3>
|
||||
<p>Values placed in this section are used as default values for all sections.
|
||||
While it is true that few values make sense in all sections; in most cases
|
||||
unused parameters cause few problems.</p>
|
||||
|
||||
<h3 id="subscription"><code>[</code><em>subscription</em><code>]</code></h3>
|
||||
<p>All sections other than <code>planet</code>, <code>DEFAULT</code>, or are
|
||||
named in <code>[planet]</code>'s <code>filters</code> or
|
||||
<code>templatefiles</code> parameters
|
||||
are treated as subscriptions and typically take the form of a
|
||||
<acronym title="Uniform Resource Identifier">URI</acronym>.</p>
|
||||
<p>Parameters placed in this section are passed to templates. While
|
||||
you are free to include as few or as many parameters as you like, most of
|
||||
the predefined themes presume that at least <code>name</code> is defined.</p>
|
||||
<p>The <code>content_type</code> parameter can be defined to indicate that
|
||||
this subscription is a <em>reading list</em>, i.e., is an external list
|
||||
of subscriptions. At the moment, two formats of reading lists are supported:
|
||||
<code>opml</code> and <code>foaf</code>. In the future, support for formats
|
||||
like <code>xoxo</code> could be added.</p>
|
||||
<p><a href="normalization.html#overrides">Normalization overrides</a> can
|
||||
also be defined here.</p>
|
||||
|
||||
<h3 id="template"><code>[</code><em>template</em><code>]</code></h3>
|
||||
<p>Sections which are listed in <code>[planet] template_files</code> are
|
||||
processed as <a href="templates.html">templates</a>. With Planet 2.0,
|
||||
it is possible to override parameters like <code>items_per_page</code>
|
||||
on a per template basis, but at the current time Planet Venus doesn't
|
||||
implement this.</p>
|
||||
|
||||
<h3 id="filter"><code>[</code><em>filter</em><code>]</code></h3>
|
||||
<p>Sections which are listed in <code>[planet] filters</code> are
|
||||
processed as <a href="filters.html">filters</a>.</p>
|
||||
<p>Parameters which are listed in this section are passed to the filter
|
||||
in a language specific manner. Given the way defaults work, filters
|
||||
should be prepared to ignore parameters that they didn't expect.</p>
|
||||
</body>
|
||||
</html>
|
||||
106
docs/docs.css
Normal file
106
docs/docs.css
Normal file
@ -0,0 +1,106 @@
|
||||
body {
|
||||
background-color: #fff;
|
||||
color: #333;
|
||||
font-family: 'Lucida Grande', Verdana, Geneva, Lucida, Helvetica, sans-serif;
|
||||
font-size: small;
|
||||
margin: 40px;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
a:link, a:visited {
|
||||
background-color: transparent;
|
||||
color: #333;
|
||||
text-decoration: none !important;
|
||||
border-bottom: 1px dotted #333 !important;
|
||||
text-decoration: underline;
|
||||
border-bottom: 0;
|
||||
}
|
||||
|
||||
a:hover {
|
||||
background-color: transparent;
|
||||
color: #993344;
|
||||
text-decoration: none !important;
|
||||
text-decoration: underline;
|
||||
border-bottom: 1px dotted #993344 !important;
|
||||
border-bottom: 0;
|
||||
}
|
||||
|
||||
code {
|
||||
color: green;
|
||||
font-size: large
|
||||
}
|
||||
|
||||
h1 {
|
||||
margin: 8px 0 10px 20px;
|
||||
padding: 0;
|
||||
font-variant: small-caps;
|
||||
letter-spacing: 0.1em;
|
||||
font-family: "Book Antiqua", Georgia, Palatino, Times, "Times New Roman", serif;
|
||||
}
|
||||
|
||||
h2 {
|
||||
clear: both;
|
||||
}
|
||||
|
||||
ul.outer > li {
|
||||
margin: 14px 0 10px 0;
|
||||
}
|
||||
|
||||
.z {
|
||||
float:left;
|
||||
background: url(img/shadowAlpha.png) no-repeat bottom right !important;
|
||||
background: url(img/shadow.gif) no-repeat bottom right;
|
||||
margin: -15px 0 20px -15px !important;
|
||||
}
|
||||
|
||||
.z p {
|
||||
margin: 14px 0 10px 15px !important;
|
||||
}
|
||||
|
||||
.z .sectionInner {
|
||||
width: 730px;
|
||||
background: none !important;
|
||||
background: url(img/shadow2.gif) no-repeat left top;
|
||||
padding: 0 !important;
|
||||
padding: 0 6px 6px 10;
|
||||
}
|
||||
|
||||
.z .sectionInner .sectionInner2 {
|
||||
background-color: #fff;
|
||||
border: 1px solid #a9a9a9;
|
||||
padding: 4px;
|
||||
margin: -6px 6px 6px -6px !important;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
ins {
|
||||
color: magenta;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
dl.compact {
|
||||
margin-bottom: 1em;
|
||||
margin-top: 1em;
|
||||
}
|
||||
|
||||
dl.code > dt {
|
||||
font-family: mono;
|
||||
}
|
||||
|
||||
dl.compact > dt {
|
||||
float: left;
|
||||
margin-bottom: 0;
|
||||
padding-right: 8px;
|
||||
margin-top: 0;
|
||||
list-style-type: none;
|
||||
}
|
||||
|
||||
dl.compact > dd {
|
||||
margin-bottom: 0;
|
||||
margin-top: 0;
|
||||
margin-left: 10em;
|
||||
}
|
||||
|
||||
th, td {
|
||||
font-size: small;
|
||||
}
|
||||
53
docs/docs.js
Normal file
53
docs/docs.js
Normal file
@ -0,0 +1,53 @@
|
||||
window.onload=function() {
|
||||
var vindex = document.URL.lastIndexOf('venus/');
|
||||
var base = document.URL.substring(0,vindex+6);
|
||||
|
||||
var body = document.getElementsByTagName('body')[0];
|
||||
var div = document.createElement('div');
|
||||
div.setAttribute('class','z');
|
||||
var h1 = document.createElement('h1');
|
||||
var span = document.createElement('span');
|
||||
span.appendChild(document.createTextNode('\u2640'));
|
||||
span.setAttribute('style','color: magenta');
|
||||
h1.appendChild(span);
|
||||
h1.appendChild(document.createTextNode(' Planet Venus'));
|
||||
|
||||
var inner2=document.createElement('div');
|
||||
inner2.setAttribute('class','sectionInner2');
|
||||
inner2.appendChild(h1);
|
||||
|
||||
var p = document.createElement('p');
|
||||
p.appendChild(document.createTextNode("Planet Venus is an awesome \u2018river of news\u2019 feed reader. It downloads news feeds published by web sites and aggregates their content together into a single combined feed, latest news first."));
|
||||
inner2.appendChild(p);
|
||||
|
||||
p = document.createElement('p');
|
||||
var a = document.createElement('a');
|
||||
a.setAttribute('href',base);
|
||||
a.appendChild(document.createTextNode('Download'));
|
||||
p.appendChild(a);
|
||||
p.appendChild(document.createTextNode(" \u00b7 "));
|
||||
a = document.createElement('a');
|
||||
a.setAttribute('href',base+'docs/');
|
||||
a.appendChild(document.createTextNode('Documentation'));
|
||||
p.appendChild(a);
|
||||
p.appendChild(document.createTextNode(" \u00b7 "));
|
||||
a = document.createElement('a');
|
||||
a.setAttribute('href',base+'tests/');
|
||||
a.appendChild(document.createTextNode('Unit tests'));
|
||||
p.appendChild(a);
|
||||
p.appendChild(document.createTextNode(" \u00b7 "));
|
||||
a = document.createElement('a');
|
||||
a.setAttribute('href','http://lists.planetplanet.org/mailman/listinfo/devel');
|
||||
a.appendChild(document.createTextNode('Mailing list'));
|
||||
p.appendChild(a);
|
||||
inner2.appendChild(p);
|
||||
|
||||
var inner1=document.createElement('div');
|
||||
inner1.setAttribute('class','sectionInner');
|
||||
inner1.setAttribute('id','inner1');
|
||||
inner1.appendChild(inner2);
|
||||
|
||||
div.appendChild(inner1);
|
||||
|
||||
body.insertBefore(div, body.firstChild);
|
||||
}
|
||||
61
docs/filters.html
Normal file
61
docs/filters.html
Normal file
@ -0,0 +1,61 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<script type="text/javascript" src="docs.js"></script>
|
||||
<link rel="stylesheet" type="text/css" href="docs.css"/>
|
||||
<title>Venus Filters</title>
|
||||
</head>
|
||||
<body>
|
||||
<h2>Filters</h2>
|
||||
<p>Filters are simple Unix pipes. Input comes in <code>stdin</code>,
|
||||
parameters come from the config file, and output goes to <code>stdout</code>.
|
||||
Anything written to <code>stderr</code> is logged as an ERROR message. If no
|
||||
<code>stdout</code> is produced, the entry is not written to the cache or
|
||||
processed further.</p>
|
||||
|
||||
<p>Input to a filter is a aggressively
|
||||
<a href="normalization.html">normalized</a> entry. For
|
||||
example, if a feed is RSS 1.0 with 10 items, the filter will be called ten
|
||||
times, each with a single Atom 1.0 entry, with all textConstructs
|
||||
expressed as XHTML, and everything encoded as UTF-8.</p>
|
||||
|
||||
<p>You will find a small set of example filters in the <a
|
||||
href="../filters">filters</a> directory. The <a
|
||||
href="../filters/coral_cdn_filter.py">coral cdn filter</a> will change links
|
||||
to images in the entry itself. The filters in the <a
|
||||
href="../filters/stripAd/">stripAd</a> subdirectory will strip specific
|
||||
types of advertisements that you may find in feeds.</p>
|
||||
|
||||
<p>The <a href="../filters/excerpt.py">excerpt</a> filter adds metadata (in
|
||||
the form of a <code>planet:excerpt</code> element) to the feed itself. You
|
||||
can see examples of how parameters are passed to this program in either
|
||||
<a href="../tests/data/filter/excerpt-images.ini">excerpt-images</a> or
|
||||
<a href="../examples/opml-top100.ini">opml-top100.ini</a>.</p>
|
||||
|
||||
<p>The <a href="../filters/xpath_sifter.py">xpath sifter</a> is a variation of
|
||||
the above, including or excluding feeds based on the presence (or absence) of
|
||||
data specified by <a href="http://www.w3.org/TR/xpath20/">xpath</a>
|
||||
expressions.</p>
|
||||
|
||||
<h3>Notes</h3>
|
||||
|
||||
<ul>
|
||||
|
||||
<li>The file extension of the filter is significant. <code>.py</code> invokes
|
||||
python. <code>.xslt</code> involkes xslt. <code>.sed</code> and
|
||||
<code>.tmpl</code> (a.k.a. htmltmp) are also options. Other languages, like
|
||||
perl or ruby or class/jar (java), aren't supported at the moment, but these
|
||||
would be easy to add.</li>
|
||||
|
||||
<li>Any filters listed in the <code>[planet]</code> section of your config.ini
|
||||
will be invoked on all feeds. Filters listed in individual
|
||||
<code>[feed]</code> sections will only be invoked on those feeds.</li>
|
||||
|
||||
<li>Filters are simply invoked in the order they are listed in the
|
||||
configuration file (think unix pipes). Planet wide filters are executed before
|
||||
feed specific filters.</li>
|
||||
|
||||
<li>Templates written using htmltmpl currently only have access to a fixed set
|
||||
of fields, whereas xslt templates have access to everything.</li>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
BIN
docs/img/shadow.gif
Normal file
BIN
docs/img/shadow.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.3 KiB |
BIN
docs/img/shadow2.gif
Normal file
BIN
docs/img/shadow2.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.9 KiB |
BIN
docs/img/shadowAlpha.png
Normal file
BIN
docs/img/shadowAlpha.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.3 KiB |
42
docs/index.html
Normal file
42
docs/index.html
Normal file
@ -0,0 +1,42 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<script type="text/javascript" src="docs.js"></script>
|
||||
<link rel="stylesheet" type="text/css" href="docs.css"/>
|
||||
<title>Venus Documentation</title>
|
||||
</head>
|
||||
<body>
|
||||
<h2>Table of Contents</h2>
|
||||
<ul class="outer">
|
||||
<li>Basic Features</li>
|
||||
<ul>
|
||||
<li><a href="config.html">Configuration</a></li>
|
||||
<li><a href="templates.html">Templates</a></li>
|
||||
</ul>
|
||||
<li>Advanced Features</li>
|
||||
<ul>
|
||||
<li><a href="venus.svg">Architecture</a></li>
|
||||
<li><a href="normalization.html">Normalization</a></li>
|
||||
<li><a href="filters.html">Filters</a></li>
|
||||
</ul>
|
||||
<li>Other</li>
|
||||
<ul>
|
||||
<li><a href="migration.html">Migration from Planet 2.0</a></li>
|
||||
</ul>
|
||||
<li>Reference</li>
|
||||
<ul>
|
||||
<li><a href="http://www.planetplanet.org/">Planet</a></li>
|
||||
<li><a href="http://feedparser.org/docs/">Universal Feed Parser</a></li>
|
||||
<li><a href="http://www.crummy.com/software/BeautifulSoup/">Beautiful Soup</a></li>
|
||||
<li><a href="http://htmltmpl.sourceforge.net/">htmltmpl</a></li>
|
||||
<li><a href="http://www.w3.org/TR/xslt">XSLT</a></li>
|
||||
<li><a href="http://www.gnu.org/software/sed/manual/html_mono/sed.html">sed</a></li>
|
||||
</ul>
|
||||
<li>Legal</li>
|
||||
<ul>
|
||||
<li><a href="../AUTHORS">Authors</a></li>
|
||||
<li><a href="../THANKS">Contributors</a></li>
|
||||
<li><a href="../LICENCE">License</a></li>
|
||||
</ul>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
21
docs/migration.html
Normal file
21
docs/migration.html
Normal file
@ -0,0 +1,21 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<script type="text/javascript" src="docs.js"></script>
|
||||
<link rel="stylesheet" type="text/css" href="docs.css"/>
|
||||
<title>Venus Migration</title>
|
||||
</head>
|
||||
<body>
|
||||
<h2>Migration from Planet 2.0</h2>
|
||||
<p>The intent is that existing Planet 2.0 users should be able to reuse
|
||||
their existing <code>config.ini</code> and <code>.tmpl</code> files,
|
||||
but the reality is that users will need to be aware of the following:</p>
|
||||
<ul>
|
||||
<li>You will need to start over with a new cache directory as the format
|
||||
of the cache has changed dramatically.</li>
|
||||
<li>Existing <code>.tmpl</code> and <code>.ini</code> files should work,
|
||||
though some <a href="config.html">configuration</a> options (e.g.,
|
||||
<code>days_per_page</code>) have not yet been implemented</li>
|
||||
<li>No testing has been done on Python 2.1, and it is presumed not to work.</li>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
87
docs/normalization.html
Normal file
87
docs/normalization.html
Normal file
@ -0,0 +1,87 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<script type="text/javascript" src="docs.js"></script>
|
||||
<link rel="stylesheet" type="text/css" href="docs.css"/>
|
||||
<title>Venus Normalization</title>
|
||||
</head>
|
||||
<body>
|
||||
<h2>Normalization</h2>
|
||||
<p>Venus builds on, and extends, the <a
|
||||
href="http://www.feedparser.org/">Universal Feed Parser</a> and <a
|
||||
href="http://www.crummy.com/software/BeautifulSoup/">BeautifulSoup</a> to
|
||||
convert all feeds into Atom 1.0, with well formed XHTML, and encoded as utf-8,
|
||||
meaning that you don't have to worry about funky feeds, tag soup, or character
|
||||
encoding.</p>
|
||||
<h3>Encoding</h3>
|
||||
<p>Input data in feeds may be enocded in a variety of formats, most commonly
|
||||
ASCII, ISO-8859-1, WIN-1252, AND UTF-8. Additionally, many feeds make use of
|
||||
the wide range of
|
||||
<a href="http://www.w3.org/TR/html401/sgml/entities.html">character entity
|
||||
references</a> provided by HTML. Each is converted to UTF-8, an encoding
|
||||
which is a proper superset of ASCII, supports the entire range of Unicode
|
||||
characters, and is one of
|
||||
<a href="http://www.w3.org/TR/2006/REC-xml-20060816/#charsets">only two</a>
|
||||
encodings required to be supported by all conformant XML processors.</p>
|
||||
<p>Encoding problems are one of the more common feed errors, and every
|
||||
attempt is made to correct common errors, such as the inclusion of
|
||||
the so-called
|
||||
<a href="http://www.fourmilab.ch/webtools/demoroniser/">moronic</a> versions
|
||||
of smart-quotes. In rare cases where individual characters can not be
|
||||
converted to valid UTF-8 or into
|
||||
<a href="http://www.w3.org/TR/xml/#charsets">characters allowed in XML 1.0
|
||||
documents</a>, such characters will be replaced with the Unicode
|
||||
<a href="http://www.fileformat.info/info/unicode/char/fffd/index.htm">Replacement character</a>, with a title that describes the original character whenever possible.</p>
|
||||
<p>In order to support the widest range of inputs, use of Python 2.3 or later,
|
||||
as well as the installation of the python <code>iconvcodec</code>, is
|
||||
recommended.</p>
|
||||
<h3>HTML</h3>
|
||||
<p>A number of different normalizations of HTML are performed. For starters,
|
||||
the HTML is
|
||||
<a href="http://www.feedparser.org/docs/html-sanitization.html">sanitized</a>,
|
||||
meaning that HTML tags and attributes that could introduce javascript or
|
||||
other security risks are removed.</p>
|
||||
<p>Then,
|
||||
<a href="http://www.feedparser.org/docs/resolving-relative-links.html">relative
|
||||
links are resolved</a> within the HTML. This is also done for links
|
||||
in other areas in the feed too.</p>
|
||||
<p>Finally, unmatched tags are closed. This is done with a
|
||||
<a href="http://www.crummy.com/software/BeautifulSoup/documentation.html#Parsing%20HTML">knowledge of the semantics of HTML</a>. Additionally, a
|
||||
<a href="http://golem.ph.utexas.edu/~distler/blog/archives/000165.html#sanitizespec">large
|
||||
subset of MathML</a>, as well as a
|
||||
<a href="http://www.w3.org/TR/SVGMobile/">tiny profile of SVG is also supported.</a></p>
|
||||
<h3>Atom 1.0</h3>
|
||||
<p>The Universal Feed Parser also
|
||||
<a href="http://www.feedparser.org/docs/content-normalization.html">normalizes the content of feeds</a>. This involves a
|
||||
<a href="http://www.feedparser.org/docs/reference.html">large number of elements</a>; the best place to start is to look at
|
||||
<a href="http://www.feedparser.org/docs/annotated-examples.html">annotated examples</a>. Among other things a large number of
|
||||
<a href="http://www.feedparser.org/docs/date-parsing.html">date formats</a>
|
||||
are converted into
|
||||
<a href="http://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a> formatted dates.</p>
|
||||
<p>If no <a href="http://www.feedparser.org/docs/reference-entry-id.html">ids</a> are found in entries, attempts are made to synthesize one using (in order):</p>
|
||||
<ul>
|
||||
<li><a href="http://www.feedparser.org/docs/reference-entry-link.html">link</a></li>
|
||||
<li><a href="http://www.feedparser.org/docs/reference-entry-title.html">title</a></li>
|
||||
<li><a href="http://www.feedparser.org/docs/reference-entry-summary.html">summary</a></li>
|
||||
<li><a href="http://www.feedparser.org/docs/reference-entry-content.html">content</a></li>
|
||||
</ul>
|
||||
<p>If no <a href="http://www.feedparser.org/docs/reference-feed-
|
||||
updated.html">updated</a> dates are found in an entry, or if the dates found
|
||||
are in the future, the current time is substitued.</p>
|
||||
<h3 id="overrides">Overrides</h3>
|
||||
<p>All of the above describes what Venus does automatically, either directly
|
||||
or through its dependencies. There are a number of errors which can not
|
||||
be corrected automatically, and for these, there are configuration parameters
|
||||
that can be used to help.</p>
|
||||
<ul>
|
||||
<li><code>ignore_in_feed</code> allows you to list any number of elements
|
||||
which are to be ignored in feeds. This is often handy in the case of feeds
|
||||
where the <code>id</code> or <code>updated</code> values can't be trusted.</li>
|
||||
<li><code>title_type</code>, <code>summary_type</code>,
|
||||
<code>content_type</code> allow you to override the
|
||||
<a href="http://www.feedparser.org/docs/reference-entry-title_detail.html#reference.entry.title_detail.type"><code>type</code></a>
|
||||
attributes on these elements.</li>
|
||||
<li><code>name_type</code> does something similar for
|
||||
<a href="http://www.feedparser.org/docs/reference-entry-author_detail.html#reference.entry.author_detail.name">author names</a></li>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
121
docs/templates.html
Normal file
121
docs/templates.html
Normal file
@ -0,0 +1,121 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<script type="text/javascript" src="docs.js"></script>
|
||||
<link rel="stylesheet" type="text/css" href="docs.css"/>
|
||||
<title>Venus Templates</title>
|
||||
</head>
|
||||
<body>
|
||||
<h2>Templates</h2>
|
||||
<p>Template names take the form
|
||||
<em>name</em><code>.</code><em>ext</em><code>.</code><em>type</em>, where
|
||||
<em>name</em><code>.</code><em>ext</em> identifies the name of the output file
|
||||
to be created in the <code>output_directory</code>, and <em>type</em>
|
||||
indicates which language processor to use for the template.</p>
|
||||
<p>Like with <a href="filter.html">filters</a>, templates may be written
|
||||
in a variety of languages and are based on the standard Unix pipe convention
|
||||
of producing <code>stdout</code> from <code>stdin</code>, but in practice
|
||||
two languages are used more than others:</p>
|
||||
<h3>htmltmpl</h3>
|
||||
<p>Many find <a href="http://htmltmpl.sourceforge.net/">htmltmpl</a>
|
||||
easier to get started with as you can take a simple example of your
|
||||
output file, sprinkle in a few <code><TMPL_VAR></code>s and
|
||||
<code><TMPL_LOOP></code>s and you are done. Eventually, however,
|
||||
you may find that your template involves <code><TMPL_IF></code>
|
||||
blocks inside of attribute values, and you may find the result difficult
|
||||
to read and create correctly.</p>
|
||||
<p>It is also important to note that htmltmpl based templates do not
|
||||
have access to the full set of information available in the feed, just
|
||||
the following (rather substantial) subset:</p>
|
||||
|
||||
<blockquote>
|
||||
<table border="1" cellpadding="5" cellspacing="0">
|
||||
<thead><th>VAR</th><th>type</th><th>source</th></thead>
|
||||
<tr><td>author</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-author.html">author</a></td></tr>
|
||||
<tr><td>author_name</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-author_detail.html#reference.feed.author_detail.name">author_detail.name</a></td></tr>
|
||||
<tr><td>generator</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-generator.html">generator</a></td></tr>
|
||||
<tr><td>id</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-id.html">id</a></td></tr>
|
||||
<tr><td>icon</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-icon.html">icon</a></td></tr>
|
||||
<tr><td>last_updated_822</td><td>Rfc822</td><td><a href="http://feedparser.org/docs/reference-feed-icon.html">updated_parsed</a></td></tr>
|
||||
<tr><td>last_updated_iso</td><td>Rfc3399</td><td><a href="http://feedparser.org/docs/reference-feed-icon.html">updated_parsed</a></td></tr>
|
||||
<tr><td>last_updated</td><td>PlanetDate</td><td><a href="http://feedparser.org/docs/reference-feed-icon.html">updated_parsed</a></td></tr>
|
||||
<tr><td>link</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-link.html">link</a></td></tr>
|
||||
<tr><td>logo</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-logo.html">logo</a></td></tr>
|
||||
<tr><td>rights</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-rights_detail.html#reference.feed.rights_detail.value">rights_detail.value</a></td></tr>
|
||||
<tr><td>subtitle</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-subtitle_detail.html#reference.feed.subtitle_detail.value">subtitle_detail.value</a></td></tr>
|
||||
<tr><td>title</td><td>String</td><td><a href="http://feedparser.org/docs/reference-feed-title_detail.html#reference.feed.title_detail.value">title_detail.value</a></td></tr>
|
||||
<tr><td>title_plain</td><td>Plain</td><td><a href="http://feedparser.org/docs/reference-feed-title_detail.html#reference.feed.title_detail.value">title_detail.value</a></td></tr>
|
||||
<tr><td rowspan="2">url</td><td rowspan="2">String</td><td><a href="http://feedparser.org/docs/reference-feed-links.html#reference.feed.links.href">links[rel='self'].href</a></td></tr>
|
||||
<tr><td><a href="http://feedparser.org/docs/reference-headers.html">headers['location']</a></td></tr>
|
||||
</table>
|
||||
</blockquote>
|
||||
|
||||
<p>Note: when multiple sources are listed, the last one wins</p>
|
||||
<p>In addition to these variables, Planet Venus makes available two
|
||||
arrays, <code>Channels</code> and <code>Items</code>, with one entry
|
||||
per subscription and per output entry respectively. The data values
|
||||
within the <code>Channels</code> array exactly match the above list.
|
||||
The data values within the <code>Items</code> array are as follows:</p>
|
||||
|
||||
<blockquote>
|
||||
<table border="1" cellpadding="5" cellspacing="0">
|
||||
<thead><th>VAR</th><th>type</th><th>source</th></thead>
|
||||
<tr><td>author</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-author.html">author</a></td></tr>
|
||||
<tr><td>author_email</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-author_detail.html#reference.entry.author_detail.email">author_detail.email</a></td></tr>
|
||||
<tr><td>author_name</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-author_detail.html#reference.entry.author_detail.name">author_detail.name</a></td></tr>
|
||||
<tr><td>author_uri</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-author_detail.html#reference.entry.author_detail.href">author_detail.href</a></td></tr>
|
||||
<tr><td>content_language</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-content.html#reference.entry.content.language">content[0].language</a></td></tr>
|
||||
<tr><td rowspan="2">content</td><td rowspan="2">String</td><td><a href="http://feedparser.org/docs/reference-entry-summary_detail.html#reference.entry.summary_detail.value">summary_detail.value</a></td></tr>
|
||||
<tr><td><a href="http://feedparser.org/docs/reference-entry-content.html#reference.entry.content.value">content[0].value</a></td></tr>
|
||||
<tr><td rowspan="2">date</td><td rowspan="2">PlanetDate</td><td><a href="http://feedparser.org/docs/reference-entry-published_parsed.html">published_parsed</a></td></tr>
|
||||
<tr><td><a href="http://feedparser.org/docs/reference-entry-updated_parsed.html">updated_parsed</a></td></tr>
|
||||
<tr><td rowspan="2">date_822</td><td rowspan="2">Rfc822</td><td><a href="http://feedparser.org/docs/reference-entry-published_parsed.html">published_parsed</a></td></tr>
|
||||
<tr><td><a href="http://feedparser.org/docs/reference-entry-updated_parsed.html">updated_parsed</a></td></tr>
|
||||
<tr><td rowspan="2">date_iso</td><td rowspan="2">Rfc3399</td><td><a href="http://feedparser.org/docs/reference-entry-published_parsed.html">published_parsed</a></td></tr>
|
||||
<tr><td><a href="http://feedparser.org/docs/reference-entry-updated_parsed.html">updated_parsed</a></td></tr>
|
||||
<tr><td>id</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-id.html">id</a></td></tr>
|
||||
<tr><td>link</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-links.html#reference.entry.links.href">links[rel='alternate'].href</a></td></tr>
|
||||
<tr><td>new_channel</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-id.html">id</a></td></tr>
|
||||
<tr><td rowspan="2">new_date</td><td rowspan="2">NewDate</td><td><a href="http://feedparser.org/docs/reference-entry-published_parsed.html">published_parsed</a></td></tr>
|
||||
<tr><td><a href="http://feedparser.org/docs/reference-entry-updated_parsed.html">updated_parsed</a></td></tr>
|
||||
<tr><td>rights</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-rights_detail.html#reference.entry.rights_detail.value">rights_detail.value</a></td></tr>
|
||||
<tr><td>title_language</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-title_detail.html#reference.entry.title_detail.language">title_detail.language</a></td></tr>
|
||||
<tr><td>title_plain</td><td>Plain</td><td><a href="http://feedparser.org/docs/reference-entry-title_detail.html#reference.entry.title_detail.value">title_detail.value</a></td></tr>
|
||||
<tr><td>title</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-title_detail.html#reference.entry.title_detail.value">title_detail.value</a></td></tr>
|
||||
<tr><td>summary_language</td><td>String</td><td><a href="http://feedparser.org/docs/reference-entry-summary_detail.html#reference.entry.summary_detail.language">summary_detail.language</a></td></tr>
|
||||
<tr><td>updated</td><td>PlanetDate</td><td><a href="http://feedparser.org/docs/reference-entry-updated_parsed.html">updated_parsed</a></td></tr>
|
||||
<tr><td>updated_822</td><td>Rfc822</td><td><a href="http://feedparser.org/docs/reference-entry-updated_parsed.html">updated_parsed</a></td></tr>
|
||||
<tr><td>updated_iso</td><td>Rfc3399</td><td><a href="http://feedparser.org/docs/reference-entry-updated_parsed.html">updated_parsed</a></td></tr>
|
||||
<tr><td>published</td><td>PlanetDate</td><td><a href="http://feedparser.org/docs/reference-entry-published_parsed.html">published_parsed</a></td></tr>
|
||||
<tr><td>published_822</td><td>Rfc822</td><td><a href="http://feedparser.org/docs/reference-entry-published_parsed.html">published_parsed</a></td></tr>
|
||||
<tr><td>published_iso</td><td>Rfc3399</td><td><a href="http://feedparser.org/docs/reference-entry-published_parsed.html">published_parsed</a></td></tr>
|
||||
</table>
|
||||
</blockquote>
|
||||
<p>Note: variables above which start with
|
||||
<code>new_</code> are only set if their values differ from the previous
|
||||
Item.</p>
|
||||
|
||||
<h3>xslt</h3>
|
||||
<p><a href="http://www.w3.org/TR/xslt">XSLT</a> is a paradox: it actually
|
||||
makes some simple things easier to do than htmltmpl, and certainly can
|
||||
make more difficult things possible; but it is fair to say that many
|
||||
find XSLT less approachable than htmltmpl.</p>
|
||||
<p>But in any case, the XSLT support is easier to document as the
|
||||
input is a <a href="normalization.html">highly normalized</a> feed,
|
||||
with a few extension elements.</p>
|
||||
<ul>
|
||||
<li><code>atom:feed</code> will have the following child elements:</li>
|
||||
<ul>
|
||||
<li>A <code>planet:source</code> element per subscription, with the same child elements as <a href="http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.source"><code>atom:source</code></a>, as well as
|
||||
an additional child element in the planet namespace for each
|
||||
<a href="config.html#subscription">configuration parameter</a> that applies to
|
||||
this subscription.</li>
|
||||
<li><a href="http://www.feedparser.org/docs/reference-version.html"><code>planet:format</code></a> indicating the format and version of the source feed.</li>
|
||||
<li><a href="http://www.feedparser.org/docs/reference-bozo.html"><code>planet:bozo</code></a> which is either <code>true</code> or <code>false</code>.</li>
|
||||
</ul>
|
||||
<li><code>atom:updated</code> and <code>atom:published</code> will have
|
||||
a <code>planet:format</code> attribute containing the referenced date
|
||||
formatted according to the <code>[planet] date_format</code> specified
|
||||
in the configuration</li>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
x
Reference in New Issue
Block a user