Latest News >> 2008-04-29

UPDATE: There seems to be some interest in Idiopidae too and I’ve been neglecting the Idiopidae project page while working on Vellum. I’ve updated that page with information and updated install procedures, so please check it out again if nothing worked for you.

2008-04-26

UPDATE: I forgot to mention that this is my first LaTeX text ever and that it’s based on one of my first Python projects and that I wrote what you find below in about 3 days while dorking around on Vellum and Idiopidae. Since I’m both a Python and LaTeX newb please feel free to school me. Better yet, if you think the typesetting sucks, then show me your samples. See if you can beat this one sent to me by Kashif Rasul. I still consider what he’s created as the bar to get over.

2008-04-18

While working on a more complex build I decided to make recursive imports work and clean up the syntax for imports in Vellum

2008-04-15

I worked on Vellum today after waking up from jetlag and Poland. I feel like it’s near ready for actual use by people. I even managed to polish it off with a nice little command line option for dumping the commands a build spec uses including their documentation. Check out this Pastie clip that shows it off.

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.