Public | Automated Build

Last pushed: a year ago
Short Description
Open Soc Debug document converter using pandoc
Full Description

Open SoC Debug Documentation Converter

The Open SoC Debug documentation is written in
Markdown. For optimal viewing it can be converted into HTML or PDF output
documents. The Docker container inside this repository contains an application
to perform this conversion.

The conversion is handled by pandoc, which is combined
with additional plugins (filters) for modifying the output to fit our needs.

Features:

  • PDF and HTML5 output
  • SVG images are supported
  • Cross-references inside the document are supported using the
    pandoc-crossref
    syntax.

Convert documents

Nothing simpler than that! You only need to install Docker and a small run
script to invoke the application inside the container.

Install Docker (if you don't already have it installed)

On Ubuntu, run (note the package name!)

$ sudo apt-get install docker.io

Get the run script

This repository contains a script which runs Docker with the necessary options.
You can either use it from this repository, or download it from GitHub.

$ curl -O https://raw.githubusercontent.com/opensocdebug/opensocdebug-doc-converter/master/osd-doc-converter
$ chmod +x osd-doc-converter

Convert documents

Call osd-doc-converter to convert documents.

Important note on file paths:
The conversion script cannot access any file in the directory hierarchy above
the directory in which you execute the script (the current working directory).
Usually, you should run the script from the topmost directory that contains your
input files and possibly any templates.

See what's possible

Call the container with --help (or just without any argument)

$ ./osd-doc-converter --help
usage: convert.py [-h] -o OUTPUT [--template TEMPLATE] [-f {pdf,html5}]
                  infile [infile ...]

positional arguments:
  infile                input file(s)

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        output file name
  --template TEMPLATE   custom template
  -f {pdf,html5}, --output-format {pdf,html5}
                        output format

Convert from Markdown to PDF

$ ./osd-doc-converter -f pdf -o overview.pdf overview/overview.md

If all goes well, the overview.pdf file is now created.

Convert from Markdown to HTML

$ mkdir outdir
$ ./osd-doc-converter -f html5 -o outdir/overview.html overview/overview.md

For HTML documents with images, the outdir directory also contains an img
subfolder with all referenced images.

Docker Pull Command
Owner
opensocdebug

Comments (0)