From 5966c45bce5dc2b3485541134ce96dbd9682b673 Mon Sep 17 00:00:00 2001 From: Sam Ruby Date: Mon, 16 Oct 2006 16:46:40 -0400 Subject: [PATCH] Initial pass at documentation --- docs/config.html | 116 +++++++++++++++++++++++++++++++++++++ docs/docs.css | 106 ++++++++++++++++++++++++++++++++++ docs/docs.js | 53 +++++++++++++++++ docs/filters.html | 61 ++++++++++++++++++++ docs/img/shadow.gif | Bin 0 -> 4363 bytes docs/img/shadow2.gif | Bin 0 -> 4043 bytes docs/img/shadowAlpha.png | Bin 0 -> 3403 bytes docs/index.html | 42 ++++++++++++++ docs/migration.html | 21 +++++++ docs/normalization.html | 87 ++++++++++++++++++++++++++++ docs/templates.html | 121 +++++++++++++++++++++++++++++++++++++++ 11 files changed, 607 insertions(+) create mode 100644 docs/config.html create mode 100644 docs/docs.css create mode 100644 docs/docs.js create mode 100644 docs/filters.html create mode 100644 docs/img/shadow.gif create mode 100644 docs/img/shadow2.gif create mode 100644 docs/img/shadowAlpha.png create mode 100644 docs/index.html create mode 100644 docs/migration.html create mode 100644 docs/normalization.html create mode 100644 docs/templates.html diff --git a/docs/config.html b/docs/config.html new file mode 100644 index 0000000..9370ee8 --- /dev/null +++ b/docs/config.html @@ -0,0 +1,116 @@ + + + + +Venus Configuration + + + +

Configuration

+

Configuration files are in ConfigParser format which basically means the same +format as INI files, i.e., they consist of a series of +[sections], in square brackets, with each section containing a +list of name:value pairs (or name=value pairs, if +you prefer).

+

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".

+

[planet]

+

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 template_files and theme.

+

Below is a complete list of predefined planet configuration parameters, +including ones not (yet) implemented by Venus and ones that +are either new or implemented differently by Venus.

+
+
+
name
+
Your planet's name
+
link
+
Link to the main page
+
owner_name
+
Your name
+
owner_email
+
Your e-mail address
+
cache_directory
+
Where cached feeds are stored
+
log_level
+
One of DEBUG, INFO, WARNING, ERROR or CRITICAL
+
output_theme
+
Directory containing a config.ini file which is merged +with this one. This is typically used to specify templating and bill of +material information.
+
output_dir
+
Directory to place output files
+
items_per_page
+
How many items to put on each page. 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.
+
days_per_page
+
How many complete days of posts to put on each page This is the absolute, hard limit (over the item limit)
+
date_format
+
strftime format for the default 'date' template variable
+
new_date_format
+
strftime format for the 'new_date' template variable only applies to htmltmpl templates
+
encoding
+
Output encoding for the file, Python 2.3+ users can use the special "xml" value to output ASCII with XML character references
+
locale
+
Locale to use for (e.g.) strings in dates, default is taken from your system
+
feed_timeout
+
Number of seconds to wait for any given feed
+
new_feed_items
+
Number of items to take from new feeds
+
activity_threshold
+
If non-zero, all feeds which have not been updated in the indicated +number of days will be marked as inactive
+
template_files
+
Space-separated list of output template files
+
template_directories
+
Space-separated list of directories in which template_files +can be found
+
bill_of_materials
+
Space-separated list of files to be copied as is directly from the template_directories to the output_dir
+
filters
+
Space-separated list of filters to apply to each entry
+
+
+ +

[DEFAULT]

+

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.

+ +

[subscription]

+

All sections other than planet, DEFAULT, or are +named in [planet]'s filters or +templatefiles parameters +are treated as subscriptions and typically take the form of a +URI.

+

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 name is defined.

+

The content_type parameter can be defined to indicate that +this subscription is a reading list, i.e., is an external list +of subscriptions. At the moment, two formats of reading lists are supported: +opml and foaf. In the future, support for formats +like xoxo could be added.

+

Normalization overrides can +also be defined here.

+ +

[template]

+

Sections which are listed in [planet] template_files are +processed as templates. With Planet 2.0, +it is possible to override parameters like items_per_page +on a per template basis, but at the current time Planet Venus doesn't +implement this.

+ +

[filter]

+

Sections which are listed in [planet] filters are +processed as filters.

+

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.

+ + diff --git a/docs/docs.css b/docs/docs.css new file mode 100644 index 0000000..c5a1baf --- /dev/null +++ b/docs/docs.css @@ -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; +} diff --git a/docs/docs.js b/docs/docs.js new file mode 100644 index 0000000..0b2a925 --- /dev/null +++ b/docs/docs.js @@ -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); +} diff --git a/docs/filters.html b/docs/filters.html new file mode 100644 index 0000000..7efdb88 --- /dev/null +++ b/docs/filters.html @@ -0,0 +1,61 @@ + + + + +Venus Filters + + +

Filters

+

Filters are simple Unix pipes. Input comes in stdin, +parameters come from the config file, and output goes to stdout. +Anything written to stderr is logged as an ERROR message. If no +stdout is produced, the entry is not written to the cache or +processed further.

+ +

Input to a filter is a aggressively +normalized 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.

+ +

You will find a small set of example filters in the filters directory. The coral cdn filter will change links +to images in the entry itself. The filters in the stripAd subdirectory will strip specific +types of advertisements that you may find in feeds.

+ +

The excerpt filter adds metadata (in +the form of a planet:excerpt element) to the feed itself. You +can see examples of how parameters are passed to this program in either +excerpt-images or +opml-top100.ini.

+ +

The xpath sifter is a variation of +the above, including or excluding feeds based on the presence (or absence) of +data specified by xpath +expressions.

+ +

Notes

+ + + + diff --git a/docs/img/shadow.gif b/docs/img/shadow.gif new file mode 100644 index 0000000000000000000000000000000000000000..f1e6cb53bdc87aa155315f6ba282e3ccda0fc3f5 GIT binary patch literal 4363 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 literal 0 HcmV?d00001 diff --git a/docs/img/shadow2.gif b/docs/img/shadow2.gif new file mode 100644 index 0000000000000000000000000000000000000000..a0b9ed4bfc79c4954979ab7254305c400c9c43a1 GIT binary patch literal 4043 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 IfQSh6KVhA$B>(^b literal 0 HcmV?d00001 diff --git a/docs/img/shadowAlpha.png b/docs/img/shadowAlpha.png new file mode 100644 index 0000000000000000000000000000000000000000..a2561df971728d988424100c74c817916eca1979 GIT binary patch literal 3403 zcmeAS@N?(olHy`uVBq!ia0y~yV738bR}L1Sh{z?w93Z7#;u=xnT$Gwvl9`{U5R#dj z$`F!Ks$i<%mYSqsWME*TU}$J%1Vly(x&~$j21QvmX+Ul4C7!;n>{pmr1x4l8+mz-4 zg*Xd5B8wRqxP?HN@zUM8KR`j2bVpxD28NCO+HqZdXMAQjaPeGm)a##I4DP>8^|Q}*osX?x zu(w4E^8SQ>2<4nWJ;;$Ch1?$dLgm)?6;Yr9_CdHMW*W(@x+ip*R06EH_T4pml(Y0_%+Z_b^VZki z+Ig-L)GH{z-FHJSJv;l^O{dMW8|Geryoiy(edpWebG3Q>oX-o7q}^hCpz*y@X6IS? ZpGWQ1{0Pup3+%oyc)I$ztaD0e0swh%>OlYi literal 0 HcmV?d00001 diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..c85f103 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,42 @@ + + + + +Venus Documentation + + +

Table of Contents

+ + + diff --git a/docs/migration.html b/docs/migration.html new file mode 100644 index 0000000..8c6405c --- /dev/null +++ b/docs/migration.html @@ -0,0 +1,21 @@ + + + + +Venus Migration + + +

Migration from Planet 2.0

+

The intent is that existing Planet 2.0 users should be able to reuse +their existing config.ini and .tmpl files, +but the reality is that users will need to be aware of the following:

+
    +
  • You will need to start over with a new cache directory as the format +of the cache has changed dramatically.
    • +
  • Existing .tmpl and .ini files should work, +though some configuration options (e.g., +days_per_page) have not yet been implemented
    • +
  • No testing has been done on Python 2.1, and it is presumed not to work.
    • +
+ + diff --git a/docs/normalization.html b/docs/normalization.html new file mode 100644 index 0000000..2f9a5f2 --- /dev/null +++ b/docs/normalization.html @@ -0,0 +1,87 @@ + + + + +Venus Normalization + + +

Normalization

+

Venus builds on, and extends, the Universal Feed Parser and BeautifulSoup 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.

+

Encoding

+

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 +character entity +references 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 +only two +encodings required to be supported by all conformant XML processors.

+

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 +moronic versions +of smart-quotes. In rare cases where individual characters can not be +converted to valid UTF-8 or into +characters allowed in XML 1.0 +documents, such characters will be replaced with the Unicode +Replacement character, with a title that describes the original character whenever possible.

+

In order to support the widest range of inputs, use of Python 2.3 or later, +as well as the installation of the python iconvcodec, is +recommended.

+

HTML

+

A number of different normalizations of HTML are performed. For starters, +the HTML is +sanitized, +meaning that HTML tags and attributes that could introduce javascript or +other security risks are removed.

+

Then, +relative +links are resolved within the HTML. This is also done for links +in other areas in the feed too.

+

Finally, unmatched tags are closed. This is done with a +knowledge of the semantics of HTML. Additionally, a +large +subset of MathML, as well as a +tiny profile of SVG is also supported.

+

Atom 1.0

+

The Universal Feed Parser also +normalizes the content of feeds. This involves a +large number of elements; the best place to start is to look at +annotated examples. Among other things a large number of +date formats +are converted into +RFC 3339 formatted dates.

+

If no ids are found in entries, attempts are made to synthesize one using (in order):

+ +

If no updated dates are found in an entry, or if the dates found +are in the future, the current time is substitued.

+

Overrides

+

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.

+
    +
  • ignore_in_feed 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 id or updated values can't be trusted.
    • +
  • title_type, summary_type, +content_type allow you to override the +type +attributes on these elements.
    • +
  • name_type does something similar for +author names
    • +
+ + diff --git a/docs/templates.html b/docs/templates.html new file mode 100644 index 0000000..8ccf572 --- /dev/null +++ b/docs/templates.html @@ -0,0 +1,121 @@ + + + + +Venus Templates + + +

Templates

+

Template names take the form +name.ext.type, where +name.ext identifies the name of the output file +to be created in the output_directory, and type +indicates which language processor to use for the template.

+

Like with filters, templates may be written +in a variety of languages and are based on the standard Unix pipe convention +of producing stdout from stdin, but in practice +two languages are used more than others:

+

htmltmpl

+

Many find htmltmpl +easier to get started with as you can take a simple example of your +output file, sprinkle in a few <TMPL_VAR>s and +<TMPL_LOOP>s and you are done. Eventually, however, +you may find that your template involves <TMPL_IF> +blocks inside of attribute values, and you may find the result difficult +to read and create correctly.

+

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:

+ +
+ + + + + + + + + + + + + + + + + + +
VARtypesource
authorStringauthor
author_nameStringauthor_detail.name
generatorStringgenerator
idStringid
iconStringicon
last_updated_822Rfc822updated_parsed
last_updated_isoRfc3399updated_parsed
last_updatedPlanetDateupdated_parsed
linkStringlink
logoStringlogo
rightsStringrights_detail.value
subtitleStringsubtitle_detail.value
titleStringtitle_detail.value
title_plainPlaintitle_detail.value
urlStringlinks[rel='self'].href
headers['location']
+
+ +

Note: when multiple sources are listed, the last one wins

+

In addition to these variables, Planet Venus makes available two +arrays, Channels and Items, with one entry +per subscription and per output entry respectively. The data values +within the Channels array exactly match the above list. +The data values within the Items array are as follows:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VARtypesource
authorStringauthor
author_emailStringauthor_detail.email
author_nameStringauthor_detail.name
author_uriStringauthor_detail.href
content_languageStringcontent[0].language
contentStringsummary_detail.value
content[0].value
datePlanetDatepublished_parsed
updated_parsed
date_822Rfc822published_parsed
updated_parsed
date_isoRfc3399published_parsed
updated_parsed
idStringid
linkStringlinks[rel='alternate'].href
new_channelStringid
new_dateNewDatepublished_parsed
updated_parsed
rightsStringrights_detail.value
title_languageStringtitle_detail.language
title_plainPlaintitle_detail.value
titleStringtitle_detail.value
summary_languageStringsummary_detail.language
updatedPlanetDateupdated_parsed
updated_822Rfc822updated_parsed
updated_isoRfc3399updated_parsed
publishedPlanetDatepublished_parsed
published_822Rfc822published_parsed
published_isoRfc3399published_parsed
+
+

Note: variables above which start with +new_ are only set if their values differ from the previous +Item.

+ +

xslt

+

XSLT 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.

+

But in any case, the XSLT support is easier to document as the +input is a highly normalized feed, +with a few extension elements.

+
    +
  • atom:feed will have the following child elements:
    • +
      +
    • A planet:source element per subscription, with the same child elements as atom:source, as well as +an additional child element in the planet namespace for each +configuration parameter that applies to +this subscription.
      • +
    • planet:format indicating the format and version of the source feed.
      • +
    • planet:bozo which is either true or false.
      • +
    +
  • atom:updated and atom:published will have +a planet:format attribute containing the referenced date +formatted according to the [planet] date_format specified +in the configuration
    • +
+ +