/usr/share/doc/olive/html/dotdir.html is in olive 1.3-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 | <html>
<head>
<title>User Manual: Dotdir</title>
<link href="./page.css" rel="stylesheet" type="text/css"/>
<link href="./olive.css" rel="stylesheet" type="text/css"/>
<link href="./manual.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<h1>5. The Dotdir</h1>
<p>
(Feeds) <a href="feeds.html">Prev</a>
| <a href="index.html">Index</a> | Next
</p>
<hr/>
<p><i>
None of the information in this section of the manual is needed to
use and enjoy Olive.
</i></p>
<p>
Olive keeps its configuration, raw data, and working data in a
directory named '<code>~/.olive</code>'. This section describes the
contents of that directory.
</p>
<h2 id="s10">5.1 The Config File</h2>
<p>
The configuration file is named '<code>olive.yaml</code>'. As its
extension indicates, it is
a <a href="http://yaml.org/">YAML</a>-formatted file. If you are
unfamiliar with YAML, you should read about it before manually
editing this file.
</p>
<h3 id="s11">5.1.1 Miscellaneous Configuration</h3>
<p>
</p>
<dl>
<dt>coe</dt>
<dd>
<b>Mnemonic:</b> Confirm On Exit<br/>
<b>Type:</b> Boolean<br/>
<b>Effect:</b> Controls whether Olive termination is immediate (0)
or confirmed (1). See <a href="options.html#s25">Section 3.2.5</a>.
</dd>
<dt>dst</dt>
<dd>
<b>Mnemonic:</b> Don't Show Titlebar<br/>
<b>Type:</b> Boolean<br/>
<b>Effect:</b> Controls whether the first line of the Olive window
is used as a titlebar (0) or to display live list data
(1). See <a href="options.html#s24">Section 3.2.4</a>.
</dd>
<dt>fr</dt>
<dd>
<b>Mnemonic:</b> First Run<br/>
<b>Type:</b> Boolean<br/>
<b>Effect:</b> Originally marked whether Olive had been run before
(1) or not (0). Now used to store the version number of Olive when
last run, paving the way for automatic upgrade procedures. Still
controls display of the first-run splash screen,
</dd>
<dt>gsp</dt>
<dd>
<b>Mnemonic:</b> Global Story Paging<br/>
<b>Type:</b> Boolean<br/>
<b>Effect:</b> Controls whether keybindings are enabled so as to
allow paging of the currently displayed story no matter where
focus is. 1 is "bind", 0 is "don't
bind". See <a href="options.html#s24">Section 3.2.4</a>.
</dd>
<dt>knf</dt>
<dd>
<b>Mnemonic:</b> Keep New Forever<br/>
<b>Type:</b> Boolean<br/>
<b>Effect:</b> Controls whether stories are removed from the
database as they fall off their feeds, or are removed only after
the user has read them. 1 is "keep", 0 is "let fall
off". See <a href="options.html#knf">Section 3.2.3</a>.
</dd>
<dt>loglevel</dt>
<dd>
<b>Mnemonic:</b> None<br/>
<b>Type:</b> Enum<br/>
<b>Effect:</b> Sets the minimum logging level for the error
log. Default is "warning". Meaningful values for Olive are
"warning", "info", and "debug" (in increasing order of
verbosity). For a full list of levels, see the
<a
href="http://search.cpan.org/search?query=log%3A%3Adispatch&mode=all">Log::Dispatch</a>
documentation.
</dd>
<dt>pw</dt>
<dd>
<b>Mnemonic:</b> Poll Wait<br/>
<b>Type:</b> Positive Integer<br/>
<b>Effect:</b> Sets the inital value, in minutes, of the delay
between automatic poll feeds. See
sections <a href="options.html#s30">3.3</a>
and <a href="feeds.html#s40">4.4</a> for more info.
</dd>
<dt>sls</dt>
<dd>
<b>Mnemonic:</b> Show List Status<br/>
<b>Type:</b> Boolean<br/>
<b>Effect:</b> Controls whether the status line will display story
list stats (1) or not (0). See <a href="options.html#s21">Section
3.2.1</a>.
</dd>
<dt>snu</dt>
<dd>
<b>Mnemonic:</b> Skip to Next Unread<br/>
<b>Type:</b> Boolean<br/>
<b>Effect:</b> Controls the behavior of the prev/next commands:
always select the story adjacent to the current selection (0) or
seek to the next unread story
(1). See <a href="options.html#s22">Section 3.2.2</a>.
</dd>
<dt>to</dt>
<dd>
<b>Mnemonic:</b> Time-Out<br/>
<b>Type:</b> Positive Integer<br/>
<b>Effect:</b> Sets the initial value for the network timeout of
the internal LWP::UserAgent object which fetches
feeds. See <a href="options.html#s40">Section 3.4</a>.
</dd>
<dt>www</dt>
<dd>
<b>Mnemonic:</b> ...<br/>
<b>Type:</b> String<br/>
<b>Effect:</b> Contains the command string which is used to launch
external browser sessions. See <a href="options.html#s50">Section
3.5</a>.
</dd>
</dl>
<h3 id="s12">5.1.2 Feeds</h3>
<p>
All information about subscribed feeds is stored in a HOHOH named
'<code>feeds</code>'. The full format is as follows:
</p>
<pre><code> feeds:
a_feed:
disp: Display Title From User
dormant: 0
feed: http://feed/url
force: 0
last: 1119248150
title: Actual Title From RSS Feed
ttl: 86400
</code></pre>
<p>
Where the '<code>a_feed</code>' stanza is repeated, with appropriate
changes, for each subscribed feed. The meanings of the individual
values is:
</p>
<ol>
<li><b>disp:</b> The feed's user-chosen display name; displayed in
the List Pane next to stories belonging to this feed.</li>
<li><b>dormant:</b> Boolean marking the feed dormant or not.</li>
<li><b>feed:</b> URL of the actual feed.</li>
<li><b>force:</b> Boolean marking the feed as force-fetchable or not.</li>
<li><b>last:</b>Value of <code>time()</code> as of the feed's last fetching.</li>
<li><b>title:</b> Actual title of the feed, taken from the feed data.</li>
<li><b>ttl:</b> The feed's time-to-live in seconds. Taken from the
feed or given a value of 3600s in the absence of a value from the
feed data.</li>
</ol>
<p>
See <a href="feeds.html">Section 4</a> for more information.
</p>
<h3 id="s13">5.1.3 Customizing Keybindings</h3>
<p>
There is no interface provided for changing keybindings within
Olive. Not all functions can be rebound. The ones which can are
altered via a HOH named '<code>keys</code>' in the config file. An
example which creates custom bindings for the functions normally
assigned to the '<code>[</code>' and '<code>]</code>' keys is:
</p>
<pre><code> keys:
next: n
prev: p
</code></pre>
<p>
Here is the list of bindable functions and their standard keys:
</p>
<table>
<tr><th>Function</th><th>Key</th><th>Description</th></tr>
<tr>
<td>prev</td>
<td><code>[</code></td>
<td>Go to previous story</td>
</tr>
<tr>
<td>next</td>
<td><code>]</code></td>
<td>Go to next story</td>
</tr>
<tr>
<td>mark</td>
<td><code>m</code></td>
<td>Mark story read</td>
</tr>
<tr>
<td>unmark</td>
<td><code>u</code></td>
<td>Mark story unread (unmark story)</td>
</tr>
<tr>
<td>star</td>
<td><code>s</code></td>
<td>Toggle story starred/unstarred</td>
</tr>
<tr>
<td>markall</td>
<td><code>M</code></td>
<td>Mark all stories read</td>
</tr>
<tr>
<td>unmarkall</td>
<td><code>U</code></td>
<td>Mark all stories unread (unmark all)</td>
</tr>
<tr>
<td>gpdn</td>
<td>'<code> </code>' (Space)</td>
<td>Global story paging: pagedown</td>
</tr>
<tr>
<td>gpup</td>
<td><code>-</code></td>
<td>Global story paging: pageup</td>
</tr>
<tr>
<td>focus</td>
<td><code>w</code></td>
<td>Shift focus between list/story panes</td>
</tr>
<tr>
<td>link</td>
<td><code>l</code></td>
<td>Execute defined link command with story URL</td>
</tr>
<tr>
<td>poll</td>
<td><code>p</code></td>
<td>Poll for updated feeds</td>
</tr>
<tr>
<td>force</td>
<td><code>P</code></td>
<td>Force-poll feeds marked as forced</td>
</tr>
<tr>
<td>filterf</td>
<td><code>F</code></td>
<td>Filter story list to show only stories from flagged feeds</td>
</tr>
<tr>
<td>filters</td>
<td><code>S</code></td>
<td>Filter story list to show only starred stories</td>
</tr>
</table>
<p>
Olive does not check for duplicate bindings or stomping on a
prebound key without providing a replacement. Also, be aware that
you may need to quote your choice of key if it is a YAML special
character (see the YAML spec for more information).
</p>
<h2 id="s20">5.2 The Error Log</h2>
<p>
Olive logs all warnings and fatal error messages (trapped or
otherwise) to a file named '<code>errors.log</code>'. On startup,
this file is copied to '<code>errors.log.1</code>' before being
overwritten, so there are logs for the past 2 runs available at any
time.
</p>
<p>
Error logs always start with a timestamp like this:
</p>
<pre><code> -- Starting up at 2005-05-22T16:58:11 --
</code></pre>
<p>
After that, there is no standard or predictable format for the
contents of the file.
</p>
<p>
Should Olive ever suddenly quit, or if you experience any problems
or weird behavior, please look at the logfile(s) and file a bug (as
per <a href="start.html#s50">Section 1.5</a>)
</p>
<h2 id="s30">5.3 The Story Database</h2>
<p>
Olive does not operate upon the raw feeds it fetches over the
network. It processes them after they are retrieved and stores
the relevant data in a <a href="http://sqlite.org/">SQLite</a>
database named '<code>story.db</code>'.
</p>
<p>
The schema of the database is as follows:
</p>
<pre><code> CREATE TABLE stories (id INTEGER PRIMARY KEY,
nick TEXT,
timestamp INT,
md5 TEXT,
read INT,
new INT,
link TEXT,
title TEXT,
desc TEXT);
</code></pre>
<h2 id="s40">5.4 The Feeds Directory</h2>
<p>
Downloaded feeds and the data needed to perform tests for HTTP 304
status are stored in a subdirectory called
'<code>feeds</code>'. Every feed you're subscribed to will have two
files there, a file named as a possibly modified form of the feed
nickname, and file with the same name as the first one, but with
".cache" appended.
</p>
<pre class='screen'> mdxi@fornax:~$ ls .olive/feeds/
atc cnn_money groklaw mdxi rjbs
atc.cache cnn_money.cache groklaw.cache mdxi.cache rjbs.cache
bbc_news gloria kate olive robert
bbc_news.cache gloria.cache kate.cache olive.cache robert.cache
</pre>
<p>
The files with no extension hold the last downloaded copy of that
feed. The <code>.cache</code> files hold HTTP header data needed to
check if the feed has been updated when it is polled next.
</p>
<p>
Files associated with a feed are unlinked when the feed is removed
from your feed list.
</p>
<hr/>
<p>
(Feeds) <a href="feeds.html">Prev</a>
| <a href="index.html">Index</a> | Next
</p>
<hr/>
<p>
$Id: dotdir.html 434 2007-02-07 05:04:51Z mdxi $
</p>
</body>
</html>
|