Using Offline Documentation
The online QMapShack documentation (which you are probably just reading)
is also available as offline documentation in the
of the source code distribution or as a Mercurial repository. If you
have Mercurial installed, you can clone the QMapShack wiki by issuing
hg clone https://bitbucket.org/maproom/qmapshack/wiki 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
Python 2.7 or better.
Python's Markdown module version 2.6.6 or better plus the following standard Markdown extensions:
- Definition Lists1
- Fenced Code Blocks1
- Sane Lists
- Table of Contents
Installation instructions for Markdown and its aforementioned extensions are for instance available here.
make. The makefile provided for maintaining the offline documentation uses "simply expanded variables" (defined via "
::=", as introduced by the Posix standard in 2012)2
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
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. ↩
If your version of
makecan't handle "
::=" and you can't find or install another one, simply replace all occurrences of "
::=" in file
Makefilein 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). ↩
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. ↩