Latest News >> 2008-07-20 2008-06-25

I’ve been completely fed up with news/feed/rss/atom readers these days. I use Linux as my primary operating system, and I only have a few feeds that I want to rip through quick so I can get to reading the content. Yet, trying to find a reader that doesn’t suck donkey balls has been a chore.

2008-06-21

Wanna know what all the Ruby vulnerabilities are? Or at least have a fun look at how to search through code for clues? It’s a blast.

2008-06-13

I’m dropping a large blog post on everyone to just say that I haven’t died, I’ve just been busy working on my book for A/W about Mongrel. I had contracted with them to do a book about deploying Mongrel, but then decided it wouldn’t be a very good book since we’d already done one about that topic and there wasn’t too much more to say.

Idiopidae: code is code; prose is prose.

UPDATE: Be sure to look at the Vellum manual for a more complete example of what Idiopidae can do. You can grab the LaTeX code using Bazaar by typing bzr pull http://zedshaw.com/repository/vellum/ to see Idiopidae in a live project. Finally, the easiest way to install Idiopidae now is via: easy_install zapps pygments idiopidae. The rest of this page has been updated to reflect this.

Read my blog for today and yesterday for more information and links about Vellum and Idiopidae.

Idiopidae is a tool that helps technical documentation authors document software projects keeping the code in the code, and the prose in the prose. Idiopidae uses include/exclude statements to merge the code and the prose to produce the final result for publication. This lets the author work on the quality of the prose without need to focus on formatting, and on the code without worrying about it’s location in the book.

The goal for Idiopidae is that it allows me (and other authors) to create LaTeX, HTML, wiki text, plain text, or anything documents that include source-highlighted source from an active functioning project with the least amount of interference. It should work for any language, and should let you put those languages into any book you’re working on.

Features

Idiopidae already has most of the features you need to do single file prose that references multi-file source code. It should already work with HTML, Wiki text, plan text, and LaTeX, but you may have to play with it to get things right.

Current list of features are:

  • Your prose stays in the files that are best for your writing. LaTex, HTML, wiki, no matter.
  • Your code stays in the files that are best for software, in any language.
  • Only minimal ### @include and ### @export statements are needed (or /// for C languages).
  • A solid parser that gives you exact error messages for all parsed files so you don’t have to scrounge around looking for errors.
  • Source-highlighting with inputs for many languages and outputs for many prose formats. Since it’s Pygments you can also extend it.
  • An API that lets you re-use the Idiopidae parser to analyze documents for your own needs, such as code browsing or searching.
  • Guessing of the right prose or code format based on file hints, or you can explicitly say what format to use.
  • Line numbering always based on the actual position in the code, not in the book (not optional yet).

Downloads and Source

You can download the latest version 0.5 or you can grab the source using Bazaar by doing:

bzr pull http://www.zedshaw.com/repository/idiopidae

Installation

You can also install it directly using easy_install with the command:

sudo easy_install zapps pygments idiopidae

Which should be the latest version as well.

Testing

Then you should have the idio command line tool. The idio command just takes a file and expects all referenced source files to be accessible from your current working directory. To try it do this:

 > idio tests/data/output.html

That’s all there is to it. It will output your code sections.

Tools

Idiopidae is written in Python and uses Pygments for source formatting, Zapps for parsing, and Nose for testing.

Samples

The best sample is currently the Vellum manual which is the manual for my Vellum project done with LaTeX and Idiopidae. This manual is a work in progress so you can periodically grab it when I announce or you can grab the bzr repository for Vellum. See the Vellum project page for more information.

The best section in the Vellum manual to look at is Appendix A, which walks through all of Vellum’s code.

There’s a few other samples you can look to see what a document looks like at the different stages of processing:

  • sample.page—The raw original sample Textile document.
  • sample-pre-html.html—A version that is the textile processed by Idiopidae, notice it detected that .page is a text document so no formatting.
  • sample.html—The sample.page without any Idiopidae processing, just textile.
  • sample.final.html—The final sample, processed by Idiopidae as an HTML document giving full syntax-highlight and formatting with line numbers pulled from the source.

The final document was produced by doing:

 > idio output/projects/idiopidae/sample.html  > output/projects/idiopidae/sample.final.html

Which takes the HTML produced by Textile and merges in all the code from Idiopidae.