Typo
[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     <author id="gwern">
43       <firstname>Gwern</firstname>
44       <surname>Branwen</surname>
45       <contrib>Documentation writer</contrib>
46       <email>gwern@gwern.net</email>
47     </author>
48   </authorgroup>
49 </articleinfo>
50 <abstract>
51   <para>
52     arbtt is a background daemon that stores which windows are open, which one
53     has the focus and how long since your last action (and possibly more sources
54     later), and stores this. It is also a program that will, based on
55     expressive rules you specify, derive what you were doing, and what for.
56   </para>
57   <para>
58     It is comparable to the window trackers  <ulink
59     url="https://www.rescuetime.com/">RescueTime</ulink>, <ulink
60     url="https://github.com/gurgeh/selfspy">selfspy</ulink>, <ulink
61     url="http://www.timesnapper.com/">TimeSnapper</ulink>, and
62     <ulink url="https://etopian.com/software/automatic-screenshots-windows-mac-linux/">
63     Productive Peach</ulink>; but it differs from the manual timetrackers like <ulink
64     url="http://projecthamster.wordpress.com/about/">Project Hamster</ulink> which require
65     the user to type a description of their activities.
66
67     <warning><para>The log file might contain very sensitive private data. Make sure
68     you understand the consequences of a full-time logger and be careful with this
69     data.</para></warning>
70   </para>
71 </abstract>
72
73 <sect1 id="installation">
74   <title>Installation</title>
75   <sect2>
76     <title>Building with <command>cabal-install</command></title>
77     <para>
78     arbtt comes in the form of a Cabalized<footnote><para>Cabal is the common software
79     packaging for Haskell programs and libraries, see <ulink
80     url="http://www.haskell.org/cabal/"/>.</para></footnote> package, and is
81     available from hackage. The easiest way of obtaining and installing arbtt is
82     via <command>cabal-install</command>. If you have
83     <command>cabal-install</command> available, just run
84     <screen>$ cabal install arbtt</screen>
85     to download, build and install arbtt.
86     </para>
87   </sect2>
88
89   <sect2>
90     <title>Building without <command>cabal-install</command></title>
91     <para>
92     You can fetch the latest arbtt source tarball from hackage, at
93     <ulink url="http://hackage.haskell.org/package/arbtt"/>. Extract the tarball
94     and run the following commands to build and install the arbtt binaries:
95     <screen>$ runhaskell Setup.hs configure
96 $ runhaskell Setup.hs build
97 $ runhaskell Setup.hs install</screen>
98     </para>
99   </sect2>
100
101   <sect2>
102     <title>Setting up the capture program</title>
103     <para>
104     To have arbtt gather useful data, you need to make sure that
105     <command>arbtt-capture</command> is started with your X session. If you use
106     GNOME or KDE, you can copy the file
107     <filename>arbtt-capture.desktop</filename> to
108     <filename>~/.config/autostart/</filename>. You might need to put the full
109     path to <command>arbtt-capture</command> in the Exec line there, if you did
110     not do a system wide installation.
111     </para>
112     <para>
113     By default, <command>arbtt-capture</command> will save one data sample per
114     minute. If you want to change that, you can pass <option>--sample-rate
115     <replaceable>RATE</replaceable></option> to <command>arbtt-capture</command>, where
116     <replaceable>RATE</replaceable> specifies the sample rate in seconds.
117     </para>
118   </sect2>
119
120   <sect2>
121     <title>Building the documentation</title>
122     <para>
123     Obviously, you can already read the documentation. If you still want to
124     build it yourself, enter the directory <filename>doc/</filename> and run
125     <command>make</command> for the documentation in HTML and PDF format.
126     </para>
127   </sect2>
128
129
130   <sect2>
131     <title>Development version</title>
132     <para>
133       If you want to try the latest unreleased state of the code, or want to
134       contribute to arbtt, you can fetch the code with
135       <screen>darcs get <ulink url="http://darcs.nomeata.de/arbtt"/></screen>
136     </para>
137   </sect2>
138
139 </sect1>
140
141 <sect1 id="configuration">
142   <title>Configuring the arbtt categorizer (<command>arbtt-stats</command>)</title>
143   <para>
144   Once <command>arbtt-capture</command> is running, it will record data without
145   any configuration. And only to analyze the recorded data, one needs to
146   configure the categorizer. Everytime the categorizer
147   (<command>arbtt-stats</command>) runs, it applies categorization rules to all
148   recorded data and tags it accordingly.  Thus, if you improve your
149   categorization rules later, they will apply also to all previous data
150   samples!
151   </para>
152
153   <sect2>
154   <title>Configuration example</title>
155   <para>
156   The configuration file needs to be placed in
157   <filename>~/.arbtt/categorize.cfg</filename>. An
158   example is included in the source distribution, and it is reproduced here:
159   see <xref linkend="catex"/>.
160   It should be more enlightening than a formal description.
161   </para>
162
163   <example id="catex">
164   <title><filename>categorize.cfg</filename></title>
165     <programlisting><xi:include  href="../categorize.cfg"  parse="text"
166       xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
167   </example>
168   </sect2>
169
170   <sect2>
171     <title>The semantics (informal)</title>
172     <para>
173       A data sample consists of the time of recording, the time passed since the
174       user’s last action, the name of the current workspace and the list of
175       windows. For each window this information is available:
176       <itemizedlist>
177         <listitem><simpara>the window title</simpara></listitem>
178         <listitem><simpara>the program name</simpara></listitem>
179         <listitem><simpara>whether the window was the active window</simpara></listitem>
180       </itemizedlist>
181       Based on this information and on the rules in
182       <filename>categorize.cfg</filename>, the categorizer
183       (<command>arbtt-stats</command>) assigns <emphasis>tags</emphasis> to
184       each sample.
185     </para>
186
187     <para>
188       A simple rule consists of a condition followed by an arrow
189       (<literal>==></literal>) and a tag expression
190       (<literal>tag</literal> keyword followed by tag name).
191       The rule ends with a coma (<literal>,</literal>).
192     </para>
193
194     <para>
195       The keyword <literal>tag</literal>, usually preceded with a condition,
196       assigns a <emphasis>tag</emphasis> to the sample; <literal>tag</literal>
197       keyword is followed by a tag name (any sequence of alphanumeric symbols,
198       underscores and hyphens). If tag name contains a colon
199       (<literal>:</literal>), the first part of the name before the colon, is
200       considered to be tag <emphasis>category</emphasis>.
201     </para>
202
203     <para>
204       For example, this rule
205       <programlisting>month $date == 1 ==> tag month:January,</programlisting>
206       if it succeeds, assigns a the tag <literal>January</literal> in the
207       category <literal>month</literal>.
208     </para>
209
210     <para>If the tag has a <emphasis>category</emphasis>, it will only be
211       assigned if no other tag of that category has been assigned. This means
212       that for each sample and each category, there can be at most only one tag
213       in that category. Tags can contain references to group matches in the
214       regular expressions used in conditions (<literal>$1</literal>,
215       <literal>$2</literal>)...). Tags can also reference some
216       variables such as window title (<literal>$current.title</literal>) or
217       program name (<literal>$current.program</literal>).
218     </para>
219
220     <para>
221       The variable <literal>$idle</literal> contains the idle time of the user,
222       measured in seconds. Usually, it is used to assign the tag
223       <literal>inactive</literal>, which is handled specially by
224       <command>arbtt-stats</command>, as can be seen in <xref linkend="catex"/>.
225     </para>
226
227     <para>
228       When applying the rules, the categorizer has a notion of
229       the <emphasis>window in scope</emphasis>, and the variables
230       <literal>$title</literal>, <literal>$program</literal> and
231       <literal>$active</literal> always refer to the window in scope.
232       By default, there is no window is in scope. Condition should be prefixed
233       with either <literal>current window</literal> or <literal>any
234       window</literal>, to define scope of these variables.
235     </para>
236
237     <para>
238       The name of the current desktop (or workspace) is available as
239       <literal>$desktop</literal>.
240     </para>
241
242     <para>
243       For <literal>current window</literal>, the currently active window is in
244       scope. If there is no such window, the condition is false.
245     </para>
246
247     <para>
248       For <literal>any window</literal>, the condition is applied to each
249       window, in turn, and if any of the windows matches, the result is true. If
250       more than one window matches it is not defined from which match the
251       variables <literal>$1</literal>... are taken from (see more about regular
252       expressions below).
253     </para>
254
255     <para>
256       The variable <literal>$time</literal> refers to the time-of-day of the
257       sample (i.e. the time since 00:00 that day, local time), while
258       <literal>$sampleage</literal> refers to the
259       time span from when the sample was recored until now, the time of
260       evaluating the statistics. The latter variable is especially useful when
261       passed to the <option>--filter</option> option of
262       <command>arbtt-stats</command>. They can be compared with expressions
263       like "hh:mm", for example
264       <programlisting>$time >=  8:00 &amp;&amp; $time &lt; 12:00 ==> tag time-of-day:morning</programlisting>
265     </para>
266
267     <para>
268       The variable <literal>$date</literal> referes to the date and time of the
269       recorded sample. It can be compared with date literals in the form
270       YYYY-MM-DD (which stand for midnight, so <programlisting>$date ==
271       2001-01-01</programlisting> will not do what you want, but
272       <programlisting>$date >= 2001-01-01 &amp;&amp; $date &lt;= 2001-01-02</programlisting>
273       would).  All dates are evaluated in local time.
274     </para>
275     <para>
276       Expression <literal>format $date</literal> evaluates to a string with
277       a date formatted according to ISO 8601, i.e. like "YYYY-MM-DD". The 19th
278       of March 2010 is formatted as "2010-03-19". Formatted date can be compared
279       to strings. Formatted dates may be useful to tag particular date ranges. But
280       also note that this is a rather expensive operation that can slow down your
281       data processing.
282     </para>
283     <para>
284       Expression <literal>month $date</literal> evaluates to an integer, from 1
285       to 12, corresponding to the month number. Expression <literal>year
286       $date</literal> evaluates to an integer which is a year number.
287       Expression <literal>day of month $date</literal> evaluates to an integer,
288       from 1 to 31, corresponding to the day of month.
289       Expression <literal>day of week $date</literal> evaluates to an integer,
290       from 1 to 7, corresponding to the day of week, Monday is 1, Sunday is 7.
291       These expressions can be compared to integers.
292     </para>
293
294     <para>
295       Expressions can be compared to literal values with <literal>==</literal>
296       (equal), <literal>/=</literal> (not equal), <literal>&lt;</literal>,
297       <literal>&lt;=</literal>, <literal>&gt;=</literal>,
298       <literal>&gt;</literal> operators. String expressions
299       (<literal>$program</literal>, <literal>$title</literal>) can be matched
300       against regular expressions with <literal>=~</literal> operator. With these
301       operatorions, the right hand side can be a comma-separated list of
302       literals enclosed in square brackets (<literal>[</literal>
303       <emphasis>...</emphasis>, <emphasis>...</emphasis>, <literal>]</literal>), which
304       succeeds if any of them succeeds.
305     </para>
306
307     <para>Regular expressions are written either between slashes
308        (<literal>/</literal> regular expression <literal>/</literal>),
309        or after a letter <literal>m</literal> followed by any symbol
310        (<literal>m</literal> <emphasis>c</emphasis> regular expression <emphasis>c</emphasis>, where <emphasis>c</emphasis> is any symbol).
311        The second appearance of that symbol ends the expression.
312        You can find both variants in <xref linkend="catex"/>.
313     </para>
314
315     <para>Complex conditions may be constructed from the simpler ones,
316       using Boolean AND (<literal>&amp;&amp;</literal>), OR
317       (<literal>||</literal>), and NOT (<literal>!</literal>) functions and
318       parentheses.
319     </para>
320
321   </sect2>
322
323   <sect2>
324     <title>The syntax</title>
325     <para>
326     <filename>categorize.cfg</filename> is a plain text file.
327     Whitespace is insignificant and Haskell-style comments are allowed.
328     A formal grammar is provided in <xref linkend="grammar"/>.
329     </para>
330
331     <figure id="grammar">
332         <title>The formal grammar of <filename>categorize.cfg</filename></title>
333         <productionset>
334           <production id="g-rules">
335             <lhs>Rules</lhs>
336             <rhs>
337               [ <nonterminal def="#g-aliasspec"/> ]
338               <nonterminal def="#g-rule"/> ( (<quote>,</quote>
339               <nonterminal def="#g-rule"/>)* | ( <quote>;</quote>
340               <nonterminal def="#g-rule"/>)* )
341             </rhs>
342           </production>
343
344           <production id="g-aliasspec">
345             <lhs>AliasSpec</lhs>
346             <rhs><quote>aliases</quote> <quote>(</quote> <nonterminal
347               def="#g-alias"/> (<quote>,</quote> <nonterminal def="#g-alias"/>)*
348               <quote>)</quote> </rhs>
349           </production>
350
351           <production id="g-alias">
352             <lhs>Alias</lhs>
353             <rhs>Literal <quote>-&gt;</quote> Literal</rhs>
354           </production>
355
356           <production id="g-rule">
357             <lhs>Rule</lhs>
358             <rhs><quote>{</quote> <nonterminal def="#g-rules"/>
359                  <quote>}</quote>
360             </rhs>
361             <rhs>
362               <nonterminal def="#g-cond"/> <quote>==&gt;</quote>
363               <nonterminal def="#g-rule"/> | <quote>if</quote>
364               <nonterminal def="#g-cond"/> <quote>then</quote>
365               <nonterminal def="#g-rule"/> <quote>else</quote>
366               <nonterminal def="#g-rule"/>
367             </rhs>
368             <rhs>
369               <quote>tag</quote> <nonterminal def="#g-tag"/>
370             </rhs>
371           </production>
372
373           <production id="g-cond">
374             <lhs>Cond</lhs>
375             <rhs><quote>(</quote> <nonterminal def="#g-cond"/>
376                  <quote>)</quote>
377             </rhs>
378             <rhs><quote>!</quote> <nonterminal def="#g-cond"/> |
379                  <nonterminal def="#g-cond"/> <quote>&amp;&amp;</quote>
380                  <nonterminal def="#g-cond"/> |
381                  <nonterminal def="#g-cond"/> <quote>||</quote> <nonterminal
382                  def="#g-cond"/>
383             </rhs>
384             <rhs> <quote>$active</quote> </rhs>
385             <rhs> <nonterminal def="#g-string"/> <nonterminal def="#g-cmpop"/>
386                  <nonterminal def="#g-string"/> </rhs>
387             <rhs> <nonterminal def="#g-string"/> <nonterminal def="#g-cmpop"/>
388                  <quote>[</quote> <nonterminal def="#g-listofstring"/>
389                  <quote>]</quote>
390                  </rhs>
391             <rhs> <nonterminal def="#g-string"/> <quote>=~</quote>
392                  <nonterminal def="#g-regex"/></rhs>
393             <rhs> <nonterminal def="#g-string"/> <quote>=~</quote>
394                  <quote>[</quote> <nonterminal def="#g-listofregex"/>
395                  <quote>]</quote>
396                  </rhs>
397             <rhs> <nonterminal def="#g-number"/> <nonterminal def="#g-cmpop"/>
398                  <nonterminal def="#g-number"/> </rhs>
399             <rhs> <nonterminal def="#g-timediff"/> <nonterminal def="#g-cmpop"/>
400                  <nonterminal def="#g-timediff"/> </rhs>
401             <rhs> <nonterminal def="#g-date"/> <nonterminal def="#g-cmpop"/>
402                  <nonterminal def="#g-date"/> </rhs>
403             <rhs> <quote>current window</quote> <nonterminal def="#g-cond"/> </rhs>
404             <rhs> <quote>any window</quote> <nonterminal def="#g-cond"/> </rhs>
405           </production>
406
407           <production id="g-string">
408             <lhs>String</lhs>
409             <rhs> <quote>$title</quote> </rhs>
410             <rhs> <quote>$program</quote> </rhs>
411             <rhs> <quote>$desktop</quote> </rhs>
412             <rhs> <quote>format</quote> <nonterminal def="#g-date" /> </rhs>
413             <rhs> <quote>"</quote> string literal <quote>"</quote> </rhs>
414           </production>
415
416           <production id="g-listofstring">
417             <lhs>ListOfString</lhs>
418             <rhs> <quote>"</quote> string literal <quote>"</quote> </rhs>
419             <rhs> <quote>"</quote> string literal <quote>"</quote> , <nonterminal def="#g-listofstring"/> </rhs>
420           </production>
421
422           <production id="g-number">
423             <lhs>Number</lhs>
424             <rhs> <quote>$idle</quote> </rhs>
425             <rhs> <quote>day of week</quote> <nonterminal def="#g-date" /> </rhs>
426             <rhs> <quote>day of month</quote> <nonterminal def="#g-date" /> </rhs>
427             <rhs> <quote>month</quote> <nonterminal def="#g-date" /> </rhs>
428             <rhs> <quote>year</quote> <nonterminal def="#g-date" /> </rhs>
429             <rhs> number literal </rhs>
430           </production>
431
432           <production id="g-date">
433             <lhs>Date</lhs>
434             <rhs> <quote>$date</quote> </rhs>
435             <!-- <rhs> <quote>$now</quote> </rhs> -->
436           </production>
437
438           <production id="g-timediff">
439             <lhs>TimeDiff</lhs>
440             <rhs> <quote>$time</quote> </rhs>
441             <rhs> <quote>$sampleage</quote> </rhs>
442             <!-- <rhs> <nonterminal def="#g-date"/> <quote>-</quote> <nonterminal def="#g-date"/></rhs> -->
443             <rhs>( Digit )* Digit <quote>:</quote> Digit Digit</rhs>
444           </production>
445
446           <production id="g-tag">
447             <lhs>Tag</lhs>
448             <rhs> [ Literal <quote>:</quote> ] Literal </rhs>
449           </production>
450
451           <production id="g-regex">
452             <lhs>RegEx</lhs>
453             <rhs>  <quote>/</quote> Literal <quote>/</quote> |
454               <quote>m</quote> <replaceable>c</replaceable> Literal
455               <replaceable>c</replaceable><lineannotation>Where
456               <replaceable>c</replaceable> can be any
457               character.</lineannotation> </rhs>
458           </production>
459
460           <production id="g-listofregex">
461             <lhs>ListOfRegex</lhs>
462             <rhs> <quote>"</quote> <nonterminal def="#g-regex"/> <quote>"</quote> </rhs>
463             <rhs> <quote>"</quote> <nonterminal def="#g-regex"/> <quote>"</quote> , <nonterminal def="#g-listofregex"/> </rhs>
464           </production>
465
466           <production id="g-cmpop">
467             <lhs>CmpOp</lhs>
468             <rhs><quote>&lt;=</quote> | <quote>&lt;</quote> | <quote>==</quote>
469             | <quote>&gt;</quote> | <quote>&gt;=</quote></rhs>
470           </production>
471
472         </productionset>
473       </figure>
474       <para>
475         A <literal>String</literal> refers to a double-quoted string of
476         characters, while a <literal>Literal</literal> is not quoted.
477         <nonterminal def="#g-tag">Tags</nonterminal> may only consist of
478         letters, dashes and underscores, or variable interpolations. A Tag maybe
479         be optionally prepended with a category, separated by a colon. The
480         category itself follows he same lexical rules as the tag. A variable
481         interpolation can be one of the following:
482         <variablelist>
483           <varlistentry>
484             <term><literal>$1</literal>, <literal>$2</literal>,...</term>
485             <listitem><simpara> will be replaced by the respective group in the last
486               successfully applied regular expression in the conditions enclosing the
487               current rule.
488             </simpara></listitem>
489           </varlistentry>
490           <varlistentry>
491             <term><literal>$current.title</literal></term>
492             <term><literal>$current.program</literal></term>
493             <listitem><simpara> will be replaced by title the currently active
494               window, resp. by the name of the currently active program.
495               If no window happens to be active, this tag will be ignored.
496             </simpara></listitem>
497           </varlistentry>
498         </variablelist>
499       </para>
500
501       <para>
502         A regular expression is, like in perl, either enclosed in forward
503         slashes or, alternatively, in any character of your choice with an
504         <literal>m</literal> (for <quote>match</quote>) in front. This is handy if you need
505         to use regular expressions that match directory names. Otherwise, the
506         syntax of the regular expressions is that of perl-compatible regular
507         expressions.
508       </para>
509   </sect2>
510 </sect1>
511
512 <sect1 id="effective-use">
513   <title>Effective Use of Arbtt</title>
514   <para>
515     Now that the syntax has been describedand the toolbox laid out,
516     how do you practically go about using and configuring arbtt?
517   </para>
518   <sect2>
519     <title>Enabling data collection</title>
520     <para>
521       After installing arbtt, you need to configure it to run. There
522       are many ways you can run the <literal>arbtt-capture</literal>
523       daemon. One standard way is to include the command
524       <programlisting>
525 arbtt-capture &amp;
526       </programlisting>
527       in your desktop environments startup script, e.g.
528       <filename>~/.xinitrc</filename> or similar.
529     </para>
530     <para>
531       Another trick is ad dit as a <ulink
532       url="https://en.wikipedia.org/wiki/Cron"><literal>cron</literal></ulink>
533       job. To do so, edit your crontab file (<literal>crontab -e</literal>) and
534       add a line like this:
535     </para>
536     <programlisting>
537 DISPLAY=:0
538 @reboot arbtt-capture --logfile=/home/username/doc/arbtt/capture.log
539 </programlisting>
540     <para>
541       At boot, <literal>arbtt-capture</literal> will be run in the
542       background and will capture a snapshot of the X metadata for
543       active windows every 60 seconds (the default). If you want more
544       fine-grained time data at the expense of doubling storage use
545       you could increase the sampling rate with a command like
546       <literal>--sample-rate=30</literal>. To be resilient to any errors
547       or segfaults, you could also wrap it in an infinite loop to restart
548       the daemon should it ever crash, with a command like
549     </para>
550     <programlisting>
551 DISPLAY=:0
552 @reboot while true; do arbtt-capture --sample-rate=30; sleep 1m; done
553 </programlisting>
554   </sect2>
555   <sect2>
556     <title>Checking data availability</title>
557     <para>
558       arbtt tracks X properties like window title, class, and running
559       program, and you write rules to classify the strings as
560       you wish; but this assumes that the necessary data is present in
561       those properties.
562     </para>
563     <para>
564       For some programs, this is the case. For example, web browsers
565       like Firefox typically set the X title to the
566       <literal>&lt;title&gt;</literal> of the web page in the
567       currently-focused tab, which is enough for classification.
568     </para>
569     <para>
570       Some programs do not set titles or class, and all arbtt sees is
571       empty strings like &quot;&quot;; or they may set the title/class
572       to a constant like &quot;Liferea&quot;, which may be acceptable if
573       that program is used for only one purpose, but if it is used for
574       many purposes, then you cannot write a rule matching it without
575       producing highly-misleading time analyses. (For example, a web
576       browser may be used for countless purposes, ranging from work to
577       research to music to writing to programming; but if the web
578       browser's title/class were always just &quot;Web browser&quot;,
579       how would you classify 5 hours spent using the web browser? If the
580       5 hours are classified as any or all of those purposes, then the
581       results will be misleading garbage - you probably did not spend 5
582       hours just listening to music, but a mixture of those purposes,
583       which changes from day to day.)
584     </para>
585     <para>
586       You should check for such problematic programs upon starting using
587       arbtt. It would be unfortunate if you were to log for a few
588       months, go back for a detailed report for some reason, and
589       discover that the necessary data was never actually available for
590       arbtt to log!
591     </para>
592     <para>
593       These programs can sometimes be customized internally, a bug
594       report filed with the maintainers, or their titles can be
595       externally set by
596       <ulink url="https://en.wikipedia.org/wiki/Wmctrl"><literal>wmctrl</literal></ulink>
597       or
598       <ulink url="http://jonisalonen.com/2014/setting-x11-window-properties-with-xprop/"><literal>xprop</literal></ulink>.
599     </para>
600     <sect3>
601       <title><literal>xprop</literal></title>
602       <para>
603         You can check the X properties of a running window by running
604         the command
605         <ulink url="http://www.xfree86.org/current/xprop.1.html"><literal>xprop</literal></ulink>
606         and clicking on the window; <literal>xprop</literal> will print
607         out all the relevant X information. For example, the output for
608         Emacs might look like this
609       </para>
610       <programlisting>
611 $ xprop | tail -5
612 WM_CLASS(STRING) = &quot;emacs&quot;, &quot;Emacs&quot;
613 WM_ICON_NAME(STRING) = &quot;emacs@elan&quot;
614 _NET_WM_ICON_NAME(UTF8_STRING) = &quot;emacs@elan&quot;
615 WM_NAME(STRING) = &quot;emacs@elan&quot;
616 _NET_WM_NAME(UTF8_STRING) = &quot;emacs@elan&quot;
617 </programlisting>
618       <para>
619         This is not very helpful: it does not tell us the filename being
620         edited, the mode being used, or anything. You could classify
621         time spent in Emacs as &quot;programming&quot; or
622         &quot;writing&quot;, but this would be imperfect, especially if
623         you do both activities regularly. However, Emacs can be
624         customized by editing <literal>~/.emacs</literal>, and after
625         some searching with queries like &quot;setting Emacs window
626         title&quot;, the
627         <ulink url="http://www.emacswiki.org/emacs-en/FrameTitle">Emacs
628         wiki</ulink> and
629         <ulink url="https://www.gnu.org/software/emacs/manual/html_node/efaq/Displaying-the-current-file-name-in-the-titlebar.html">manual</ulink>
630         advise us to put something like this Elisp in our
631         <literal>.emacs</literal> file:
632       </para>
633       <programlisting>
634 (setq frame-title-format &quot;%f&quot;)
635 </programlisting>
636       <para>
637         Now the output looks different:
638       </para>
639       <programlisting>
640 $ xprop | tail -5
641 WM_CLASS(STRING) = &quot;emacs&quot;, &quot;Emacs&quot;
642 WM_ICON_NAME(STRING) = &quot;/home/gwern/arbtt.page&quot;
643 _NET_WM_ICON_NAME(UTF8_STRING) = &quot;/home/gwern/arbtt.page&quot;
644 WM_NAME(STRING) = &quot;/home/gwern/arbtt.page&quot;
645 _NET_WM_NAME(UTF8_STRING) = &quot;/home/gwern/arbtt.page&quot;
646 </programlisting>
647       <para>
648         With this, we can usefully classify all such time samples as
649         being “writing”.
650       </para>
651       <para>
652         Another common gap is terminals/shells: they often do not
653         include information in the title like the current working
654         directory or last shell command. For example, urxvt/Bash:
655       </para>
656       <programlisting>
657 WM_COMMAND(STRING) = { &quot;urxvt&quot; }
658 _NET_WM_ICON_NAME(UTF8_STRING) = &quot;urxvt&quot;
659 WM_ICON_NAME(STRING) = &quot;urxvt&quot;
660 _NET_WM_NAME(UTF8_STRING) = &quot;urxvt&quot;
661 WM_NAME(STRING) = &quot;urxvt&quot;
662 </programlisting>
663       <para>
664         Programmers may spend many hours in the shell doing a variety of
665         things (like Emacs), so this is a problem. Fortunately, this is
666         also solvable by customizing one's <literal>.bashrc</literal> to
667         set the prompt to emit an escape code interpreted by the
668         terminal (baroque, but it works). The following will include the
669         working directory, a timestamp, and the last command:
670       </para>
671       <programlisting>
672 trap 'echo -ne &quot;\033]2;$(pwd); $(history 1 | sed &quot;s/^[ ]*[0-9]*[ ]*//g&quot;)\007&quot;' DEBUG
673 </programlisting>
674       <para>
675         Now the urxvt samples are useful:
676       </para>
677       <programlisting>
678 _NET_WM_NAME(UTF8_STRING) = &quot;/home/gwern/wiki; 2014-09-03 13:39:32 arbtt-stats --help&quot;
679 </programlisting>
680       <para>
681         Some distributions (e.g. Debian) already provide the relevant
682         configuration for this to happen. If it does not work for you, you can try to add
683         <programlisting>. /etc/profile.d/vte.sh</programlisting>
684         to your <filename>~/.bashrc</filename>.
685       </para>
686       <para>
687         A rule could classify based on the directory you are working in,
688         the command one ran, or both. Other shells like zsh can be fixed
689         this way too but the exact command may differ; you will need to
690         research and experiment.
691       </para>
692       <para>
693         Some programs can be tricky to set. The
694         <ulink url="http://feh.finalrewind.org/">X image viewer
695         feh</ulink> has a <literal>--title</literal> option but it
696         cannot be set in the configuration file,
697         <literal>.config/feh/themes</literal>, because it needs to be
698         specified dynamically; so you need to set up a shell alias or
699         script to wrap the command like
700         <literal>feh --title &quot;$(pwd) / %f / %n&quot;</literal>.
701       </para>
702     </sect3>
703     <sect3>
704       <title>Raw samples</title>
705       <para>
706         <literal>xprop</literal> can be tedious to use on every running
707         window and you may forget to check seldomly used programs. A better
708         approach is to use <literal>arbtt-stats</literal>’s
709         <literal>--dump-samples</literal> option: this option will print
710         out the collected data for specified time periods, allowing you
711         to examine the X properties en masse. This option can be used
712         with the <literal>--exclude=</literal>
713         option to print the samples for <emphasis>samples not matched
714         by existing rules</emphasis> as well, which is indispensable for
715         improving coverage and suggesting ideas for new rules. A good
716         way to figure out what customizations to make is to run arbtt as
717         a daemon for a day or so, and then begin examining the raw
718         samples for problems.
719       </para>
720       <example>
721       <title>An initial configuration session</title>
722       <para>
723         An example: suppose I create a simple category file named
724         <literal>foo</literal> with just the line
725       </para>
726       <programlisting>
727 $idle &gt; 30 ==&gt; tag inactive
728 </programlisting>
729       <para>
730         I can then dump all my arbtt samples for the past day with a
731         command like this:
732       </para>
733       <programlisting>
734 arbtt-stats --categorizefile=foo --m=0 --filter='$sampleage &lt;24:00' --dump-samples
735 </programlisting>
736       <para>
737         Because there are so many open windows, this produces a large
738         amount (26586 lines) of hard-to-read output:
739       </para>
740       <programlisting>
741 ...
742 ( ) Navigator:      /r/Touhou's Favorite Arranges! Part 71: Retribution for the Eternal Night ~ Imperishable Night : touhou - Iceweasel
743 ( ) Navigator:      Configuring the arbtt categorizer (arbtt-stats) - Iceweasel
744 ( ) evince:         ATTACHMENT02
745 ( ) evince:         2009-geisler.pdf — Heart rate variability predicts self-control in goal pursuit
746 ( ) urxvt:          /home/gwern; arbtt-stats --categorizefile=foo --m=0 --filter='$sampleage &lt;24:00' --dump-samples
747 ( ) mnemosyne:      Mnemosyne
748 ( ) urxvt:          /home/gwern; 2014-09-03 13:11:45 xprop
749 ( ) urxvt:          /home/gwern; 2014-09-03 13:42:17 history 1 | cut --delimiter=' ' --fields=5-
750 ( ) urxvt:          /home/gwern; 2014-09-03 13:12:21 git log -p .emacs
751 (*) emacs:          emacs@elan
752 ( ) urxvt:          /home/gwern; 2014-09-01 14:50:30 while true; do cd ~/ &amp;&amp; getmail_fetch --ssl pop.gmail.com gwern0 'ugaozoumbhwcijxb' ./mail/; done
753 ( ) urxvt:          /home/gwern/blackmarket-mirrors/silkroad2-forums; 2014-08-31 23:20:10 mv /home/gwern/cookies.txt ./; http_proxy=&quot;localhost:8118&quot; wget...
754 ( ) urxvt:          /home/gwern/blackmarket-mirrors/agora; 2014-08-31 23:15:50 mv /home/gwern/cookies.txt ./; http_proxy=&quot;localhost:8118&quot; wget --mirror ...
755 ( ) urxvt:          /home/gwern/blackmarket-mirrors/evolution-forums; 2014-08-31 23:04:10 mv ~/cookies.txt ./; http_proxy=&quot;localhost:8118&quot; wget --mirror ...
756 ( ) puddletag:      puddletag: /home/gwern/music
757 </programlisting>
758       <para>
759         Active windows are denoted by an asterisk, so I can focus &amp;
760         simplify by adding a pipe like <literal>| fgrep '(*)'</literal>,
761         producing more manageable output like
762       </para>
763       <programlisting>
764 (*) urxvt:          irssi
765 (*) urxvt:          irssi
766 (*) urxvt:          irssi
767 (*) Navigator:      Pyramid of Technology - NextNature.net - Iceweasel
768 (*) Navigator:      Search results - gwern0@gmail.com - Gmail - Iceweasel
769 (*) Navigator:      [New comment] The Wrong Path - gwern0@gmail.com - Gmail - Iceweasel
770 (*) Navigator:      Iceweasel
771 (*) Navigator:      Litecoin Exchange Rate - $4.83 USD - litecoinexchangerate.org - Iceweasel
772 (*) Navigator:      PredictionBook: LiteCoin will trade at &gt;=10 USD per ltc in 2 years, - Iceweasel
773 (*) urxvt:          irssi
774 (*) Navigator:      Bug#691547 closed by Mikhail Gusarov &lt;dottedmag@dottedmag.net&gt; (Re: s3cmd: Man page: --default-mime-type documentation incomplete...)
775 (*) Navigator:      Bug#691547 closed by Mikhail Gusarov &lt;dottedmag@dottedmag.net&gt; (Re: s3cmd: Man page: --default-mime-type documentation incomplete...)
776 (*) Navigator:      Bug#691547 closed by Mikhail Gusarov &lt;dottedmag@dottedmag.net&gt; (Re: s3cmd: Man page: --default-mime-type documentation incomplete...)
777 (*) urxvt:          /home/gwern; 2014-09-02 14:25:17 man s3cmd
778 (*) evince:         bayesiancausality.pdf
779 (*) evince:         bayesiancausality.pdf
780 (*) puddletag:      puddletag: /home/gwern/music
781 (*) puddletag:      puddletag: /home/gwern/music
782 (*) evince:         bayesiancausality.pdf
783 (*) Navigator:      ▶ Umineko no Naku Koro ni Music Box 4 - オルガン小曲 第2億番 ハ短調 - YouTube - Iceweasel
784 ...
785 </programlisting>
786       <para>
787         This is better. We can see a few things: the windows all now
788         produce enough information to be usefully classified (Gmail can
789         be classified under email, irssi can be classified as IRC, the
790         urxvt usage can clearly be classified as programming, the PDF
791         being read is statistics, etc) in part because of customizations
792         to bash/urxvt. The duplication still impedes focus, and we don't
793         know what's most common. We can use another pipeline to sort,
794         count duplicates, and sort by number of duplicates
795         (<literal>| sort | uniq --count | sort --general-numeric-sort</literal>),
796         yielding:
797       </para>
798       <programlisting>
799  ...
800  14     (*) Navigator:      A Bluer Shade of White Chapter 4, a frozen fanfic | FanFiction - Iceweasel
801  14     (*) Navigator:      Iceweasel
802  15     (*) evince:         2009-geisler.pdf — Heart rate variability predicts self-control in goal pursuit
803  15     (*) Navigator:      Tool use by animals - Wikipedia, the free encyclopedia - Iceweasel
804  16     (*) Navigator:      Hacker News | Add Comment - Iceweasel
805  17     (*) evince:         bayesiancausality.pdf
806  17     (*) Navigator:      Comments - Less Wrong Discussion - Iceweasel
807  17     (*) Navigator:      Keith Gessen · Why not kill them all?: In Donetsk · LRB 11 September 2014 - Iceweasel
808  17     (*) Navigator:      Notes on the Celebrity Data Theft | Hacker News - Iceweasel
809  18     (*) Navigator:      A Bluer Shade of White Chapter 1, a frozen fanfic | FanFiction - Iceweasel
810  19     (*) gl:             mplayer2
811  19     (*) Navigator:      Neural networks and deep learning - Iceweasel
812  20     (*) Navigator:      Harry Potter and the Philosopher's Zombie, a harry potter fanfic | FanFiction - Iceweasel
813  20     (*) Navigator:      [OBNYC] Time tracking app - gwern0@gmail.com - Gmail - Iceweasel
814  25     (*) evince:         ps2007.pdf — untitled
815  35     (*) emacs:          /home/gwern/arbtt.page
816  43     (*) Navigator:      CCC comments on The Octopus, the Dolphin and Us: a Great Filter tale - Less Wrong - Iceweasel
817  62     (*) evince:         The physics of information processing superobjects - Anders Sandberg - 1999.pdf — Brains2
818  69     (*) liferea:        Liferea
819  82     (*) evince:         BMS_raftery.pdf — untitled
820  84     (*) emacs:          emacs@elan
821  87     (*) Navigator:      overview for gwern - Iceweasel
822 109     (*) puddletag:      puddletag: /home/gwern/music
823 150     (*) urxvt:          irssi
824 </programlisting>
825       <para>
826         Put this way, we can see what rules we should write to
827         categorize: we could categorize the activities here into a few
828         categories of &quot;recreational&quot;, &quot;statistics&quot;,
829         &quot;music&quot;, &quot;email&quot;, &quot;IRC&quot;,
830         &quot;research&quot;, and &quot;writing&quot;; and add to the
831         <literal>categorize.cfg</literal> some rules like thus:
832       </para>
833       <programlisting>
834 $idle &gt; 30 ==&gt; tag inactive,
835
836 current window $title =~ [/.*Hacker News.*/, /.*Less Wrong.*/, /.*overview for gwern.*/, /.*[fF]an[fF]ic.*/, /.* LRB .*/]
837   || current window $program == &quot;liferea&quot; ==&gt; tag Recreation,
838 current window $title =~ [/.*puddletag.*/, /.*mplayer2.*/] ==&gt; tag Music,
839 current window $title =~ [/.*[bB]ayesian.*/, /.*[nN]eural [nN]etworks.*/, /.*ps2007.pdf.*/, /.*[Rr]aftery.*/] ==&gt; tag Statistics,
840 current window $title =~ [/.*Wikipedia.*/, /.*Heart rate variability.*/, /.*Anders Sandberg.*/] ==&gt; tag Research,
841 current window $title =~ [/.*Gmail.*/] ==&gt; tag Email,
842 current window $title =~ [/.*arbtt.*/] ==&gt; tag Writing,
843 current window $title == &quot;irssi&quot; ==&gt; tag IRC,
844 </programlisting>
845       <para>
846         If we reran the command, we'd see the same output, so we need to
847         leverage our new rules and <emphasis>exclude</emphasis> any
848         samples matching our current tags, so now we run a command like:
849       </para>
850       <programlisting>
851 arbtt-stats --categorizefile=foo --filter='$sampleage &lt;24:00' --dump-samples --exclude=Recreation --exclude=Music --exclude=Statistics
852              --exclude=Research --exclude=Email --exclude=Writing --exclude=IRC |
853              fgrep '(*)' | sort | uniq --count | sort --general-numeric-sort
854 </programlisting>
855       <para>
856         Now the previous samples disappear, leaving us with a fresh
857         batch of unclassified samples to work with:
858       </para>
859       <programlisting>
860   9     (*) Navigator:      New Web Order &gt; Nik Cubrilovic - - Notes on the Celebrity Data Theft - Iceweasel
861   9     ( ) urxvt:          /home/gwern; arbtt-stats --categorizefile=foo --filter='$sampleage &lt;24:00' --dump-samples | fgrep '(*)' | less
862  10     (*) evince:         ATTACHMENT02
863  10     (*) Navigator:      These Giant Copper Orbs Show Just How Much Metal Comes From a Mine | Design | WIRED - Iceweasel
864  12     (*) evince:         [Jon_Elster]_Alchemies_of_the_Mind_Rationality_an(BookFi.org).pdf — Alchemies of the mind
865  12     (*) Navigator:      Morality Quiz/Test your Morals, Values &amp; Ethics - YourMorals.Org - Iceweasel
866  33     ( ) urxvt:          /home/gwern; arbtt-stats --categorizefile=foo --filter='$sampleage &lt;24:00' --dump-samples | fgrep '(*)'...
867 </programlisting>
868       <para>
869         We can add rules categorizing these as 'Recreational',
870         'Writing', 'Research', 'Recreational', 'Research', 'Writing',
871         and 'Writing' respectively; and we might decide at this point
872         that 'Writing' is starting to become overloaded, so we'll split
873         it into two tags, 'Writing' and 'Programming'. And then after
874         tossing another <literal>--exclude=Programming</literal> into
875         our rules, we can repeat the process.
876       </para>
877       <para>
878         As we refine our rules, we will quickly spot instances where the
879         title/class/program are insufficient to allow accurate
880         classification, and we will figure out the best collection of
881         tags for our particular purposes. A few iterations is enough for
882         most purposes.
883       </para>
884       </example>
885     </sect3>
886   </sect2>
887   <sect2>
888     <title>Categorizing advice</title>
889     <para>
890       When building up rules, a few rules of thumb should be kept in
891       mind:
892     </para>
893     <orderedlist numeration="arabic">
894       <listitem>
895         <para>
896           categorize by purpose, not by program
897         </para>
898         <para>
899           This leads to misleading time reports. Avoid, for example,
900           lumping all web browser time into a single category named
901           'Internet'; this is more misleading than helpful. Good
902           categories describe an activity or goal, such as 'Work' or
903           'Recreation', not a tool, like 'Emacs' or 'Vim'.
904         </para>
905       </listitem>
906       <listitem>
907         <para>
908           when in doubt, write narrow rules and generalize later
909         </para>
910         <para>
911           Regexps are tricky and it can be easy to write rules far
912           broader than one intended. The <literal>--exclude</literal>
913           filters mean that one will never see samples which are matched
914           accidentally. If one is in doubt, it can be helpful to take a
915           specific sample one wants to match and several similar strings
916           and look at how well one's regexp rule works in Emacs's
917           <ulink url="http://www.emacswiki.org/emacs/ReBuilder">regexp-builder</ulink>
918           or online regexp-testers like
919           <ulink url="http://regexpal.com/">regexpal</ulink>.
920         </para>
921       </listitem>
922       <listitem>
923         <para>
924           don't try to classify everything
925         </para>
926         <para>
927           You will never classify 100% of samples because sometimes
928           programs do not include useful X properties and cannot be
929           fixed, you have samples from before you fixed them, or they
930           are too transient (like popups and dialogues) to be worth
931           fixing. It is not necessary to classify 100% of your time,
932           since as long as the most common programs and, say,
933           <ulink url="https://en.wikipedia.org/wiki/Pareto_principle">80%</ulink>
934           of your time is classified, then you have most of the value.
935           It is easy to waste more time tweaking arbtt than one gains
936           from increased accuracy or more finely-grained tags.
937         </para>
938       </listitem>
939     </orderedlist>
940   </sect2>
941   <sect2>
942     <title>Long-term storage</title>
943     <para>
944       Each halving of the sampling rate doubles the number of samples
945       taken and hence the storage requirement; sampling rates below 20s
946       are probably wasteful. But even the default 60s can accumulate
947       into a nontrivial amount of data over a year. A
948       constantly-changing binary file can interact poorly with backup
949       systems, may make arbtt analyses slower, and if one's system
950       occasionally crashes or experiences other problems, cause some
951       corruption of the log and be a nuisance in having to run
952       <literal>arbtt-recover</literal>.
953     </para>
954     <para>
955       Thus it may be a good idea to archive one's
956       <literal>capture.log</literal> on an annual basis. If one needs to
957       query the historical data, the particular log file can be
958       specified as an option like
959       <literal>--logfile=/home/gwern/doc/arbtt/2013-2014.log</literal>
960     </para>
961   </sect2>
962   <sect2>
963     <title>External processing of arbtt statistics</title>
964     <para>
965       arbtt supports CSV export of time by category in various levels of
966       granularity in a 'long' format (multiple rows for each day, with
967       <emphasis>n</emphasis> row specifying a category's value for that
968       day). These CSV exports can be imported into statistical programs
969       like R or Excel and manipulated as desired.
970     </para>
971     <para>
972       R users may prefer to have their time data in a 'wide' format
973       (each row is 1 day, with <emphasis>n</emphasis> columns for each
974       possible category); this can be done with the
975       <literal>reshape</literal> default library. After reading in the
976       CSV, the time-intervals can be converted to counts and the data to
977       a wide data-frame with R code like the following:
978     </para>
979     <programlisting>
980 arbtt &lt;- read.csv(&quot;arbtt.csv&quot;)
981 interval &lt;- function(x) { if (!is.na(x)) { if (grepl(&quot; s&quot;,x)) as.integer(sub(&quot; s&quot;,&quot;&quot;,x))
982                                           else { y &lt;- unlist(strsplit(x, &quot;:&quot;));
983                                                  as.integer(y[[1]])*3600 + as.integer(y[[2]])*60 + as.integer(y[[3]]); }
984                                                  }
985                          else NA
986                          }
987 arbtt$Time &lt;- sapply(as.character(arbtt$Time), interval)
988 library(reshape)
989 arbtt &lt;- reshape(arbtt, v.names=&quot;Time&quot;, timevar=&quot;Tag&quot;, idvar=&quot;Day&quot;, direction=&quot;wide&quot;)
990 </programlisting>
991   </sect2>
992 </sect1>
993 <sect1 id="references">
994   <title>Program references</title>
995   <para>arbtt consists of a few command line tools, the most important one is
996   <command>arbtt-stats</command>. This overview is followed by their manual
997   pages.
998   </para>
999
1000   <!-- <sect2>
1001     <title>Generating statistics</title> -->
1002     <para>To generate statistics about the data that
1003     <command>arbtt-capture</command> has gathered, use the program
1004     <command>arbtt-stats</command>. A detailed description of the possible
1005     options is given in <xref linkend="arbtt-stats"/>.</para>
1006   <!--
1007   </sect2>
1008
1009   <sect2>
1010     <title>Gathering data</title>
1011   -->
1012     <para>The collection of data is done by <command>arbtt-capture</command>.
1013     Usually, you only set it up once to run automatically, as described in <xref
1014     linkend="installation"/>, and do not have to
1015     worry about it again. Its command line reference is given in <xref
1016     linkend="arbtt-capture"/>.</para>
1017   <!--
1018   </sect2>
1019
1020   <sect2>
1021     <title>Dumping data</title>
1022   -->
1023     <para>Because the data log file is binary, a tool names
1024     <command>arbtt-dump</command> can bee used to dump the data in
1025     various textual formats. Its command line reference is given in <xref
1026     linkend="arbtt-dump"/>.</para>
1027
1028     <para>If <command>arbtt-capture</command> crashes it might be that the log
1029     file is not readable any more. In some cases, this can be fixed using the
1030     (relatively raw) <command>arbtt-recover</command> tool. Its command line
1031     reference is given in <xref linkend="arbtt-recover"/>.</para>
1032   <!--
1033   </sect2>
1034   -->
1035
1036
1037   <refentry id="arbtt-stats">
1038     <refmeta>
1039       <refentrytitle>arbtt-stats</refentrytitle>
1040       <manvolnum>1</manvolnum>
1041       <refmiscinfo class="source">arbtt manual</refmiscinfo>
1042     </refmeta>
1043
1044     <refnamediv>
1045       <refname>arbtt-stats</refname>
1046       <refpurpose>generate statistics from the arbtt data samples</refpurpose>
1047     </refnamediv>
1048
1049     <refsynopsisdiv>
1050       <cmdsynopsis>
1051         <command>arbtt-stats</command>
1052         <arg rep="repeat">OPTION</arg>
1053       </cmdsynopsis>
1054     </refsynopsisdiv>
1055
1056     <refsect1><title>Description</title>
1057       <para>
1058       <command>arbtt-stats</command> reads the samples that were recorded so far
1059       by <command>arbtt-capture</command> from the log file, filters them
1060       according to the users specifications and generates one or more reports
1061       from the data.
1062       </para>
1063       <para>
1064       When run without any options, <option>--total-time</option> is assumed.
1065       </para>
1066       <para>
1067       The order in which filters (<option>--exclude</option>,
1068       <option>--only</option>, <option>--also-inactive</option> and
1069       <option>--filter</option>) and reports are passed to the program is
1070       irrelevant: All filters given on the command line are active for all
1071       reports.
1072       </para>
1073     </refsect1>
1074
1075     <refsect1><title>Options</title>
1076       <variablelist>
1077         <varlistentry>
1078           <term><option>-h</option></term>
1079           <term><option>-?</option></term>
1080           <term><option>--help</option></term>
1081           <listitem><simpara>shows a short summary of the available
1082           options, and exists.</simpara></listitem>
1083         </varlistentry>
1084         <varlistentry>
1085         <term><option>-V</option></term>
1086         <term><option>--version</option></term>
1087         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1088         </varlistentry>
1089         <varlistentry>
1090         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
1091         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1092         </varlistentry>
1093         <varlistentry>
1094         <term><option>--categorizefile</option></term>
1095         <listitem><simpara>categorize file to use instead of <filename>~/.arbtt/categorize.cfg</filename></simpara></listitem>
1096         </varlistentry>
1097       </variablelist>
1098       <refsect2><title>Filtering options</title>
1099         <variablelist>
1100           <varlistentry>
1101             <term><option>-x</option> <replaceable>TAG</replaceable></term>
1102             <term><option>--exclude</option> <replaceable>TAG</replaceable></term>
1103             <listitem><simpara>Ignore any data samples that have
1104             been assigned this tag or category. To distinguish tags and categories, the latter have to be
1105             entered followed by a colon. Can be given more than once.</simpara></listitem>
1106           </varlistentry>
1107           <varlistentry>
1108             <term><option>-o</option> <replaceable>TAG</replaceable></term>
1109             <term><option>--only</option> <replaceable>TAG</replaceable></term>
1110             <listitem><simpara>Ignore any data samples that have
1111             not been assigned this tag. To distinguish tags and categories, the latter have to be
1112             entered followed by a colon. Can be given more than once.</simpara></listitem>
1113           </varlistentry>
1114           <varlistentry>
1115             <term><option>--also-inactive</option></term>
1116             <listitem><simpara>by default, <command>arbtt-stats</command> ignores
1117             any samples which have been assigned the tag
1118             <literal>inactive</literal>. This flag disables this behaviour.</simpara></listitem>
1119           </varlistentry>
1120           <varlistentry>
1121             <term><option>-f</option> <replaceable>CONDITION</replaceable></term>
1122             <term><option>--filter</option> <replaceable>CONDITION</replaceable></term>
1123             <listitem><simpara>Only consider samples matching
1124             the given condition, which follows the same syntax as in
1125             <filename>categorize.cfg</filename> (Nonterminal <nonterminal def="#g-cond"/> in
1126             <phrase condition="html"><xref linkend="grammar"/></phrase><phrase condition="man">the formal grammar specification found in the user guide</phrase>).</simpara></listitem>
1127           </varlistentry>
1128         </variablelist>
1129       </refsect2>
1130       <refsect2><title>Report options</title>
1131         <variablelist>
1132           <varlistentry>
1133             <term><option>-m</option> <replaceable>PERCENTAGE</replaceable></term>
1134             <term><option>--min-percentage</option> <replaceable>PERCENTAGE</replaceable></term>
1135             <listitem><para>
1136               Ignore tags whose percentage is less than the value specified
1137               here. Default percentage: 1%.
1138             </para></listitem>
1139           </varlistentry>
1140           <varlistentry>
1141             <term><option>--output-exclude</option> <replaceable>TAG</replaceable></term>
1142             <listitem><para>
1143               Skip this tag or category when printing statistics. Only affects
1144               the reports <option>--total-time</option> and
1145               <option>--category</option>. To distinguish tags and categories,
1146               the latter have to be entered followed by a colon. Can be given
1147               more than once.
1148             </para></listitem>
1149           </varlistentry>
1150           <varlistentry>
1151             <term><option>--output-only</option> <replaceable>TAG</replaceable></term>
1152             <listitem><para>
1153               Prints statistics only for the specified tag or category. Only
1154               affects the reports <option>--total-time</option> and
1155               <option>--category</option>. To distinguish tags and categories,
1156               the latter have to be entered followed by a colon. Can be given
1157               more than once.
1158             </para></listitem>
1159           </varlistentry>
1160           <varlistentry>
1161             <term><option>--output-format</option> <replaceable>FORMAT</replaceable></term>
1162             <listitem><para>
1163               Specify the report output format, may be one of: text, csv
1164               (comma-separated values), tsv (TAB-separated values).
1165               Default format: text.
1166             </para></listitem>
1167           </varlistentry>
1168         </variablelist>
1169       </refsect2>
1170       <refsect2><title>Reports</title>
1171         <variablelist>
1172           <varlistentry>
1173             <term><option>-i</option></term>
1174             <term><option>--information</option></term>
1175             <listitem><para>
1176               Various bits of information about the recorded data, such as total
1177               time recorded, number of records etc. In this report, <quote>time
1178               recorded</quote> is the sum of <emphasis>all</emphasis>
1179               samples, including inactive and those that are disabled by the
1180               filter, while <quote>time selected</quote> is the sum of the
1181               samples that are matched by the given filters.
1182             </para></listitem>
1183           </varlistentry>
1184           <varlistentry>
1185             <term><option>-t</option></term>
1186             <term><option>--total-time</option></term>
1187             <listitem><para>For all tags, print the part of the selected time
1188             with this tag applied to, both as an absolute value and a percentage
1189             of the selected time.
1190             </para></listitem>
1191           </varlistentry>
1192           <varlistentry>
1193             <term><option>-c</option> <replaceable>CATEGORY</replaceable></term>
1194             <term><option>--category</option> <replaceable>CATEGORY</replaceable></term>
1195             <listitem><para>For the given category, give the textual equivalent
1196             of a pie chart: For each possible value of the category, including
1197             one for <quote>no tag of this category present</quote>, give the absolute time and
1198             fraction. Entries which are not displayed because of the option
1199             <option>--min-percentage</option> are aggregated.</para></listitem>
1200           </varlistentry>
1201           <varlistentry>
1202             <term><option>--each-category</option></term>
1203             <listitem><para>This is just a shortcut for a series of
1204             <option>--category</option> options, one for each category found in
1205             the data.
1206             </para></listitem>
1207           </varlistentry>
1208           <varlistentry>
1209             <term><option>--intervals</option> [<replaceable>TAG</replaceable>|<replaceable>CATEGORY</replaceable>:] </term>
1210             <listitem><para>This report lists all periods of consecutive time
1211             intervals where the given tag has been applied to, or where the
1212             given category has the same value.
1213             </para>
1214
1215             <para>To distinguish tags and categories, the latter have to be
1216             entered followed by a colon.</para>
1217
1218             <para>This report will give wrong results if an activity has been
1219             carried out at the end of a session and right at the beginning, as
1220             the intermediate time is thought to be part of the interval.
1221             Inactive times while <command>arbtt-capture</command> is running
1222             will separate the results as expected.</para>
1223
1224             </listitem>
1225           </varlistentry>
1226           <varlistentry>
1227             <term><option>--for-each</option> <replaceable>PERIOD</replaceable></term>
1228             <listitem><para>This is not a report of its own, but causes the selected
1229             report to be executed for each of the given PERIOD (which can be
1230             minute, hour,day, month or year) where there exist selected
1231             samples. All the reports will then be printed one after another or,
1232             in the case of CSV output, with an additional column.</para>
1233
1234             <para>Note that if this option is enabled, samples that are filtered out
1235             are completely ignored (to avoid empty reports for periods with
1236             only filtered samples). Therefore, the
1237             <option>--information</option> report will print the numbers for
1238             the samples selected also for the totals.</para>
1239
1240             </listitem>
1241           </varlistentry>
1242         </variablelist>
1243       </refsect2>
1244     </refsect1>
1245
1246     <refsect1><title>Examples</title>
1247       <para>Some useful examples of what you can do with
1248       <command>arbtt-stats</command> are provided here:</para>
1249       <screen># Only consider the time when I was programming in Haskell
1250 arbtt-stats -o Editing-Haskell
1251
1252 # Tell me what evolution folders I spend my time in when I actually do
1253 # work with e-Mail
1254 arbtt-stats -o Program:evolution -c Evo-Folder
1255
1256 # Generate statistics about the last hour
1257 arbtt-stats -f '$sampleage &lt; 1:00'</screen>
1258     </refsect1>
1259
1260     <refsect1><title>Files</title>
1261       <variablelist>
1262         <varlistentry>
1263           <term><filename>~/.arbtt/capture.log</filename></term>
1264           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1265         </varlistentry>
1266         <varlistentry>
1267           <term><filename>~/.arbtt/categorize.cfg</filename></term>
1268           <listitem><para>specification of the arbtt categorizer syntax. A
1269           detailed description is given in <xref linkend="configuration"/></para></listitem>
1270         </varlistentry>
1271       </variablelist>
1272     </refsect1>
1273
1274     <refsect1><title>See also</title>
1275       <para>See the arbtt manual for more information and the <ulink
1276       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1277       newer versions of arbtt.</para>
1278     </refsect1>
1279   </refentry>
1280
1281   <refentry id="arbtt-capture">
1282     <refmeta>
1283       <refentrytitle>arbtt-capture</refentrytitle>
1284       <manvolnum>1</manvolnum>
1285       <refmiscinfo class="source">arbtt manual</refmiscinfo>
1286     </refmeta>
1287
1288     <refnamediv>
1289       <refname>arbtt-capture</refname>
1290       <refpurpose>collect data samples for arbtt</refpurpose>
1291     </refnamediv>
1292
1293     <refsynopsisdiv>
1294       <cmdsynopsis>
1295         <command>arbtt-capture</command>
1296         <arg rep="repeat">OPTION</arg>
1297       </cmdsynopsis>
1298     </refsynopsisdiv>
1299
1300     <refsect1><title>Description</title>
1301       <para>
1302       <command>arbtt-capture</command> runs continuously and saves at the given
1303       sample rate, usually once per minute, the collected data to
1304       <filename>~/.arbtt/capture.log</filename>.
1305       </para>
1306     </refsect1>
1307
1308     <refsect1><title>Options</title>
1309       <variablelist>
1310         <varlistentry>
1311           <term><option>-h</option></term>
1312           <term><option>-?</option></term>
1313           <term><option>--help</option></term>
1314           <listitem><simpara>shows a short summary of the available
1315           options, and exists.</simpara></listitem>
1316         </varlistentry>
1317         <varlistentry>
1318         <term><option>-V</option></term>
1319         <term><option>--version</option></term>
1320         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1321         </varlistentry>
1322         <varlistentry>
1323         <term><option>-r</option> <replaceable>RATE</replaceable></term>
1324         <term><option>--sample-rate</option> <replaceable>RATE</replaceable></term>
1325         <listitem><simpara>sets the sample rate in seconds (default: 60)</simpara></listitem>
1326         </varlistentry>
1327         <varlistentry>
1328         <term><option>-f</option> <replaceable>FILE</replaceable></term>
1329         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
1330         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1331         </varlistentry>
1332         <varlistentry>
1333         <term><option>-d</option></term>
1334         <term><option>--dump</option></term>
1335         <listitem><simpara>dump one current sample instead of modifying the logfile</simpara></listitem>
1336         </varlistentry>
1337       </variablelist>
1338     </refsect1>
1339     <refsect1><title>Files</title>
1340       <variablelist>
1341         <varlistentry>
1342           <term><filename>~/.arbtt/capture.log</filename></term>
1343           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1344         </varlistentry>
1345       </variablelist>
1346     </refsect1>
1347
1348
1349     <refsect1><title>See also</title>
1350       <para>See the arbtt manual for more information and the <ulink
1351       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1352       newer versions of arbtt.</para>
1353     </refsect1>
1354   </refentry>
1355
1356   <refentry id="arbtt-dump">
1357     <refmeta>
1358       <refentrytitle>arbtt-dump</refentrytitle>
1359       <manvolnum>1</manvolnum>
1360       <refmiscinfo class="source">arbtt manual</refmiscinfo>
1361     </refmeta>
1362
1363     <refnamediv>
1364       <refname>arbtt-dump</refname>
1365       <refpurpose>dumps arbtt data samples</refpurpose>
1366     </refnamediv>
1367
1368     <refsynopsisdiv>
1369       <cmdsynopsis>
1370         <command>arbtt-dump</command>
1371         <arg rep="repeat">OPTION</arg>
1372       </cmdsynopsis>
1373     </refsynopsisdiv>
1374
1375     <refsect1><title>Description</title>
1376       <para>
1377       <command>arbtt-dump</command> reads the data samples recorded by <xref
1378       linkend="arbtt-capture"/> and writes them so the standard output in an
1379       ascii based format.
1380       </para>
1381     </refsect1>
1382
1383     <refsect1><title>Options</title>
1384       <variablelist>
1385         <varlistentry>
1386           <term><option>-h</option></term>
1387           <term><option>-?</option></term>
1388           <term><option>--help</option></term>
1389           <listitem><simpara>shows a short summary of the available
1390           options, and exists.</simpara></listitem>
1391         </varlistentry>
1392         <varlistentry>
1393         <term><option>-V</option></term>
1394         <term><option>--version</option></term>
1395         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1396         </varlistentry>
1397         <varlistentry>
1398         <term><option>-f</option> <replaceable>FILE</replaceable></term>
1399         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
1400         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1401         </varlistentry>
1402         <varlistentry>
1403         <term><option>-t</option> <replaceable>FORMAT</replaceable></term>
1404         <term><option>--format</option> <replaceable>FORMAT</replaceable></term>
1405         <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>
1406         </varlistentry>
1407         <varlistentry>
1408         <term><option>-l</option> <replaceable>NUMBER</replaceable></term>
1409         <term><option>--last</option> <replaceable>NUMBER</replaceable></term>
1410         <listitem><simpara>dump only the last <replaceable>NUMBER</replaceable> of samples.</simpara></listitem>
1411         </varlistentry>
1412       </variablelist>
1413     </refsect1>
1414
1415     <refsect1><title>Files</title>
1416       <variablelist>
1417         <varlistentry>
1418           <term><filename>~/.arbtt/capture.log</filename></term>
1419           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1420         </varlistentry>
1421       </variablelist>
1422     </refsect1>
1423
1424     <refsect1><title>Formats</title>
1425       <refsect2><title>Human</title>
1426       <para>This format is intended for human inspection, but not for further
1427       processing. Hence, it may change in new versions of arbtt without notice.
1428       Example output:</para>
1429       <screen>2013-06-20 14:53:50 (48ms inactive):
1430     ( ) Navigator:      arbtt-dump - Iceweasel
1431     ( ) gnome-terminal-server: jojo@kirk:~/projekte/programming/arbtt/doc
1432     (*) gvim:           arbtt.xml + (~/projekte/programming/arbtt/doc) - GVIM2
1433 </screen>
1434       <para>The line with a star indicates the currently active window.</para>
1435       </refsect2>
1436
1437       <refsect2><title>Show</title>
1438       <para>This is the default serialization format of Haskell's
1439       <literal>Show</literal> type class, one entry per line. This can be
1440       useful if the data is to be processed by further Haskell code. Example
1441       output, with indentation added manually:</para>
1442       <screen>TimeLogEntry
1443     { tlTime = 2013-06-20 14:53:50.957763 UTC
1444     , tlRate = 60000
1445     , tlData = CaptureData
1446         { cWindows =
1447             [ (False,"arbtt-dump - Iceweasel","Navigator")
1448             , (False,"jojo@kirk:~/projekte/programming/arbtt/doc","gnome-terminal-server")
1449             , (True,"arbtt.xml + (~/projekte/programming/arbtt/doc) - GVIM2","gvim")
1450             ]
1451         , cLastActivity = 48
1452         }
1453     }</screen>
1454       </refsect2>
1455
1456       <refsect2><title>JSON</title>
1457       <para>For interoperability, arbtt supports dumping its data to JSON, which can
1458       easily be parsed by many different programming languages. Some level of
1459       backward-compatibility will be provided, as far as possible. Default
1460       output, again with indentation and spacing added manually:</para>
1461       <screen>[ ...,
1462   { "windows": [
1463       { "program": "arbtt-dump - Iceweasel",
1464         "title": "Navigator",
1465         "active": false},
1466       { "program": "jojo@kirk:~/projekte/programming/arbtt/doc",
1467         "title":" gnome-terminal-server",
1468         "active": false},
1469       { "program": "arbtt.xml + (~/projekte/programming/arbtt/doc) - GVIM2",
1470         "title": "gvim",
1471         "active":true
1472       }],
1473     "inactive": 48,
1474     "date": "2013-06-20T14:53:50.957Z",
1475     "rate": 60000},
1476   ...
1477 ]</screen>
1478       </refsect2>
1479     </refsect1>
1480
1481     <refsect1><title>See also</title>
1482       <para>See the arbtt manual for more information and the <ulink
1483       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1484       newer versions of arbtt.</para>
1485     </refsect1>
1486   </refentry>
1487
1488   <refentry>
1489     <refnamediv>
1490       <refname>arbtt-import</refname>
1491       <refpurpose>imports dumped arbtt data samples</refpurpose>
1492     </refnamediv>
1493
1494     <refsynopsisdiv>
1495       <cmdsynopsis>
1496         <command>arbtt-import</command>
1497         <arg rep="repeat">OPTION</arg>
1498       </cmdsynopsis>
1499     </refsynopsisdiv>
1500
1501     <refsect1><title>Description</title>
1502       <para>
1503       <command>arbtt-import</command> expects the output of
1504       <command>arbtt-dump</command> on the standard input and saves them as the
1505       logfile or the specified file.
1506       </para>
1507       <para>
1508       This program would completely override the existing file, therefore it
1509       will refuse to work if the log file already exists. If you want to
1510       overwrite a file, please delete it before running
1511       <command>arbtt-import</command>.
1512       </para>
1513     </refsect1>
1514
1515     <refsect1><title>Options</title>
1516       <variablelist>
1517         <varlistentry>
1518           <term><option>-h</option></term>
1519           <term><option>-?</option></term>
1520           <term><option>--help</option></term>
1521           <listitem><simpara>shows a short summary of the available
1522           options, and exists.</simpara></listitem>
1523         </varlistentry>
1524         <varlistentry>
1525         <term><option>-V</option></term>
1526         <term><option>--version</option></term>
1527         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1528         </varlistentry>
1529         <varlistentry>
1530         <term><option>-f</option> <replaceable>FILE</replaceable></term>
1531         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
1532         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1533         </varlistentry>
1534       </variablelist>
1535     </refsect1>
1536     <refsect1><title>Files</title>
1537       <variablelist>
1538         <varlistentry>
1539           <term><filename>~/.arbtt/capture.log</filename></term>
1540           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1541         </varlistentry>
1542       </variablelist>
1543     </refsect1>
1544
1545     <refsect1><title>See also</title>
1546       <para>See the arbtt manual for more information and the <ulink
1547       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1548       newer versions of arbtt.</para>
1549     </refsect1>
1550   </refentry>
1551
1552   <refentry id="arbtt-recover">
1553     <refmeta>
1554       <refentrytitle>arbtt-recover</refentrytitle>
1555       <manvolnum>1</manvolnum>
1556       <refmiscinfo class="source">arbtt manual</refmiscinfo>
1557     </refmeta>
1558
1559     <refnamediv>
1560       <refname>arbtt-recover</refname>
1561       <refpurpose>tries to recover a broken arbtt data log</refpurpose>
1562     </refnamediv>
1563
1564     <refsynopsisdiv>
1565       <cmdsynopsis>
1566         <command>arbtt-recover</command>
1567         <arg rep="repeat">OPTION</arg>
1568       </cmdsynopsis>
1569     </refsynopsisdiv>
1570
1571     <refsect1><title>Description</title>
1572       <para>
1573       <command>arbtt-recover</command> tries to read the data samples recorded
1574       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>.
1575       </para>
1576       <para>
1577       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.
1578       </para>
1579     </refsect1>
1580
1581     <refsect1><title>Options</title>
1582       <variablelist>
1583         <varlistentry>
1584           <term><option>-h</option></term>
1585           <term><option>-?</option></term>
1586           <term><option>--help</option></term>
1587           <listitem><simpara>shows a short summary of the available
1588           options, and exists.</simpara></listitem>
1589         </varlistentry>
1590         <varlistentry>
1591         <term><option>-V</option></term>
1592         <term><option>--version</option></term>
1593         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1594         </varlistentry>
1595         <varlistentry>
1596         <term><option>-i</option></term>
1597         <term><option>--infile</option></term>
1598         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1599         </varlistentry>
1600         <varlistentry>
1601         <term><option>-o</option></term>
1602         <term><option>--outfile</option></term>
1603         <listitem><simpara>where to save the recovered file, instead of <filename>~/.arbtt/capture.log.recovered</filename></simpara></listitem>
1604         </varlistentry>
1605       </variablelist>
1606     </refsect1>
1607     <refsect1><title>Files</title>
1608       <variablelist>
1609         <varlistentry>
1610           <term><filename>~/.arbtt/capture.log</filename></term>
1611           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1612         </varlistentry>
1613         <varlistentry>
1614           <term><filename>~/.arbtt/capture.log.recovered</filename></term>
1615           <listitem><para>binary file, storing the fixed arbtt data samples</para></listitem>
1616         </varlistentry>
1617       </variablelist>
1618     </refsect1>
1619
1620     <refsect1><title>See also</title>
1621       <para>See the arbtt manual for more information and the <ulink
1622       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1623       newer versions of arbtt.</para>
1624     </refsect1>
1625   </refentry>
1626 </sect1>
1627
1628 <sect1 id="troubleshooting">
1629   <title>Troubleshooting</title>
1630   <sect2>
1631     <title>arbtt and xmonad</title>
1632     <para>
1633       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>.
1634     </para>
1635   </sect2>
1636 </sect1>
1637
1638 <sect1 id="copyright">
1639   <title>Copyright and Contact</title>
1640   <para>
1641   arbtt is Copyright © 2009-2010 Joachim Breitner
1642   </para>
1643
1644   <para>
1645     arbtt does not have a bug tracker yet. If you have bug reports, suggestions
1646     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>.
1647   </para>
1648
1649   <sect2>
1650     <title>arbtt License</title>
1651     <para>
1652     <literallayout>
1653 This program is free software; you can redistribute it and/or modify
1654 it under the terms of the GNU General Public License as published by
1655 the Free Software Foundation; either version 2 of the License, or
1656 (at your option) any later version.
1657
1658 This program is distributed in the hope that it will be useful,
1659 but WITHOUT ANY WARRANTY; without even the implied warranty of
1660 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1661 GNU General Public License for more details.
1662
1663 You should have received a copy of the GNU General Public License
1664 along with this program; if not, write to the Free Software
1665 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
1666     </literallayout>
1667     </para>
1668   </sect2>
1669 </sect1>
1670
1671 <sect1 id="release-notes">
1672   <title>Release Notes</title>
1673   <para>
1674   The version history with changes relevant for the user is documented here.
1675   </para>
1676
1677   <sect2 id="release-notes-0.9">
1678     <title>Version 0.9 (unreleased)</title>
1679     <itemizedlist>
1680       <listitem>
1681         <para>
1682           The <option>--for-each</option> option of
1683           <command>arbtt-stats</command> now supports grouping results by
1684           minute or hour.
1685         </para>
1686       </listitem>
1687       <listitem>
1688         <para>
1689           Gwern Branwen contributed the <xref linkend="effective-use"/>.
1690         </para>
1691       </listitem>
1692     </itemizedlist>
1693   </sect2>
1694
1695   <sect2 id="release-notes-0.8.1">
1696     <title>Version 0.8.1</title>
1697     <itemizedlist>
1698       <listitem>
1699         <para>
1700           The syntax now allows for time differences larger than 99:99.
1701           (<ulink url="https://bitbucket.org/nomeata/arbtt/issue/14/improve-time-categorization-directives">issue #14</ulink>)
1702         </para>
1703       </listitem>
1704     </itemizedlist>
1705   </sect2>
1706
1707   <sect2 id="release-notes-0.8">
1708     <title>Version 0.8</title>
1709     <itemizedlist>
1710       <listitem>
1711         <para>
1712           <command>arbtt-dump</command> can now show the data in other formats
1713           as well, as suggested by Waldir Pimenta (option
1714           <option>--format</option>). This includes a human-readale output and
1715           JSON.
1716         </para>
1717       </listitem>
1718       <listitem>
1719         <para>New option <option>--last</option> of <command>arbtt-dump</command>.</para>
1720       </listitem>
1721       <listitem>
1722         <para><command>arbtt-recover</command> can handle larger datasets with a reasonable amount of memory.</para>
1723       </listitem>
1724       <listitem>
1725         <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>
1726       </listitem>
1727       <listitem>
1728         <para><command>arbtt-capture</command> now supports the option <option>--dump</option> for development and debugging purposes.</para>
1729       </listitem>
1730       <listitem>
1731         <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>
1732       </listitem>
1733       <listitem>
1734         <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>
1735       </listitem>
1736       <listitem>
1737         <para><command>arbtt-stats</command> can print reports split by time interval, using the <option>--for-each</option> option.</para>
1738       </listitem>
1739       <listitem>
1740         <para><command>arbtt-stats</command> can print the actual samples selected, with <option>--dump-samples</option>.</para>
1741       </listitem>
1742       <listitem>
1743         <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>
1744       </listitem>
1745       <listitem>
1746         <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>
1747       </listitem>
1748       <listitem>
1749         <para>Waldir Pimenta contributed a new web page, hosted at <ulink url="http://arbtt.nomeata.de/">arbtt.nomeata.de</ulink>.</para>
1750       </listitem>
1751     </itemizedlist>
1752   </sect2>
1753
1754   <sect2>
1755     <title>Version 0.7</title>
1756     <itemizedlist>
1757       <listitem>
1758         <para>Make sure that the log file is only readable by the current user. Thanks to Joey Hess for pointing that out.</para>
1759       </listitem>
1760       <listitem>
1761         <para>Show a progress bar in <command>arbtt-stats</command>.</para>
1762       </listitem>
1763       <listitem>
1764         <para>GHC-7.6 compatibility, thanks to Isaac Dupree.</para>
1765       </listitem>
1766     </itemizedlist>
1767   </sect2>
1768
1769   <sect2>
1770     <title>Version 0.6.4.1</title>
1771     <itemizedlist>
1772       <listitem>
1773         <para>
1774         Added missing module to the packages.
1775         </para>
1776       </listitem>
1777     </itemizedlist>
1778   </sect2>
1779
1780   <sect2>
1781     <title>Version 0.6.4</title>
1782     <itemizedlist>
1783       <listitem>
1784         <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>
1785       </listitem>
1786     </itemizedlist>
1787   </sect2>
1788
1789   <sect2>
1790     <title>Version 0.6.3</title>
1791     <itemizedlist>
1792       <listitem>
1793         <para>Performance improvements.</para>
1794       </listitem>
1795       <listitem>
1796         <para>Support comparing a string to a list of strings, or matching it against a list ofregular expressions.</para>
1797       </listitem>
1798     </itemizedlist>
1799   </sect2>
1800
1801   <sect2>
1802     <title>Version 0.6.2</title>
1803     <itemizedlist>
1804       <listitem>
1805         <para>Add a warning whtn the system locale is not supported.</para>
1806       </listitem>
1807       <listitem>
1808         <para>Allwo RTS options to be passed to the arbtt binaries.</para>
1809       </listitem>
1810       <listitem>
1811         <para>GHC 7.4 compatibility.</para>
1812       </listitem>
1813     </itemizedlist>
1814   </sect2>
1815
1816   <sect2>
1817     <title>Version 0.6.1</title>
1818     <itemizedlist>
1819       <listitem>
1820         <para>Performance improvements.</para>
1821       </listitem>
1822     </itemizedlist>
1823   </sect2>
1824
1825   <sect2>
1826     <title>Version 0.6</title>
1827     <itemizedlist>
1828       <listitem>
1829         <para>The command <command>arbtt-capture</command> now supports the
1830         <option>--logfile</option>.
1831         </para>
1832       </listitem>
1833       <listitem>
1834         <para>New report “intervals”, available using <command>arbtt-stats</command> <option>--intervals</option>.
1835         </para>
1836       </listitem>
1837       <listitem>
1838         <para>The paramters <option>--exclude</option> and
1839         <option>--include</option> of <command>arbtt-stats</command> can match
1840         categories as well as tags.
1841         </para>
1842       </listitem>
1843       <listitem>
1844         <para>Bugfix: Numbers in tag names are no longer replaced by an underscore.</para>
1845       </listitem>
1846       <listitem>
1847         <para>New paramters <option>--output-exclude</option> and
1848         <option>--output-include</option> of <command>arbtt-stats</command>.
1849         </para>
1850       </listitem>
1851     </itemizedlist>
1852   </sect2>
1853
1854   <sect2>
1855     <title>Version 0.5 (The ZuriHac-Release)</title>
1856     <itemizedlist>
1857       <listitem>
1858         <para>New command <command>arbtt-import</command>, which imports the output from <command>arbtt-dump</command>.
1859         </para>
1860       </listitem>
1861       <listitem>
1862         <para>The command <command>arbtt-stats</command> now supports the
1863         <option>--logfile</option> and <option>--categorizefile</option> as well.
1864         (<xref linkend="martin"/>)
1865         </para>
1866       </listitem>
1867       <listitem>
1868         <para>
1869           The command <command>arbtt-stats</command> now supports the csv
1870           (comma-separated values) and tsv (TAB-separated values) report output
1871           formats in addition to text.
1872           (<xref linkend="muharem"/>)
1873         </para>
1874       </listitem>
1875       <listitem>
1876         <para>
1877           Unicode is handled correctly in regular expressions.
1878         </para>
1879       </listitem>
1880       <listitem>
1881         <para>
1882           Improved date-handling functions for <filename>categorize.cfg</filename>.
1883           (<xref linkend="sergey"/>)
1884         </para>
1885       </listitem>
1886     </itemizedlist>
1887   </sect2>
1888
1889   <sect2>
1890     <title>Version 0.4.5.1</title>
1891     <itemizedlist>
1892       <listitem>
1893         <para>Bugfix: Added missing modules to the cabal file.
1894         </para>
1895       </listitem>
1896     </itemizedlist>
1897   </sect2>
1898
1899   <sect2>
1900     <title>Version 0.4.5</title>
1901     <itemizedlist>
1902       <listitem>
1903         <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.
1904         </para>
1905       </listitem>
1906     </itemizedlist>
1907   </sect2>
1908
1909   <sect2>
1910     <title>Version 0.4.4</title>
1911     <itemizedlist>
1912       <listitem>
1913         <para>Bugfix: Correctly parse a tag name containing a colon when passed to <command>arbtt-stats</command> <option>--exclude</option>.</para>
1914       </listitem>
1915       <listitem>
1916         <para>Bugfix: Only warn once when the <token>_NET_CLIENT_LIST</token> X property is not set for the root window.</para>
1917       </listitem>
1918     </itemizedlist>
1919   </sect2>
1920
1921
1922   <sect2>
1923     <title>Version 0.4.3</title>
1924     <itemizedlist>
1925       <listitem>
1926         <para>Use fetchName from xmonad instead of xFetchName, as it works with unicode characters in window titles.</para>
1927       </listitem>
1928     </itemizedlist>
1929   </sect2>
1930
1931   <sect2>
1932     <title>Version 0.4.2</title>
1933     <itemizedlist>
1934       <listitem>
1935         <para>Implement option <option>--logfile</option> to
1936         <command>arbtt-dump</command>.</para>
1937       </listitem>
1938       <listitem>
1939         <para>New command <command>arbtt-recover</command> to rescue data from
1940         a proken data log file.</para>
1941       </listitem>
1942       <listitem>
1943         <para>Actually include this documentation in the released tarball.</para>
1944       </listitem>
1945     </itemizedlist>
1946   </sect2>
1947
1948   <sect2>
1949     <title>Version 0.4.1</title>
1950     <itemizedlist>
1951       <listitem>
1952         <para>Write this documentation</para>
1953       </listitem>
1954       <listitem>
1955         <para>Drop dependency on setlocale: Copy the SetLocale module.</para>
1956       </listitem>
1957       <listitem>
1958         <para>Drop dependency on tabular: Implement custom table rendering code.</para>
1959       </listitem>
1960       <listitem>
1961         <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>
1962       </listitem>
1963     </itemizedlist>
1964   </sect2>
1965
1966   <sect2>
1967     <title>Version 0.4</title>
1968     <itemizedlist>
1969       <listitem>
1970         <para>Implement option <option>--each-categories</option> to
1971         <command>arbtt-stats</command></para>
1972       </listitem>
1973       <listitem>
1974         <para>Eliminate one possible cause for crashes of
1975         <command>arbtt-capture</command>.</para>
1976       </listitem>
1977     </itemizedlist>
1978   </sect2>
1979
1980   <sect2>
1981     <title>Version 0.3.0</title>
1982     <itemizedlist>
1983       <listitem>
1984         <para>Switch to binary log file format, for greatly increased speed</para>
1985       </listitem>
1986       <listitem>
1987         <para><command>arbtt-capture</command> will automatically detect and
1988         convert log files in the old format.</para>
1989       </listitem>
1990     </itemizedlist>
1991   </sect2>
1992
1993   <sect2>
1994     <title>Version 0.2.0</title>
1995     <itemizedlist>
1996       <listitem>
1997         <para>Add option <option>--filter</option> to
1998         <command>arbtt-stats</command></para>
1999       </listitem>
2000       <listitem>
2001         <para>Add option <option>--sample-rate</option> to
2002         <command>arbtt-capture</command></para>
2003       </listitem>
2004       <listitem>
2005         <para>Introduce time-base variables <literal>$time</literal> and
2006         <literal>$sampleage</literal></para>
2007       </listitem>
2008     </itemizedlist>
2009   </sect2>
2010
2011   <sect2>
2012     <title>Version 0.1.5</title>
2013     <itemizedlist>
2014       <listitem>
2015         <para>Use <function>setlocale</function> to get umlauts in window titles correctly</para>
2016       </listitem>
2017     </itemizedlist>
2018   </sect2>
2019
2020   <sect2>
2021     <title>Version 0.1.4</title>
2022     <itemizedlist>
2023       <listitem>
2024         <para>Be smarter when figuring out what window is active. Thanks to CJ
2025         van den Berg for investigating the issue.</para>
2026       </listitem>
2027     </itemizedlist>
2028   </sect2>
2029
2030   <sect2>
2031     <title>Version 0.1.3</title>
2032     <itemizedlist>
2033       <listitem><para>Read <literal>_NET_CLIENT_LIST</literal> for the list of
2034       applications, for compatibility with window managers such as metacity</para></listitem>
2035     </itemizedlist>
2036   </sect2>
2037
2038   <sect2>
2039     <title>Version 0.1.2</title>
2040     <itemizedlist>
2041       <listitem><para>Off-By-Ten error in the time display</para></listitem>
2042       <listitem><para>Correctly show total number of records in
2043       <option>--information</option></para></listitem>
2044     </itemizedlist>
2045   </sect2>
2046
2047   <sect2>
2048     <title>Version 0.1.1</title>
2049     <para>
2050     Rename files to allow building on MacOS.
2051     </para>
2052   </sect2>
2053
2054   <sect2>
2055     <title>Version 0.1</title>
2056     <para>
2057     Initial release of arbtt
2058     </para>
2059   </sect2>
2060 </sect1>
2061
2062 </article>