-
Notifications
You must be signed in to change notification settings - Fork 63
OfflineDocumentation
Prev (Compile Instructions for OSX) | Home | Manual | Index | (Getting started) Next
Table of contents
Attention: This page describes features tested only with the Bitbucket Wiki!
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.
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).
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.
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 OSX) | Home | Manual | Index | Top | (Getting started) Next