OpenOrienteering Mapper User Manual

This repository is the source of the OpenOrienteering Mapper User Manual. It is online at https://www.openorienteering.org/mapper-manual/, and it is merged into the released software packages. User are encouraged to contribute to this manual on Github.

Information for contributors

Frontpage: pages/index.md

This manual uses American English.

Pages may be edited directly on Github. Github's online editor even features a preview. Changes must be saved to another branch and submitted by pull requests. Pull request are automatically spellchecked.

The manual pages are written in Markdown format, with some extensions. HTML is supported, too. The manual is published online by means of Jekyll and offline in the release packages by means of Doxygen. Only a subset of Markdown, Jekyll and Doxygen features is available for both publishing paths.

Guidelines

• Don't put or modify files outside the pages directory unless you know what you are doing. (Only this directory is merged back to the mapper repository.)
• Pages must be named ending in ".md" (for Markdown).
• Links to pages must use the .md ending, too.
• There must be a cycle-free page/subpage hierarchy. (This is used for the contents tree in the offline documentation.) To create a page/subpage relation, put {: .subpage} behind the link to the "subpage" in the "page" (cf. frontpage).
• Don't put to much effort in fancy formatting. (The HTML subset supported in the offline version is very limited.)
• Put images in the pages/images directory if they are used only in the documentation (e.g. screenshots).
• Images which are used by the Mapper software itself (residing in the images folder of the mapper repository) are merged here in the mapper-images subtree.

Information for maintainers

The following assumes that

• you are working in the mapper-manual repository (i.e. git remote "origin" points to the mapper-manual repository on Github),
• you added another git remote "mapper" which points to the mapper repository on Github,
• you fetched the master branch from the mapper repository,
• you configured a local branch "master" for the mapper repository.

The initial setup could look like this:

git clone -b gh-pages https://github.com/OpenOrienteering/mapper-manual.git
cd mapper-manual
git remote add mapper https://github.com/OpenOrienteering/mapper.git
git fetch mapper master

The git subtree command no longer creates the same history as when we started. But it is possible to run the original git-subtree.sh script, available at:
https://github.com/git/git/raw/refs/tags/v2.17.1/contrib/subtree/git-subtree.sh
The following steps assume that this script in a place where it is found via the PATH environment variable.

Merging the images from Mapper to the manual

The images used by Mapper are maintained in the images directory of the mapper repository. The mapper-manual gh-pages branch has a copy of these images in the mapper-images subtree. To update this copy, git subtree needs to be invoked twice. The git history is maintained in the mapper master branch, so we can squash all changes.

1. Split the images out of the mapper master branch into the mapper images branch:

   git fetch mapper master
   git checkout mapper/master
   git-subtree.sh split -P images
   

   The last command will print a git commit ID <sha> which can be used to create local or remote branches, or to access the commits directly.

2. Merge the images into the mapper-images subtree of the mapper-manual gh-pages branch:

   git fetch origin gh-pages
   git checkout origin/gh-pages
   git-subtree.sh merge -P mapper-images --squash <sha>
   

3. You can push the changes to your fork of the mapper-manual repository

   git push <your-remote> HEAD:refs/heads/update-pages
   

   When everything is ready, open a pull request in the manual repository of Mapper. Use title "Merge updated mapper-images".

Merging the pages from the manual repository to Mapper

The contents of the manual are maintained in the pages directory of this repository. The mapper repository master branch has a copy of these pages in the doc/manual/pages subtree. To update that copy, git subtree needs to be invoked twice. The git history is maintained in this repository's gh-pages branch, so we can squash all changes.

The following assumes that you are working in the mapper-manual repository (i.e. git remote "origin" points to the mapper-manual repository on Github), and you add another git remote "mapper" which points to the mapper repository on Github.

1. Split the pages out of this repository's gh-pages branch into the mapper manual branch:

   git fetch origin gh-pages
   git checkout origin/gh-pages
   git-subtree.sh split -P pages
   

   The last command will print a git commit ID <sha> which can be used to create local or remote branches, or to access the commits directly.

2. Merge the pages into the doc/manual/pages subtree of the mapper master branch.

   git fetch mapper master
   git checkout mapper/master
   git-subtree.sh merge -P doc/manual/pages --squash <sha>
   

3. You can push the changes to your fork of the mapper repository

   git push <your-remote> HEAD:refs/heads/update-pages
   

4. Integrate the changes in a local build, and check that Mapper builds without errors for doc/manual. Check the resulting manual. Really do that.

5. When everything is ready, open a pull request in the main repository of Mapper. Use title "doc/manual: Merge updated manual pages".