From 17aed2496647ac3591c49188d0cebb212797dd33 Mon Sep 17 00:00:00 2001 From: Sam Ruby Date: Tue, 17 Oct 2006 09:57:38 -0400 Subject: [PATCH] Documentation updates --- README | 8 ++--- TODO | 5 --- docs/config.html | 51 ++++++++++++++++++---------- docs/docs.css | 21 ++++-------- docs/docs.js | 2 ++ docs/img/shadow.gif | Bin 4363 -> 0 bytes docs/img/shadow2.gif | Bin 4043 -> 0 bytes docs/index.html | 3 +- docs/installation.html | 66 +++++++++++++++++++++++++++++++++++++ docs/normalization.html | 5 +-- themes/asf/index.html.xslt | 2 +- 11 files changed, 119 insertions(+), 44 deletions(-) delete mode 100644 docs/img/shadow.gif delete mode 100644 docs/img/shadow2.gif create mode 100644 docs/installation.html diff --git a/README b/README index a1fb9e9..3014d89 100644 --- a/README +++ b/README @@ -9,11 +9,11 @@ also actively being maintained. It uses Mark Pilgrim's Universal Feed Parser to read from CDF, RDF, RSS and Atom feeds; Leonard Richardson's Beautiful Soup to correct markup issues; -and Tomas Styblo's templating engine to output static files in any -format you can dream up. +and either Tomas Styblo's templating engine Daniel Viellard's implementation +of XSLT to output static files in any format you can dream up. -To get started, check out the INSTALL file in this directory. If you have any -questions or comments, please don't hesitate to use the planet mailing list: +To get started, check out the documentation in the docs directory. If you have +any questions or comments, please don't hesitate to use the planet mailing list: http://lists.planetplanet.org/mailman/listinfo/devel diff --git a/TODO b/TODO index 62c6c1a..0350a25 100644 --- a/TODO +++ b/TODO @@ -1,11 +1,6 @@ TODO ==== - * Enable per-feed adjustments - - The goal is to better cope with feeds that don't have dates or ids or - consitently encode or escape things incorrectly. - * Expire feed history The feed cache doesn't currently expire old entries, so could get diff --git a/docs/config.html b/docs/config.html index 503f350..4b64564 100644 --- a/docs/config.html +++ b/docs/config.html @@ -27,6 +27,7 @@ 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
@@ -37,16 +38,35 @@ are either new or implemented differently by Venus.

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
+
output_dir
+
Directory to place output files
+ +
+
+ +
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
+
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
+ +
+
+
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 @@ -61,22 +81,19 @@ for this across all templates.
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
+
activity_threshold
+
If non-zero, all feeds which have not been updated in the indicated +number of days will be marked as inactive
+ +
+
+ +
log_level
+
One of DEBUG, INFO, WARNING, ERROR or CRITICAL
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
diff --git a/docs/docs.css b/docs/docs.css index c5a1baf..65b290c 100644 --- a/docs/docs.css +++ b/docs/docs.css @@ -12,21 +12,18 @@ a:link, a:visited { 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; + color: #934; text-decoration: none !important; - text-decoration: underline; border-bottom: 1px dotted #993344 !important; - border-bottom: 0; } code { - color: green; + background-color: #FFF; + color: #00F; font-size: large } @@ -42,14 +39,13 @@ h2 { clear: both; } -ul.outer > li { +ul, 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; } @@ -60,21 +56,18 @@ ul.outer > li { .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; + background-color: #FFF; + color: #F0F; text-decoration: none; } @@ -84,7 +77,7 @@ dl.compact { } dl.code > dt { - font-family: mono; + font-family: monospace; } dl.compact > dt { diff --git a/docs/docs.js b/docs/docs.js index 0b2a925..229b13c 100644 --- a/docs/docs.js +++ b/docs/docs.js @@ -1,6 +1,8 @@ window.onload=function() { var vindex = document.URL.lastIndexOf('venus/'); + if (vindex<0) vindex = document.URL.lastIndexOf('planet/'); var base = document.URL.substring(0,vindex+6); + if (vindex<0) vindex = '..'; var body = document.getElementsByTagName('body')[0]; var div = document.createElement('div'); diff --git a/docs/img/shadow.gif b/docs/img/shadow.gif deleted file mode 100644 index f1e6cb53bdc87aa155315f6ba282e3ccda0fc3f5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4363 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 diff --git a/docs/img/shadow2.gif b/docs/img/shadow2.gif deleted file mode 100644 index a0b9ed4bfc79c4954979ab7254305c400c9c43a1..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4043 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 IfQSh6KVhA$B>(^b diff --git a/docs/index.html b/docs/index.html index 7889335..b19d0c8 100644 --- a/docs/index.html +++ b/docs/index.html @@ -10,6 +10,7 @@

Table of Contents

    +
  • Getting started
  • Basic Features
    • -
  • Legal +
  • Credits and License
    • Authors
    • Contributors
      • diff --git a/docs/installation.html b/docs/installation.html new file mode 100644 index 0000000..42eff05 --- /dev/null +++ b/docs/installation.html @@ -0,0 +1,66 @@ + + + + + +Venus Installation + + +

      Installation

      +

      Venus has been tested on Linux, and Mac OSX, and Windows.

      + +

      You'll need at least Python 2.2 installed on your system, we recommend +Python 2.4 though as there may be bugs with the earlier libraries.

      + +

      Everything Pythonesque Planet need to provide basic operation should be +included in the distribution. Additionally:

      +
        +
      • Usage of XSLT requires either +xsltproc +or python-libxslt.
        • +
      • The current interface to filters written in non-templating languages +(e.g., python) uses the +subprocess +module which was introduced in Python 2.4.
        • +
      • Usage of FOAF as a reading list requires +librdf.
        • +
      + +

      Instructions

      + +
        +

      1. If you are reading this online, you will need to +download and extract the files into a folder somewhere. +You can place this wherever you like, ~/planet +and ~/venus are good +choices, but so's anywhere else you prefer.

        2. +

      2. This is very important: from within that directory, type the following +command:

        +
        python runtests.py
        +

        This should take anywhere from a one to ten seconds to execute. No network +connection is required, and the script cleans up after itself. If the +script completes with an "OK", you are good to go. Otherwise stopping here +and inquiring on the +mailing list + is a good idea as it can save you lots of frustration down the road.

        3. +

      3. Make a copy of one of the ini the files in the +examples subdirectory, +and put it wherever you like; I like to use the Planet's name (so +~/planet/debian), but it's really up to you.

        4. +

      4. Edit the config.ini file in this directory to taste, +it's pretty well documented so you shouldn't have any problems here. Pay +particular attention to the output_dir option, which should be +readable by your web server. If the directory you specify in your +cache_dir exists; make sure that it is empty.

        5. +

      5. Run it: python planet.py pathto/config.ini

        +

        You'll want to add this to cron, make sure you run it from the +right directory.

        6. +

      6. (Optional)

        +

        Tell us about it! We'd love to link to you on planetplanet.org :-)

        7. +

      7. (Optional)

        +

        Build your own themes, templates, or filters! And share!

        8. +
      + + diff --git a/docs/normalization.html b/docs/normalization.html index 6e27e2a..63455ea 100644 --- a/docs/normalization.html +++ b/docs/normalization.html @@ -51,12 +51,13 @@ in other areas in the feed too.

      knowledge of the semantics of HTML. Additionally, a large subset of MathML, as well as a -tiny profile of SVG is also supported.

      +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 +annotated examples. Among other things a wide variety of date formats are converted into RFC 3339 formatted dates.

      diff --git a/themes/asf/index.html.xslt b/themes/asf/index.html.xslt index dbd6246..fffdcd8 100644 --- a/themes/asf/index.html.xslt +++ b/themes/asf/index.html.xslt @@ -153,7 +153,7 @@ - +