Generating HTML from Markdown with Pandoc

I'm writing more and more things that are not code these days, and my content-managing toolchains are becoming more developed all the time. I've written in REstructured Text, Asciidoc, and LaTeX, and today I'm working on an article which eventually wants to be HTML but I'm creating in Markdown because it's much easier.

My swiss army knife of document formats is a program called pandoc. It's absolutely fabulous, powerful, and not too complicated if you don't need to do anything too complicated. It will guess input and output formats from file extensions, or you can be more specific if you need to. Today's command looks like this:

pandoc article.md -o article.html

You won't be surprised to hear that this command takes a file called article.md which contains my markdown, and outputs a file called article.html containing the HTML. I also use this to convert between all the various text markups, HTML, but also PDF and office document formats - it's a very comprehensive tool!

Screencasting in Ubuntu: Kazam

If you've ever seen a live demo, you will know that these things are fraught with danger. Even if the wifi works, the presenter knows what they are doing, and nothing crashes, you'll often end up watching someone explaining something to their laptop in detail, or clearly demonstrating their inability to type. Either way, it doesn't make good, informative content, which is why I never ever demo in a conference talk - I'm there to entertain and time is always of the essence. At this point, you can probably guess why I'm writing a blog post about my screencasting toolchain - I simply pre-record whatever it is that I want to show in the talk.

On an ubuntu platform, I've had a few false starts with video over the years, and mostly avoided it. But now my "Debugging HTTP" talk really does make more sense if you can see the process of something broken, what the tools show, and how to understand that information and fix the problem.

Kazam

kazam-close Continue reading

Accurate Ubuntu Window Sizing with Wmctrl

I'm working on a bunch of screencasts at the moment (more posts to come) and one of the things that tripped me up the most was getting all the windows the same size, so that the resulting videos are the same size and can easily be put back together. Enter wmctrl, a very nice linux tool that can do all of this for me.

I'm aiming to have a series of windows all sized at 800x600, and the first step is to look at a list of windows in wmctrl:

wmctrl -lG

wmctrl-lg

The -l switch provides a list, and the -G switch shows the geometry of the windows. This is especially useful if you want to place something on a second monitor, you can look where a correctly-placed window would go and then use those co-ordinates! Also beware that windows positioned at the origin of a desktop space rarely end up where you expect them to go.

To set a new geometry for a window, we use the -e switch to specify what that should be. The format is:

"gravity, X, Y, width, height"

For gravity, try zero. X and Y are the co-ordinates of the top left hand corner of the window, and width and height hopefully you can guess. It's also acceptable to pass -1 for any of these values for the window to retain its current setting.

To specify a window, we use the -r switch to indicate to wmctrl which window wants the resize. You can give the title of the window, or the identifier shown in the list output, but I found it most useful to use the special value ":SELECT:" and then just click on the window I wanted to affect. Therefore the command I used the most became:

wmctrl -r ":SELECT:" -e "0, -1, -1, 800, 600"

As a final tip, make sure (by resizing the window to something definitely smaller than the desktop it is on) that the window is not maximised - if it is, it will stay that way and you will wonder what you are doing wrong.

Ttytter: Command Line Twitter Tweaks

I've been using ttytter for quite a while, it's a superbly inoffensive twitter client - and it's console-based. This makes it easy to use from the keyboard, fast, and also makes it look a bit less like twitter if that's not something people should be seeing over your shoulder!

I have customised a few settings which I find superhelpful, so I thought I'd share my config file and say a bit about some of the entries in there. The config for ttytter is held in a file called .ttytterrc in my home directory. Mine looks like this: Continue reading

DC4D 6: Not-Programming for Programmers

In case you haven't seen the news, the next episode of Day Camp 4 Developers is coming up on Friday 26th July. This edition is about getting beyond being awesome at the code, which we know that you are, and picking up some other skills to complete you as a profesional. Whether you work in a large international corporation, a smaller company, or alone, we've got content that will make a difference.

Day Camp 4 Developers is a virtual conference, and it's $40 (about 25 quid for UK people). If you can't make it on the day, just get the video ticket and download the recorded sessions later. What I'm trying to say in this paragraph is that there are quite literally no excuses for missing out on this :)
Continue reading

Are Subqueries RESTful?

Twitter is great for one-liners, but it's very difficult to carry on any kind of advanced conversation there. Therefore when I saw this tweet yesterday, I knew I'd be picking a different medium to reply:

The blog seems like a good place, as I can put examples and all kinds other things here, and waffle at length (which is really why I like it!). Because when condensed to tweet form, the answer is really "it depends".

The Problem(s)

REST is all about representations of resources. They might come in different formats, and they might appear at their own URI as well as in one or more collections, but essentially you just get a representation of a thing. This is great, apart from when it isn't.

  • What if you want a smaller result set with only a limited number of fields?
  • What if you want related data? For every resource in a collection?

Continue reading

What Goes in Source Control?

Short answer: everything! However we need some good directory structures and source control configuration to make that a really practical answer, so this article is a quick outline of my usual advice for a good source control structure for a standard web project. The examples are for a PHP project but I'm sure you could apply this to your own language of choice, also. Continue reading

Pretty-Printing JSON with Python's JSON Tool

Today's quick tip is something that was widely retweeted after my "Debugging HTTP" talk at the ever-fabulous WhiskyWeb conference last weekend. When working with JSON on the commandline, here's a quick tip for showing the JSON in a nicer format:

curl http://api.joind.in | python -mjson.tool

You need python installed, but the JSON extension is probably included, and that's all you need for this tool. The result is something like:

python-mjsontool

You can also use this approach to present JSON data that has been captured to another file, for example, it's a handy trick that I use often when developing something with JSON as a data format.

Installing XHGui

There's a new version of XHGui (well, a few months old) and it's fabulous! It's got a few new dependencies though so I thought I'd write down how I set up my version, in case it's helpful to anyone else (and so I feel like a pro next time I have to do this!). If you're not familiar with XHGui it's a fabulously easy and friendly way to profile your application; to understand which method calls in a page take the time and how many times they are made, so you can improve the performance of your application. All these instructions are for my 32-bit Ubuntu 12.10 system, hopefully they will work for you or you'll be able to adapt them as appropriate.

Dependencies

XHGui needs version numbers or fluffy animal names, because this is a really major release and quite different to what went before in both technology and in looks. In particular, it now uses MongoDB. If you're not familiar with MongoDB, it's a super-friendly NoSQL database that makes a really handy backend for this kind of unstructured data - because every run of every page will look different. Therefore you will need:

  • MongoDB itself
  • The pecl extension for mongo
  • The xhprof pecl extension (read on if you're using PHP 5.4, there's a gotcha)

Continue reading

Endpoints for HTTP Testing

While working on a book ("PHP Web Services" from O'Reilly, not out yet but soon!) recently, I was looking for some place I could make HTTP requests to, to show off how to make different kinds of requests with different tools. On my own machine, I have a couple of scripts that chatter back giving debug information about the requests that were made, but I wanted to get the tools examples going without any additional dependencies at all. I hadn't used anything like these tools before, but I found quite a few alternatives, so I thought I'd share what I came up with. Continue reading