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