Posts Tagged ‘DRY’

when versus remind

Sunday, January 30th, 2011

Right off the bat I want to say that both when and remind are excellent pieces of software.

Common to both are that they are CLI applications, light on resources, and store data in plaintext formats.

They differ in syntax and through that they differ somewhat in complexity, and, although unconfirmed, this may also affect their individual capabilities (i.e. the more complex the syntax, the more time to learn it, but the more powerful the expressions).

Of the two I found out about when first, but I can’t for the life of me recall when or where I first read about it. It may very well have been through StumbleUpon.

remind, on the other hand, was recommended to me some time ago by my very good friend bumby.

Comparing their different syntaxes might be the best way of showing off their differences:

We’ll start with something simple, like a notice to remember the fifth of
November:

when syntax:

* 11 5. Remember, remember, the fifth of November

remind syntax:

REM Nov 5 MSG Remember, remember, the fifth of November

Or, let’s say you want to be reminded to celebrate the birth of the Epoch, and know how “old” the Epoch is now.

In when syntax, that would be expressed as:

1970* 1 1, The Epoch is now \a years old

the same expression would, in remind be:

REM Jan 1 MSG The Epoch is now [year(trigdate())-1970] years old

Now, truth be told, I have created an expression in when which I am not sure I could (or as I probably can, how I would do it) in remind:

y=2010 & m>=4 & ((m=11 & d<6) | (m<11)) & (d=1 | d=11 | d=21), #FSCONS2010, #fscons@freenode, 14:00

During the planning of FSCONS 2010, we had meetings at 14:00 hours the 1st, 11th and 21st of every month between April and November. This expression kept me on track.

I guess I can rest assured that bumby will spend all night coming up with the equivalent expression for remind ;)

Since I while back I decided that remind was the right choice for me. What was the killer feature which had me leave when for remind? Well, truth be told, the feature isn’t in remind at all.

The one thing I lacked in when was some sort of graphical “calendaric” view. Sure, in a pinch cal will do the job, but I wanted something more flexible, something more interactive, something more like… calcurse.

The only problem? calcurse stores appointments in a file of its own, in a different format, and even if I had acted on my initial urge to write a converter between the two formats, I would still have been in violation of the DRY-principle.

This problem doesn’t exist with remind, as there exist a software almost identical to calcurse named wyrd, with the one crucial difference: where calcurse store appointments in a format of its own, wyrd operates solely on the files used by remind.

So was it worth it? Switching from a syntax I fully comprehend, to a more complex one which will take me a while to learn? A switch which also meant having to rewrite the Important Dates Notifier-script? In the long term? Yes, it will be worth it. In the long term, complexity will turn into power, as I begin to better understand the syntax, and become able to fully utilize it.

But for anyone with a brain wired like mine (thinking the FSCONS-meeting example above made perfect sense), who can live without any additional power/complexity, I still warmly recommend when. And if you need that power, have a look at remind. It might be just what you need.

:wq

Documentation, best practices?

Friday, November 14th, 2008

I am, as part of the AFST course, working on a free software project, Vox Anonymus. One of the requirements for the software is that it should come complete with documentation on how to install it (not at all unreasonable by any measure).

But I find asking myself how to handle this install information. I needs to be included in the INSTALL file, as well as on the website. At the same time, I feel the urge to not repeat myself. DRY (Don’t Repeat Yourself).

I’ve read up on some techniques, reStructured Text, python-docutils, etc. but I have been unable to find a suitable solution which would convert some simple text format to both (x)html and some reasonable plain text representation for the INSTALL file.

The simplest solution would probably be to use some mark-up language, and a formatting system, and then let the source file be the INSTALL file, from which the html file can be generated. This would leave some “mark-up artifacts” for the prospective users of the application.

Second easist solution: Have the html file be the source file, and generate the INSTALL file by stripping the tags out of the html file. While this would be acceptable, two things bother me:

  • It could potentially take some work in order to make the stripping / reformatting perform properly (with regards to newlines, indentation, etc)
  • Going against YAGNI (You Ain’t Gonna Need It), what if there is a future format I would wish to support?

(I will have to admit though, whilst browsing through “Beginning Python” by Magnus Lie Hetland (Apress) I discovered a chapter (20) outlining a simple system for doing just this, and it sparked my curiosity, so I might have been more than a little “influenced” to reject all other ideas ;))

The third option, then, the path I at least for the moment, have settled on, is to create a miniature mark-up syntax, with the accompanying formatter scripts, to allow for generation of both plain text and html, and extensibility for the future.

The final tipping point is that I can have more automation this way. With the first approach, this would have had to have been a tack-on ugly hack. With the second approach, since a couple of simple sed commands would have done the trick, and I would thus have employed a shell script to reformat the text I would have had to solve it manually, but now with the third option, it can be brought into the cor functionality;

The tarball I generate is given a filename consisting of the name of the project, as well as the version of the project, as can be found in setup.py. Hence, the web-page download link need to be updated every now and then. If I am generating the html, it would make sense to have python also generate an up to date link to the tarball.

Overall, this seem to have the makings of a good solution (all things considered) as well as being a good learning experience. Win-win.

But this was actually not what my post was supposed to be about. In the title, notice the question mark? With it I was not implying that I might be on to the best practice, but rather a question aimed at you, the readers. How would you have done it? Because there is bound to be better ways, with better motivations, than what I have cobbled up. There just has to be, since people have been putting together INSTALL instructions and other application documentation for free software for at least a good… what? thirty – forty? years. And there are bound to be those who doesn’t like repeating yourselves.