Here’s the first player, our code.

    % ls Repository/trunk/clementine/interfaces/gesture
    CLGestureCue.cxx           CLGestureCueAppearance.h   CLGestureListener.cxx      CLGestureParser.h
    CLGestureCue.h             CLGestureInterface.cxx     CLGestureListener.h        CLGestureTrainer.cxx
    CLGestureCueAppearance.cxx CLGestureInterface.h       CLGestureParser.cxx        CLGestureTrainer.h

    % cat CLGestureListener.h
    #ifndef __CLEMENTINE_INTERFACES_GESTURE_CLGESTURELISTENER_H__
    #define __CLEMENTINE_INTERFACES_GESTURE_CLGESTURELISTENER_H__

    #include "CLGestureParser.h"
    #include <string>

    /**
     * CLGestureListener is responsible for listening on the CLGestureInterface
     * for a single gesture type.
     */
    class CLGestureListener
    {
            public:
                    /**
                     * Instantiate the listener.
                     * @param gestureName the name of the gesture
                     * (and consequently, the filename to parse) that this object is created to listen for.
                     */
                    CLGestureListener(std::string gestureName);
    ... etc

It’s a whole bunch of header and implementation files for a C++ project I’m involved with. This project requires the use of thorough documentation, but our design documents are hundreds of revisions behind our code. While it’s important to have gone through initial designs, our code at this point is miles removed from those designs. It would be nice to be able to automagically update our design document to be kept current on what is occurring in the code. This will not make up our entire design document. It is meant to be used in conjunction with manual, hand-written and hand-proofed analysis of the larger architecture.

The second player is AsciiDoc, a wonderful formatting and markup system. You may know it from the Git User’s Manual. AsciiDoc affords us several advantages.

• It is in plain text, which means it can sit in source control, right alongside our code, and diffs are easily viewable.
• It is a templating language, which allows output into HTML, PDF, you name it. With enough hacking, you can produce really distinct output for webpages and PDF readers.
• It allows division of sections into different files, so authors can focus on the sections that concern them without being overwhelmed by the text they’re editing.

Act Two: The Tools

We want the comments in our code to be part of the documentation, but that’s not all. Since UML is the standard when it comes to software engineering description, it would be nice to have UML diagrams in our output as well. The ubiquitous free diagramming tool Dia provides, with its invocation, command line arguments to convert Dia diagrams into images. It goes like this, where you wish the output to be image_name.png:

    dia -t png -e image_name.png diagram_name.dia

So this part will be simple. Generating the Dia diagrams from code is already taken care of for us. Aaron Trevena has written an excellent script called AutoDia which provides this functionality. All we need to do is put these pieces together, along with writing the functionality to extract the comments we want to become documentation.

Act Three: The Program

I am calling it Amorfus, because I think client-side applications should start getting into the Web 2.0 naming crazes.

How do you use it?

1. Create a new CommentDocParser, with these parameters: a string pointing to the subdirectory of your trunk that you wish to document, a string containing the conceptual name of the code in that directory, and a string containing your trunk directory. You can leave this last one out, and it will default to '.'.
2. Run #parse on that parser.
3. Create a file handle, and output the return value of #to_asciidoc to that file.
4. That’s it!

Here’s an example:

	require 'amorfus'
	DIRECTORY_HEADER_LEVEL = 1 # This will become the section depth, in AsciiDoc, for each individual class we find
	r = CommentDocParser.new 'interfaces/gesture', 'Gesture Interface', 'Repository/trunk'
	r.parse
	t = File.new('output.txt', 'w')
	t.write r.to_asciidoc
	t.close

What does it do in the background?

1. It uses a dumb regex based heurestic to determine if a comment has value.
2. It classifies methods by what it can find of their name.
3. It generates Dia diagrams whenever it can find an object.
4. When generating images, it parses Dia diagrams using Nokogiri and removes irrelevant objects from that diagram, so that only the featured object shows up in the image.

Finally, we’ll need to make a small patch to AutoDia to make it recognize structs as equally valid objects. This is extremely hackish (see the Epilogue), but it manages to work for now.

--- Autodia-2.03/lib/Autodia/Handler/Cpp.pm     2009-04-15 01:10:46.000000000 -0400
+++ Autodia-2.03.orig/lib/Autodia/Handler/Cpp.pm        2005-04-15 08:02:49.000000000 -0400
@@ -72,7 +72,7 @@
          $i++;
 
          # check for class declaration
-         if ($line =~ m/^\s*(?:class|struct)\s+(\w+)/)
+         if ($line =~ m/^\s*class\s+(\w+)/)
            {
 
 #            print "found class : $line \n";

Act Four: The Results

The resultant HTML looks like this:

From our previous example, this can be generated on the command line like so:

    % asciidoc --unsafe -e data-uri output.txt

The --unsafe and -e data-uri allows AsciiDoc to embed the images you’ve created directly into the HTML, instead of referencing them externally. This makes the document self-contained, in a sense. You can ignore these flags if you wish. In that case, standard <img> tags will be generated.

Epilogue: Warnings

This functionality was hacked together in about two hours. It does horrible things to Dia’s XML documents, it guesses at what the current spec for AsciiDoc is, and requires a hastily applied patch to a third party tool, AutoDia, in order to accomplish its goals. Because of it’s nature, I can’t make any guarantees as to how effectively it will work, what circumstances it will work under, and the like. If you have any suggestions or improvements, I implore you to fork the code (currently hosted at this Gist) and see what you can come up with. For example:

• I don’t even think it recognizes variables correctly. You might want to fix this.
• It ignores public:, private:, and protected:. You might want to fix this, but it is meant for design documents, so all methods should be documented.
• If a class has more than one constructor, only one will be displayed in the documentation. You might want to fix this.

    (This is a link)[http://www.google.com]

Then press the shortcut key you’ve assigned to it. I use ^↘.

I don’t know if it handles other hyperlink markup Markdown offers. Enjoy!

Multiruby embeds the name of a specific Rubygems mirror, http://files.rubyforge.vm.bytemark.co.uk/rubygems, into its code. This isn’t a horrible thing, since we can use an environment variable to overwrite it if that mirror stops responding; however, it may be a better idea to use the RubyForge mirror selector as that URL permanently. Until then,

# GEM_URL=http://master.mirror.rubyforge.org/rubygems/ multiruby_setup rubygems:update

Two threads of thought have occupied my attention since I stopped working on Canticore. They both have to do with perception and functionality of blogging engines, and they both kind of merge into each other. The first is the decision whether or not to include an web-based interface for writing, editing, and managing posts. Just like one of NetNewsWire’s design goals was to allow a person to literally have a coffee in one hand and read the news with the other, one of my design goals is to allow people to interact with Canticore in a comfortable environment. The song-and-dance of working in your favorite text editor and then copying and pasting your output to the web-based interface is anachronistic. We have our text editor, we have XML-RPC. Theoretically there should be nothing stopping us from keeping an arm’s length from the administrative process inherent in a web interface.

And if Canticore starts becoming a publishing platform instead of just a blog engine through its plugins, there’s nothing stopping plugin editors from defining mini-specs that would interface with a canticore command-line executable. Suppose, for example, a plugin existed that created a ‘featured’ list of articles like you see on many pages — an series of images and blurbs that transition from one to the next indefinitely. Ignoring for now the problem of uploading the media, the plugin could define a namespaced XML-RPC request that took a set of arguments. For our purposes, a 3-tuple of arguments for each ‘feature’ article will suffice:

  [
    { :image => 'garden.png', :blurb => 'Lorem ipsum...', :link_to_article => 14 }
    # ...
  ]

Canticore already contains an XML generator for the most-used data types in Ruby, so if these 3-tuples were defined in a YAML document, we could perform something like the following:

$ cat features.yml
--- 
- :image: garden.png
  :blurb: An article about gardens...
  :link_to_article: 1
- :image: cleaning.png
  :blurb: An article about cleaning...
  :link_to_article: 4
$ canticore --blog myblog --post pluginName.sendFeatures < features.yml

And we could receive a status message from the plugin as to if the features list was well-formed, if it could find all the necessary images and articles, and so on.

Now we’ve managed to segue into the second train of thought: a canticore command-line client. It would help generate blogs, retrieve information about them, and allow people to automate any task necessary for blog maintenance. It would include a Ruby API so it could be called from Rake scripts and the like, and we could throw it into crontabs whenever necessary, constantly building on the software that works well and already exists instead of trying to reinvent the wheel. The practical upshot of this is that people would have the ability to keep their articles locally, under source control, and even provide post-commit hooks for publishing, like some prominent content publishers in the Ruby arena seem to focus on (Jekyll, in particular).

If these both existed, it would be a cinch to use Gist as the de facto repository for all the Rails Templates we’ll start seeing when 2.3 gets released for reals.

spec_helper.rb

require 'rubygems'
require 'my_sinatra_app'
 
AwesomeApp.set :custom_option, "wopphta"
@app = Sinatra.new AwesomeApp

Then, you can make sure it exists:

awesome_app.rb

require 'rubygems'
require 'sinatra/base'
 
class AwesomeApp < Sinatra::Base
  get '/' do
    Sinatra::Application.custom_option
  end
end

It’s my fervent hope that I can use this abstract option-setting for individual instances of the AwesomeApp class in production mode. If that’s not the case, then oh well, but at least I have a way of setting test-specific options in the app.

Here was my original configuration. Two columns of spaces, three rows. Note the application assignments. I’ve asked Mail.app to stay on Space 5.

This is my new configuration. Three by three spaces. The application assignments haven’t changed, but they’ve changed in spirit. Where I was consigning Mail.app to the bottom left corner, it now sits right in the middle. Apple already has a plan for when the number of spaces are reduced – push everything from the removed ones onto the remaining ones. Shouldn’t there be a smarter way to handle the addition of spaces? If something’s in a corner, keep it there. If something’s on the top row, keep it there. I doubt there’s an intuitive way to both do this and keep the numbering system Leopard uses for designating spaces, but if anyone can do it, it’s Apple.

Minus all the cruft of being a gem, this is the only code you’ll write to create a Markdown plugin for your Canticore blog.

require 'canticore/plugin'
require 'rdiscount'
 
Canticore::PluginGem::Create 'markdown' do
  enhances :all
 
  def to_markdown_formatted_html data
    RDiscount.new(data).to_html
  end
 
  filter [:post, :body], :to_markdown_formatted_html
end

That filter command does exactly what you expect it to. Every time it comes across a post body, it sends it as the parameter to the function to_markdown_formatted_html! Simple as that.

Theme designers, take note: Filters are not applied automatically! The HAML line = post.body will still output the plain post body, and not spin up the filter function at all. The line = post.filtered(:body), however, will!

I haven’t yet decided if filters can be arbitrarily ordered. I think that’s needless complexity and I can’t think of a good reason to do so.

Interested in developing Canticore or for Canticore? There hasn’t been a better time to get started! Send a message to my GitHub profile if you’d like to contribute, and I’ll point you towards some thing that needs to be done. I have a fucking laundry list, here.

It’s called Canticore. It’s written in Ruby, and has the features I want in it, but this feature list may be common to a lot of people.

• (Multi)Markdown support
• Aggressive Caching
• Threaded comments
• Multiple users
• Painless upgrade
• Rich RSS (by category, post, tag, comment)
• Static pages
• Support for common blogging APIs (Blogger, metaWeblog, Movable Type)
• Syntax Highlighting
• Trackbacks
• Web administration

The most important feature is one that I think will make the difference. Plugins and themes are RubyGems. That’s it. That’s the killer thing. That’s what’s most important to me. I sat down and knew I wanted hooks and filters, themes, all that good stuff, but as I worked on the domain for those things, I realized RubyGems did everything I wanted my plugins and themes to do: simple versioning, metadata, easy installation and painless upgrading. So that became my new goal.

At this point, the codebase is a bit of an uncommented mess, but it has everything in place to make my goals work. This early announcement was pre-empted by two things: Matt’s removal of themes from wordpress.org, and GitHub’s announcement of their new feature, GitHub Pages: the former, because theme and plugin submissions on canticore.org will be provided with the ability to choose a license upon submission, and the latter because people might flock to that instead of looking for alternatives :-)

The repository is available at GitHub, along with the official website repository, some plugins to ensure certain functionality is baked in, and the first theme, called default.

I’ve secured a gorgeous place for people to upload gems that they create. I was considering creating a sub-reddit for this purpose, and not do any of this work, but I also wanted a demo server for people to try out themes that interest them. If you’re interested in contributing, or having a say in the next feature, or want to file bugs or tests, join the conversation! I want to make something exciting and beautiful, but I know I may not have the time to do it alone, anymore.

For people interested in how it works for plugin and theme developers, keep reading.

Plugins

Imagine being able to write a blog plugin with proper object-orientation! :-) Plugins have an extremely simple syntax that you can pick up just from reading a sample.

  require 'canticore/plugin'
 
  Canticore::Plugin::Create 'theme-changer' do
    enhances :index
    variable :before_text, 
      { :summary => "Dropdown Prefix Text", 
          :desc => "Text to display before the drop-down.",
          :default => "Change Theme: " }
 
    def output
      haml :output
    end
 
    hook :body, :output
 
  end

The #enhances block tells the blog what pages the plugin should be enabled on: :index just means it will be enabled on the landing page, and not archive pages, individual post pages, static pages, et cetera. You can also use enhances :all for a blanket enabling.

Each variable you want the user to change and be able to save to the database begins with a #variable function. Give it a name and a list of options.

Hooks are where you attach your functionality to Canticore. Right now there’s only a few, :body being one of them. The line hook :body, :output tells Canticore to attach the output of the function called :output to the body hook. You can use HAML for your plugins, in this case the function output looks for a file called views/output.haml in your plugin gem to render.

Filters are coming.

Themes

Themes are designed in HAML and can use SASS and plain old CSS. You need certain layout pages for your theme to be valid:

• archive.haml for archive listings.
• index.haml for the landing page of your blog.
• layout.haml for the global layout.
• page.haml for static page content.
• post.haml for individual post pages.
• _entry.haml for what a post will look like when displayed in a listing.

And that’s it! Static content goes in your gem under static, and stylesheets go under stylesheets, whether or not they’re SASS or CSS. Canticore is smart enough to figure it out. The name static/snapshot.png is reserved for the screenshot you want to take of your theme to display to users on canticore.org and in Canticore’s administration panel.

    =======================================================
    Report on Comment number 1 (id=2390)
    Comment Author: FIELD_NICKNAME
    Comment Content: 
    -----------------------------------------
    FIELD_MESSAGE_cnaroronoo