all repos — h3rald @ 6b243ded05a7593922d198634c681075de1c12e2

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
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
-----
title: "Announcement: RedBook v0.4.0 released"
content-type: article
timestamp: 1196235240
tags: "opensource|productivity|redbook|ruby"
-----
<p>I'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'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'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'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'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's duration and the duration of each of its child
	activity.</p>
<p>What if you'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'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'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>