Clone wiki

QMapShack / OfflineDocumentation

Prev (Compile Instructions for Ubuntu-18) | Home | Manual | Index | (Getting started) Next

Using Offline Documentation

The online QMapShack documentation (which you are probably just reading) is also available as offline documentation in the doc/ sub-directory of the source code distribution or as a Mercurial repository. If you have Mercurial installed, you can clone the QMapShack wiki by issuing the command

    hg clone QMapShack-doc

Both, the source code distribution's doc/ sub-directory and the Mercurial repository contain Markdown (*.md) files, and to read them you will either need some Markdown plugin for your browser or you'll need to create *.html input files for your browser from the *.md files as described below.


To create the *.html files from the corresponding *.md files you will need:

  • Python 2.7 or better.

  • Python's Markdown module version 2.6.6 or better plus the following standard Markdown extensions:

    • Abbreviations1
    • Definition Lists1
    • Fenced Code Blocks1
    • Footnotes1
    • Sane Lists
    • Table of Contents
    • Tables1
    • WikiLinks

    Installation instructions for Markdown and its aforementioned extensions are for instance available here.

  • GNU make. The makefile provided for maintaining the offline documentation uses "simply expanded variables" (defined via "::=", as introduced by the Posix standard in 2012)2

Building the *.html files

Change into the QMapShack-doc directory containing the offline documentation and issue the commands

cd QMapShack-doc
make doc
_YourBrowser_ DocMain.html

This will create any new and update all outdated *.html files before it opens your browser at the main documentation page. If you plan to frequently reference the offline documentation, you might consider creating a command alias from the last command line above by executing

alias qms-doc='YourBrowser /absolute/path/to/doc/DocMain.html'3

  1. These extensions are sub-extensions included in Python's Markdown Extra extension. Since these are the only sub-extensions of the Extra extension which are supported by the Bitbucket server, these are also the only extensions of the Extra extension used by the conversion script. 

  2. If your version of make can't handle "::=" and you can't find or install another one, simply replace all occurrences of "::=" in file Makefile in the documentation directory with "=". In this makefile using "simply expanded variables" (defined via the "::=" assignment) rather than "recursively expanded variables" (defined via the normal "=" assignment) is just a matter of efficiency: referencing variables assigned with "::=" will burn less CPU cycles but in the case at hand will not produce different results in any way ("::=" is the type of variable assignment we are used from normal programming languages, while "=" behaves more like a function definition). 

  3. Under Cygwin you should instead use

    alias qms-doc="YourBrowser $(cygpath -w /absolute/path/to/doc/DocMain.html)"

    because in that case the argument passed to your browser must be interpretable as a Windows path. 

Prev (Compile Instructions for Ubuntu-18) | Home | Manual | Index | Top | (Getting started) Next