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