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