linux

Lately I’ve been working on a pretty hefty spec for work (hint hint… it’s a REST API spec). I like writing my specs in TextMate using MediaWiki markup, so I can easily post them to our internal wiki once they’re ready.

One of the annoying things about this spec is that it involves dozens of examples in XML and JSON that are embedded in <pre> tags. I wanted to be able to develop and edit these samples as native XML and JSON files for convenience, but it was becoming a real pain to keep them updated in the main document via cut and paste. The obvious solution to this problem is a text preprocessor that would allow you to include a .xml file in the main .wiki document. There are dozens of these, but they’re all a pain in the butt to use and I didn’t feel like setting them up.

The solution, which couldn’t possibly be more obvious, was suggested, somewhat jokingly, by a coworker of mine:

cpp

Yup, the good old GNU C Preprocessor. If you run Linux, or you have a Mac (basically, any *nix), or you do any development whatsoever, chances are you have one hiding out on your machine somewhere. Chances are you’re also familiar with the #include "foo.h", which you’ve used since freshman year to have the preprocessor include the header for another C file before it passes it off to the actual compiler. But you never thought about using it to help you with your homework (or your specs) before.

Well cpp has a handy -P parameter that tells it to forgo the inclusion of the normal linemarkers it includes for the benefit of the compiler. This makes it perfect for simple stuff like embedding one text file in another.

In your main document, use a #include statement to include your example file:

document.txt:

== XML Example ==
The following is an example of the server's response in XML:

<pre>
#include "example.xml"
</pre>

example.xml:

<example>
      <message>Hello World!</message>
</example>

Then use a simple Makefile to build your output document:

Makefile:

all:
        cpp -P document.txt document.out.txt

Using a Makefile means you can use TextMate’s Makefile bundle to quickly and easily build your document.

There you go, a completely “duh” way of doing simple text includes on any *nix system.