OfflineDocumentation

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

---

Table of contents

• Using Offline Documentation
  • Prerequisites
  • Building the *.html files
  • QMapTool documentation

---

Attention: This page describes features tested only with the Bitbucket Wiki!

Using Offline Documentation

The online QMapShack documentation (which you are probably just reading) is also available as offline documentation in the QMSgithub wiki If you have GIT installed, you can clone the QMapShack wiki by issuing the command

    git clone https://github.com/Maproom/qmapshack.wiki.git QMapShack-doc

The wiki consists of 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.

Prerequisites

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:

  • Abbreviations[^1]
  • Definition Lists[^1]
  • Fenced Code Blocks[^1]
  • Footnotes[^1]
  • Sane Lists
  • Table of Contents
  • Tables[^1]
  • 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]

[^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).

Building the *.html files

Open a bash shell window, 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]

[^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.

QMapTool documentation

The offline QMapTool documentation is located in the QMapShack-doc/QMapTool directory. To create navigation bars and HTML files for the files in this subdirectory change to this subdirectory and proceed as described above for QMS.

///Footnotes Go Here///

---

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