arbtt.xml: effective use: +irssi solution
[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 described and 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 add it 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 an option 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 <ulink url="https://en.wikipedia.org/wiki/X_Window_System_protocols_and_architecture#Attributes_and_properties"
559       >X</ulink> properties like window title, class, and running
560       program, and you write rules to classify those strings as
561       you wish; but this assumes that the necessary data is present in
562       those properties.
563     </para>
564     <para>
565       For some programs, this is the case. For example, web browsers
566       like Firefox typically set the X title to the
567       HTML <literal>&lt;title&gt;</literal> element of the web page in the
568       currently-focused tab, which is enough for classification.
569     </para>
570     <para>
571       Some programs have title-setting available as plugins. The IRC client <ulink url="http://www.irssi.org/">irssi</ulink>
572       in a GNU screen or X terminal usually sets the title to just "<literal>irssi</literal>",
573       which blocks more accurate time-classification based on IRC channel (one channel may be for
574       recreation, another for programming, and yet another for work), but can be easily configured
575       to set the title using the extension
576       <ulink url="http://scripts.irssi.org/scripts/title.pl"><literal>title.pl</literal></ulink>.
577     </para>
578     <para>
579       Some programs do not set titles or class, and all arbtt sees is
580       empty strings like <literal>&quot;&quot;</literal>; or they may set the title/class
581       to a constant like <literal>&quot;Liferea&quot;</literal>, which may be acceptable if
582       that program is used for only one purpose, but if it is used for
583       many purposes, then you cannot write a rule matching it without
584       producing highly-misleading time analyses. (For example, a web
585       browser may be used for countless purposes, ranging from work to
586       research to music to writing to programming; but if the web
587       browser's title/class were always just <literal>&quot;Web browser&quot;</literal>,
588       how would you classify 5 hours spent using the web browser? If the
589       5 hours are classified as any or all of those purposes, then the
590       results will be misleading garbage - you probably did not spend 5
591       hours just listening to music, but a mixture of those purposes,
592       which changes from day to day.)
593     </para>
594     <para>
595       You should check for such problematic programs upon starting using
596       arbtt. It would be unfortunate if you were to log for a few
597       months, go back for a detailed report for some reason, and
598       discover that the necessary data was never available for
599       arbtt to log!
600     </para>
601     <para>
602       These programs can sometimes be customized internally, a bug
603       report filed with the maintainers, or their titles can be
604       externally set by
605       <ulink url="https://en.wikipedia.org/wiki/Wmctrl"><literal>wmctrl</literal></ulink>
606       or
607       <ulink url="http://jonisalonen.com/2014/setting-x11-window-properties-with-xprop/"><literal>xprop</literal></ulink>.
608     </para>
609     <sect3>
610       <title><literal>xprop</literal></title>
611       <para>
612         You can check the X properties of a running window by running
613         the command
614         <ulink url="http://www.xfree86.org/current/xprop.1.html"><literal>xprop</literal></ulink>
615         and clicking on the window; <literal>xprop</literal> will print
616         out all the relevant X information. For example, the output for
617         Emacs might look like this
618       </para>
619       <programlisting>
620 $ xprop | tail -5
621 WM_CLASS(STRING) = &quot;emacs&quot;, &quot;Emacs&quot;
622 WM_ICON_NAME(STRING) = &quot;emacs@elan&quot;
623 _NET_WM_ICON_NAME(UTF8_STRING) = &quot;emacs@elan&quot;
624 WM_NAME(STRING) = &quot;emacs@elan&quot;
625 _NET_WM_NAME(UTF8_STRING) = &quot;emacs@elan&quot;
626 </programlisting>
627       <para>
628         This is not very helpful: it does not tell us the filename being
629         edited, the mode being used, or anything. You could classify
630         time spent in Emacs as &quot;programming&quot; or
631         &quot;writing&quot;, but this would be imperfect, especially if
632         you do both activities regularly. However, Emacs can be
633         customized by editing <literal>~/.emacs</literal>, and after
634         some searching with queries like &quot;setting Emacs window
635         title&quot;, the
636         <ulink url="http://www.emacswiki.org/emacs-en/FrameTitle">Emacs
637         wiki</ulink> and
638         <ulink url="https://www.gnu.org/software/emacs/manual/html_node/efaq/Displaying-the-current-file-name-in-the-titlebar.html">manual</ulink>
639         advise us to put something like this Elisp in our
640         <literal>.emacs</literal> file:
641       </para>
642       <programlisting>
643 (setq frame-title-format &quot;%f&quot;)
644 </programlisting>
645       <para>
646         Now the output looks different:
647       </para>
648       <programlisting>
649 $ xprop | tail -5
650 WM_CLASS(STRING) = &quot;emacs&quot;, &quot;Emacs&quot;
651 WM_ICON_NAME(STRING) = &quot;/home/gwern/arbtt.page&quot;
652 _NET_WM_ICON_NAME(UTF8_STRING) = &quot;/home/gwern/arbtt.page&quot;
653 WM_NAME(STRING) = &quot;/home/gwern/arbtt.page&quot;
654 _NET_WM_NAME(UTF8_STRING) = &quot;/home/gwern/arbtt.page&quot;
655 </programlisting>
656       <para>
657         With this, we can usefully classify all such time samples as
658         being “writing”:
659       </para>
660 <programlisting>
661 current window $title == &quot;/home/gwern/arbtt.page&quot; ==> tag Writing,
662 </programlisting>
663       <para>
664         Another common gap is terminals/shells: they often do not
665         include information in the title like the current working
666         directory or last shell command. For example, urxvt/Bash:
667       </para>
668       <programlisting>
669 WM_COMMAND(STRING) = { &quot;urxvt&quot; }
670 _NET_WM_ICON_NAME(UTF8_STRING) = &quot;urxvt&quot;
671 WM_ICON_NAME(STRING) = &quot;urxvt&quot;
672 _NET_WM_NAME(UTF8_STRING) = &quot;urxvt&quot;
673 WM_NAME(STRING) = &quot;urxvt&quot;
674 </programlisting>
675       <para>
676         Programmers may spend many hours in the shell doing a variety of
677         things (like Emacs), so this is a problem. Fortunately, this is
678         also solvable by customizing one's <literal>.bashrc</literal> to
679         set the prompt to emit an escape code interpreted by the
680         terminal (baroque, but it works). The following will include the
681         working directory, a timestamp, and the last command:
682       </para>
683       <programlisting>
684 trap 'echo -ne &quot;\033]2;$(pwd); $(history 1 | sed &quot;s/^[ ]*[0-9]*[ ]*//g&quot;)\007&quot;' DEBUG
685 </programlisting>
686       <para>
687         Now the urxvt samples are useful:
688       </para>
689       <programlisting>
690 _NET_WM_NAME(UTF8_STRING) = &quot;/home/gwern/wiki; 2014-09-03 13:39:32 arbtt-stats --help&quot;
691 </programlisting>
692       <para>
693     Some distributions (e.g. Debian) already provide the relevant
694     configuration for this to happen. If it does not work for you, you can try to add
695     <programlisting>. /etc/profile.d/vte.sh</programlisting>
696     to your <filename>~/.bashrc</filename>.
697       </para>
698       <para>
699         A rule could classify based on the directory you are working in,
700         the command one ran, or both. Other shells like zsh can be fixed
701         this way too but the exact command may differ; you will need to
702         research and experiment.
703       </para>
704       <para>
705         Some programs can be tricky to set. The
706         <ulink url="http://feh.finalrewind.org/">X image viewer
707         feh</ulink> has a <literal>--title</literal> option but it
708         cannot be set in the configuration file,
709         <literal>.config/feh/themes</literal>, because it needs to be
710         specified dynamically; so you need to set up a shell alias or
711         script to wrap the command like
712         <literal>feh --title &quot;$(pwd) / %f / %n&quot;</literal>.
713       </para>
714     </sect3>
715     <sect3>
716       <title>Raw samples</title>
717       <para>
718         <literal>xprop</literal> can be tedious to use on every running
719         window and you may forget to check seldomly used programs. A better
720         approach is to use <literal>arbtt-stats</literal>’s
721         <literal>--dump-samples</literal> option: this option will print
722         out the collected data for specified time periods, allowing you
723         to examine the X properties en masse. This option can be used
724         with the <literal>--exclude=</literal>
725         option to print the samples for <emphasis>samples not matched
726         by existing rules</emphasis> as well, which is indispensable for
727         improving coverage and suggesting ideas for new rules. A good
728         way to figure out what customizations to make is to run arbtt as
729         a daemon for a day or so, and then begin examining the raw
730         samples for problems.
731       </para>
732       <example>
733       <title>An initial configuration session</title>
734       <para>
735         An example: suppose I create a simple category file named
736         <literal>foo</literal> with just the line
737       </para>
738       <programlisting>
739 $idle &gt; 30 ==&gt; tag inactive
740 </programlisting>
741       <para>
742         I can then dump all my arbtt samples for the past day with a
743         command like this:
744       </para>
745       <programlisting>
746 arbtt-stats --categorizefile=foo --m=0 --filter='$sampleage &lt;24:00' --dump-samples
747 </programlisting>
748       <para>
749         Because there are so many open windows, this produces a large
750         amount (26586 lines) of hard-to-read output:
751       </para>
752       <programlisting>
753 ...
754 ( ) Navigator:      /r/Touhou's Favorite Arranges! Part 71: Retribution for the Eternal Night ~ Imperishable Night : touhou - Iceweasel
755 ( ) Navigator:      Configuring the arbtt categorizer (arbtt-stats) - Iceweasel
756 ( ) evince:         ATTACHMENT02
757 ( ) evince:         2009-geisler.pdf — Heart rate variability predicts self-control in goal pursuit
758 ( ) urxvt:          /home/gwern; arbtt-stats --categorizefile=foo --m=0 --filter='$sampleage &lt;24:00' --dump-samples
759 ( ) mnemosyne:      Mnemosyne
760 ( ) urxvt:          /home/gwern; 2014-09-03 13:11:45 xprop
761 ( ) urxvt:          /home/gwern; 2014-09-03 13:42:17 history 1 | cut --delimiter=' ' --fields=5-
762 ( ) urxvt:          /home/gwern; 2014-09-03 13:12:21 git log -p .emacs
763 (*) emacs:          emacs@elan
764 ( ) 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
765 ( ) 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...
766 ( ) 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 ...
767 ( ) urxvt:          /home/gwern/blackmarket-mirrors/evolution-forums; 2014-08-31 23:04:10 mv ~/cookies.txt ./; http_proxy=&quot;localhost:8118&quot; wget --mirror ...
768 ( ) puddletag:      puddletag: /home/gwern/music
769 </programlisting>
770       <para>
771         Active windows are denoted by an asterisk, so I can focus &amp;
772         simplify by adding a pipe like <literal>| fgrep '(*)'</literal>,
773         producing more manageable output like
774       </para>
775       <programlisting>
776 (*) urxvt:          irssi
777 (*) urxvt:          irssi
778 (*) urxvt:          irssi
779 (*) Navigator:      Pyramid of Technology - NextNature.net - Iceweasel
780 (*) Navigator:      Search results - gwern0@gmail.com - Gmail - Iceweasel
781 (*) Navigator:      [New comment] The Wrong Path - gwern0@gmail.com - Gmail - Iceweasel
782 (*) Navigator:      Iceweasel
783 (*) Navigator:      Litecoin Exchange Rate - $4.83 USD - litecoinexchangerate.org - Iceweasel
784 (*) Navigator:      PredictionBook: LiteCoin will trade at &gt;=10 USD per ltc in 2 years, - Iceweasel
785 (*) urxvt:          irssi
786 (*) Navigator:      Bug#691547 closed by Mikhail Gusarov &lt;dottedmag@dottedmag.net&gt; (Re: s3cmd: Man page: --default-mime-type documentation incomplete...)
787 (*) Navigator:      Bug#691547 closed by Mikhail Gusarov &lt;dottedmag@dottedmag.net&gt; (Re: s3cmd: Man page: --default-mime-type documentation incomplete...)
788 (*) Navigator:      Bug#691547 closed by Mikhail Gusarov &lt;dottedmag@dottedmag.net&gt; (Re: s3cmd: Man page: --default-mime-type documentation incomplete...)
789 (*) urxvt:          /home/gwern; 2014-09-02 14:25:17 man s3cmd
790 (*) evince:         bayesiancausality.pdf
791 (*) evince:         bayesiancausality.pdf
792 (*) puddletag:      puddletag: /home/gwern/music
793 (*) puddletag:      puddletag: /home/gwern/music
794 (*) evince:         bayesiancausality.pdf
795 (*) Navigator:      ▶ Umineko no Naku Koro ni Music Box 4 - オルガン小曲 第2億番 ハ短調 - YouTube - Iceweasel
796 ...
797 </programlisting>
798       <para>
799         This is better. We can see a few things: the windows all now
800         produce enough information to be usefully classified (Gmail can
801         be classified under email, irssi can be classified as IRC, the
802         urxvt usage can clearly be classified as programming, the PDF
803         being read is statistics, etc) in part because of customizations
804         to bash/urxvt. The duplication still impedes focus, and we don't
805         know what's most common. We can use another pipeline to sort,
806         count duplicates, and sort by number of duplicates
807         (<literal>| sort | uniq --count | sort --general-numeric-sort</literal>),
808         yielding:
809       </para>
810       <programlisting>
811  ...
812  14     (*) Navigator:      A Bluer Shade of White Chapter 4, a frozen fanfic | FanFiction - Iceweasel
813  14     (*) Navigator:      Iceweasel
814  15     (*) evince:         2009-geisler.pdf — Heart rate variability predicts self-control in goal pursuit
815  15     (*) Navigator:      Tool use by animals - Wikipedia, the free encyclopedia - Iceweasel
816  16     (*) Navigator:      Hacker News | Add Comment - Iceweasel
817  17     (*) evince:         bayesiancausality.pdf
818  17     (*) Navigator:      Comments - Less Wrong Discussion - Iceweasel
819  17     (*) Navigator:      Keith Gessen · Why not kill them all?: In Donetsk · LRB 11 September 2014 - Iceweasel
820  17     (*) Navigator:      Notes on the Celebrity Data Theft | Hacker News - Iceweasel
821  18     (*) Navigator:      A Bluer Shade of White Chapter 1, a frozen fanfic | FanFiction - Iceweasel
822  19     (*) gl:             mplayer2
823  19     (*) Navigator:      Neural networks and deep learning - Iceweasel
824  20     (*) Navigator:      Harry Potter and the Philosopher's Zombie, a harry potter fanfic | FanFiction - Iceweasel
825  20     (*) Navigator:      [OBNYC] Time tracking app - gwern0@gmail.com - Gmail - Iceweasel
826  25     (*) evince:         ps2007.pdf — untitled
827  35     (*) emacs:          /home/gwern/arbtt.page
828  43     (*) Navigator:      CCC comments on The Octopus, the Dolphin and Us: a Great Filter tale - Less Wrong - Iceweasel
829  62     (*) evince:         The physics of information processing superobjects - Anders Sandberg - 1999.pdf — Brains2
830  69     (*) liferea:        Liferea
831  82     (*) evince:         BMS_raftery.pdf — untitled
832  84     (*) emacs:          emacs@elan
833  87     (*) Navigator:      overview for gwern - Iceweasel
834 109     (*) puddletag:      puddletag: /home/gwern/music
835 150     (*) urxvt:          irssi
836 </programlisting>
837       <para>
838         Put this way, we can see what rules we should write to
839         categorize: we could categorize the activities here into a few
840         categories of &quot;recreational&quot;, &quot;statistics&quot;,
841         &quot;music&quot;, &quot;email&quot;, &quot;IRC&quot;,
842         &quot;research&quot;, and &quot;writing&quot;; and add to the
843         <literal>categorize.cfg</literal> some rules like thus:
844       </para>
845       <programlisting>
846 $idle &gt; 30 ==&gt; tag inactive,
847
848 current window $title =~ [/.*Hacker News.*/, /.*Less Wrong.*/, /.*overview for gwern.*/, /.*[fF]an[fF]ic.*/, /.* LRB .*/]
849   || current window $program == &quot;liferea&quot; ==&gt; tag Recreation,
850 current window $title =~ [/.*puddletag.*/, /.*mplayer2.*/] ==&gt; tag Music,
851 current window $title =~ [/.*[bB]ayesian.*/, /.*[nN]eural [nN]etworks.*/, /.*ps2007.pdf.*/, /.*[Rr]aftery.*/] ==&gt; tag Statistics,
852 current window $title =~ [/.*Wikipedia.*/, /.*Heart rate variability.*/, /.*Anders Sandberg.*/] ==&gt; tag Research,
853 current window $title =~ [/.*Gmail.*/] ==&gt; tag Email,
854 current window $title =~ [/.*arbtt.*/] ==&gt; tag Writing,
855 current window $title == &quot;irssi&quot; ==&gt; tag IRC,
856 </programlisting>
857       <para>
858         If we reran the command, we'd see the same output, so we need to
859         leverage our new rules and <emphasis>exclude</emphasis> any
860         samples matching our current tags, so now we run a command like:
861       </para>
862       <programlisting>
863 arbtt-stats --categorizefile=foo --filter='$sampleage &lt;24:00' --dump-samples --exclude=Recreation --exclude=Music --exclude=Statistics
864              --exclude=Research --exclude=Email --exclude=Writing --exclude=IRC |
865              fgrep '(*)' | sort | uniq --count | sort --general-numeric-sort
866 </programlisting>
867       <para>
868         Now the previous samples disappear, leaving us with a fresh
869         batch of unclassified samples to work with:
870       </para>
871       <programlisting>
872   9     (*) Navigator:      New Web Order &gt; Nik Cubrilovic - - Notes on the Celebrity Data Theft - Iceweasel
873   9     ( ) urxvt:          /home/gwern; arbtt-stats --categorizefile=foo --filter='$sampleage &lt;24:00' --dump-samples | fgrep '(*)' | less
874  10     (*) evince:         ATTACHMENT02
875  10     (*) Navigator:      These Giant Copper Orbs Show Just How Much Metal Comes From a Mine | Design | WIRED - Iceweasel
876  12     (*) evince:         [Jon_Elster]_Alchemies_of_the_Mind_Rationality_an(BookFi.org).pdf — Alchemies of the mind
877  12     (*) Navigator:      Morality Quiz/Test your Morals, Values &amp; Ethics - YourMorals.Org - Iceweasel
878  33     ( ) urxvt:          /home/gwern; arbtt-stats --categorizefile=foo --filter='$sampleage &lt;24:00' --dump-samples | fgrep '(*)'...
879 </programlisting>
880       <para>
881         We can add rules categorizing these as 'Recreational',
882         'Writing', 'Research', 'Recreational', 'Research', 'Writing',
883         and 'Writing' respectively; and we might decide at this point
884         that 'Writing' is starting to become overloaded, so we'll split
885         it into two tags, 'Writing' and 'Programming'. And then after
886         tossing another <literal>--exclude=Programming</literal> into
887         our rules, we can repeat the process.
888       </para>
889       <para>
890         As we refine our rules, we will quickly spot instances where the
891         title/class/program are insufficient to allow accurate
892         classification, and we will figure out the best collection of
893         tags for our particular purposes. A few iterations is enough for
894         most purposes.
895       </para>
896       </example>
897     </sect3>
898   </sect2>
899   <sect2>
900     <title>Categorizing advice</title>
901     <para>
902       When building up rules, a few rules of thumb should be kept in
903       mind:
904     </para>
905     <sect3>
906         <title>
907           Categorize by purpose, not by program
908         </title>
909         <para>
910           This leads to misleading time reports. Avoid, for example,
911           lumping all web browser time into a single category named
912           'Internet'; this is more misleading than helpful. Good
913           categories describe an activity or goal, such as 'Work' or
914           'Recreation', not a tool, like 'Emacs' or 'Vim'.
915         </para>
916     </sect3>
917     <sect3>
918         <title>
919           When in doubt, write narrow rules and generalize later
920         </title>
921         <para>
922           Regexps are tricky and it can be easy to write rules far
923           broader than one intended. The <literal>--exclude</literal>
924           filters mean that one will never see samples which are matched
925           accidentally. If one is in doubt, it can be helpful to take a
926           specific sample one wants to match and several similar strings
927           and look at how well one's regexp rule works in Emacs's
928           <ulink url="http://www.emacswiki.org/emacs/ReBuilder">regexp-builder</ulink>
929           or online regexp-testers like
930           <ulink url="http://regexpal.com/">regexpal</ulink>.
931         </para>
932     </sect3>
933     <sect3>
934         <title>
935           Don't try to classify everything
936         </title>
937         <para>
938           You will never classify 100% of samples because sometimes
939           programs do not include useful X properties and cannot be
940           fixed, you have samples from before you fixed them, or they
941           are too transient (like popups and dialogues) to be worth
942           fixing. It is not necessary to classify 100% of your time,
943           since as long as the most common programs and, say,
944           <ulink url="https://en.wikipedia.org/wiki/Pareto_principle">80%</ulink>
945           of your time is classified, then you have most of the value.
946           It is easy to waste more time tweaking arbtt than one gains
947           from increased accuracy or more finely-grained tags.
948         </para>
949     </sect3>
950     <sect3>
951     <title>
952       Avoid large and microscopic tags
953     </title>
954     <para>
955       If a tag takes up more than a third or so of your time, it is
956       probably too large, masks variation, and can be broken down into more
957       meaningful tags. Conversely, a tag too narrow to show up regularly in
958       reports (because it is below the default 1% filter) may not be
959       helpful because it is usually tiny, and can be combined with the most
960       similar tag to yield more compact and easily interpreted reports.
961     </para>
962     </sect3>
963   </sect2>
964   <sect2>
965     <title>Long-term storage</title>
966     <para>
967       Each halving of the sampling rate doubles the number of samples
968       taken and hence the storage requirement; sampling rates below 20s
969       are probably wasteful. But even the default 60s can accumulate
970       into a nontrivial amount of data over a year. A
971       constantly-changing binary file can interact poorly with backup
972       systems, may make arbtt analyses slower, and if one's system
973       occasionally crashes or experiences other problems, cause some
974       corruption of the log and be a nuisance in having to run
975       <literal>arbtt-recover</literal>.
976     </para>
977     <para>
978       Thus it may be a good idea to archive one's
979       <literal>capture.log</literal> on an annual basis. If one needs to
980       query the historical data, the particular log file can be
981       specified as an option like
982       <literal>--logfile=/home/gwern/doc/arbtt/2013-2014.log</literal>
983     </para>
984   </sect2>
985   <sect2 id="external-processing">
986     <title>External processing of arbtt statistics</title>
987     <para>
988       arbtt supports CSV export of time by category in various levels of
989       granularity in a 'long' format (multiple rows for each day, with
990       <emphasis>n</emphasis> row specifying a category's value for that
991       day). These CSV exports can be imported into statistical programs
992       like R or Excel and manipulated as desired.
993     </para>
994     <para>
995       R users may prefer to have their time data in a 'wide' format
996       (each row is 1 day, with <emphasis>n</emphasis> columns for each
997       possible category); this can be done with the
998       <literal>reshape</literal> default library. After reading in the
999       CSV, the time-intervals can be converted to counts and the data to
1000       a wide data-frame with R code like the following:
1001     </para>
1002     <programlisting>
1003 arbtt &lt;- read.csv(&quot;arbtt.csv&quot;)
1004 interval &lt;- function(x) { if (!is.na(x)) { if (grepl(&quot; s&quot;,x)) as.integer(sub(&quot; s&quot;,&quot;&quot;,x))
1005                                           else { y &lt;- unlist(strsplit(x, &quot;:&quot;));
1006                                                  as.integer(y[[1]])*3600 + as.integer(y[[2]])*60 + as.integer(y[[3]]); }
1007                                                  }
1008                          else NA
1009                          }
1010 arbtt$Time &lt;- sapply(as.character(arbtt$Time), interval)
1011 library(reshape)
1012 arbtt &lt;- reshape(arbtt, v.names=&quot;Time&quot;, timevar=&quot;Tag&quot;, idvar=&quot;Day&quot;, direction=&quot;wide&quot;)
1013 </programlisting>
1014   </sect2>
1015 </sect1>
1016 <sect1 id="contributed">
1017   <title>Contributed tools</title>
1018   <para>
1019     Due to the export facilities of arbtt (as explained in <xref
1020     linkend="external-processing"/>), tools analyzing arbtt’s data can be
1021     developed independently. This section lists those that we are aware of. If
1022     you create a tool of your own, or find one somewhere, please tell us on the
1023     mailing list (see <xref linkend="copyright"/>).
1024   </para>
1025   <sect2>
1026     <title>arbtt-graph</title>
1027     <para>
1028       Jayesh Kumar Gupta created a nice d3-based visualization of your arbtt
1029       data, including daily pie charts and barcode graphs.
1030     </para>
1031     <para>
1032       You can find his tool on <ulink url="https://github.com/rejuvyesh/arbtt-graph">https://github.com/rejuvyesh/arbtt-graph</ulink>.
1033     </para>
1034   </sect2>
1035 </sect1>
1036 <sect1 id="references">
1037   <title>Program references</title>
1038   <para>arbtt consists of a few command line tools, the most important one is
1039   <command>arbtt-stats</command>. This overview is followed by their manual
1040   pages.
1041   </para>
1042
1043   <!-- <sect2>
1044     <title>Generating statistics</title> -->
1045     <para>To generate statistics about the data that
1046     <command>arbtt-capture</command> has gathered, use the program
1047     <command>arbtt-stats</command>. A detailed description of the possible
1048     options is given in <xref linkend="arbtt-stats"/>.</para>
1049   <!--
1050   </sect2>
1051
1052   <sect2>
1053     <title>Gathering data</title>
1054   -->
1055     <para>The collection of data is done by <command>arbtt-capture</command>.
1056     Usually, you only set it up once to run automatically, as described in <xref
1057     linkend="installation"/>, and do not have to
1058     worry about it again. Its command line reference is given in <xref
1059     linkend="arbtt-capture"/>.</para>
1060   <!--
1061   </sect2>
1062
1063   <sect2>
1064     <title>Dumping data</title>
1065   -->
1066     <para>Because the data log file is binary, a tool names
1067     <command>arbtt-dump</command> can bee used to dump the data in
1068     various textual formats. Its command line reference is given in <xref
1069     linkend="arbtt-dump"/>.</para>
1070
1071     <para>If <command>arbtt-capture</command> crashes it might be that the log
1072     file is not readable any more. In some cases, this can be fixed using the
1073     (relatively raw) <command>arbtt-recover</command> tool. Its command line
1074     reference is given in <xref linkend="arbtt-recover"/>.</para>
1075   <!--
1076   </sect2>
1077   -->
1078
1079
1080   <refentry id="arbtt-stats">
1081     <refmeta>
1082       <refentrytitle>arbtt-stats</refentrytitle>
1083       <manvolnum>1</manvolnum>
1084       <refmiscinfo class="source">arbtt manual</refmiscinfo>
1085     </refmeta>
1086
1087     <refnamediv>
1088       <refname>arbtt-stats</refname>
1089       <refpurpose>generate statistics from the arbtt data samples</refpurpose>
1090     </refnamediv>
1091
1092     <refsynopsisdiv>
1093       <cmdsynopsis>
1094         <command>arbtt-stats</command>
1095         <arg rep="repeat">OPTION</arg>
1096       </cmdsynopsis>
1097     </refsynopsisdiv>
1098
1099     <refsect1><title>Description</title>
1100       <para>
1101       <command>arbtt-stats</command> reads the samples that were recorded so far
1102       by <command>arbtt-capture</command> from the log file, filters them
1103       according to the users specifications and generates one or more reports
1104       from the data.
1105       </para>
1106       <para>
1107       When run without any options, <option>--total-time</option> is assumed.
1108       </para>
1109       <para>
1110       The order in which filters (<option>--exclude</option>,
1111       <option>--only</option>, <option>--also-inactive</option> and
1112       <option>--filter</option>) and reports are passed to the program is
1113       irrelevant: All filters given on the command line are active for all
1114       reports.
1115       </para>
1116     </refsect1>
1117
1118     <refsect1><title>Options</title>
1119       <variablelist>
1120         <varlistentry>
1121           <term><option>-h</option></term>
1122           <term><option>-?</option></term>
1123           <term><option>--help</option></term>
1124           <listitem><simpara>shows a short summary of the available
1125           options, and exists.</simpara></listitem>
1126         </varlistentry>
1127         <varlistentry>
1128         <term><option>-V</option></term>
1129         <term><option>--version</option></term>
1130         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1131         </varlistentry>
1132         <varlistentry>
1133         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
1134         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1135         </varlistentry>
1136         <varlistentry>
1137         <term><option>--categorizefile</option></term>
1138         <listitem><simpara>categorize file to use instead of <filename>~/.arbtt/categorize.cfg</filename></simpara></listitem>
1139         </varlistentry>
1140       </variablelist>
1141       <refsect2><title>Filtering options</title>
1142         <variablelist>
1143           <varlistentry>
1144             <term><option>-x</option> <replaceable>TAG</replaceable></term>
1145             <term><option>--exclude</option> <replaceable>TAG</replaceable></term>
1146             <listitem><simpara>Ignore any data samples that have
1147             been assigned this tag or category. To distinguish tags and categories, the latter have to be
1148             entered followed by a colon. Can be given more than once.</simpara></listitem>
1149           </varlistentry>
1150           <varlistentry>
1151             <term><option>-o</option> <replaceable>TAG</replaceable></term>
1152             <term><option>--only</option> <replaceable>TAG</replaceable></term>
1153             <listitem><simpara>Ignore any data samples that have
1154             not been assigned this tag. To distinguish tags and categories, the latter have to be
1155             entered followed by a colon. Can be given more than once.</simpara></listitem>
1156           </varlistentry>
1157           <varlistentry>
1158             <term><option>--also-inactive</option></term>
1159             <listitem><simpara>by default, <command>arbtt-stats</command> ignores
1160             any samples which have been assigned the tag
1161             <literal>inactive</literal>. This flag disables this behaviour.</simpara></listitem>
1162           </varlistentry>
1163           <varlistentry>
1164             <term><option>-f</option> <replaceable>CONDITION</replaceable></term>
1165             <term><option>--filter</option> <replaceable>CONDITION</replaceable></term>
1166             <listitem><simpara>Only consider samples matching
1167             the given condition, which follows the same syntax as in
1168             <filename>categorize.cfg</filename> (Nonterminal <nonterminal def="#g-cond"/> in
1169             <phrase condition="html"><xref linkend="grammar"/></phrase><phrase condition="man">the formal grammar specification found in the user guide</phrase>).</simpara></listitem>
1170           </varlistentry>
1171         </variablelist>
1172       </refsect2>
1173       <refsect2><title>Report options</title>
1174         <variablelist>
1175           <varlistentry>
1176             <term><option>-m</option> <replaceable>PERCENTAGE</replaceable></term>
1177             <term><option>--min-percentage</option> <replaceable>PERCENTAGE</replaceable></term>
1178             <listitem><para>
1179               Ignore tags whose percentage is less than the value specified
1180               here. Default percentage: 1%.
1181             </para></listitem>
1182           </varlistentry>
1183           <varlistentry>
1184             <term><option>--output-exclude</option> <replaceable>TAG</replaceable></term>
1185             <listitem><para>
1186               Skip this tag or category when printing statistics. Only affects
1187               the reports <option>--total-time</option> and
1188               <option>--category</option>. To distinguish tags and categories,
1189               the latter have to be entered followed by a colon. Can be given
1190               more than once.
1191             </para></listitem>
1192           </varlistentry>
1193           <varlistentry>
1194             <term><option>--output-only</option> <replaceable>TAG</replaceable></term>
1195             <listitem><para>
1196               Prints statistics only for the specified tag or category. Only
1197               affects the reports <option>--total-time</option> and
1198               <option>--category</option>. To distinguish tags and categories,
1199               the latter have to be entered followed by a colon. Can be given
1200               more than once.
1201             </para></listitem>
1202           </varlistentry>
1203           <varlistentry>
1204             <term><option>--output-format</option> <replaceable>FORMAT</replaceable></term>
1205             <listitem><para>
1206               Specify the report output format, may be one of: text, csv
1207               (comma-separated values), tsv (TAB-separated values).
1208               Default format: text.
1209             </para></listitem>
1210           </varlistentry>
1211         </variablelist>
1212       </refsect2>
1213       <refsect2><title>Reports</title>
1214         <variablelist>
1215           <varlistentry>
1216             <term><option>-i</option></term>
1217             <term><option>--information</option></term>
1218             <listitem><para>
1219               Various bits of information about the recorded data, such as total
1220               time recorded, number of records etc. In this report, <quote>time
1221               recorded</quote> is the sum of <emphasis>all</emphasis>
1222               samples, including inactive and those that are disabled by the
1223               filter, while <quote>time selected</quote> is the sum of the
1224               samples that are matched by the given filters.
1225             </para></listitem>
1226           </varlistentry>
1227           <varlistentry>
1228             <term><option>-t</option></term>
1229             <term><option>--total-time</option></term>
1230             <listitem><para>For all tags, print the part of the selected time
1231             with this tag applied to, both as an absolute value and a percentage
1232             of the selected time.
1233             </para></listitem>
1234           </varlistentry>
1235           <varlistentry>
1236             <term><option>-c</option> <replaceable>CATEGORY</replaceable></term>
1237             <term><option>--category</option> <replaceable>CATEGORY</replaceable></term>
1238             <listitem><para>For the given category, give the textual equivalent
1239             of a pie chart: For each possible value of the category, including
1240             one for <quote>no tag of this category present</quote>, give the absolute time and
1241             fraction. Entries which are not displayed because of the option
1242             <option>--min-percentage</option> are aggregated.</para></listitem>
1243           </varlistentry>
1244           <varlistentry>
1245             <term><option>--each-category</option></term>
1246             <listitem><para>This is just a shortcut for a series of
1247             <option>--category</option> options, one for each category found in
1248             the data.
1249             </para></listitem>
1250           </varlistentry>
1251           <varlistentry>
1252             <term><option>--intervals</option> [<replaceable>TAG</replaceable>|<replaceable>CATEGORY</replaceable>:] </term>
1253             <listitem><para>This report lists all periods of consecutive time
1254             intervals where the given tag has been applied to, or where the
1255             given category has the same value.
1256             </para>
1257
1258             <para>To distinguish tags and categories, the latter have to be
1259             entered followed by a colon.</para>
1260
1261             <para>This report will give wrong results if an activity has been
1262             carried out at the end of a session and right at the beginning, as
1263             the intermediate time is thought to be part of the interval.
1264             Inactive times while <command>arbtt-capture</command> is running
1265             will separate the results as expected.</para>
1266
1267             </listitem>
1268           </varlistentry>
1269           <varlistentry>
1270             <term><option>--for-each</option> <replaceable>PERIOD</replaceable></term>
1271             <listitem><para>This is not a report of its own, but causes the selected
1272             report to be executed for each of the given PERIOD (which can be
1273             minute, hour,day, month or year) where there exist selected
1274             samples. All the reports will then be printed one after another or,
1275             in the case of CSV output, with an additional column.</para>
1276
1277             <para>Note that if this option is enabled, samples that are filtered out
1278             are completely ignored (to avoid empty reports for periods with
1279             only filtered samples). Therefore, the
1280             <option>--information</option> report will print the numbers for
1281             the samples selected also for the totals.</para>
1282
1283             </listitem>
1284           </varlistentry>
1285         </variablelist>
1286       </refsect2>
1287     </refsect1>
1288
1289     <refsect1><title>Examples</title>
1290       <para>Some useful examples of what you can do with
1291       <command>arbtt-stats</command> are provided here:</para>
1292       <screen># Only consider the time when I was programming in Haskell
1293 arbtt-stats -o Editing-Haskell
1294
1295 # Tell me what evolution folders I spend my time in when I actually do
1296 # work with e-Mail
1297 arbtt-stats -o Program:evolution -c Evo-Folder
1298
1299 # Generate statistics about the last hour
1300 arbtt-stats -f '$sampleage &lt; 1:00'</screen>
1301     </refsect1>
1302
1303     <refsect1><title>Files</title>
1304       <variablelist>
1305         <varlistentry>
1306           <term><filename>~/.arbtt/capture.log</filename></term>
1307           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1308         </varlistentry>
1309         <varlistentry>
1310           <term><filename>~/.arbtt/categorize.cfg</filename></term>
1311           <listitem><para>specification of the arbtt categorizer syntax. A
1312           detailed description is given in <xref linkend="configuration"/></para></listitem>
1313         </varlistentry>
1314       </variablelist>
1315     </refsect1>
1316
1317     <refsect1><title>See also</title>
1318       <para>See the arbtt manual for more information and the <ulink
1319       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1320       newer versions of arbtt.</para>
1321     </refsect1>
1322   </refentry>
1323
1324   <refentry id="arbtt-capture">
1325     <refmeta>
1326       <refentrytitle>arbtt-capture</refentrytitle>
1327       <manvolnum>1</manvolnum>
1328       <refmiscinfo class="source">arbtt manual</refmiscinfo>
1329     </refmeta>
1330
1331     <refnamediv>
1332       <refname>arbtt-capture</refname>
1333       <refpurpose>collect data samples for arbtt</refpurpose>
1334     </refnamediv>
1335
1336     <refsynopsisdiv>
1337       <cmdsynopsis>
1338         <command>arbtt-capture</command>
1339         <arg rep="repeat">OPTION</arg>
1340       </cmdsynopsis>
1341     </refsynopsisdiv>
1342
1343     <refsect1><title>Description</title>
1344       <para>
1345       <command>arbtt-capture</command> runs continuously and saves at the given
1346       sample rate, usually once per minute, the collected data to
1347       <filename>~/.arbtt/capture.log</filename>.
1348       </para>
1349     </refsect1>
1350
1351     <refsect1><title>Options</title>
1352       <variablelist>
1353         <varlistentry>
1354           <term><option>-h</option></term>
1355           <term><option>-?</option></term>
1356           <term><option>--help</option></term>
1357           <listitem><simpara>shows a short summary of the available
1358           options, and exists.</simpara></listitem>
1359         </varlistentry>
1360         <varlistentry>
1361         <term><option>-V</option></term>
1362         <term><option>--version</option></term>
1363         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1364         </varlistentry>
1365         <varlistentry>
1366         <term><option>-r</option> <replaceable>RATE</replaceable></term>
1367         <term><option>--sample-rate</option> <replaceable>RATE</replaceable></term>
1368         <listitem><simpara>sets the sample rate in seconds (default: 60)</simpara></listitem>
1369         </varlistentry>
1370         <varlistentry>
1371         <term><option>-f</option> <replaceable>FILE</replaceable></term>
1372         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
1373         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1374         </varlistentry>
1375         <varlistentry>
1376         <term><option>-d</option></term>
1377         <term><option>--dump</option></term>
1378         <listitem><simpara>dump one current sample instead of modifying the logfile</simpara></listitem>
1379         </varlistentry>
1380       </variablelist>
1381     </refsect1>
1382     <refsect1><title>Files</title>
1383       <variablelist>
1384         <varlistentry>
1385           <term><filename>~/.arbtt/capture.log</filename></term>
1386           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1387         </varlistentry>
1388       </variablelist>
1389     </refsect1>
1390
1391
1392     <refsect1><title>See also</title>
1393       <para>See the arbtt manual for more information and the <ulink
1394       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1395       newer versions of arbtt.</para>
1396     </refsect1>
1397   </refentry>
1398
1399   <refentry id="arbtt-dump">
1400     <refmeta>
1401       <refentrytitle>arbtt-dump</refentrytitle>
1402       <manvolnum>1</manvolnum>
1403       <refmiscinfo class="source">arbtt manual</refmiscinfo>
1404     </refmeta>
1405
1406     <refnamediv>
1407       <refname>arbtt-dump</refname>
1408       <refpurpose>dumps arbtt data samples</refpurpose>
1409     </refnamediv>
1410
1411     <refsynopsisdiv>
1412       <cmdsynopsis>
1413         <command>arbtt-dump</command>
1414         <arg rep="repeat">OPTION</arg>
1415       </cmdsynopsis>
1416     </refsynopsisdiv>
1417
1418     <refsect1><title>Description</title>
1419       <para>
1420       <command>arbtt-dump</command> reads the data samples recorded by <xref
1421       linkend="arbtt-capture"/> and writes them so the standard output in an
1422       ascii based format.
1423       </para>
1424     </refsect1>
1425
1426     <refsect1><title>Options</title>
1427       <variablelist>
1428         <varlistentry>
1429           <term><option>-h</option></term>
1430           <term><option>-?</option></term>
1431           <term><option>--help</option></term>
1432           <listitem><simpara>shows a short summary of the available
1433           options, and exists.</simpara></listitem>
1434         </varlistentry>
1435         <varlistentry>
1436         <term><option>-V</option></term>
1437         <term><option>--version</option></term>
1438         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1439     </varlistentry>
1440         <varlistentry>
1441         <term><option>-f</option> <replaceable>FILE</replaceable></term>
1442         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
1443         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1444         </varlistentry>
1445         <varlistentry>
1446         <term><option>-t</option> <replaceable>FORMAT</replaceable></term>
1447         <term><option>--format</option> <replaceable>FORMAT</replaceable></term>
1448         <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>
1449     </varlistentry>
1450         <varlistentry>
1451         <term><option>-l</option> <replaceable>NUMBER</replaceable></term>
1452         <term><option>--last</option> <replaceable>NUMBER</replaceable></term>
1453         <listitem><simpara>dump only the last <replaceable>NUMBER</replaceable> of samples.</simpara></listitem>
1454         </varlistentry>
1455       </variablelist>
1456     </refsect1>
1457
1458     <refsect1><title>Files</title>
1459       <variablelist>
1460         <varlistentry>
1461           <term><filename>~/.arbtt/capture.log</filename></term>
1462           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1463         </varlistentry>
1464       </variablelist>
1465     </refsect1>
1466
1467     <refsect1><title>Formats</title>
1468       <refsect2><title>Human</title>
1469       <para>This format is intended for human inspection, but not for further
1470       processing. Hence, it may change in new versions of arbtt without notice.
1471       Example output:</para>
1472       <screen>2013-06-20 14:53:50 (48ms inactive):
1473     ( ) Navigator:      arbtt-dump - Iceweasel
1474     ( ) gnome-terminal-server: jojo@kirk:~/projekte/programming/arbtt/doc
1475     (*) gvim:           arbtt.xml + (~/projekte/programming/arbtt/doc) - GVIM2
1476 </screen>
1477       <para>The line with a star indicates the currently active window.</para>
1478       </refsect2>
1479
1480       <refsect2><title>Show</title>
1481       <para>This is the default serialization format of Haskell's
1482       <literal>Show</literal> type class, one entry per line. This can be
1483       useful if the data is to be processed by further Haskell code. Example
1484       output, with indentation added manually:</para>
1485       <screen>TimeLogEntry
1486     { tlTime = 2013-06-20 14:53:50.957763 UTC
1487     , tlRate = 60000
1488     , tlData = CaptureData
1489         { cWindows =
1490             [ (False,"arbtt-dump - Iceweasel","Navigator")
1491             , (False,"jojo@kirk:~/projekte/programming/arbtt/doc","gnome-terminal-server")
1492             , (True,"arbtt.xml + (~/projekte/programming/arbtt/doc) - GVIM2","gvim")
1493             ]
1494         , cLastActivity = 48
1495         }
1496     }</screen>
1497       </refsect2>
1498
1499       <refsect2><title>JSON</title>
1500       <para>For interoperability, arbtt supports dumping its data to JSON, which can
1501       easily be parsed by many different programming languages. Some level of
1502       backward-compatibility will be provided, as far as possible. Default
1503       output, again with indentation and spacing added manually:</para>
1504       <screen>[ ...,
1505   { "windows": [
1506       { "program": "arbtt-dump - Iceweasel",
1507         "title": "Navigator",
1508         "active": false},
1509       { "program": "jojo@kirk:~/projekte/programming/arbtt/doc",
1510         "title":" gnome-terminal-server",
1511         "active": false},
1512       { "program": "arbtt.xml + (~/projekte/programming/arbtt/doc) - GVIM2",
1513         "title": "gvim",
1514         "active":true
1515       }],
1516     "inactive": 48,
1517     "date": "2013-06-20T14:53:50.957Z",
1518     "rate": 60000},
1519   ...
1520 ]</screen>
1521       </refsect2>
1522     </refsect1>
1523
1524     <refsect1><title>See also</title>
1525       <para>See the arbtt manual for more information and the <ulink
1526       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1527       newer versions of arbtt.</para>
1528     </refsect1>
1529   </refentry>
1530
1531   <refentry>
1532     <refnamediv>
1533       <refname>arbtt-import</refname>
1534       <refpurpose>imports dumped arbtt data samples</refpurpose>
1535     </refnamediv>
1536
1537     <refsynopsisdiv>
1538       <cmdsynopsis>
1539         <command>arbtt-import</command>
1540         <arg rep="repeat">OPTION</arg>
1541       </cmdsynopsis>
1542     </refsynopsisdiv>
1543
1544     <refsect1><title>Description</title>
1545       <para>
1546       <command>arbtt-import</command> expects the output of
1547       <command>arbtt-dump</command> on the standard input and saves them as the
1548       logfile or the specified file.
1549       </para>
1550       <para>
1551       This program would completely override the existing file, therefore it
1552       will refuse to work if the log file already exists. If you want to
1553       overwrite a file, please delete it before running
1554       <command>arbtt-import</command>.
1555       </para>
1556     </refsect1>
1557
1558     <refsect1><title>Options</title>
1559       <variablelist>
1560         <varlistentry>
1561           <term><option>-h</option></term>
1562           <term><option>-?</option></term>
1563           <term><option>--help</option></term>
1564           <listitem><simpara>shows a short summary of the available
1565           options, and exists.</simpara></listitem>
1566         </varlistentry>
1567         <varlistentry>
1568         <term><option>-V</option></term>
1569         <term><option>--version</option></term>
1570         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1571     </varlistentry>
1572         <varlistentry>
1573         <term><option>-f</option> <replaceable>FILE</replaceable></term>
1574         <term><option>--logfile</option> <replaceable>FILE</replaceable></term>
1575         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1576         </varlistentry>
1577       </variablelist>
1578     </refsect1>
1579     <refsect1><title>Files</title>
1580       <variablelist>
1581         <varlistentry>
1582           <term><filename>~/.arbtt/capture.log</filename></term>
1583           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1584         </varlistentry>
1585       </variablelist>
1586     </refsect1>
1587
1588     <refsect1><title>See also</title>
1589       <para>See the arbtt manual for more information and the <ulink
1590       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1591       newer versions of arbtt.</para>
1592     </refsect1>
1593   </refentry>
1594
1595   <refentry id="arbtt-recover">
1596     <refmeta>
1597       <refentrytitle>arbtt-recover</refentrytitle>
1598       <manvolnum>1</manvolnum>
1599       <refmiscinfo class="source">arbtt manual</refmiscinfo>
1600     </refmeta>
1601
1602     <refnamediv>
1603       <refname>arbtt-recover</refname>
1604       <refpurpose>tries to recover a broken arbtt data log</refpurpose>
1605     </refnamediv>
1606
1607     <refsynopsisdiv>
1608       <cmdsynopsis>
1609         <command>arbtt-recover</command>
1610         <arg rep="repeat">OPTION</arg>
1611       </cmdsynopsis>
1612     </refsynopsisdiv>
1613
1614     <refsect1><title>Description</title>
1615       <para>
1616       <command>arbtt-recover</command> tries to read the data samples recorded
1617       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>.
1618       </para>
1619       <para>
1620       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.
1621       </para>
1622     </refsect1>
1623
1624     <refsect1><title>Options</title>
1625       <variablelist>
1626         <varlistentry>
1627           <term><option>-h</option></term>
1628           <term><option>-?</option></term>
1629           <term><option>--help</option></term>
1630           <listitem><simpara>shows a short summary of the available
1631           options, and exists.</simpara></listitem>
1632         </varlistentry>
1633         <varlistentry>
1634         <term><option>-V</option></term>
1635         <term><option>--version</option></term>
1636         <listitem><simpara>shows the version number, and exists.</simpara></listitem>
1637     </varlistentry>
1638         <varlistentry>
1639         <term><option>-i</option></term>
1640         <term><option>--infile</option></term>
1641         <listitem><simpara>logfile to use instead of <filename>~/.arbtt/capture.log</filename></simpara></listitem>
1642         </varlistentry>
1643         <varlistentry>
1644         <term><option>-o</option></term>
1645         <term><option>--outfile</option></term>
1646         <listitem><simpara>where to save the recovered file, instead of <filename>~/.arbtt/capture.log.recovered</filename></simpara></listitem>
1647         </varlistentry>
1648       </variablelist>
1649     </refsect1>
1650     <refsect1><title>Files</title>
1651       <variablelist>
1652         <varlistentry>
1653           <term><filename>~/.arbtt/capture.log</filename></term>
1654           <listitem><para>binary file, storing the arbtt data samples</para></listitem>
1655         </varlistentry>
1656         <varlistentry>
1657           <term><filename>~/.arbtt/capture.log.recovered</filename></term>
1658           <listitem><para>binary file, storing the fixed arbtt data samples</para></listitem>
1659         </varlistentry>
1660       </variablelist>
1661     </refsect1>
1662
1663     <refsect1><title>See also</title>
1664       <para>See the arbtt manual for more information and the <ulink
1665       url="http://hackage.haskell.org/package/arbtt">arbtt hackage page</ulink> for
1666       newer versions of arbtt.</para>
1667     </refsect1>
1668   </refentry>
1669 </sect1>
1670
1671 <sect1 id="troubleshooting">
1672   <title>Troubleshooting</title>
1673   <sect2>
1674     <title>arbtt and xmonad</title>
1675     <para>
1676       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>.
1677     </para>
1678   </sect2>
1679 </sect1>
1680
1681 <sect1 id="copyright">
1682   <title>Copyright and Contact</title>
1683   <para>
1684   arbtt is Copyright © 2009-2010 Joachim Breitner
1685   </para>
1686
1687   <para>
1688     arbtt does not have a bug tracker yet. If you have bug reports, suggestions
1689     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>.
1690   </para>
1691
1692   <sect2>
1693     <title>arbtt License</title>
1694     <para>
1695     <literallayout>
1696 This program is free software; you can redistribute it and/or modify
1697 it under the terms of the GNU General Public License as published by
1698 the Free Software Foundation; either version 2 of the License, or
1699 (at your option) any later version.
1700
1701 This program is distributed in the hope that it will be useful,
1702 but WITHOUT ANY WARRANTY; without even the implied warranty of
1703 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1704 GNU General Public License for more details.
1705
1706 You should have received a copy of the GNU General Public License
1707 along with this program; if not, write to the Free Software
1708 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
1709     </literallayout>
1710     </para>
1711   </sect2>
1712 </sect1>
1713
1714 <sect1 id="release-notes">
1715   <title>Release Notes</title>
1716   <para>
1717   The version history with changes relevant for the user is documented here.
1718   </para>
1719
1720   <sect2 id="release-notes-0.9">
1721     <title>Version 0.9</title>
1722     <itemizedlist>
1723       <listitem>
1724     <para>
1725           The <option>--for-each</option> option of
1726           <command>arbtt-stats</command> now supports grouping results by
1727           minute or hour.
1728     </para>
1729       </listitem>
1730       <listitem>
1731     <para>
1732       Gwern Branwen contributed the <xref linkend="effective-use"/>.
1733     </para>
1734       </listitem>
1735     </itemizedlist>
1736   </sect2>
1737
1738   <sect2 id="release-notes-0.8.1">
1739     <title>Version 0.8.1</title>
1740     <itemizedlist>
1741       <listitem>
1742     <para>
1743       The syntax now allows for time differences larger than 99:99.
1744           (<ulink url="https://bitbucket.org/nomeata/arbtt/issue/14/improve-time-categorization-directives">issue #14</ulink>)
1745     </para>
1746       </listitem>
1747     </itemizedlist>
1748   </sect2>
1749
1750   <sect2 id="release-notes-0.8">
1751     <title>Version 0.8</title>
1752     <itemizedlist>
1753       <listitem>
1754     <para>
1755       <command>arbtt-dump</command> can now show the data in other formats
1756       as well, as suggested by Waldir Pimenta (option
1757       <option>--format</option>). This includes a human-readale output and
1758       JSON.
1759     </para>
1760       </listitem>
1761       <listitem>
1762         <para>New option <option>--last</option> of <command>arbtt-dump</command>.</para>
1763       </listitem>
1764       <listitem>
1765         <para><command>arbtt-recover</command> can handle larger datasets with a reasonable amount of memory.</para>
1766       </listitem>
1767       <listitem>
1768         <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>
1769       </listitem>
1770       <listitem>
1771         <para><command>arbtt-capture</command> now supports the option <option>--dump</option> for development and debugging purposes.</para>
1772       </listitem>
1773       <listitem>
1774         <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>
1775       </listitem>
1776       <listitem>
1777         <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>
1778       </listitem>
1779       <listitem>
1780         <para><command>arbtt-stats</command> can print reports split by time interval, using the <option>--for-each</option> option.</para>
1781       </listitem>
1782       <listitem>
1783         <para><command>arbtt-stats</command> can print the actual samples selected, with <option>--dump-samples</option>.</para>
1784       </listitem>
1785       <listitem>
1786         <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>
1787       </listitem>
1788       <listitem>
1789         <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>
1790       </listitem>
1791       <listitem>
1792         <para>Waldir Pimenta contributed a new web page, hosted at <ulink url="http://arbtt.nomeata.de/">arbtt.nomeata.de</ulink>.</para>
1793       </listitem>
1794     </itemizedlist>
1795   </sect2>
1796
1797   <sect2>
1798     <title>Version 0.7</title>
1799     <itemizedlist>
1800       <listitem>
1801         <para>Make sure that the log file is only readable by the current user. Thanks to Joey Hess for pointing that out.</para>
1802       </listitem>
1803       <listitem>
1804         <para>Show a progress bar in <command>arbtt-stats</command>.</para>
1805       </listitem>
1806       <listitem>
1807         <para>GHC-7.6 compatibility, thanks to Isaac Dupree.</para>
1808       </listitem>
1809     </itemizedlist>
1810   </sect2>
1811
1812   <sect2>
1813     <title>Version 0.6.4.1</title>
1814     <itemizedlist>
1815       <listitem>
1816         <para>
1817         Added missing module to the packages.
1818         </para>
1819       </listitem>
1820     </itemizedlist>
1821   </sect2>
1822
1823   <sect2>
1824     <title>Version 0.6.4</title>
1825     <itemizedlist>
1826       <listitem>
1827         <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>
1828       </listitem>
1829     </itemizedlist>
1830   </sect2>
1831
1832   <sect2>
1833     <title>Version 0.6.3</title>
1834     <itemizedlist>
1835       <listitem>
1836         <para>Performance improvements.</para>
1837       </listitem>
1838       <listitem>
1839         <para>Support comparing a string to a list of strings, or matching it against a list ofregular expressions.</para>
1840       </listitem>
1841     </itemizedlist>
1842   </sect2>
1843
1844   <sect2>
1845     <title>Version 0.6.2</title>
1846     <itemizedlist>
1847       <listitem>
1848         <para>Add a warning whtn the system locale is not supported.</para>
1849       </listitem>
1850       <listitem>
1851         <para>Allwo RTS options to be passed to the arbtt binaries.</para>
1852       </listitem>
1853       <listitem>
1854         <para>GHC 7.4 compatibility.</para>
1855       </listitem>
1856     </itemizedlist>
1857   </sect2>
1858
1859   <sect2>
1860     <title>Version 0.6.1</title>
1861     <itemizedlist>
1862       <listitem>
1863         <para>Performance improvements.</para>
1864       </listitem>
1865     </itemizedlist>
1866   </sect2>
1867
1868   <sect2>
1869     <title>Version 0.6</title>
1870     <itemizedlist>
1871       <listitem>
1872         <para>The command <command>arbtt-capture</command> now supports the
1873         <option>--logfile</option>.
1874         </para>
1875       </listitem>
1876       <listitem>
1877         <para>New report “intervals”, available using <command>arbtt-stats</command> <option>--intervals</option>.
1878         </para>
1879       </listitem>
1880       <listitem>
1881         <para>The paramters <option>--exclude</option> and
1882         <option>--include</option> of <command>arbtt-stats</command> can match
1883         categories as well as tags.
1884         </para>
1885       </listitem>
1886       <listitem>
1887         <para>Bugfix: Numbers in tag names are no longer replaced by an underscore.</para>
1888       </listitem>
1889       <listitem>
1890         <para>New paramters <option>--output-exclude</option> and
1891         <option>--output-include</option> of <command>arbtt-stats</command>.
1892         </para>
1893       </listitem>
1894     </itemizedlist>
1895   </sect2>
1896
1897   <sect2>
1898     <title>Version 0.5 (The ZuriHac-Release)</title>
1899     <itemizedlist>
1900       <listitem>
1901     <para>New command <command>arbtt-import</command>, which imports the output from <command>arbtt-dump</command>.
1902         </para>
1903       </listitem>
1904       <listitem>
1905         <para>The command <command>arbtt-stats</command> now supports the
1906         <option>--logfile</option> and <option>--categorizefile</option> as well.
1907         (<xref linkend="martin"/>)
1908         </para>
1909       </listitem>
1910       <listitem>
1911         <para>
1912           The command <command>arbtt-stats</command> now supports the csv
1913           (comma-separated values) and tsv (TAB-separated values) report output
1914           formats in addition to text.
1915           (<xref linkend="muharem"/>)
1916         </para>
1917       </listitem>
1918       <listitem>
1919         <para>
1920       Unicode is handled correctly in regular expressions.
1921     </para>
1922       </listitem>
1923       <listitem>
1924         <para>
1925       Improved date-handling functions for <filename>categorize.cfg</filename>.
1926           (<xref linkend="sergey"/>)
1927     </para>
1928       </listitem>
1929     </itemizedlist>
1930   </sect2>
1931
1932   <sect2>
1933     <title>Version 0.4.5.1</title>
1934     <itemizedlist>
1935       <listitem>
1936         <para>Bugfix: Added missing modules to the cabal file.
1937     </para>
1938       </listitem>
1939     </itemizedlist>
1940   </sect2>
1941
1942   <sect2>
1943     <title>Version 0.4.5</title>
1944     <itemizedlist>
1945       <listitem>
1946         <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.
1947     </para>
1948       </listitem>
1949     </itemizedlist>
1950   </sect2>
1951
1952   <sect2>
1953     <title>Version 0.4.4</title>
1954     <itemizedlist>
1955       <listitem>
1956         <para>Bugfix: Correctly parse a tag name containing a colon when passed to <command>arbtt-stats</command> <option>--exclude</option>.</para>
1957       </listitem>
1958       <listitem>
1959         <para>Bugfix: Only warn once when the <token>_NET_CLIENT_LIST</token> X property is not set for the root window.</para>
1960       </listitem>
1961     </itemizedlist>
1962   </sect2>
1963
1964
1965   <sect2>
1966     <title>Version 0.4.3</title>
1967     <itemizedlist>
1968       <listitem>
1969         <para>Use fetchName from xmonad instead of xFetchName, as it works with unicode characters in window titles.</para>
1970       </listitem>
1971     </itemizedlist>
1972   </sect2>
1973
1974   <sect2>
1975     <title>Version 0.4.2</title>
1976     <itemizedlist>
1977       <listitem>
1978         <para>Implement option <option>--logfile</option> to
1979         <command>arbtt-dump</command>.</para>
1980       </listitem>
1981       <listitem>
1982     <para>New command <command>arbtt-recover</command> to rescue data from
1983     a proken data log file.</para>
1984       </listitem>
1985       <listitem>
1986     <para>Actually include this documentation in the released tarball.</para>
1987       </listitem>
1988     </itemizedlist>
1989   </sect2>
1990
1991   <sect2>
1992     <title>Version 0.4.1</title>
1993     <itemizedlist>
1994       <listitem>
1995         <para>Write this documentation</para>
1996       </listitem>
1997       <listitem>
1998         <para>Drop dependency on setlocale: Copy the SetLocale module.</para>
1999       </listitem>
2000       <listitem>
2001         <para>Drop dependency on tabular: Implement custom table rendering code.</para>
2002       </listitem>
2003       <listitem>
2004         <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>
2005       </listitem>
2006     </itemizedlist>
2007   </sect2>
2008
2009   <sect2>
2010     <title>Version 0.4</title>
2011     <itemizedlist>
2012       <listitem>
2013         <para>Implement option <option>--each-categories</option> to
2014         <command>arbtt-stats</command></para>
2015       </listitem>
2016       <listitem>
2017         <para>Eliminate one possible cause for crashes of
2018         <command>arbtt-capture</command>.</para>
2019       </listitem>
2020     </itemizedlist>
2021   </sect2>
2022
2023   <sect2>
2024     <title>Version 0.3.0</title>
2025     <itemizedlist>
2026       <listitem>
2027         <para>Switch to binary log file format, for greatly increased speed</para>
2028       </listitem>
2029       <listitem>
2030         <para><command>arbtt-capture</command> will automatically detect and
2031         convert log files in the old format.</para>
2032       </listitem>
2033     </itemizedlist>
2034   </sect2>
2035
2036   <sect2>
2037     <title>Version 0.2.0</title>
2038     <itemizedlist>
2039       <listitem>
2040         <para>Add option <option>--filter</option> to
2041         <command>arbtt-stats</command></para>
2042       </listitem>
2043       <listitem>
2044         <para>Add option <option>--sample-rate</option> to
2045         <command>arbtt-capture</command></para>
2046       </listitem>
2047       <listitem>
2048         <para>Introduce time-base variables <literal>$time</literal> and
2049         <literal>$sampleage</literal></para>
2050       </listitem>
2051     </itemizedlist>
2052   </sect2>
2053
2054   <sect2>
2055     <title>Version 0.1.5</title>
2056     <itemizedlist>
2057       <listitem>
2058         <para>Use <function>setlocale</function> to get umlauts in window titles correctly</para>
2059       </listitem>
2060     </itemizedlist>
2061   </sect2>
2062
2063   <sect2>
2064     <title>Version 0.1.4</title>
2065     <itemizedlist>
2066       <listitem>
2067         <para>Be smarter when figuring out what window is active. Thanks to CJ
2068         van den Berg for investigating the issue.</para>
2069       </listitem>
2070     </itemizedlist>
2071   </sect2>
2072
2073   <sect2>
2074     <title>Version 0.1.3</title>
2075     <itemizedlist>
2076       <listitem><para>Read <literal>_NET_CLIENT_LIST</literal> for the list of
2077       applications, for compatibility with window managers such as metacity</para></listitem>
2078     </itemizedlist>
2079   </sect2>
2080
2081   <sect2>
2082     <title>Version 0.1.2</title>
2083     <itemizedlist>
2084       <listitem><para>Off-By-Ten error in the time display</para></listitem>
2085       <listitem><para>Correctly show total number of records in
2086       <option>--information</option></para></listitem>
2087     </itemizedlist>
2088   </sect2>
2089
2090   <sect2>
2091     <title>Version 0.1.1</title>
2092     <para>
2093     Rename files to allow building on MacOS.
2094     </para>
2095   </sect2>
2096
2097   <sect2>
2098     <title>Version 0.1</title>
2099     <para>
2100     Initial release of arbtt
2101     </para>
2102   </sect2>
2103 </sect1>
2104
2105 </article>