Terry Burton's blog
The weblog of Terry Burton, Leicester, UK

<<< Home

Creating PDF Documentation From a GitHub Wiki Using Pandoc

By , .

The following explains how the printable documentation for Barcode Writer in Pure PostScript was refreshed so that it could be generated primarily from content in the wiki.

Adding the Wiki as a Git Submodule

To allow the documentation build system to access files in the wiki, build directory and main project repository using predictable relative file names you can add the wiki repository as a git submodule to the main repository:

git submodule add ../postscriptbarcode.wiki.git wikidocs

In future you will want to checkout your repository as follows:

git clone --recursive git@github.com:bwipp/postscriptbarcode.git

Documentation Build System File Structure

We create the Pandoc-based documentation build system in the __pandoc directory of the wikidocs submodule.

wikidocs
│
│ (Documentation build system)
│
├── __pandoc
│   │
│   ├── Makefile ①
│   │
│   │ (Symlink to wiki images directory)
│   │
│   ├── images -> ../images/
│   │
│   │ (Filters for pre-processing the wiki markdown)
│   │
│   ├── __rewritewikilinks.hs ②
│   ├── __rewritepngtoeps.hs ③
│   │
│   │ (PDF specific content — mainly section headings, introductions, etc.)
│   │
│   ├── __symbology-reference.md
│   ├── __options-reference.md
│   └── __knowledge-base.md
│
│ (Normal wiki content follows)
│
├── images
│   ├── ean13-1.eps   (EPS files purpose generated for PDF documentation)
│   └── ean13-1.png
│
├── symbologies
│   └── EAN-13.md
├── options
│   └── Text-Properties.md
└── kb
      └── FAQs.md

Pandoc Arguments

To build the PDF documentation we run Pandoc with as follow:

$ pandoc

  --from=markdown_github
  --to=latex

  --filter __pandoc/__rewritewikilinks.hs ②
  --filter __pandoc/__rewritepngtoeps.hs ③

  -M title="Barcode Writer in Pure PostScript"
  -M author="http://bwipp.terryburton.co.uk"

  -V geometry:a4paper,margin=2cm

  --toc --toc-depth=2
  --chapters

  --output=__pandoc/barcodewriter.pdf

  [ followed by a list of *.md files ]

Note that this requires Pandoc version 1.12 or later for filter support.

Makefile ①

Using a makefile allows the documentation to be rebuilt and added to the main repository using the following commands:

$ cd wikidocs
$ make -f __pandoc/Makefile
$ cp __pandoc/barcodewriter.pdf ../docs
PANDOC_DIR = __pandoc
PANDOC_TEMPLATE_LATEX = $(PANDOC_DIR)/templates/template.latex
EPS_IMAGES = $(wildcard images/*.eps)
PDF_DOCS  = $(PANDOC_DIR)/barcodewriter.pdf

define MD_FILES =
  ../README.md                            \
  kb/Quick-Guide.md                       \
  ../src/README.monolithic                \
  ../src/README.resource                  \
                                          \
  $(PANDOC_DIR)/__symbology-reference.md  \
  symbologies/EAN-13.md                   \
...
  $(PANDOC_DIR)/__options-reference.md    \
  options/Text-Properties.md              \
...
  $(PANDOC_DIR)/__knowledge-base.md       \
  kb/FAQs.md                              \
...
  ../cited-by.md
endef

$(PDF_DOCS): $(MD_FILES) $(EPS_IMAGES) $(PANDOC_TEMPLATE_LATEX) $(INTRO_FILE_LATEX)
    pandoc                                      \
  -f markdown_github -t latex                   \
  -F $(PANDOC_DIR)/__rewritewikilinks.hs        \
  -F $(PANDOC_DIR)/__rewritepngtoeps.hs         \
  -M title="Barcode Writer in Pure PostScript"  \
  -M author="http://bwipp.terryburton.co.uk"    \
  -V geometry:a4paper,margin=2cm                \
  --toc --toc-depth=2                           \
  --chapters                                    \
  -o $@                                         \
  $(MD_FILES)

Filter: rewritewikilinks.hs ②

Rewrite relative links to other wiki pages to lowercase in-page style links maintaining existing in-page links and absolute website links, e.g. links to a EAN-13 wiki page would become a #ean-13 in-page link. Then ensure that each page begins with a heading named after the page such that these rewritten links map to the label for the corresponding heading thus maintaining a functioning navigation system in the final PDF document.

#!/usr/bin/env runhaskell

import Text.Pandoc.JSON
import Data.Char

main = toJSONFilter rewritewikilinks

rewritewikilinks :: Inline -> [Inline]
rewritewikilinks ( Link txt ('#':url,title) ) = [ ( Link txt ("#"++url,title) ) ]
rewritewikilinks ( Link txt ('h':'t':'t':'p':':':url,title) ) = [ ( Link txt ("http:"++url,title) ) ]
rewritewikilinks ( Link txt ('h':'t':'t':'p':'s':':':url,title) ) = [ ( Link txt ("https:"++url,title) ) ]
rewritewikilinks ( Link txt (url,title) ) = [ ( Link txt ("#" ++ map toLower url,title) ) ]
rewritewikilinks x = [x]

Filter: rewritepngtoeps.hs ③

Rewrite sources for images from .png file to the corresponding .eps file. Obviously this requires you to create the EPS files in the first place. For barcodes this greatly improves the quality of the images in the PDF output by maintaining them in vector format. This might not be as important for other types of content.

#!/usr/bin/env runhaskell

import Text.Pandoc.JSON
import System.FilePath

main = toJSONFilter rewritepngtoeps

rewritepngtoeps :: Inline -> [Inline]
rewritepngtoeps ( Image txt (url,title) ) = [ ( Image txt (rewritefile url,title) ) ]
rewritepngtoeps x = [x]

rewritefile :: String -> String
rewritefile filename = replaceExtension filename ".eps"

<<< Home


Comments


Homepage | Online Barcode Generator | Barcode Writer in Pure PostScript