ba1363d9f50972c5e034187675e151e4108e8bc6
[darcs-mirror-arbtt.git] / doc / arbtt.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook EBNF Module V1.1CR1//EN"
3                "http://www.oasis-open.org/docbook/xml/ebnf/1.1CR1/dbebnf.dtd">
4 <!--
5 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
6   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []>
7 -->
8 <article>
9 <articleinfo>
10   <title>arbtt – The Automatic Rule-Base Time Tracker</title>
11   <authorgroup>
12     <author>
13       <firstname>Joachim</firstname>
14       <surname>Breitner</surname>
15       <contrib>Main author of arbtt</contrib>
16       <email>mail@joachim-breitner.de</email>
17     </author>
18     <author id="sergey">
19       <firstname>Sergey</firstname>
20       <surname>Astanin</surname>
21       <contrib>Contributor</contrib>
22       <email>s.astanin@gmail.com</email>
23     </author>
24     <author id="martin">
25       <firstname>Martin</firstname>
26       <surname>Kiefel</surname>
27       <contrib>Contributor</contrib>
28       <email>mk@nopw.de</email>
29     </author>
30     <author id="muharem">
31       <firstname>Muharem</firstname>
32       <surname>Hrnjadovic</surname>
33       <contrib>Contributor</contrib>
34       <email>muharem@linux.com</email>
35     </author>
36     <author id="waldir">
37       <firstname>Waldir</firstname>
38       <surname>Pimenta</surname>
39       <contrib>Documentation writer</contrib>
40       <email>waldir@email.com</email>
41     </author>
42   </authorgroup>
43 </articleinfo>
44 <abstract>
45   <para>
46     arbtt is a background daemon that stores which windows are open, which one
47     has the focus and how long since your last action (and possibly more sources
48     later), and stores this. It is also a program that will, based on
49     expressive rules you specify, derive what you were doing, and what for.
50
51     <warning><para>The log file might contain very sensitive private data. Make sure
52
53     you understand the consequences of a full-time logger and be careful with this
54     data.</para></warning>
55   </para>
56 </abstract>
57
58 <sect1 id="installation">
59   <title>Installation</title>
60   <sect2>
61     <title>Building with <command>cabal-install</command></title>
62     <para>
63     arbtt comes in the form of a Cabalized<footnote><para>Cabal is the common software
64     packaging for Haskell programs and libraries, see <ulink
65     url="http://www.haskell.org/cabal/"/>.</para></footnote> package, and is
66     available from hackage. The easiest way of obtaining and installing arbtt is
67     via <command>cabal-install</command>. If you have
68     <command>cabal-install</command> available, just run
69     <screen>$ cabal install arbtt</screen>
70     to download, build and install arbtt.
71     </para>
72   </sect2>
73
74   <sect2>
75     <title>Building without <command>cabal-install</command></title>
76     <para>
77     You can fetch the latest arbtt source tarball from hackage, at
78     <ulink url="http://hackage.haskell.org/package/arbtt"/>. Extract the tarball
79     and run the following commands to build and install the arbtt binaries:
80     <screen>$ runhaskell Setup.hs configure
81 $ runhaskell Setup.hs build
82 $ runhaskell Setup.hs install</screen>
83     </para>
84   </sect2>
85
86   <sect2>
87     <title>Setting up the capture program</title>
88     <para>
89     To have arbtt gather useful data, you need to make sure that
90     <command>arbtt-capture</command> is started with your X session. If you use
91     GNOME or KDE, you can copy the file
92     <filename>arbtt-capture.desktop</filename> to
93     <filename>~/.config/autostart/</filename>. You might need to put the full
94     path to <command>arbtt-capture</command> in the Exec line there, if you did
95     not do a system wide installation.
96     </para>
97     <para>
98     By default, <command>arbtt-capture</command> will save one data sample per
99     minute. If you want to change that, you can pass <option>--sample-rate
100     <replaceable>RATE</replaceable></option> to <command>arbtt-capture</command>, where
101     <replaceable>RATE</replaceable> specifies the sample rate in seconds.
102     </para>
103   </sect2>
104
105   <sect2>
106     <title>Building the documentation</title>
107     <para>
108     Obviously, you can already read the documentation. If you still want to
109     build it yourself, enter the directory <filename>doc/</filename> and run
110     <command>make</command> for the documentation in HTML and PDF format. 
111     </para>
112   </sect2>
113
114
115   <sect2>
116     <title>Development version</title>
117     <para>
118       If you want to try the latest unreleased state of the code, or want to
119       contribute to arbtt, you can fetch the code with
120       <screen>darcs get <ulink url="http://darcs.nomeata.de/arbtt"/></screen>
121     </para>
122   </sect2>
123
124 </sect1>
125
126 <sect1 id="configuration">
127   <title>Configuring the arbtt categorizer (<command>arbtt-stats</command>)</title>
128   <para>
129   Once <command>arbtt-capture</command> is running, it will record data without
130   any configuration. And only to analyze the recorded data, one needs to
131   configure the categorizer. Everytime the categorizer
132   (<command>arbtt-stats</command>) runs, it applies categorization rules to all
133   recorded data and tags it accordingly.  Thus, if you improve your
134   categorization rules later, they will apply also to all previous data
135   samples!
136   </para>
137
138   <sect2>
139   <title>Configuration example</title>
140   <para>
141   The configuration file needs to be placed in
142   <filename>~/.arbtt/categorize.cfg</filename>. An
143   example is included in the source distribution, and it is reproduced here:
144   see <xref linkend="catex"/>.
145   It should be more enlightening than a formal description.
146   </para>
147
148   <example id="catex">
149   <title><filename>categorize.cfg</filename></title>
150     <programlisting><xi:include  href="../categorize.cfg"  parse="text"  
151       xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
152   </example>
153   </sect2>
154
155   <sect2>
156     <title>The semantics (informal)</title>
157     <para>
158       A data sample consists of the time of recording, the time passed since the
159       user’s last action, the name of the current workspace and the list of
160       windows. For each window this information is available:
161       <itemizedlist>
162         <listitem><simpara>the window title</simpara></listitem>
163         <listitem><simpara>the program name</simpara></listitem>
164         <listitem><simpara>whether the window was the active window</simpara></listitem>
165       </itemizedlist>
166       Based on this information and on the rules in
167       <filename>categorize.cfg</filename>, the categorizer
168       (<command>arbtt-stats</command>) assigns <emphasis>tags</emphasis> to
169       each sample.
170     </para>
171
172     <para>
173       A simple rule consists of a condition followed by an arrow
174       (<literal>==></literal>) and a tag expression
175       (<literal>tag</literal> keyword followed by tag name).
176       The rule ends with a coma (<literal>,</literal>).
177     </para>
178
179     <para>
180       The keyword <literal>tag</literal>, usually preceded with a condition,
181       assigns a <emphasis>tag</emphasis> to the sample; <literal>tag</literal>
182       keyword is followed by a tag name (any sequence of alphanumeric symbols,
183       underscores and hyphens). If tag name contains a colon
184       (<literal>:</literal>), the first part of the name before the colon, is
185       considered to be tag <emphasis>category</emphasis>.
186     </para>
187
188     <para>
189       For example, this rule
190       <programlisting>month $date == 1 ==> tag month:January,</programlisting>
191       if it succeeds, assigns a the tag <literal>January</literal> in the
192       category <literal>month</literal>.
193     </para>
194
195     <para>If the tag has a <emphasis>category</emphasis>, it will only be
196       assigned if no other tag of that category has been assigned. This means
197       that for each sample and each category, there can be at most only one tag
198       in that category. Tags can contain references to group matches in the
199       regular expressions used in conditions (<literal>$1</literal>,
200       <literal>$2</literal>)...). Tags can also reference some
201       variables such as window title (<literal>$current.title</literal>) or
202       program name (<literal>$current.program</literal>).
203     </para>
204
205     <para>
206       The variable <literal>$idle</literal> contains the idle time of the user,
207       measured in seconds. Usually, it is used to assign the tag
208       <literal>inactive</literal>, which is handled specially by
209       <command>arbtt-stats</command>, as can be seen in <xref linkend="catex"/>.
210     </para>
211
212     <para>
213       When applying the rules, the categorizer has a notion of
214       the <emphasis>window in scope</emphasis>, and the variables
215       <literal>$title</literal>, <literal>$program</literal> and
216       <literal>$active</literal> always refer to the window in scope.
217       By default, there is no window is in scope. Condition should be prefixed
218       with either <literal>current window</literal> or <literal>any
219       window</literal>, to define scope of these variables.
220     </para>
221
222     <para>
223       The name of the current desktop (or workspace) is available as
224       <literal>$desktop</literal>.
225     </para>
226
227     <para>
228       For <literal>current window</literal>, the currently active window is in
229       scope. If there is no such window, the condition is false.
230     </para>
231     
232     <para>
233       For <literal>any window</literal>, the condition is applied to each
234       window, in turn, and if any of the windows matches, the result is true. If
235       more than one window matches it is not defined from which match the
236       variables <literal>$1</literal>... are taken from (see more about regular
237       expressions below).
238     </para>
239
240     <para>
241       The variable <literal>$time</literal> refers to the time-of-day of the
242       sample (i.e. the time since 00:00 that day, local time), while
243       <literal>$sampleage</literal> refers to the
244       time span from when the sample was recored until now, the time of
245       evaluating the statistics. The latter variable is especially useful when
246       passed to the <option>--filter</option> option of
247       <command>arbtt-stats</command>. They can be compared with expressions 
248       like "hh:mm", for example
249       <programlisting>$time >=  8:00 &amp;&amp; $time &lt; 12:00 ==> tag time-of-day:morning</programlisting>
250     </para>
251
252     <para>
253       The variable <literal>$date</literal> referes to the date and time of the
254       recorded sample. It can be compared with date literals in the form
255       YYYY-MM-DD (which stand for midnight, so <programlisting>$date ==
256       2001-01-01</programlisting> will not do what you want, but
257       <programlisting>$date >= 2001-01-01 &amp;&amp; $date &lt;= 2001-01-02</programlisting>
258       would).  All dates are evaluated in local time.
259     </para>
260     <para>
261       Expression <literal>format $date</literal> evaluates to a string with
262       a date formatted according to ISO 8601, i.e. like "YYYY-MM-DD". The 19th
263       of March 2010 is formatted as "2010-03-19". Formatted date can be compared
264       to strings. Formatted dates may be useful to tag particular date ranges. But
265       also note that this is a rather expensive operation that can slow down your
266       data processing.
267     </para>
268     <para>
269       Expression <literal>month $date</literal> evaluates to an integer, from 1
270       to 12, corresponding to the month number. Expression <literal>year
271       $date</literal> evaluates to an integer which is a year number.
272       Expression <literal>day of month $date</literal> evaluates to an integer,
273       from 1 to 31, corresponding to the day of month.
274       Expression <literal>day of week $date</literal> evaluates to an integer,
275       from 1 to 7, corresponding to the day of week, Monday is 1, Sunday is 7.
276       These expressions can be compared to integers.
277     </para>
278
279     <para>
280       Expressions can be compared to literal values with <literal>==</literal>
281       (equal), <literal>/=</literal> (not equal), <literal>&lt;</literal>,
282       <literal>&lt;=</literal>, <literal>&gt;=</literal>,
283       <literal>&gt;</literal> operators. String expressions
284       (<literal>$program</literal>, <literal>$title</literal>) can be matched
285       against regular expressions with <literal>=~</literal> operator. With these
286       operatorions, the right hand side can be a comma-separated list of
287       literals enclosed in square brackets (<literal>[</literal>
288       <emphasis>...</emphasis>, <emphasis>...</emphasis>, <literal>]</literal>), which
289       succeeds if any of them succeeds.
290     </para>
291
292     <para>Regular expressions are written either between slashes
293        (<literal>/</literal> regular expression <literal>/</literal>),
294        or after a letter <literal>m</literal> followed by any symbol
295        (<literal>m</literal> <emphasis>c</emphasis> regular expression <emphasis>c</emphasis>, where <emphasis>c</emphasis> is any symbol).
296        The second appearance of that symbol ends the expression.
297        You can find both variants in <xref linkend="catex"/>.
298     </para>
299
300     <para>Complex conditions may be constructed from the simpler ones,
301       using Boolean AND (<literal>&amp;&amp;</literal>), OR
302       (<literal>||</literal>), and NOT (<literal>!</literal>) functions and
303       parentheses.
304     </para>
305
306   </sect2>
307
308   <sect2>
309     <title>The syntax</title>
310     <para>
311     <filename>categorize.cfg</filename> is a plain text file.
312     Whitespace is insignificant and Haskell-style comments are allowed.
313     A formal grammar is provided in <xref linkend="grammar"/>.
314     </para>
315
316     <figure id="grammar">
317         <title>The formal grammar of <filename>categorize.cfg</filename></title>
318         <productionset>
319           <production id="g-rules">
320             <lhs>Rules</lhs>
321             <rhs>
322               [ <nonterminal def="#g-aliasspec"/> ]
323               <nonterminal def="#g-rule"/> ( (<quote>,</quote>
324               <nonterminal def="#g-rule"/>)* | ( <quote>;</quote>
325               <nonterminal def="#g-rule"/>)* )
326             </rhs>
327           </production>
328
329           <production id="g-aliasspec">
330             <lhs>AliasSpec</lhs>
331             <rhs><quote>aliases</quote> <quote>(</quote> <nonterminal
332               def="#g-alias"/> (<quote>,</quote> <nonterminal def="#g-alias"/>)*
333               <quote>)</quote> </rhs>
334           </production>
335
336           <production id="g-alias">
337             <lhs>Alias</lhs>
338             <rhs>Literal <quote>-&gt;</quote> Literal</rhs>
339           </production>
340
341           <production id="g-rule">
342             <lhs>Rule</lhs>
343             <rhs><quote>{</quote> <nonterminal def="#g-rules"/>
344                  <quote>}</quote>
345             </rhs>
346             <rhs>
347               <nonterminal def="#g-cond"/> <quote>==&gt;</quote> 
348               <nonterminal def="#g-rule"/> | <quote>if</quote>
349               <nonterminal def="#g-cond"/> <quote>then</quote>
350               <nonterminal def="#g-rule"/> <quote>else</quote>
351               <nonterminal def="#g-rule"/>
352             </rhs>
353             <rhs>
354               <quote>tag</quote> <nonterminal def="#g-tag"/>
355             </rhs>
356           </production>
357
358           <production id="g-cond">
359             <lhs>Cond</lhs>
360             <rhs><quote>(</quote> <nonterminal def="#g-cond"/>
361                  <quote>)</quote>
362             </rhs>
363             <rhs><quote>!</quote> <nonterminal def="#g-cond"/> |
364                  <nonterminal def="#g-cond"/> <quote>&amp;&amp;</quote>
365                  <nonterminal def="#g-cond"/> |
366                  <nonterminal def="#g-cond"/> <quote>||</quote> <nonterminal
367                  def="#g-cond"/>
368             </rhs>
369             <rhs> <quote>$active</quote> </rhs>
370             <rhs> <nonterminal def="#g-string"/> <nonterminal def="#g-cmpop"/>
371                  <nonterminal def="#g-string"/> </rhs>
372             <rhs> <nonterminal def="#g-string"/> <nonterminal def="#g-cmpop"/>
373                  <quote>[</quote> <nonterminal def="#g-listofstring"/> 
374                  <quote>]</quote>
375                  </rhs> 
376             <rhs> <nonterminal def="#g-string"/> <quote>=~</quote>
377                  <nonterminal def="#g-regex"/></rhs>
378             <rhs> <nonterminal def="#g-string"/> <quote>=~</quote>
379                  <quote>[</quote> <nonterminal def="#g-listofregex"/> 
380                  <quote>]</quote>
381                  </rhs>
382             <rhs> <nonterminal def="#g-number"/> <nonterminal def="#g-cmpop"/>
383                  <nonterminal def="#g-number"/> </rhs>
384             <rhs> <nonterminal def="#g-timediff"/> <nonterminal def="#g-cmpop"/>
385                  <nonterminal def="#g-timediff"/> </rhs>
386             <rhs> <nonterminal def="#g-date"/> <nonterminal def="#g-cmpop"/>
387                  <nonterminal def="#g-date"/> </rhs>
388             <rhs> <quote>current window</quote> <nonterminal def="#g-cond"/> </rhs>
389             <rhs> <quote>any window</quote> <nonterminal def="#g-cond"/> </rhs>
390           </production>
391
392           <production id="g-string">
393             <lhs>String</lhs>
394             <rhs> <quote>$title</quote> </rhs>
395             <rhs> <quote>$program</quote> </rhs>
396             <rhs> <quote>$desktop</quote> </rhs>
397             <rhs> <quote>format</quote> <nonterminal def="#g-date" /> </rhs>
398             <rhs> <quote>"</quote> string literal <quote>"</quote> </rhs>
399           </production>
400
401           <production id="g-listofstring">
402             <lhs>ListOfString</lhs>
403             <rhs> <quote>"</quote> string literal <quote>"</quote> </rhs>
404             <rhs> <quote>"</quote> string literal <quote>"</quote> , <nonterminal def="#g-listofstring"/> </rhs>
405           </production>
406
407           <production id="g-number">
408             <lhs>Number</lhs>
409             <rhs> <quote>$idle</quote> </rhs>
410             <rhs> <quote>day of week</quote> <nonterminal def="#g-date" /> </rhs>
411             <rhs> <quote>day of month</quote> <nonterminal def="#g-date" /> </rhs>
412             <rhs> <quote>month</quote> <nonterminal def="#g-date" /> </rhs>
413             <rhs> <quote>year</quote> <nonterminal def="#g-date" /> </rhs>
414             <rhs> number literal </rhs>
415           </production>
416
417           <production id="g-date">
418             <lhs>Date</lhs>
419             <rhs> <quote>$date</quote> </rhs>
420             <!-- <rhs> <quote>$now</quote> </rhs> -->
421           </production>
422
423           <production id="g-timediff">
424             <lhs>TimeDiff</lhs>
425             <rhs> <quote>$time</quote> </rhs>
426             <rhs> <quote>$sampleage</quote> </rhs>
427             <!-- <rhs> <nonterminal def="#g-date"/> <quote>-</quote> <nonterminal def="#g-date"/></rhs> -->
428             <rhs>( Digit )* Digit <quote>:</quote> Digit Digit</rhs>
429           </production>
430
431           <production id="g-tag">
432             <lhs>Tag</lhs>
433             <rhs> [ Literal <quote>:</quote> ] Literal </rhs>
434           </production>
435
436           <production id="g-regex">
437             <lhs>RegEx</lhs>
438             <rhs>  <quote>/</quote> Literal <quote>/</quote> |
439               <quote>m</quote> <replaceable>c</replaceable> Literal
440               <replaceable>c</replaceable><lineannotation>Where
441               <replaceable>c</replaceable> can be any
442               character.</lineannotation> </rhs>
443           </production>
444
445           <production id="g-listofregex">
446             <lhs>ListOfRegex</lhs>
447             <rhs> <quote>"</quote> <nonterminal def="#g-regex"/> <quote>"</quote> </rhs>
448             <rhs> <quote>"</quote> <nonterminal def="#g-regex"/> <quote>"</quote> , <nonterminal def="#g-listofregex"/> </rhs>
449           </production>
450
451           <production id="g-cmpop">
452             <lhs>CmpOp</lhs>
453             <rhs><quote>&lt;=</quote> | <quote>&lt;</quote> | <quote>==</quote>
454             | <quote>&gt;</quote> | <quote>&gt;=</quote></rhs>
455           </production>
456
457         </productionset>
458       </figure>
459       <para>
460         A <literal>String</literal> refers to a double-quoted string of
461         characters, while a <literal>Literal</literal> is not quoted.
462         <nonterminal def="#g-tag">Tags</nonterminal> may only consist of
463         letters, dashes and underscores, or variable interpolations. A Tag maybe
464         be optionally prepended with a category, separated by a colon. The
465         category itself follows he same lexical rules as the tag. A variable
466         interpolation can be one of the following:
467         <variablelist>
468           <varlistentry>
469             <term><literal>$1</literal>, <literal>$2</literal>,...</term>
470             <listitem><simpara> will be replaced by the respective group in the last
471               successfully applied regular expression in the conditions enclosing the
472               current rule.
473             </simpara></listitem>
474           </varlistentry>
475           <varlistentry>
476             <term><literal>$current.title</literal></term>
477             <term><literal>$current.program</literal></term>
478             <listitem><simpara> will be replaced by title the currently active
479               window, resp. by the name of the currently active program.
480               If no window happens to be active, this tag will be ignored.
481             </simpara></listitem>
482           </varlistentry>
483         </variablelist>
484       </para>
485
486       <para>
487         A regular expression is, like in perl, either enclosed in forward
488         slashes or, alternatively, in any character of your choice with an
489         <literal>m</literal> (for <quote>match</quote>) in front. This is handy if you need
490         to use regular expressions that match directory names. Otherwise, the
491         syntax of the regular expressions is that of perl-compatible regular
492         expressions.
493       </para>
494   </sect2>
495   
496 </sect1>
497
498 <sect1 id="references">
499   <title>Program references</title>
500   <para>arbtt consists of a few command line tools, the most important one is
501   <command>arbtt-stats</command>. This overview is followed by their manual
502   pages.
503   </para>
504   
505   <!-- <sect2>
506     <title>Generating statistics</title> -->
507     <para>To generate statistics about the data that
508     <command>arbtt-capture</command> has gathered, use the program
509     <command>arbtt-stats</command>. A detailed description of the possible
510     options is given in <xref linkend="arbtt-stats"/>.</para>
511   <!--
512   </sect2>
513
514   <sect2>
515     <title>Gathering data</title>
516   -->
517     <para>The collection of data is done by <command>arbtt-capture</command>.
518     Usually, you only set it up once to run automatically, as described in <xref
519     linkend="installation"/>, and do not have to
520     worry about it again. Its command line reference is given in <xref
521     linkend="arbtt-capture"/>.</para>
522   <!--
523   </sect2>
524
525   <sect2>
526     <title>Dumping data</title>
527   -->
528     <para>Because the data log file is binary, a tool names
529     <command>arbtt-dump</command> can bee used to dump the data in
530     various textual formats. Its command line reference is given in <xref
531     linkend="arbtt-dump"/>.</para>
532
533     <para>If <command>arbtt-capture</command> crashes it might be that the log
534     file is not readable any more. In some cases, this can be fixed using the
535     (relatively raw) <command>arbtt-recover</command> tool. Its command line
536     reference is given in <xref linkend="arbtt-recover"/>.</para>
537   <!--
538   </sect2>
539   -->
540
541
542   <refentry id="arbtt-stats">
543     <refmeta>
544       <refentrytitle>arbtt-stats</refentrytitle>
545       <manvolnum>1</manvolnum>
546       <refmiscinfo class="source">arbtt manual</refmiscinfo>
547     </refmeta>
548
549     <refnamediv>
550       <refname>arbtt-stats</refname>
551       <refpurpose>generate statistics from the arbtt data samples</refpurpose>
552     </refnamediv>
553   
554     <refsynopsisdiv>
555       <cmdsynopsis>
556         <command>arbtt-stats</command>
557         <arg rep="repeat">OPTION</arg>
558       </cmdsynopsis>
559     </refsynopsisdiv>
560
561     <refsect1><title>Description</title>
562       <para>
563       <command>arbtt-stats</command> reads the samples that were recorded so far
564       by <command>arbtt-capture</command> from the log file, filters them
565       according to the users specifications and generates one or more reports
566       from the data.
567       </para>
568       <para>
569       When run without any options, <option>--total-time</option> is assumed.
570       </para>
571       <para>
572       The order in which filters (<option>--exclude</option>,
573       <option>--only</option>, <option>--also-inactive</option> and
574       <option>--filter</option>) and reports are passed to the program is
575       irrelevant: All filters given on the command line are active for all
576       reports.
577       </para>
578     </refsect1>
579
580     <refsect1><title>Options</title>
581       <variablelist>
582         <varlistentry>
583           <term><option>-h</option></term>
584           <term><option>-?</option></term>
585           <term><option>--help</option></term>
586           <listitem><simpara>shows a short summary of the available
587           options, and exists.</simpara></listitem>
588         </varlistentry>
589         <varlistentry>
590         <term><option>-V</option></term>
591         <term><option>--version</option></term>
592         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
593         </varlistentry>
594         <varlistentry>
595         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
596         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
597         </varlistentry>
598         <varlistentry>
599         <term><option>--categorizefile</option></term>
600         <listitem><simpara>categorize file to use instead of <filename>~/.arbtt/categorize.cfg</filename></simpara></listitem>
601         </varlistentry>
602       </variablelist>
603       <refsect2><title>Filtering options</title>
604         <variablelist>
605           <varlistentry>
606             <term><option>-x</option> <replaceable>TAG</replaceable></term>
607             <term><option>--exclude</option> <replaceable>TAG</replaceable></term>
608             <listitem><simpara>Ignore any data samples that have
609             been assigned this tag or category. To distinguish tags and categories, the latter have to be
610             entered followed by a colon. Can be given more than once.</simpara></listitem>
611           </varlistentry>
612           <varlistentry>
613             <term><option>-o</option> <replaceable>TAG</replaceable></term>
614             <term><option>--only</option> <replaceable>TAG</replaceable></term>
615             <listitem><simpara>Ignore any data samples that have
616             not been assigned this tag. To distinguish tags and categories, the latter have to be
617             entered followed by a colon. Can be given more than once.</simpara></listitem>
618           </varlistentry>
619           <varlistentry>
620             <term><option>--also-inactive</option></term>
621             <listitem><simpara>by default, <command>arbtt-stats</command> ignores
622             any samples which have been assigned the tag
623             <literal>inactive</literal>. This flag disables this behaviour.</simpara></listitem>
624           </varlistentry>
625           <varlistentry>
626             <term><option>-f</option> <replaceable>CONDITION</replaceable></term>
627             <term><option>--filter</option> <replaceable>CONDITION</replaceable></term>
628             <listitem><simpara>Only consider samples matching
629             the given condition, which follows the same syntax as in
630             <filename>categorize.cfg</filename> (Nonterminal <nonterminal def="#g-cond"/> in
631             <phrase condition="html"><xref linkend="grammar"/></phrase><phrase condition="man">the formal grammar specification found in the user guide</phrase>).</simpara></listitem>
632           </varlistentry>
633         </variablelist>
634       </refsect2>
635       <refsect2><title>Report options</title>
636         <variablelist>
637           <varlistentry>
638             <term><option>-m</option> <replaceable>PERCENTAGE</replaceable></term>
639             <term><option>--min-percentage</option> <replaceable>PERCENTAGE</replaceable></term>
640             <listitem><para>
641               Ignore tags whose percentage is less than the value specified
642               here. Default percentage: 1%.
643             </para></listitem>
644           </varlistentry>
645           <varlistentry>
646             <term><option>--output-exclude</option> <replaceable>TAG</replaceable></term>
647             <listitem><para>
648               Skip this tag or category when printing statistics. Only affects
649               the reports <option>--total-time</option> and
650               <option>--category</option>. To distinguish tags and categories,
651               the latter have to be entered followed by a colon. Can be given
652               more than once.
653             </para></listitem>
654           </varlistentry>
655           <varlistentry>
656             <term><option>--output-only</option> <replaceable>TAG</replaceable></term>
657             <listitem><para>
658               Prints statistics only for the specified tag or category. Only
659               affects the reports <option>--total-time</option> and
660               <option>--category</option>. To distinguish tags and categories,
661               the latter have to be entered followed by a colon. Can be given
662               more than once.
663             </para></listitem>
664           </varlistentry>
665           <varlistentry>
666             <term><option>--output-format</option> <replaceable>FORMAT</replaceable></term>
667             <listitem><para>
668               Specify the report output format, may be one of: text, csv
669               (comma-separated values), tsv (TAB-separated values).
670               Default format: text.
671             </para></listitem>
672           </varlistentry>
673         </variablelist>
674       </refsect2>
675       <refsect2><title>Reports</title>
676         <variablelist>
677           <varlistentry>
678             <term><option>-i</option></term>
679             <term><option>--information</option></term>
680             <listitem><para>
681               Various bits of information about the recorded data, such as total
682               time recorded, number of records etc. In this report, <quote>time
683               recorded</quote> is the sum of <emphasis>all</emphasis>
684               samples, including inactive and those that are disabled by the
685               filter, while <quote>time selected</quote> is the sum of the
686               samples that are matched by the given filters.
687             </para></listitem>
688           </varlistentry>
689           <varlistentry>
690             <term><option>-t</option></term>
691             <term><option>--total-time</option></term>
692             <listitem><para>For all tags, print the part of the selected time
693             with this tag applied to, both as an absolute value and a percentage
694             of the selected time.
695             </para></listitem>
696           </varlistentry>
697           <varlistentry>
698             <term><option>-c</option> <replaceable>CATEGORY</replaceable></term>
699             <term><option>--category</option> <replaceable>CATEGORY</replaceable></term>
700             <listitem><para>For the given category, give the textual equivalent
701             of a pie chart: For each possible value of the category, including
702             one for <quote>no tag of this category present</quote>, give the absolute time and
703             fraction. Entries which are not displayed because of the option
704             <option>--min-percentage</option> are aggregated.</para></listitem>
705           </varlistentry>
706           <varlistentry>
707             <term><option>--each-category</option></term>
708             <listitem><para>This is just a shortcut for a series of
709             <option>--category</option> options, one for each category found in
710             the data.
711             </para></listitem>
712           </varlistentry>
713           <varlistentry>
714             <term><option>--intervals</option> [<replaceable>TAG</replaceable>|<replaceable>CATEGORY</replaceable>:] </term>
715             <listitem><para>This report lists all periods of consecutive time
716             intervals where the given tag has been applied to, or where the
717             given category has the same value.
718             </para>
719             
720             <para>To distinguish tags and categories, the latter have to be
721             entered followed by a colon.</para>
722             
723             <para>This report will give wrong results if an activity has been
724             carried out at the end of a session and right at the beginning, as
725             the intermediate time is thought to be part of the interval.
726             Inactive times while <command>arbtt-capture</command> is running
727             will separate the results as expected.</para>
728             
729             </listitem>
730           </varlistentry>
731           <varlistentry>
732             <term><option>--for-each</option> <replaceable>PERIOD</replaceable></term>
733             <listitem><para>This is not a report of its own, but causes the selected
734             report to be executed for each of the given PERIOD (which can be
735             day, month or year) where there exist selected samples. All the reports 
736             will then be printed one after another or, in the case of CSV output,
737             with an additional column.</para>
738             
739             <para>Note that if this option is enabled, samples that are filtered out
740             are completely ignored (to avoid empty reports for periods with
741             only filtered samples). Therefore, the
742             <option>--information</option> report will print the numbers for
743             the samples selected also for the totals.</para>
744
745             </listitem>
746           </varlistentry>
747         </variablelist>
748       </refsect2>
749     </refsect1>
750
751     <refsect1><title>Examples</title>
752       <para>Some useful examples of what you can do with
753       <command>arbtt-stats</command> are provided here:</para>
754       <screen># Only consider the time when I was programming in Haskell 
755 arbtt-stats -o Editing-Haskell
756
757 # Tell me what evolution folders I spend my time in when I actually do
758 # work with e-Mail
759 arbtt-stats -o Program:evolution -c Evo-Folder
760
761 # Generate statistics about the last hour
762 arbtt-stats -f '$sampleage &lt; 1:00'</screen>
763     </refsect1>
764
765     <refsect1><title>Files</title>
766       <variablelist>
767         <varlistentry>
768           <term><filename>~/.arbtt/capture.log</filename></term>
769           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
770         </varlistentry>
771         <varlistentry>
772           <term><filename>~/.arbtt/categorize.cfg</filename></term>
773           <listitem><para>specification of the arbtt categorizer syntax. A
774           detailed description is given in <xref linkend="configuration"/></para></listitem>
775         </varlistentry>
776       </variablelist>
777     </refsect1>
778
779     <refsect1><title>See also</title>
780       <para>See the arbtt manual for more information and the <ulink
781       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
782       newer versions of arbtt.</para>
783     </refsect1>
784   </refentry>
785   
786   <refentry id="arbtt-capture">
787     <refmeta>
788       <refentrytitle>arbtt-capture</refentrytitle>
789       <manvolnum>1</manvolnum>
790       <refmiscinfo class="source">arbtt manual</refmiscinfo>
791     </refmeta>
792
793     <refnamediv>
794       <refname>arbtt-capture</refname>
795       <refpurpose>collect data samples for arbtt</refpurpose>
796     </refnamediv>
797   
798     <refsynopsisdiv>
799       <cmdsynopsis>
800         <command>arbtt-capture</command>
801         <arg rep="repeat">OPTION</arg>
802       </cmdsynopsis>
803     </refsynopsisdiv>
804
805     <refsect1><title>Description</title>
806       <para>
807       <command>arbtt-capture</command> runs continuously and saves at the given
808       sample rate, usually once per minute, the collected data to
809       <filename>~/.arbtt/capture.log</filename>. 
810       </para>
811     </refsect1>
812
813     <refsect1><title>Options</title>
814       <variablelist>
815         <varlistentry>
816           <term><option>-h</option></term>
817           <term><option>-?</option></term>
818           <term><option>--help</option></term>
819           <listitem><simpara>shows a short summary of the available
820           options, and exists.</simpara></listitem>
821         </varlistentry>
822         <varlistentry>
823         <term><option>-V</option></term>
824         <term><option>--version</option></term>
825         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
826         </varlistentry>
827         <varlistentry>
828         <term><option>-r</option> <replaceable>RATE</replaceable></term>
829         <term><option>--sample-rate</option> <replaceable>RATE</replaceable></term>
830         <listitem><simpara>sets the sample rate in seconds (default: 60)</simpara></listitem>
831         </varlistentry>
832         <varlistentry>
833         <term><option>-f</option> <replaceable>FILE</replaceable></term>
834         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
835         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
836         </varlistentry>
837         <varlistentry>
838         <term><option>-d</option></term>
839         <term><option>--dump</option></term>
840         <listitem><simpara>dump one current sample instead of modifying the logfile</simpara></listitem>
841         </varlistentry>
842       </variablelist>
843     </refsect1>
844     <refsect1><title>Files</title>
845       <variablelist>
846         <varlistentry>
847           <term><filename>~/.arbtt/capture.log</filename></term>
848           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
849         </varlistentry>
850       </variablelist>
851     </refsect1>
852
853
854     <refsect1><title>See also</title>
855       <para>See the arbtt manual for more information and the <ulink
856       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
857       newer versions of arbtt.</para>
858     </refsect1>
859   </refentry>
860
861   <refentry id="arbtt-dump">
862     <refmeta>
863       <refentrytitle>arbtt-dump</refentrytitle>
864       <manvolnum>1</manvolnum>
865       <refmiscinfo class="source">arbtt manual</refmiscinfo>
866     </refmeta>
867
868     <refnamediv>
869       <refname>arbtt-dump</refname>
870       <refpurpose>dumps arbtt data samples</refpurpose>
871     </refnamediv>
872   
873     <refsynopsisdiv>
874       <cmdsynopsis>
875         <command>arbtt-dump</command>
876         <arg rep="repeat">OPTION</arg>
877       </cmdsynopsis>
878     </refsynopsisdiv>
879
880     <refsect1><title>Description</title>
881       <para>
882       <command>arbtt-dump</command> reads the data samples recorded by <xref
883       linkend="arbtt-capture"/> and writes them so the standard output in an
884       ascii based format.
885       </para>
886     </refsect1>
887
888     <refsect1><title>Options</title>
889       <variablelist>
890         <varlistentry>
891           <term><option>-h</option></term>
892           <term><option>-?</option></term>
893           <term><option>--help</option></term>
894           <listitem><simpara>shows a short summary of the available
895           options, and exists.</simpara></listitem>
896         </varlistentry>
897         <varlistentry>
898         <term><option>-V</option></term>
899         <term><option>--version</option></term>
900         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
901         </varlistentry>
902         <varlistentry>
903         <term><option>-f</option> <replaceable>FILE</replaceable></term>
904         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
905         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
906         </varlistentry>
907         <varlistentry>
908         <term><option>-t</option> <replaceable>FORMAT</replaceable></term>
909         <term><option>--format</option> <replaceable>FORMAT</replaceable></term>
910         <listitem><simpara>dumping format to use, where <replaceable>FORMAT</replaceable> is one of <literal>human</literal> (the default), <literal>show</literal> or <literal>JSON</literal>. Case in-sensitive.</simpara></listitem>
911         </varlistentry>
912         <varlistentry>
913         <term><option>-l</option> <replaceable>NUMBER</replaceable></term>
914         <term><option>--last</option> <replaceable>NUMBER</replaceable></term>
915         <listitem><simpara>dump only the last <replaceable>NUMBER</replaceable> of samples.</simpara></listitem>
916         </varlistentry>
917       </variablelist>
918     </refsect1>
919
920     <refsect1><title>Files</title>
921       <variablelist>
922         <varlistentry>
923           <term><filename>~/.arbtt/capture.log</filename></term>
924           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
925         </varlistentry>
926       </variablelist>
927     </refsect1>
928
929     <refsect1><title>Formats</title>
930       <refsect2><title>Human</title>
931       <para>This format is intended for human inspection, but not for further
932       processing. Hence, it may change in new versions of arbtt without notice.
933       Example output:</para>
934       <screen>2013-06-20 14:53:50 (48ms inactive):
935     ( ) Navigator:      arbtt-dump - Iceweasel
936     ( ) gnome-terminal-server: jojo@kirk:~/projekte/programming/arbtt/doc
937     (*) gvim:           arbtt.xml + (~/projekte/programming/arbtt/doc) - GVIM2
938 </screen>
939       <para>The line with a star indicates the currently active window.</para>
940       </refsect2>
941
942       <refsect2><title>Show</title>
943       <para>This is the default serialization format of Haskell's
944       <literal>Show</literal> type class, one entry per line. This can be
945       useful if the data is to be processed by further Haskell code. Example
946       output, with indentation added manually:</para>
947       <screen>TimeLogEntry
948     { tlTime = 2013-06-20 14:53:50.957763 UTC
949     , tlRate = 60000
950     , tlData = CaptureData
951         { cWindows =
952             [ (False,"arbtt-dump - Iceweasel","Navigator")
953             , (False,"jojo@kirk:~/projekte/programming/arbtt/doc","gnome-terminal-server")
954             , (True,"arbtt.xml + (~/projekte/programming/arbtt/doc) - GVIM2","gvim")
955             ]
956         , cLastActivity = 48
957         }
958     }</screen>
959       </refsect2>
960
961       <refsect2><title>JSON</title>
962       <para>For interoperability, arbtt supports dumping its data to JSON, which can
963       easily be parsed by many different programming languages. Some level of
964       backward-compatibility will be provided, as far as possible. Default
965       output, again with indentation and spacing added manually:</para>
966       <screen>[ ...,
967   { "windows": [
968       { "program": "arbtt-dump - Iceweasel",
969         "title": "Navigator",
970         "active": false},
971       { "program": "jojo@kirk:~/projekte/programming/arbtt/doc",
972         "title":" gnome-terminal-server",
973         "active": false},
974       { "program": "arbtt.xml + (~/projekte/programming/arbtt/doc) - GVIM2",
975         "title": "gvim",
976         "active":true
977       }],
978     "inactive": 48,
979     "date": "2013-06-20T14:53:50.957Z",
980     "rate": 60000},
981   ...
982 ]</screen>
983       </refsect2>
984     </refsect1>
985
986     <refsect1><title>See also</title>
987       <para>See the arbtt manual for more information and the <ulink
988       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
989       newer versions of arbtt.</para>
990     </refsect1>
991   </refentry>
992
993   <refentry>
994     <refnamediv>
995       <refname>arbtt-import</refname>
996       <refpurpose>imports dumped arbtt data samples</refpurpose>
997     </refnamediv>
998   
999     <refsynopsisdiv>
1000       <cmdsynopsis>
1001         <command>arbtt-import</command>
1002         <arg rep="repeat">OPTION</arg>
1003       </cmdsynopsis>
1004     </refsynopsisdiv>
1005
1006     <refsect1><title>Description</title>
1007       <para>
1008       <command>arbtt-import</command> expects the output of
1009       <command>arbtt-dump</command> on the standard input and saves them as the
1010       logfile or the specified file.
1011       </para>
1012       <para>
1013       This program would completely override the existing file, therefore it
1014       will refuse to work if the log file already exists. If you want to
1015       overwrite a file, please delete it before running
1016       <command>arbtt-import</command>.
1017       </para>
1018     </refsect1>
1019
1020     <refsect1><title>Options</title>
1021       <variablelist>
1022         <varlistentry>
1023           <term><option>-h</option></term>
1024           <term><option>-?</option></term>
1025           <term><option>--help</option></term>
1026           <listitem><simpara>shows a short summary of the available
1027           options, and exists.</simpara></listitem>
1028         </varlistentry>
1029         <varlistentry>
1030         <term><option>-V</option></term>
1031         <term><option>--version</option></term>
1032         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1033         </varlistentry>
1034         <varlistentry>
1035         <term><option>-f</option> <replaceable>FILE</replaceable></term>
1036         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
1037         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1038         </varlistentry>
1039       </variablelist>
1040     </refsect1>
1041     <refsect1><title>Files</title>
1042       <variablelist>
1043         <varlistentry>
1044           <term><filename>~/.arbtt/capture.log</filename></term>
1045           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1046         </varlistentry>
1047       </variablelist>
1048     </refsect1>
1049
1050     <refsect1><title>See also</title>
1051       <para>See the arbtt manual for more information and the <ulink
1052       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1053       newer versions of arbtt.</para>
1054     </refsect1>
1055   </refentry>
1056
1057   <refentry id="arbtt-recover">
1058     <refmeta>
1059       <refentrytitle>arbtt-recover</refentrytitle>
1060       <manvolnum>1</manvolnum>
1061       <refmiscinfo class="source">arbtt manual</refmiscinfo>
1062     </refmeta>
1063
1064     <refnamediv>
1065       <refname>arbtt-recover</refname>
1066       <refpurpose>tries to recover a broken arbtt data log</refpurpose>
1067     </refnamediv>
1068   
1069     <refsynopsisdiv>
1070       <cmdsynopsis>
1071         <command>arbtt-recover</command>
1072         <arg rep="repeat">OPTION</arg>
1073       </cmdsynopsis>
1074     </refsynopsisdiv>
1075
1076     <refsect1><title>Description</title>
1077       <para>
1078       <command>arbtt-recover</command> tries to read the data samples recorded
1079       by <xref linkend="arbtt-capture"/>, skipping over possible broken entries. A fixed log file is written to <filename>~/.arbtt/capture.log.recovered</filename>. If the recovery was successful, you should stop <command>arbtt-capture</command> and move the file to <filename>~/.arbtt/capture.log</filename>.
1080       </para>
1081       <para>
1082       As a side effect, <command>arbtt-recover</command> applies the log compression method implemented in version 0.4.5 to the samples created by an earlier version. If you have a large logfile written by older versions, running <command>arbtt-recover</command> is recommended.
1083       </para>
1084     </refsect1>
1085
1086     <refsect1><title>Options</title>
1087       <variablelist>
1088         <varlistentry>
1089           <term><option>-h</option></term>
1090           <term><option>-?</option></term>
1091           <term><option>--help</option></term>
1092           <listitem><simpara>shows a short summary of the available
1093           options, and exists.</simpara></listitem>
1094         </varlistentry>
1095         <varlistentry>
1096         <term><option>-V</option></term>
1097         <term><option>--version</option></term>
1098         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1099         </varlistentry>
1100         <varlistentry>
1101         <term><option>-i</option></term>
1102         <term><option>--infile</option></term>
1103         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1104         </varlistentry>
1105         <varlistentry>
1106         <term><option>-o</option></term>
1107         <term><option>--outfile</option></term>
1108         <listitem><simpara>where to save the recovered file, instead of <filename>~/.arbtt/capture.log.recovered</filename></simpara></listitem>
1109         </varlistentry>
1110       </variablelist>
1111     </refsect1>
1112     <refsect1><title>Files</title>
1113       <variablelist>
1114         <varlistentry>
1115           <term><filename>~/.arbtt/capture.log</filename></term>
1116           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1117         </varlistentry>
1118         <varlistentry>
1119           <term><filename>~/.arbtt/capture.log.recovered</filename></term>
1120           <listitem><para>binary file, storing the fixed arbtt data samples</para></listitem>
1121         </varlistentry>
1122       </variablelist>
1123     </refsect1>
1124
1125     <refsect1><title>See also</title>
1126       <para>See the arbtt manual for more information and the <ulink
1127       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1128       newer versions of arbtt.</para>
1129     </refsect1>
1130   </refentry>
1131 </sect1>
1132
1133 <sect1 id="troubleshooting">
1134   <title>Troubleshooting</title>
1135   <sect2>
1136     <title>arbtt and xmonad</title>
1137     <para>
1138       If you are using the <ulink url="http://xmonad.org">xmonad</ulink> window manager and arbtt does ont record any windows, ensure that your xmonad configuration includes the EWMH-Hints extensions in the module <ulink url="http://hackage.haskell.org/packages/archive/xmonad-contrib/latest/doc/html/XMonad-Hooks-EwmhDesktops.html">XMonad.Hooks.EwmhDesktops</ulink>.
1139     </para>
1140   </sect2>
1141 </sect1>
1142
1143 <sect1 id="copyright">
1144   <title>Copyright and Contact</title>
1145   <para>
1146   arbtt is Copyright © 2009-2010 Joachim Breitner
1147   </para>
1148
1149   <para>
1150     arbtt does not have a bug tracker yet. If you have bug reports, suggestions
1151     or questions, please send an email to the arbtt mailing list at <ulink url="mailto:arbtt@lists.nomeata.de">arbtt@lists.nomeata.de</ulink>, which you can subscribe at <ulink url="http://lists.nomeata.de/mailman/listinfo/arbtt">http://lists.nomeata.de/mailman/listinfo/arbtt</ulink>.
1152   </para>
1153
1154   <sect2>
1155     <title>arbtt License</title>
1156     <para>
1157     <literallayout>
1158 This program is free software; you can redistribute it and/or modify
1159 it under the terms of the GNU General Public License as published by
1160 the Free Software Foundation; either version 2 of the License, or
1161 (at your option) any later version.
1162
1163 This program is distributed in the hope that it will be useful,
1164 but WITHOUT ANY WARRANTY; without even the implied warranty of
1165 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1166 GNU General Public License for more details.
1167
1168 You should have received a copy of the GNU General Public License
1169 along with this program; if not, write to the Free Software
1170 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
1171     </literallayout>
1172     </para>
1173   </sect2>
1174 </sect1>
1175
1176 <sect1 id="release-notes">
1177   <title>Release Notes</title>
1178   <para>
1179   The version history with changes relevant for the user is documented here.
1180   </para>
1181
1182   <sect2 id="release-notes-0.8.1">
1183     <title>Version 0.8.1</title>
1184     <itemizedlist>
1185       <listitem>
1186         <para>
1187           The syntax now allows for time differences larger than 99:99.
1188           (<ulink url="https://bitbucket.org/nomeata/arbtt/issue/14/improve-time-categorization-directives">issue #14</ulink>)
1189         </para>
1190       </listitem>
1191     </itemizedlist>
1192   </sect2>
1193
1194   <sect2 id="release-notes-0.8">
1195     <title>Version 0.8</title>
1196     <itemizedlist>
1197       <listitem>
1198         <para>
1199           <command>arbtt-dump</command> can now show the data in other formats
1200           as well, as suggested by Waldir Pimenta (option
1201           <option>--format</option>). This includes a human-readale output and
1202           JSON.
1203         </para>
1204       </listitem>
1205       <listitem>
1206         <para>New option <option>--last</option> of <command>arbtt-dump</command>.</para>
1207       </listitem>
1208       <listitem>
1209         <para><command>arbtt-recover</command> can handle larger datasets with a reasonable amount of memory.</para>
1210       </listitem>
1211       <listitem>
1212         <para>When dumping samples with <command>arbtt-stats</command> or <command>arbtt-dump</command> (in human-readable mode), times are printed in the local time zone, as suggested by Oren Gampel.</para>
1213       </listitem>
1214       <listitem>
1215         <para><command>arbtt-capture</command> now supports the option <option>--dump</option> for development and debugging purposes.</para>
1216       </listitem>
1217       <listitem>
1218         <para>The name of the current desktop (or workspace) is also recorded, and available as <literal>$desktop</literal> (<ulink url="https://bitbucket.org/nomeata/arbtt/issue/1/track-active-workspace-name">issue #1</ulink>).</para>
1219       </listitem>
1220       <listitem>
1221         <para>Two bugs in the parser were fixed (<ulink url="https://bitbucket.org/nomeata/arbtt/issue/4/parsing-of-if-then-else-fails">issue #4</ulink> and <ulink url="https://bitbucket.org/nomeata/arbtt/issue/5/parsing-of-fails">issue #5</ulink>).</para>
1222       </listitem>
1223       <listitem>
1224         <para><command>arbtt-stats</command> can print reports split by time interval, using the <option>--for-each</option> option.</para>
1225       </listitem>
1226       <listitem>
1227         <para><command>arbtt-stats</command> can print the actual samples selected, with <option>--dump-samples</option>.</para>
1228       </listitem>
1229       <listitem>
1230         <para>Support for GHC-7.8 was added, with help from Jayesh Kumar Gupta (<ulink url="https://bitbucket.org/nomeata/arbtt/issue/8/update-base-bounds-for-newer-ghc">issue #8</ulink>).</para>
1231       </listitem>
1232       <listitem>
1233         <para>Arbtt now has a proper testsuite integrated into Cabal, and an <ulink url="https://travis-ci.org/nomeata/darcs-mirror-arbtt">automated test infrastructure</ulink> on Travis.</para>
1234       </listitem>
1235       <listitem>
1236         <para>Waldir Pimenta contributed a new web page, hosted at <ulink url="http://arbtt.nomeata.de/">arbtt.nomeata.de</ulink>.</para>
1237       </listitem>
1238     </itemizedlist>
1239   </sect2>
1240   
1241   <sect2>
1242     <title>Version 0.7</title>
1243     <itemizedlist>
1244       <listitem>
1245         <para>Make sure that the log file is only readable by the current user. Thanks to Joey Hess for pointing that out.</para>
1246       </listitem>
1247       <listitem>
1248         <para>Show a progress bar in <command>arbtt-stats</command>.</para>
1249       </listitem>
1250       <listitem>
1251         <para>GHC-7.6 compatibility, thanks to Isaac Dupree.</para>
1252       </listitem>
1253     </itemizedlist>
1254   </sect2>
1255
1256   <sect2>
1257     <title>Version 0.6.4.1</title>
1258     <itemizedlist>
1259       <listitem>
1260         <para>
1261         Added missing module to the packages.
1262         </para>
1263       </listitem>
1264     </itemizedlist>
1265   </sect2>
1266
1267   <sect2>
1268     <title>Version 0.6.4</title>
1269     <itemizedlist>
1270       <listitem>
1271         <para>Massive memory footprint reduction, due to processing the data in one run. See <ulink url="http://www.joachim-breitner.de/blog/archives/560-The-might-applicative-left-fold.html">my blog post for technical information</ulink>.</para>
1272       </listitem>
1273     </itemizedlist>
1274   </sect2>
1275
1276   <sect2>
1277     <title>Version 0.6.3</title>
1278     <itemizedlist>
1279       <listitem>
1280         <para>Performance improvements.</para>
1281       </listitem>
1282       <listitem>
1283         <para>Support comparing a string to a list of strings, or matching it against a list ofregular expressions.</para>
1284       </listitem>
1285     </itemizedlist>
1286   </sect2>
1287
1288   <sect2>
1289     <title>Version 0.6.2</title>
1290     <itemizedlist>
1291       <listitem>
1292         <para>Add a warning whtn the system locale is not supported.</para>
1293       </listitem>
1294       <listitem>
1295         <para>Allwo RTS options to be passed to the arbtt binaries.</para>
1296       </listitem>
1297       <listitem>
1298         <para>GHC 7.4 compatibility.</para>
1299       </listitem>
1300     </itemizedlist>
1301   </sect2>
1302
1303   <sect2>
1304     <title>Version 0.6.1</title>
1305     <itemizedlist>
1306       <listitem>
1307         <para>Performance improvements.</para>
1308       </listitem>
1309     </itemizedlist>
1310   </sect2>
1311
1312   <sect2>
1313     <title>Version 0.6</title>
1314     <itemizedlist>
1315       <listitem>
1316         <para>The command <command>arbtt-capture</command> now supports the
1317         <option>--logfile</option>.
1318         </para>
1319       </listitem>
1320       <listitem>
1321         <para>New report “intervals”, available using <command>arbtt-stats</command> <option>--intervals</option>.
1322         </para>
1323       </listitem>
1324       <listitem>
1325         <para>The paramters <option>--exclude</option> and
1326         <option>--include</option> of <command>arbtt-stats</command> can match
1327         categories as well as tags.
1328         </para>
1329       </listitem>
1330       <listitem>
1331         <para>Bugfix: Numbers in tag names are no longer replaced by an underscore.</para>
1332       </listitem>
1333       <listitem>
1334         <para>New paramters <option>--output-exclude</option> and
1335         <option>--output-include</option> of <command>arbtt-stats</command>.
1336         </para>
1337       </listitem>
1338     </itemizedlist>
1339   </sect2>
1340
1341   <sect2>
1342     <title>Version 0.5 (The ZuriHac-Release)</title>
1343     <itemizedlist>
1344       <listitem>
1345         <para>New command <command>arbtt-import</command>, which imports the output from <command>arbtt-dump</command>.
1346         </para>
1347       </listitem>
1348       <listitem>
1349         <para>The command <command>arbtt-stats</command> now supports the
1350         <option>--logfile</option> and <option>--categorizefile</option> as well.
1351         (<xref linkend="martin"/>)
1352         </para>
1353       </listitem>
1354       <listitem>
1355         <para>
1356           The command <command>arbtt-stats</command> now supports the csv
1357           (comma-separated values) and tsv (TAB-separated values) report output
1358           formats in addition to text.
1359           (<xref linkend="muharem"/>)
1360         </para>
1361       </listitem>
1362       <listitem>
1363         <para>
1364           Unicode is handled correctly in regular expressions.
1365         </para>
1366       </listitem>
1367       <listitem>
1368         <para>
1369           Improved date-handling functions for <filename>categorize.cfg</filename>.
1370           (<xref linkend="sergey"/>)
1371         </para>
1372       </listitem>
1373     </itemizedlist>
1374   </sect2>
1375
1376   <sect2>
1377     <title>Version 0.4.5.1</title>
1378     <itemizedlist>
1379       <listitem>
1380         <para>Bugfix: Added missing modules to the cabal file.
1381         </para>
1382       </listitem>
1383     </itemizedlist>
1384   </sect2>
1385
1386   <sect2>
1387     <title>Version 0.4.5</title>
1388     <itemizedlist>
1389       <listitem>
1390         <para>Implement a custom compression method greatly reduce the file size of the log file. Run <command>arbtt-capture</command> to compress the previous samples as well.
1391         </para>
1392       </listitem>
1393     </itemizedlist>
1394   </sect2>
1395
1396   <sect2>
1397     <title>Version 0.4.4</title>
1398     <itemizedlist>
1399       <listitem>
1400         <para>Bugfix: Correctly parse a tag name containing a colon when passed to <command>arbtt-stats</command> <option>--exclude</option>.</para>
1401       </listitem>
1402       <listitem>
1403         <para>Bugfix: Only warn once when the <token>_NET_CLIENT_LIST</token> X property is not set for the root window.</para>
1404       </listitem>
1405     </itemizedlist>
1406   </sect2>
1407
1408
1409   <sect2>
1410     <title>Version 0.4.3</title>
1411     <itemizedlist>
1412       <listitem>
1413         <para>Use fetchName from xmonad instead of xFetchName, as it works with unicode characters in window titles.</para>
1414       </listitem>
1415     </itemizedlist>
1416   </sect2>
1417
1418   <sect2>
1419     <title>Version 0.4.2</title>
1420     <itemizedlist>
1421       <listitem>
1422         <para>Implement option <option>--logfile</option> to
1423         <command>arbtt-dump</command>.</para>
1424       </listitem>
1425       <listitem>
1426         <para>New command <command>arbtt-recover</command> to rescue data from
1427         a proken data log file.</para>
1428       </listitem>
1429       <listitem>
1430         <para>Actually include this documentation in the released tarball.</para>
1431       </listitem>
1432     </itemizedlist>
1433   </sect2>
1434
1435   <sect2>
1436     <title>Version 0.4.1</title>
1437     <itemizedlist>
1438       <listitem>
1439         <para>Write this documentation</para>
1440       </listitem>
1441       <listitem>
1442         <para>Drop dependency on setlocale: Copy the SetLocale module.</para>
1443       </listitem>
1444       <listitem>
1445         <para>Drop dependency on tabular: Implement custom table rendering code.</para>
1446       </listitem>
1447       <listitem>
1448         <para>In the absence of _NET_CLIENT_LIST, look for application windows as children of the root windows. This should work for users of window managers like i3 without EWHM support.</para>
1449       </listitem>
1450     </itemizedlist>
1451   </sect2>
1452
1453   <sect2>
1454     <title>Version 0.4</title>
1455     <itemizedlist>
1456       <listitem>
1457         <para>Implement option <option>--each-categories</option> to
1458         <command>arbtt-stats</command></para>
1459       </listitem>
1460       <listitem>
1461         <para>Eliminate one possible cause for crashes of
1462         <command>arbtt-capture</command>.</para>
1463       </listitem>
1464     </itemizedlist>
1465   </sect2>
1466
1467   <sect2>
1468     <title>Version 0.3.0</title>
1469     <itemizedlist>
1470       <listitem>
1471         <para>Switch to binary log file format, for greatly increased speed</para>
1472       </listitem>
1473       <listitem>
1474         <para><command>arbtt-capture</command> will automatically detect and
1475         convert log files in the old format.</para>
1476       </listitem>
1477     </itemizedlist>
1478   </sect2>
1479
1480   <sect2>
1481     <title>Version 0.2.0</title>
1482     <itemizedlist>
1483       <listitem>
1484         <para>Add option <option>--filter</option> to
1485         <command>arbtt-stats</command></para>
1486       </listitem>
1487       <listitem>
1488         <para>Add option <option>--sample-rate</option> to
1489         <command>arbtt-capture</command></para>
1490       </listitem>
1491       <listitem>
1492         <para>Introduce time-base variables <literal>$time</literal> and
1493         <literal>$sampleage</literal></para>
1494       </listitem>
1495     </itemizedlist>
1496   </sect2>
1497
1498   <sect2>
1499     <title>Version 0.1.5</title>
1500     <itemizedlist>
1501       <listitem>
1502         <para>Use <function>setlocale</function> to get umlauts in window titles correctly</para>
1503       </listitem>
1504     </itemizedlist>
1505   </sect2>
1506
1507   <sect2>
1508     <title>Version 0.1.4</title>
1509     <itemizedlist>
1510       <listitem>
1511         <para>Be smarter when figuring out what window is active. Thanks to CJ
1512         van den Berg for investigating the issue.</para>
1513       </listitem>
1514     </itemizedlist>
1515   </sect2>
1516
1517   <sect2>
1518     <title>Version 0.1.3</title>
1519     <itemizedlist>
1520       <listitem><para>Read <literal>_NET_CLIENT_LIST</literal> for the list of
1521       applications, for compatibility with window managers such as metacity</para></listitem>
1522     </itemizedlist>
1523   </sect2>
1524
1525   <sect2>
1526     <title>Version 0.1.2</title>
1527     <itemizedlist>
1528       <listitem><para>Off-By-Ten error in the time display</para></listitem>
1529       <listitem><para>Correctly show total number of records in
1530       <option>--information</option></para></listitem>
1531     </itemizedlist>
1532   </sect2>
1533
1534   <sect2>
1535     <title>Version 0.1.1</title>
1536     <para>
1537     Rename files to allow building on MacOS.
1538     </para>
1539   </sect2>
1540
1541   <sect2>
1542     <title>Version 0.1</title>
1543     <para>
1544     Initial release of arbtt
1545     </para>
1546   </sect2>
1547 </sect1>
1548
1549 </article>