Make resulting docs identical in 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
Merge pull request #1929 from pieterlexis/clean-doc-build

Resulting docs identical for pandoc 1.12 and 1.13