From 8731cc5ad70723b9a155917df509d857579c355d Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Tue, 21 Apr 2020 03:02:38 +0000
Subject: CTAN sync 202004210302

---
 .../mercatormap/mercatormap.doc.maptiles.tex       | 934 +++++++++++++++++++++
 1 file changed, 934 insertions(+)
 create mode 100644 macros/latex/contrib/mercatormap/mercatormap.doc.maptiles.tex

(limited to 'macros/latex/contrib/mercatormap/mercatormap.doc.maptiles.tex')

diff --git a/macros/latex/contrib/mercatormap/mercatormap.doc.maptiles.tex b/macros/latex/contrib/mercatormap/mercatormap.doc.maptiles.tex
new file mode 100644
index 0000000000..c5289f537c
--- /dev/null
+++ b/macros/latex/contrib/mercatormap/mercatormap.doc.maptiles.tex
@@ -0,0 +1,934 @@
+% !TeX root = mercatormap.tex
+% !TeX encoding=UTF-8
+% !TeX spellcheck=en_US
+% include file of mercatormap.tex (manual of the LaTeX package mercatormap)
+\clearpage
+\section{Automated Map Definition and Map Tiles}\label{sec:automated_map}%
+
+\begin{center}
+\begin{tikzpicture}[every node/.style={minimum width=3cm,minimum height=2cm,
+  align=center,fill=red!5,draw=red!50!gray}]
+\node (A) {Map Supply};
+\node[at=(A.east),right=8mm] (B) {Python Script};
+\node[at=(B.east),right=8mm] (C) {Map Apply};
+\node[at=(C.east),right=8mm] (D) {Map Drawing};
+\begin{scope}[->,very thick,Blue_Gray]
+\draw (A)--(B); \draw (B)--(C); \draw (C)--(D);
+\end{scope}
+\end{tikzpicture}
+\end{center}
+
+As illustrated above, the script aided map definition is a process with
+several stages.
+
+\begin{itemize}
+\item Map Supply: \refCom{mrcsupplymap} is the replacement of the manual setup by
+  \refCom{mrcdefinemap}. Actually, it is quite similar to \refCom{mrcdefinemap}.
+  With \refCom{mrcsupplymap} directions for the following Python script
+  are formulated.
+\item Python Script: The script is executed by \refCom{mrcsupplymap} during
+  compilation. It does some coordinate system computations and downloads
+  map tiles from a Web server. Finally, it writes a map definition into
+  a file \meta{id}|.def|.
+\item Map Apply: \refCom{mrcapplymap} reads and applies the
+  map definition from \meta{id}|.def|.
+\item Map Drawing: Afterwards, the map can be drawn by \refCom{mrcdrawmap}
+  and other commands.
+\end{itemize}
+
+A map can be applied more than once, e.g. reused later in the document.
+If this is not needed, map supply and map apply can be combined by
+\refCom{mrcmap}.
+
+
+%-------------------------------------------------------------------------------
+\subsection{Script Activation}
+
+Remember to install Python beforehand, see \Fullref{sec:python}.
+
+\begin{docCommand}{mrcactivatescript}{}
+  Use this inside the preamble of your document to activate the
+  accompanying Python script.
+  Without this command, the script is not executed!
+  If the document is final (or the maps are final),
+  this line could be removed and the document
+  should be compilable without script.
+\end{docCommand}
+
+
+\begin{docMrcKey}{python}{=\meta{python}}{no default, initially |python|}
+  Names the Python~3 interpreter as \meta{python}. If your Python~3 interpreter
+  is not called |python|, but e.g. |python3|, then use
+  \begin{dispListing}
+  \mermapset{python=python3}
+  \end{dispListing}
+\end{docMrcKey}
+
+
+\clearpage
+%-------------------------------------------------------------------------------
+\subsection{Map Types}
+Currently, there are three methods provided how a map is computed by the
+accompanying Python script. The technical background is documented in
+\cite[Section~5]{Sturm:2020}.
+
+\begin{enumerate}
+\item \refKey{/mermap/supply/type}|=|\docValue{reference}:
+  \tcbsidebyside[sidebyside adapt=left,blankest,grow to left by=1cm]
+  {
+  \tikzexternaldisable
+  \begin{tikzpicture}
+  \useasboundingbox (0,0) rectangle (3,2);
+  \path[draw,fill=yellow!10] (0,0) rectangle (3,2);
+  \path[fill=red] (1.5,1) circle [radius=1mm];
+  \end{tikzpicture}
+  }{
+  The default method determines the map dimensions from a reference
+  position and given document map dimensions.
+  Also, a zoom level \refKey{/mermap/supply/zoom}
+  is required which relates to the Web Mercator map tile covering of the Earth.
+  A higher zoom level gives a growing number of smaller map tiles.
+  Alternative to the zoom level, a \meta{scale denominator} can be provided
+  by \refKey{/mermap/supply/flex area scale}, \refKey{/mermap/flex scale}
+  or \refKey{/mermap/supply/flex reference scale} which determines
+  the zoom level implicitly.
+  As default, the reference position is the center of the map, but can be
+  aligned at the map borders. This method is quite safe to use and could
+  be the preferred one for many applications like showing the neighborhood
+  of a route target.
+  Finding the best reference point for depicting a certain area could
+  be more tricky.
+  }
+
+\item \refKey{/mermap/supply/type}|=|\docValue{areafit}:
+  \tcbsidebyside[sidebyside adapt=left,blankest,grow to left by=1cm]
+  {
+  \tikzexternaldisable
+  \begin{tikzpicture}
+  \useasboundingbox (0,0) rectangle (3,2);
+  \path[draw,fill=yellow!10] (0,0) rectangle (3,2);
+  \path[draw=red,line width=0.5mm] (0.2,0.5) rectangle (2.8,1.5);
+  \end{tikzpicture}
+  }
+  {
+  The map dimensions are determined by an area with
+  latitude and longitude boundaries which is fitted into given
+  document map dimensions. The zoom level is computed accordingly
+  for a fixed document tile size or by \refKey{/mermap/supply/flex area fit}.
+  In any case, the map contains the target area plus some protrusion.
+  This method is also quite safe to use and may be
+  the preferred one for many applications like showing a map which contains
+  a bunch of markers (e.g. for locations of universities).
+  If the map borders are required to exactly meet the boundaries,
+  the third method can be regarded.
+  }
+
+\item \refKey{/mermap/supply/type}|=|\docValue{boundaries}:
+  \tcbsidebyside[sidebyside adapt=left,blankest,grow to left by=1cm]
+  {
+  \tikzexternaldisable
+  \begin{tikzpicture}
+  \useasboundingbox (0,0) rectangle (3,2);
+  \path[draw=red,line width=0.5mm,fill=yellow!10] (0.2,0.5) rectangle (2.8,1.5);
+  \end{tikzpicture}
+  }{
+  The most obvious method determines the map dimensions from
+  latitude and longitude boundaries. For this, a corresponding zoom level
+  \refKey{/mermap/supply/zoom}
+  is required which relates to the Web Mercator map tile covering of the Earth.
+  Alternative to the zoom level, a \meta{scale denominator} can be provided
+  by \refKey{/mermap/supply/flex area scale}
+  or \refKey{/mermap/supply/flex reference scale} which determines
+  the zoom level implicitly.
+  Note that a too high zoom level imposes the risk of downloading an unwanted
+  high quantity of map tiles resulting in a much too large document map.
+  Therefore, this most obvious method is \emph{not recommended} for the
+  beginner and may be explored after some experience.
+  }
+\end{enumerate}
+
+
+
+\clearpage
+%-------------------------------------------------------------------------------
+\subsection{Map Supply}
+
+\begin{docCommand}{mrcsupplymap}{\oarg{options}\marg{definition}}
+  The \meta{options} provide parameters for the Python~3 script to supply all
+  materials for a map.
+  All options share the common prefix |/mermap/supply/|.\par
+  The map is identified by\\
+  \meta{id}=\refKey{/mermap/definition prefix}+\meta{definition}\\
+  for later drawing.
+  This identifier \meta{id} has to be unique for the document.
+  It corresponds to generated files \meta{id}|.def|, \meta{id}|.md5|, and
+  possibly \meta{id}|.png|.
+  Do not use spaces or special characters like umlauts for \meta{definition}.
+  \par
+  If \refCom{mrcactivatescript} is used inside the preamble,
+  \refCom{mrcsupplymap} executes the Python~3 script, otherwise nothing happens.
+\end{docCommand}
+
+
+\begin{docCommand}{mermapsetsupply}{\marg{options}}
+  Sets \meta{options} for all following maps inside the current \TeX\ group.
+  All options share the common prefix |/mermap/supply/|, e.g. for setting
+  \refKey{/mermap/supply/type} use
+  \begin{dispListing}
+    \mermapsetsupply{type=reference}
+  \end{dispListing}
+  Also see \refCom{mermapset} and \refCom{mermapsetmarker}.
+\end{docCommand}
+
+
+\begin{docMrcKey}{definition prefix}{=\meta{definition prefix}}{no default, initially |maps/|}
+  Prefix for map identifiers and generated map files, see \refCom{mrcsupplymap}
+  and \refCom{mrcapplymap}.
+  Note that \refKey{/mermap/definition prefix} is not to be used inside
+  the option list for \refCom{mrcsupplymap}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/type}{=\meta{type}}{no default, initially |reference|}
+  The \meta{type} defines the basic computation for the map. Feasible values are
+  \begin{itemize}
+  \item\docValue{reference}: \flqq map with reference position\frqq\\
+    The map is constructed from a given reference position
+    \refKey{/mermap/supply/latitude},\\
+    \refKey{/mermap/supply/longitude},\\
+    a zoom level \refKey{/mermap/supply/zoom},\\
+    map dimensions\\
+    \refKey{/mermap/supply/width},\\
+    \refKey{/mermap/supply/height},\\
+    and alignment \refKey{/mermap/supply/align}.
+  \item\docValue{areafit}: \flqq map fitting an area\frqq\\
+    The map is constructed from a given area boundaries\\
+    \refKey{/mermap/supply/west},\\
+    \refKey{/mermap/supply/east},\\
+    \refKey{/mermap/supply/north},\\
+    \refKey{/mermap/supply/south},\\
+    map dimensions\\
+    \refKey{/mermap/supply/width},\\
+    \refKey{/mermap/supply/height},\\
+    and alignment \refKey{/mermap/supply/align}.
+  \item\docValue{boundaries}: \flqq map with boundaries\frqq\\
+    The map is constructed from given boundaries\\
+    \refKey{/mermap/supply/west},\\
+    \refKey{/mermap/supply/east},\\
+    \refKey{/mermap/supply/north},\\
+    \refKey{/mermap/supply/south},\\
+    and zoom level \refKey{/mermap/supply/zoom}.
+  \end{itemize}
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/zoom}{=\meta{setup zoom}}{no default, initially |9|}
+  Map tile zoom factor alias $z$ coordinate of the map tiles.
+  Used for map types \docValue{boundaries} and \docValue{reference}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/north}{=\meta{setup north latitude}}{no default, initially |50|}
+  Northern latitude degree, possibly negative for the southern hemisphere,
+  lower than $90$ but always larger than \refKey{/mermap/supply/south}.
+  Used for map types \docValue{boundaries} and \docValue{areafit}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/south}{=\meta{setup south latitude}}{no default, initially |48|}
+  Southern latitude degree, possibly negative for the southern hemisphere,
+  larger than $-90$ but always lower than \refKey{/mermap/supply/north}.
+  Used for map types \docValue{boundaries} and \docValue{areafit}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/west}{=\meta{setup west longitude}}{no default, initially |11|}
+  Western longitude degree, possibly negative for the western hemisphere,
+  possibly shifted periodically, but always lower than \refKey{/mermap/supply/east}.
+  Used for map types \docValue{boundaries} and \docValue{areafit}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/east}{=\meta{setup east longitude}}{no default, initially |13|}
+  Eastern longitude degree, possibly negative for the western hemisphere,
+  possibly shifted periodically, but always larger than \refKey{/mermap/supply/west}.
+  Used for map types \docValue{boundaries} and \docValue{areafit}.
+\end{docMrcKey}
+
+
+\begin{docMrcKey}{supply/area}{=\marg{comma separated list of named positions}}{no default}
+  Sets
+  \refKey{/mermap/supply/north}, \refKey{/mermap/supply/south},
+  \refKey{/mermap/supply/west}, \refKey{/mermap/supply/east}
+  according to the given \meta{comma separated list of named positions}, i.e.
+  the described area contains all these positions.
+  Note that you need at least two points inside the list.
+  Also note to take special care, if the international dateline is on your
+  resulting map, see \Fullref{sec:dateline}.
+  Used for map types \docValue{boundaries} and \docValue{areafit}.
+\end{docMrcKey}
+
+
+\begin{docMrcKey}{supply/add area}{=\marg{comma separated list of named positions}}{no default}
+  Nearly identical to \refKey{/mermap/supply/area}, but
+  the given \meta{comma separated list of named positions}
+  does not reset the current area, i.e. the positions are added to the
+  current area which possibly grows to fit all positions.
+  Used for map types \docValue{boundaries} and \docValue{areafit}.
+\end{docMrcKey}
+
+
+\begin{docMrcKey}{supply/area to reference}{}{no value, initially unset}
+  The map settings
+  \refKey{/mermap/supply/north}, \refKey{/mermap/supply/south},
+  \refKey{/mermap/supply/west}, \refKey{/mermap/supply/east}
+  are taken to compute the map center. This center position is saved
+  to \refKey{/mermap/supply/latitude} and \refKey{/mermap/supply/longitude}.
+  Used for map type \docValue{reference}.
+\end{docMrcKey}
+
+
+
+\begin{docMrcKey}{supply/latitude}{=\meta{setup latitude}}{no default, initially |49|}
+  Latitude degree of a reference point, possibly negative for the southern hemisphere.
+  Used for map type \docValue{reference}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/longitude}{=\meta{setup longitude}}{no default, initially |12|}
+  Longitude degree of a reference point, possibly negative for the western hemisphere.
+  Used for map type \docValue{reference}.
+\end{docMrcKey}
+
+
+\begin{docMrcKey}{supply/position}{=\meta{setup latitude}:\meta{setup longitude}}{no default, initially |49:12|}
+  Latitude degree and longitude of a reference point.
+  Used for map type \docValue{reference}.
+\end{docMrcKey}
+
+
+\begin{docMrcKey}{supply/named position}{=\meta{name}}{style, no default}
+  The \emph{named position} given by \meta{name} describes
+  a reference point, see \Fullref{sec:names_positions}.
+  Used for map type \docValue{reference}.
+\end{docMrcKey}
+
+
+\pagebreak
+\begin{docMrcKey}{supply/width}{=\meta{setup width in tiles}}{no default, initially |4|}
+  Width of the map as multiplicity of map tiles.
+  Used for map types \docValue{reference} and \docValue{areafit}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/tex width}{=\meta{width}}{style, no default}
+  Width of the map as \TeX\ dimension.
+  This is a style to compute \refKey{/mermap/supply/width} according to
+  the current \refKey{/mermap/tile size}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/height}{=\meta{setup height in tiles}}{no default, initially |4|}
+  Height of the map as multiplicity of map tiles.
+  Used for map types \docValue{reference} and \docValue{areafit}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/tex height}{=\meta{width}}{style, no default}
+  Height of the map as \TeX\ dimension.
+  This is a style to compute \refKey{/mermap/supply/height} according to
+  the current \refKey{/mermap/tile size}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/align}{=\meta{setup alignment}}{no default, initially |center|}
+  Alignment of reference point or area for map types \docValue{reference} and \docValue{areafit}.
+  Feasible values are
+  \docValue{northwest}, \docValue{north}, \docValue{northeast}, \docValue{west},
+  \docValue{center}, \docValue{east}, \docValue{southwest},\docValue{south}, \docValue{southeast}.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/target}{=\meta{setup target}}{no default, initially |tiles|}
+  Defines the type of output for the Python~3 script. Feasible values are:
+  \begin{itemize}
+  \item\docValue{none}: No tiles are downloaded and no merged map is generated, just map computation.
+    This is the fastest method and needs no tile supplier.
+  \item\docValue{tiles}: Download map tiles from a tile map service (TMS) \refKey{/mermap/supply/url}.
+    Compilation of a document with map tile takes longer than compilation
+    with a merged map and transparency should not be used with tiles,
+    but the resulting document is smaller than a document with merged maps.
+  \item\docValue{mergedmap}: Download map tiles from a tile map service (TMS)
+    \refKey{/mermap/supply/url} and merge them into a single map picture.
+    This speeds compilation and allows transparency effects, but
+    the resulting document is possibly larger than a document with map tiles,
+    because map tiles often are optimized 8-bit image files while the merged
+    image is a 24-bit PNG file. Additionally, synergy effects of using the same map tiles
+    for different maps are lost.
+    Also, since the pixel map is clipped to full pixels, the resulting map
+    may differ (shift/size) from the more accurate tile representation by
+    one pixel.
+  \item\docValue{wmsmap}: Download a single map from a web map service (WMS)
+    \refKey{/mermap/supply/url}. Internally, the package treats a WMS like
+    a tile map service including all tile calculations. Actually, a single
+    file is downloaded.
+  \end{itemize}
+\end{docMrcKey}
+
+
+\clearpage
+\begin{docMrcKey}{supply/url}{=\meta{setup URL}}{no default, initially empty}
+  Here, the url format with placeholder |{z}{x}{y}| for map tile download is defined.
+  \textbf{Be sure that you have the permission to download, save, and use
+  the map tiles from that URL. Illegal downloads are not endorsed in any
+  way.}
+  \begin{dispListing}
+    url={https://abc.efg.hij/{z}/{x}/{y}.png?apikey=12345678},
+  \end{dispListing}
+  See \Fullref{sec:maptileserver} for predefined URLs.
+\end{docMrcKey}
+
+
+\begin{docMrcKey}{supply/url with api key}{=\marg{prefix}\marg{name}\marg{postfix}}{no default}
+  This is an alternative version of \refKey{/mermap/supply/url}.
+  The URL is constructed from some fixed \meta{prefix} and \meta{postfix} with
+  an API key in between. The API key is retrieved by \meta{name} from a
+  repository filled by \refCom{mrcsetapikey}.
+  \begin{dispListing}
+    url={https://abc.efg.hij/{z}/{x}/{y}.png?apikey=}{myservice}{},
+  \end{dispListing}
+  See \Fullref{sec:maptileserver} for predefined URLs.
+\end{docMrcKey}
+
+
+\begin{docCommand}{mrcsetapikey}{\marg{name}\marg{value}}
+  Stores an API key \meta{value} for access with the given \meta{name}.
+  Typically, \meta{value} is a received ID from a map tile service provider
+  after personal registration. \meta{name} is a placeholder which is used
+  inside \refKey{/mermap/supply/url with api key} to mark the insertion
+  point for the API key.
+  \begin{dispListing}
+    \mrcsetapikey{myservice}{....K942XY....}
+  \end{dispListing}
+\end{docCommand}
+
+
+
+\begin{docMrcKey}{supply/attribution}{=\meta{attribution text}}{no default, initially empty}
+  Attribution text for the map source. Typically, it acknowledges the copyright
+  of the map data provider. It may contain hyperlinks.
+  It is used to set up \refKey{/mermap/mapdef/attribution} afterwards
+  and it is accessible as \docAuxCommand{mrcmapattribution} (use read-only).\par
+  For technical reasons, do not use \verb+"+. \docAuxCommand{mrcumlaut}
+  may be used for masking umlauts, e.g. use \verb+\mrcumlaut{u}+ instead of
+  \verb+\"{u}+, but umlauts can also be used directly, e.g. as UTF-8 coded characters.
+\end{docMrcKey}
+
+\begin{docMrcKey}{supply/attribution print}{=\meta{attribution text}}{no default, initially empty}
+  Attribution text for the map source.
+  In contrast to \refKey{/mermap/supply/attribution} it is intended for media
+  that does not support hyperlinks like printed posters, books, etc.
+  It is used to set up \refKey{/mermap/mapdef/attribution print} afterwards
+  and it is accessible as \docAuxCommand{mrcmapattributionprint} (use read-only).
+\end{docMrcKey}
+
+
+\begin{docMrcKey}{supply/basename}{=\meta{setup tile base name}}{no default, initially \texttt{tiles/tile}}
+  Prefix for local tile files, e.g. '|tiles/map|' for '|tiles/map_10_10_10.png|'.
+\end{docMrcKey}
+
+
+\clearpage
+\begin{docMrcKey}{supply/flex reference scale}{=\meta{scale denominator}}{no default}
+  With the given \meta{scale denominator}, an appropriate \refKey{/mermap/supply/zoom}
+  and \refKey{/mermap/tile size} is computed. Note that
+  the \meta{scale denominator}
+  always applies to the current \refKey{/mermap/supply/latitude}
+  and is used for map type \docValue{boundaries} and \docValue{reference}.
+  For example, if the reference point is on the north side of the map,
+  also the \meta{scale denominator}
+  applies to the most northern latitude.
+
+  Note to take special care to the order of the options.
+  \begin{itemize}
+  \item The reference point has to be set \emph{before}
+    \refKey{/mermap/supply/flex reference scale}, e.g. by
+    \refKey{/mermap/supply/latitude}, \refKey{/mermap/supply/position},
+    \refKey{/mermap/supply/named position}.
+  \item \refKey{/mermap/supply/tex height}, \refKey{/mermap/supply/tex width}
+    (only for map type \docValue{reference})
+    have to be set \emph{after} \refKey{/mermap/supply/flex reference scale},
+    because the \refKey{/mermap/tile size} is adapted.
+  \end{itemize}
+  Also see \refKey{/mermap/flex tile size}, \refKey{/mermap/flex zoom},
+  and \refKey{/mermap/flex scale}.
+\tikzsetnextfilename{maptiles_flex_reference_scale}%
+\begin{dispExample}
+\begin{tikzpicture}
+  \mrcmap[type=reference,latitude=48.14,longitude=11.57,
+    flex reference scale=250000,
+    source=opentopomap,
+    tex width=\linewidth,tex height=5cm]{}
+  \mrcdrawmap
+  \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south)
+        {\mrcmapattribution};
+  \mrcclipmap
+  \path[draw] (mrcmap.south west) rectangle (mrcmap.north east);
+  \node[below left=2mm,align=right,fill=white,fill opacity=0.5,
+    text opacity=1] at (mrcmap.north east) {scale \mrcprettymapscale};
+\end{tikzpicture}
+\end{dispExample}
+\end{docMrcKey}
+
+
+\begin{docMrcKey}{supply/flex area scale}{=\meta{scale denominator}}{no default}
+  This is a shortcut for setting \refKey{/mermap/supply/area to reference}
+  and \refKey{/mermap/supply/flex reference scale}=\meta{scale denominator}.
+  Used for map type \docValue{boundaries} and \docValue{reference}.
+
+  Note to take special care to the order of the options.
+  \begin{itemize}
+  \item The reference point has to be set \emph{before}
+    \refKey{/mermap/supply/flex area scale}.
+  \item \refKey{/mermap/supply/tex height}, \refKey{/mermap/supply/tex width}
+    (only for map type \docValue{reference})
+    have to be set \emph{after} \refKey{/mermap/supply/flex reference scale}.
+  \end{itemize}
+\end{docMrcKey}
+
+
+\clearpage
+\begin{docMrcKey}{supply/flex area fit}{\colOpt{=\meta{size}}}{default |0pt|}
+  This key can be used for map type \docValue{areafit} as \emph{final}
+  option \emph{after} all other options.
+  It applies a fine tuning to \refKey{/mermap/tile size},
+  \refKey{/mermap/supply/width}, and \refKey{/mermap/supply/height} such
+  that the defined area fits exactly into the map region.
+  If a \meta{size} is specified, width and height are reduced for the
+  calculation by this \meta{size}, e.g. \meta{size}|=1cm| ensures a
+  border of |5mm| on each side.
+  Also see \refKey{/mermap/flex tile size} and \refKey{/mermap/flex zoom}.
+
+\tikzsetnextfilename{maptiles_flex_area_fit}%
+\begin{dispExample}
+\begin{tikzpicture}
+  \mrcNPdef{munich}{48.14}{11.58}
+  \mrcNPdef{rio}{-22.91}{-43.20}
+  \mrcNPdef{newyork}{40.71}{-74.01}
+  \mrcmap[  type = areafit, area = {munich,rio,newyork},
+    source=topplusopen web grau,
+    tex width=\linewidth, tex height=7cm,
+    flex area fit=1cm ]{}
+  \mrcdrawmap
+  \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south)
+        {\mrcmapattribution};
+  \draw[yellow] ([xshift=5mm,yshift=5mm]mrcmap.south west) rectangle
+                ([xshift=-5mm,yshift=-5mm]mrcmap.north east);
+  \draw[red,fill=red!50!gray!50!white,fill opacity=0.25]
+    (\mrcNPcs{newyork}) -- (\mrcNPcs{rio}) -- (\mrcNPcs{munich}) -- cycle;
+\end{tikzpicture}
+\end{dispExample}
+\end{docMrcKey}
+
+
+
+
+\clearpage
+\begin{docMrcKey}{supply/pixel}{=\meta{setup pixel size}}{no default, initially |256|}
+  Pixel width (and height) of a tile. It is especially needed for
+  target \docValue{mergedmap} and also \docValue{wmsmap}.
+  For \docValue{wmsmap}, it is multiplied with a pseudo tile calculation
+  to compute the actual picture size to download.
+\end{docMrcKey}
+
+
+\begin{docMrcKey}{supply/dpi}{=\meta{dpi value}}{style, no default}
+  This style sets \refKey{/mermap/supply/pixel} such that the given \meta{dpi value}
+  is resulting (approximately).
+  \begin{itemize}
+  \item Note that this only applies for WMS Servers and not for
+    TMS (Tile Map Service) Servers,
+    because there \refKey{/mermap/supply/pixel} is a fixed number depending on
+    Server settings and cannot be chosen arbitrarily.
+  \item A high \meta{dpi value} results in large downloaded map files.
+    If the server does not provide a high resolution map, you will get
+    unnecessary large files with blurred content.
+  \item The \meta{dpi value} for TMS data can be changed by adapting
+    \refKey{/mermap/tile size} or \refKey{/mermap/flex tile size}.
+  \end{itemize}
+
+\tikzsetnextfilename{maptiles_dpi_value}
+\begin{dispExample}
+\begin{tikzpicture}
+  \mrcmap[type=reference,latitude=48.14,longitude=11.57,
+    flex reference scale=250000,
+    source=topplusopen p250, target=wmsmap, dpi=300,
+    tex width=\linewidth,tex height=5cm]{dpi_value}
+  \mrcdrawmap
+  \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south)
+        {\mrcmapattribution};
+  \mrcclipmap
+  \path[draw] (mrcmap.south west) rectangle (mrcmap.north east);
+\end{tikzpicture}
+\end{dispExample}
+
+\end{docMrcKey}
+
+
+
+
+
+%-------------------------------------------------------------------------------
+\subsection{Map Apply}
+
+\begin{docCommand}{mrcapplymap}{\marg{definition}}
+  A map which is supplied by \refCom{mrcsupplymap} is applied
+  inside a |tikzpicture| environment by
+  \refCom{mrcapplymap} where \meta{definition} identifies the map.
+  \refCom{mrcapplymap} replaces a manual setup by \refCom{mrcdefinemap}.
+  The same map can be applied more than once inside a document.
+  Note that applying a map does not mean to draw the map, but to prepare
+  everything for drawing.
+\end{docCommand}
+
+
+\begin{docCommand}{mrcmap}{\oarg{options}\marg{definition}}
+  This is a combination of
+  \refCom{mrcsupplymap} with the given \meta{options}
+  followed immediately by \refCom{mrcapplymap}.
+  If \meta{definition} is left empty, an automated unique identifier is
+  inserted.
+  If a map is to be used just once, \refCom{mrcmap} may be preferred.
+\end{docCommand}
+
+
+
+
+
+\clearpage
+%-------------------------------------------------------------------------------
+\subsection{Map Tile Server}\label{sec:maptileserver}
+
+
+To use map tiles with this package you obviously need access to a map tile server.
+Thanks to all the many contributors to
+\href{https://openstreetmap.org/copyright}{OpenStreetMap},
+map data is free for everyone to use.
+\textbf{But, map tile servers based on OpenStreetMap are not necessarily free}.
+
+A list of online raster tile servers based on OpenStreetMap data is found here:\\
+\url{https://wiki.openstreetmap.org/wiki/Tile_servers}
+
+\begin{itemize}
+\item\bfseries I do not run a map tile server.
+\item I do not and cannot grant any permission to access a map tile server.
+\item I do not and cannot grant any permission to use map tiles in
+  private, academic, free, or commercial publications.
+\item All operators of map tile servers require to mention an attribution
+  for their maps.
+\end{itemize}
+
+The following option allows easy usage of very few selected tile servers.
+The tile server of \href{https://openstreetmap.org/copyright}{OpenStreetMap}
+is not included because of its
+\href{https://operations.osmfoundation.org/policies/tiles/}{Tile Usage Policy}.
+I am aware that the following list could be enlarged much more, but I do not
+want to add more to avoid any legal uncertainties.
+
+\begin{itemize}
+\item\bfseries I will remove an entry immediately, if the tile server operator
+  asks for it.
+\item\mdseries If \textbf{YOU} operate a tile server and you want an entry here, I would be
+  glad to add it to the following list.
+\end{itemize}
+
+\medskip
+\begin{docMrcKey}{supply/source}{=\meta{source}}{style, no default}
+  This style sets \refKey{/mermap/supply/url}, \refKey{/mermap/supply/attribution},\\
+  \refKey{/mermap/supply/attribution print} and \refKey{/mermap/supply/basename}.\\
+  Feasible values for \meta{source} are:
+  %\mermapset{tile size=3.2512cm}
+  \newcommand{\mapexample}[3][]{%
+    \begingroup
+    \mermapset{supply/source=#2}%
+    \begin{itemize}
+    \item Required attribution (\docAuxCommand{mrcmapattribution}):
+      \begin{tcolorbox}[sharp corners,size=fbox,colback=yellow!8,colframe=yellow!80!gray,halign=flush left]
+        \mrcmapattribution\end{tcolorbox}
+    \item Required attribution for media without hyperlinks (\docAuxCommand{mrcmapattributionprint}):
+      \begin{tcolorbox}[sharp corners,size=fbox,colback=yellow!8,colframe=yellow!80!gray,halign=flush left]
+        \mrcmapattributionprint\end{tcolorbox}
+    %\par\smallskip\
+    \end{itemize}
+    \endgroup\par\smallskip\tikzsetnextfilename{maptiles_#3}%
+    \begin{tikzpicture}
+    \mrcmap[source=#2,
+      type=reference,latitude=48.14,longitude=11.58,zoom=7,
+      tex width=\linewidth,tex height=2cm,#1]{#3}
+      \mrcdrawmap
+      \node[below,font=\fontsize{7pt}{7pt}\sffamily] at (mrcmap.south)
+        {\mrcmapattribution};
+    \end{tikzpicture}\par%
+  }%
+  \begin{itemize}
+
+  \item\docValue{dummy}:\\
+    Dummy tile server at loopback |127.0.0.1| for test purposes.
+
+  \item\docValue{opentopomap}:\\
+    Tile server (TMS) of \href{http://opentopomap.org/}{OpenTopoMap}.
+    \begin{itemize}
+    \item Usage (German language): \url{https://opentopomap.org/about#verwendung}
+    \end{itemize}
+    \mapexample{opentopomap}{opentopomap}
+
+\clearpage
+  \item\docValue{openrouteservice mapsurfer}:\\
+    Tile server of \href{https://openrouteservice.org/}{OpenRouteService}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{openrouteservice}}\marg{api-key}.\\
+    Usage: \url{https://openrouteservice.org/terms-of-service/}\\
+    API documentation: \url{https://openrouteservice.org/dev/#/api-docs}
+    \mapexample{openrouteservice mapsurfer}{openrouteservice_mapsurfer}
+
+  \item\docValue{stamen terrain}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#terrain}
+    \mapexample{stamen terrain}{stamen_terrain}
+
+  \item\docValue{stamen terrain-background}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#terrain-background}
+    \mapexample{stamen terrain-background}{stamen_terrain-background}
+
+\clearpage
+  \item\docValue{stamen terrain-labels}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#terrain-labels}
+    \mapexample{stamen terrain-labels}{stamen_terrain-labels}
+
+  \item\docValue{stamen terrain-lines}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#terrain-lines}
+    \mapexample{stamen terrain-lines}{stamen_terrain-lines}
+
+  \item\docValue{stamen toner}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#toner}
+    \mapexample{stamen toner}{stamen_toner}
+
+\clearpage
+  \item\docValue{stamen toner-lite}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#toner-lite}
+    \mapexample{stamen toner-lite}{stamen_toner-lite}
+
+  \item\docValue{stamen toner-hybrid}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#toner-hybrid}
+    \mapexample{stamen toner-hybrid}{stamen_toner-hybrid}
+
+  \item\docValue{stamen toner-background}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#toner-background}
+    \mapexample{stamen toner-background}{stamen_toner-background}
+
+\clearpage
+  \item\docValue{stamen toner-labels}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#toner-labels}
+    \mapexample{stamen toner-labels}{stamen_toner-labels}
+
+  \item\docValue{stamen toner-lines}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#toner-lines}
+    \mapexample{stamen toner-lines}{stamen_toner-lines}
+
+  \item\docValue{stamen watercolor}:\\
+    Tile server of \href{http://stamen.com}{Stamen Design}.\\
+    Usage: \url{http://maps.stamen.com/#watercolor}
+    \mapexample{stamen watercolor}{stamen_watercolor}
+
+\clearpage
+  \item\docValue{thunderforest opencyclemap}:\\
+    Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}.
+    \begin{itemize}
+    \item Usage: \url{https://www.thunderforest.com/terms}
+    \item API documentation: \url{https://www.thunderforest.com/maps/opencyclemap}
+    \end{itemize}
+    \mapexample{thunderforest opencyclemap}{thunderforest_opencyclemap}
+
+  \item\docValue{thunderforest transport}:\\
+    Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}.
+    \begin{itemize}
+    \item Usage: \url{https://www.thunderforest.com/terms}
+    \item API documentation: \url{https://www.thunderforest.com/maps/transport}
+    \end{itemize}
+    \mapexample{thunderforest transport}{thunderforest_transport}
+
+  \item\docValue{thunderforest landscape}:\\
+    Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}.
+    \begin{itemize}
+    \item Usage: \url{https://www.thunderforest.com/terms}
+    \item API documentation: \url{https://www.thunderforest.com/maps/landscape}
+    \end{itemize}
+    \mapexample{thunderforest landscape}{thunderforest_landscape}
+
+\clearpage
+  \item\docValue{thunderforest outdoors}:\\
+    Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}.
+    \begin{itemize}
+    \item Usage: \url{https://www.thunderforest.com/terms}
+    \item API documentation: \url{https://www.thunderforest.com/maps/outdoors}
+    \end{itemize}
+    \mapexample{thunderforest outdoors}{thunderforest_outdoors}
+
+  \item\docValue{thunderforest transport-dark}:\\
+    Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}.
+    \begin{itemize}
+    \item Usage: \url{https://www.thunderforest.com/terms}
+    \item API documentation: \url{https://www.thunderforest.com/maps/transport-dark}
+    \end{itemize}
+    \mapexample{thunderforest transport-dark}{thunderforest_transport-dark}
+
+  \item\docValue{thunderforest spinal-map}:\\
+    Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}.
+    \begin{itemize}
+    \item Usage: \url{https://www.thunderforest.com/terms}
+    \item API documentation: \url{https://www.thunderforest.com/maps/spinal-map}
+    \end{itemize}
+    \mapexample{thunderforest spinal-map}{thunderforest_spinal-map}
+
+\clearpage
+  \item\docValue{thunderforest pioneer}:\\
+    Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}.
+    \begin{itemize}
+    \item Usage: \url{https://www.thunderforest.com/terms}
+    \item API documentation: \url{https://www.thunderforest.com/maps/pioneer}
+    \end{itemize}
+    \mapexample{thunderforest pioneer}{thunderforest_pioneer}
+
+  \item\docValue{thunderforest mobile-atlas}:\\
+    Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}.
+    \begin{itemize}
+    \item Usage: \url{https://www.thunderforest.com/terms}
+    \item API documentation: \url{https://www.thunderforest.com/maps/mobile-atlas}
+    \end{itemize}
+    \mapexample{thunderforest mobile-atlas}{thunderforest_mobile-atlas}
+
+  \item\docValue{thunderforest neighbourhood}:\\
+    Tile server of \href{https://www.thunderforest.com}{Thunderforest}.\\
+    A registered \meta{api-key} is needed (free plan available)
+    which is applied by\\
+    \refCom{mrcsetapikey}\brackets{\docValue{thunderforest}}\marg{api-key}.
+    \begin{itemize}
+    \item Usage: \url{https://www.thunderforest.com/terms}
+    \item API documentation: \url{https://www.thunderforest.com/maps/neighbourhood}
+    \end{itemize}
+    \mapexample{thunderforest neighbourhood}{thunderforest_neighbourhood}
+
+\clearpage
+  \item\docValue{topplusopen web}:\\
+    Tile server (TMS) of \href{http://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}.
+    \begin{itemize}
+    \item Covers world / Europe / Germany depending on zoom level
+    \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/webdienste/topplus-produkte/wmts-topplusopen-wmts-topplus-open.html}
+    \end{itemize}
+    \mapexample{topplusopen web}{topplusopen_web}
+
+  \item\docValue{topplusopen web grau}:\\
+    Tile server (TMS) of \href{http://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}.
+    \begin{itemize}
+    \item Covers world / Europe / Germany depending on zoom level
+    \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/webdienste/topplus-produkte/wmts-topplusopen-wmts-topplus-open.html}
+    \end{itemize}
+    \mapexample{topplusopen web grau}{topplusopen_web_grau}
+
+\end{itemize}
+
+\clearpage
+\begin{tcolorbox}[spartan,colback=white]
+The following sources are Web map server (WMS). Therefore,
+\refKey{/mermap/supply/target} can only be set to \docValue{wmsmap}
+or \docValue{none}.
+\end{tcolorbox}
+
+\begingroup
+\ExplSyntaxOn
+\int_gzero:N \g_tmpa_int
+\NewDocumentCommand \cleanstep {}
+{
+  \fp_compare:nNnT { \g_tmpa_int-trunc(\g_tmpa_int/3)*3 } = 0
+    {
+      \int_compare:nNnT \g_tmpa_int > 0
+        {
+          \clearpage
+        }
+    }
+  \int_gincr:N \g_tmpa_int
+}
+\ExplSyntaxOff
+
+  \begin{itemize}
+
+\foreach \name / \scdenom / \xtra in {p5/5000,p10/10000,p17.5/17500,p25/25000,p50/50000,p100/100000,p250/250000}
+{
+\cleanstep
+  \item\docValue{topplusopen \name}:\\
+    Web map server (WMS) of \href{http://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}.
+    \begin{itemize}
+    \item 1:\scdenom, covers Europe / Germany depending on zoom level
+    \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/webdienste/topplus-produkte/wmts-topplusopen-wmts-topplus-open.html}
+    \end{itemize}
+    \mapexample[target=wmsmap]{topplusopen \name}{topplusopen_\name}
+
+\cleanstep
+  \item\docValue{topplusopen \name\ grau}:\\
+    Web map server (WMS) of \href{http://www.bkg.bund.de}{Bundesamt f\"{u}r Kartographie und Geod\"{a}sie}.
+    \begin{itemize}
+    \item 1:\scdenom, covers Europe / Germany depending on zoom level
+    \item Usage (German language): \url{https://gdz.bkg.bund.de/index.php/default/webdienste/topplus-produkte/wmts-topplusopen-wmts-topplus-open.html}
+    \end{itemize}
+    \def\grau{ grau}%
+    \mapexample[target=wmsmap]{topplusopen \name\grau}{topplusopen_\name_grau}
+}
+
+  \end{itemize}
+\endgroup
+
+\end{docMrcKey}
+
+
+
+\begin{docCommand}{mrcnewsupplysource}{\marg{source}\marg{options}}
+  Adds a new \meta{source} value to \refKey{/mermap/supply/source}.
+  The \meta{options} should set the keys
+  \refKey{/mermap/supply/url}, \refKey{/mermap/supply/attribution},\\
+  \refKey{/mermap/supply/attribution print} and \refKey{/mermap/supply/basename}.
+  It is recommend to use |x ...| for \meta{source} to avoid conflicts
+  with future official additions to \refKey{/mermap/supply/source}.
+  \begin{dispListing}
+  \mrcnewsupplysource{x example}
+  {
+    url               = http://127.0.0.1/dummy/{z}/{x}/{y}.png,
+    attribution       = {Dummy tile server},
+    attribution print = {Dummy tile server},
+    basename          = tiles/dummy,
+  }
+  \end{dispListing}
+\end{docCommand}
+
+
-- 
cgit v1.2.3

