all repos — h3rald @ 014a4bffb19de55f0ef2494bc119480df3adb9b6

The sources of https://h3rald.com

contents/articles/redbook-040-released.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
-----
title: "Announcement: RedBook v0.4.0 released"
content-type: article
timestamp: 1196235240
tags: "opensource|productivity|redbook|ruby"
-----
<p>I&#8217;m pleased to announce a new release of the RedBook daily logging and time tracking script. This release introduces two new operations, four stats-related directives and a brand new Windows Installer able to setup RedBook in a blink, with (almost) no configuration at all.</p>
<p>Let&#8217;s have a closer look&#8230;h2. New Operations</p>
<p>Suppose that you just logged a message and you noticed one of these two things happened:</p>
<ul>
	<li>You didn&#8217;t really wanted to log it</li>
	<li>You made a silly typo in the message or in the tags</li>
</ul>
<p>What can you do about it? Up to RedBook 0.3, the only solution was to open the <span class="caps">YAML</span> file and correct the mistake manually. From now on there&#8217;s also another simpler way to operate in such situations: using the :update and :delete operations!</p>
<h3>:update</h3>
<p>This operation can be used to update the message and or the tags of a previously-logged activity. The usage is simple: load a dataset first, and then execute an <code>:update</code> command like:</p>
<p><code>:update 4 :message My updated message :with new_tag1 new_tag2</code></p>
<p>This will update the 4th message of the dataset modifying its message and tags. Of course you can update either of the two things or both; the timestamp of the activity will not be changed.</p>
<h3>:delete</h3>
<p>The delete operation can be used to completely delete a message from the log. Just load a dataset using a <code>:select</code> operation and then execute a <code>:delete</code> command, e.g.:</p>
<ul>
	<li><code>:delete 1</code> <em>(will delete the first activity)</em></li>
	<li><code>:delete 4 2 7 9</code> <em>(will delete activity #2, #4, #7 and #9)</em></li>
	<li><code>:delete</code> <em>(will delete the entire dataset)</em></li>
</ul>
<p>A confirmation message will appear before deleting the message(s).</p>
<p><strong><span class="caps">IMPORTANT</span></strong><br />
<em>Due to the architecture of the application, whenever an <code>:update</code> or <code>:delete</code> occurs the log file will be reloaded in memory and completely overwritten. This doesn&#8217;t cause problems, although for big log files (10,000+ activities) this may take a few seconds.</em></p>
<h2>Statistics</h2>
<p>Another important new feature introduced by this release is <em>time tracking</em>. It was actually already there, kind of: the <code>:calc</code> operation was already able to calculate the time elapsed between two activities&#8230; however, this is not really practical.</p>
<p>Since last release, it is possible to log the completion of an activity using the <code>:finish</code> command. This will basically re-log the same activity prepending <em>[<span class="caps">COMPLETED</span>]</em> to its message.<br />
If you started using the <code>:finish</code> command to complete your activities, RedBook can now calculate the following stats for you:</p>
<ul>
	<li>Count the number of messages in a dataset</li>
	<li>Calculate the average time spent for the completed activities in a dataset</li>
	<li>Calculate the total time spent for the completed activities in a dataset</li>
	<li>Calculate the duration of each completed activity in a dataset</li>
</ul>
<p>Each of these calculations is performed by adding special directive to a <code>:select</code> command, as explained in the following sections.</p>
<h3>:count</h3>
<p>This directive can be added to a <code>:select</code> command to return just the number of message of the loaded dataset. <br />
In other words, executing the following:</p>
<p><code>:select :count :with mail !work</code></p>
<p>&#8230;will return the number of activities tagged with <em>mail</em> but not with <em>personal</em>, without listing all the activities.</p>
<h3>:avg</h3>
<p>The <code>:avg</code> directive can be used to calculate the average time spent on activities matching certain criteria, for example:</p>
<p><code>:select Status Meeting :avg :with meeting</code></p>
<p>&#8230;will return the average time spent on activities whose messages matches <em>/Status Meeting/</em> and are tagged with <em>meeting</em>.</p>
<h3>:total</h3>
<p>Similarly, <code>:total</code> can be used to return the total time spent on activities matching certain criteria, e.g.:</p>
<p><code>:select :total :with mail work</code></p>
<p>&#8230;will return the total time spent on activities tagged with <em>mail</em> and <em>work</em>.</p>
<h3>:duration</h3>
<p>Lastly, <code>:duration</code> will print each completed task along with its duration. The syntax is similar to the others:</p>
<p><code>:select :duration :with break</code></p>
<p>This will print each completed activity tagged with <em>break</em> along with its duration.</p>
<h3>:nodiff and _concurrent</h3>
<p>The logic behind the above-mentioned directives may seem trivial to implement, but it is not. The fun part was telling RedBook to subtract the duration of each sub-activity contained in another activity&#8230; a feature I considered necessary for time tracking purpose. However, if you start your work day with a <em>Working Day</em> activity and you complete that activity using the <code>:finish</code> command, when calculating the duration of the working day RedBook will subtract the duration of <em>all the completed sub-activities</em> from the duration of <em>Working Day</em>. This is not OK, so I added the directive <code>:nodiff</code> which can be used to prevent RedBook from calculating the difference between the parent activity&#8217;s duration and the duration of each of its child activity.</p>
<p>What if you&#8217;re doing two things at once? use the special <code>_concurrent</code> tag, and that activity will be considered symultaneous to its parent activity for time tracking purposes.</p>
<h2>Activity Status Filters</h2>
<p>RedBook is now fully aware of the &#8220;status&#8221; of each activity, so it is possible to display only activities in a certain status using the following directives:</p>
<h3>:plain</h3>
<p>Executing <code>:select :plain :from today</code> will return all the activities logged today, omitting their completions (if any), i.e. any activity beginning with <em>[<span class="caps">COMPLETED</span>]</em>.</p>
<h3>:pending</h3>
<p>Executing <code>:select :pending :from today</code> will return all the activities logged today which have not been completed yet. Again, this was not too trivial to implement, but it seems to work (it also smart enough to detect if the same activity has been relogged etc. etc.).</p>
<p><strong><span class="caps">WARNING</span>:</strong> <br />
<em>Using this directive with a large dataset may cause RedBook to take some time before delivering the result, due to the amount of iterations to perform. Use with care.</em></p>
<h3>:completed</h3>
<p>Executing <code>:select :completed :from today</code> will return all the activities logged today which have been completed.</p>
<h2>Windows Installer</h2>
<p>I decided to spend some time (half an hour) and create a proper setup file for Windows using InnoSetup. The setup will take care of almost everything for you, so you have no excuse not to try RedBook because it&#8217;s not user-friendly to install!</p>
<p>Check out the <a href="http://redbook.h3rald.com">manual</a> for more details.</p>
<h2>RubyForge Project</h2>
<p>Finally, I registered a new <a href="http://rubyforge.org/projects/redbook/">RubyForge Project</a> for RedBook, which include a public <span class="caps">SVN</span> repository updated every week (Assembla doesn&#8217;t allow anonymous checkouts, unfortunately).<br />
This project will also host the official RedBook Gem, scheduled for the 1.0 release.</p>
<p style="text-align:center;"><strong><a href="http://www.assembla.com/spaces/files/redbook"><span class="caps">DOWNLOAD</span></a> | <a href="http://redbook.h3rald.com/"><span class="caps">MANUAL</span></a></strong></p>