c19082b07623892e02709721d113806c81d1fc43
[uranus.git] / README
1 Uranus Ruby Planet Generator
2 ============================
3
4 Uranus generates a planet (aka blogroll) from a given set of RSS or
5 Atom feeds. It was written because the main software used for such
6 purposes, Planet (see http://www.planetplanet.org) has not seen any
7 development since years and fails on certain HTTPS URLs. Likewise, any
8 spinoffs planet caused are not developed anymore either as can
9 currently be seen impressively on the Debian planet (see
10 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=813313).
11
12 There is another alternative, Pluto, which was written by Gerald Bauer
13 (see https://github.com/feedreader/pluto). The software however has
14 basically no documentation, which makes it hard to use, and it has a
15 large number of dependencies, which seems overengineered for such a
16 simple purpose as collecting some feeds.
17
18 So, here is Uranus. It has exactly no dependencies other than Ruby
19 with its included standard library, thus it should work on any modern
20 Ruby installation without further work.
21
22 --- Installation ---
23
24 I don’t currently do releases of Uranus, but cloning the Git
25 repository is enough to get up and running. Once you installed the
26 Ruby interpreter (see https://www.ruby-lang.org or just use your
27 distribution's package manager), do this:
28
29 $ git clone git://git.guelkerdev.de/uranus.git
30
31 That’s it. You can continue with the configuration as outlined below.
32
33 --- Configuration ---
34
35 Uranus can currently generate exactly one planet per
36 installation. Most people will probaly not want to host multiple
37 planets, and even if that is required, one can just install another
38 copy of Uranus for the new planet. Maybe I extend Uranus later to
39 support multiple planets.
40
41 The main configuration is done in the config.yml file, which is a file
42 in YAML format, i.e. key-value pairs are separated by colons and you
43 need to be careful with leading whitespace, as it is significant. Just
44 edit the example configuration file to suit your needs.
45
46 The example configuration file explains all directives
47 available. Since there are no optional directives, you'll have to edit
48 them all anyway (or leave them at the default values).
49
50 Make sure the directories you configure actually exist. Uranus won't
51 create them for you and will fail if they are not there. This is
52 especially relevant if you for whatever reason want it to use a
53 temporary file system like the hierarchy under /tmp on many Linux
54 distributions.
55
56 --- Templates ---
57
58 Templates are the part where you will spent most time. When run,
59 Uranus copies all files inside the configured `template_dir' that do
60 /not/ end with `.erb' /unmodified/ into the directory configured via the
61 `output_dir' configuration option. This is useful for stylesheets,
62 images, and other static content.
63
64 All files inside the `template_dir' that /do/ end with `.erb' are
65 /template files/. These files are processed by Uranus before the
66 result is stored under the same file name with just `.erb' stripped
67 inside the `output_dir' directory.
68
69 The template files can contain whatever you want; the processor looks
70 for tags that look like <% ... %> and <%= ... %>, which makes them
71 look nice in HTML files. Everything between these two tags is executed
72 as (Ruby) code, though it is not required to know Ruby to modify
73 template files as the DSL provided makes things pretty simple. If you
74 do know Ruby, then you can of course make use of the full
75 possibilities this gives. The <% ... %> form only executes the
76 contained code, but does not insert anything into the document
77 written. <%= ... %> inserts the result of the operation at the point
78 this tag was encountered into the document.
79
80 The most important things about the Ruby syntax that you'll need:
81
82 1) Conditions:
83
84 Conditionals look like this:
85
86 if condition
87 # Code if true
88 else
89 # Code if false
90 end
91
92 2) For loop:
93
94 Iterate over a collection like this:
95
96 for item in collection
97 # Do something with `item'
98 end
99
100 3) Method call:
101
102 Use a colon to invoke a method, as in `obj.method'. Parentheses around
103 method arguments are optional.
104
105 The processor makes a number of special variables available to you;
106 these variables all start with an @ sign, and a reference is
107 below. See the provided index.html.erb file for an example of using
108 them. The most important, but also most complex variable is @entries,
109 which is a nested array of articles. The articles are grouped first by
110 day, then by feed so that when iterating the list you first get all
111 feeds that published something on a given day and one level deeper all
112 articles in that feed. This is particularyly useful when building a
113 web page, but if you don't need this nice structure, use @flat_entries
114 instead, which is an ordinary array consisting just of all articles in
115 descending order.
116
117 Both @entries and @flat_entries contain Entry objects, which will give
118 you information both about the article and the feed the article came
119 from. See below for the exact methods available.
120
121 --- Variable reference ---
122
123 The following variables are available in a template:
124
125 @generator [String]
126 This is the name and version of Uranus.
127
128 @planet_title [String]
129 The value of the configuration directive `planet_title'.
130
131 @planet_link [String]
132 The value of the configuration directive `planet_link'.
133
134 @owner_name [String]
135 The value of the configuration directive `owner_name'.
136
137 @owner_email [String]
138 The value of the configuration directive `owner_email'.
139
140 @entries [Nested array of Entry objects]
141 A grouped (nested) list of Entry objects. The
142 number of items on the lowest level of this array taken together is at
143 maximum the number of items configured via the `item_count' directive
144 in the configuration file.
145
146 @flat_entries [Array of Entry objects]
147 The same entries as in @entries, but without the nesting.
148
149 @feeds [Array of Feed objects]
150 A list of Feed objects each representing one subscribed feed.
151
152 --- Helper functions ---
153
154 The following helper functions are available:
155
156 escape_html( str ) -> String
157 This function escapes any special HTML characters, such as < or & and
158 returns the result, which can safely be included into an HTML DOM.
159
160 strftime( time, format ) -> String
161 Takes a Time object and applies a date(1)-like string to it, i.e.
162 %Y is replaced by the time's year, %d by the day, etc. Refer to
163 date(1) for the available % sequences.
164
165 --- Entry ---
166
167 Objects of this kind have two methods.
168
169 feed() -> Feed
170 This returns the feed an article is associated with.
171
172 article() -> article
173 This returns the actual article, with all information such as title,
174 link, and content.
175
176 --- Feed ---
177
178 On these the following methods are available:
179
180 url() -> String
181 The URL to the RSS or Atom feed subscribed to.
182
183 title() -> String
184 The title of the feed, as it was configured in the configuration file
185 for this feed.
186
187 human_url() -> String
188 The URL to the human-readable website of the feed susbcribed to, as
189 configured in the configuration file for this feed.
190
191 custom_key( key ) -> String
192 This method takes as argument a string key and returns one of the
193 additional entries for this feed in the configuration file.
194
195 --- Article ---
196
197 These have the methods url(), title(), author(), summary(), and
198 content(), which all return strings and are otherwise
199 self-explanatory. Additionally, date() returns the publishing date
200 (you can pass this into the strftime() helper).
201
202 Beware that author() and summary() may be nil, i.e. nothing. If you
203 insert nil into the template, nothing will be inserted.