Resulting docs identical for pandoc 1.12 and 1.13

Several fixes:
 1. Use perl instead of sed for consistent behaviour between platforms
 2. Change the way we include files into the docs so the pandoc filter.
    works for both 1.12 and 1.13.
 3. More escaping fixes

Closes #1919 

@Habbie could you test this on Mac OS X?