Posts

If you want to view the annotated source online, then you want the annotated source html.

Introduction

What follows is what I would describe as a ridiculously in-depth line-by-line walk through of the blosxom source code. This is based on version 2.0.2 of the source, dated July 16, 2006, which you can find at the Blosxom project website on SourceForge.

The annotated source itself is available as a single file in text, pdf, and html formats. The content of the files is essentially the same.

• The text version is formatted in markdown;
• The pdf is nothing more than the text version output to pdf in case that's useful to you for some reason;
• The html is just the markdown converted to html.

Be aware that this is a large document. The pdf copy is over 160 printed pages.

While it's possible to read the whole thing from beginning to end, I assume that most people will instead jump to a particular section of the code or a specific line number. All of the line numbers are available as named anchors.

Because the annotated source is so long, I've also created a series of diagrams that follow the flow of execution. This isn't a line by line breakdown but there is sufficient detail so that you should be able to use the diagrams to understand the code. There are ten diagrams in total. One is a collection of thumbnails of the other nine, so you can get oriented. None of the thumbnails are actually readable however. The other nine represent some logical grouping of the code. The definitions of various routines are all on separate diagrams, as are the static and dynamic blocks, etc.

You can download everything as a single .zip file (approximately 8MB). What follows is a list of links to all of these files, and then the rest of the post discusses the annotated source a little more.

Finally, I want to mention that Frank Hecker tackled the project of annotating the blosxom source before I did. I've never looked at his version (because I had my own purposes for working on this), but from what I've heard, he's done a good job. I have no doubt that his approach is quite different than what I've done. So I encourage you to check out his work. Thanks, Frank, for your efforts. And thanks to everyone working on and using blosxom.

Annotated source

• Annotated source in markdown
• Annotated source as pdf
• Annotated source html

Diagrams

• blosxom overview diagram .png
• blosxom execution diagram .png
• template routine definition diagram .png
• entries routine definition diagram .png
• dynamic block execution diagram .png
• static block execution diagram .png
• generate routine definition diagram .png
• interpolate routine definition diagram .png
• sort routine definition diagram .png
• nice_date routine definition diagram .png

Downloadable archive of all files

• blosxom 2.0.2 annotations bundle .zip

Relevant details

• What: Heavily annotated source, blosxom 2.0.2 (July 16, 2006) at SourceForge
• Annotations by: Rob Reed, robreed at gmail dot com
• Contact info: Email me if you have any questions, comments, or feedback
• Date: 2007/0622
• Annotations version: 20.1

More info about the annotated source

The approach is very straightforward.

• All lines in the source are reproduced here with notes underneath discussing each line.
• Comments in the original source are reproduced here and show up in the code, as they do in the source itself.
• The line numbers are identical to the line numbers in the original source.

• Each line number is available as a named anchor link.

  If you're looking for a particular line, append #number to the end of the page address in the address bar.

  e.g.

  www.example.net/path/current_page.html#143

  ...is a link to line number 143 on ../current_page.html.

Why/how is this useful?

I don't know that it is.

If you do find it useful then you're better able to answer that question than I am.

Please send me an email and tell me how this is useful to you, robreed@gmail.com.

I will say that it's intended to be at least somewhat instructive. There's information here about Perl and there are tips or hints related to blosxom. Unfortunately, this may mean that someone who's not a Perl novice may find the commentary annoying because I constantly revisit issues of syntax and talk about various operators, etc. But because blosxom has been out for so many years and because it was my intention to put together a very thorough walk-through, I erred on the side of being generous in my descriptions of things to make the discussion as accessible as possible. I doubt experienced blosxom or Perl users will have much use for this other than maybe quickly referring to the odd line for a description. Hopefully in that case it's not too annoying that there's so much overhead.

Why did I take the time to do this?

I'm working on a project closely related to blosxom emphasizing clean accessible code and documentation. The idea is to create a lively, responsible open source project around a strong, practical bit of software (something like blosxom). For me, this is the first step toward that goal.

This is a living document. There are a lot of mistakes, typos etc. some more unfortunate than others. Hopefully nothing that will confuse or complicate things for you.

I will shortly (today is 0622/2007) be moving this post to a wiki so that others can edit it directly. I'm also setting up a forum for discussion related to this document. Keep in mind that the purpose of this document is simply to describe the 2.0.2 version of the code as-is and not or modify it. I am working on modifying the code itself, but that's another project. If you're interested in that feel free to send me an email, robreed@gmail.com.

I've updated this post and the annotated blosxom source. Also, I've posted a number of other resources related to this project including a number of diagrams detailing the code.

Please take a look at the new post, Heavily Annotated Blosxom 2.0.2 Source (v.20 2007_0622).