Skip to content

Build your personal knowledge base with Trilium Notes

docs(geomap): write the guide in plainer English

Elian Doran595f10f986ce
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Collections/Geo Map.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Collections/Geo Map.html
index d04cb78d88..713b7217ea 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Collections/Geo Map.html
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Collections/Geo Map.html
@@ -23,9 +23,9 @@
an error message will appear instead of the map (<em>This map can't be drawn because WebGL isn't available…</em>).</p>
<h2>Interaction</h2>
<ul>
- <li>At the top-left there is the search bar, which looks through the notes
- already on the map and, when asked, through an online place search. While
- a search's results are being stepped through, a counter with previous/next
+ <li>At the top-left there is the search bar. It searches the notes already on
+ the map, and it can also search for places online when you ask it to. While
+ you move through the results of a search, a counter with previous and next
buttons appears under it.</li>
<li>At the bottom-center there is a central toolbar which provides editing
features: adding new markers on the map and importing GPX tracks.</li>
@@ -55,39 +55,41 @@
<p>The position on the map and the zoom are saved inside the map note and
restored when visiting again the note.</p>
<h2>Searching the map</h2>
-<p>The search bar at the top-left of the map looks in two places: the notes
- already on the map, and — when asked — an online place search.</p>
+<p>The search bar at the top-left of the map searches in two places. It always
+ searches the notes that are already on the map. It can also search for places
+ online, but only when you ask it to.</p>
<h3>Searching the notes already on the map</h3>
-<p>Type in the search bar and the map's own notes are matched by their title as
- you type. Accents are ignored on both sides, so typing <code spellcheck="false">zurich</code> finds
- <em>Zürich Hauptbahnhof</em>, and each word is looked for on its own, so
- <code spellcheck="false">hotel paris</code> finds <em>Paris Hotel</em>. Notes without a
+<p>Type in the search bar, and the notes on the map are matched by their title
+ as you type. Accents are ignored, both in what you type and in the titles, so
+ <code spellcheck="false">zurich</code> finds <em>Zürich Hauptbahnhof</em>. Each word is searched
+ for on its own, so <code spellcheck="false">hotel paris</code> finds <em>Paris Hotel</em>. Notes without a
<code spellcheck="false">#geolocation</code> attribute are not offered, since there would be nowhere
to go. GPS tracks are offered, even though they carry no such attribute: selecting one brings
its whole route into view.</p>
-<p>Where more notes match than the list has room for, the ones nearest to what
- the map is showing are offered.</p>
+<p>If more notes match than the list can show, you are offered the ones closest
+ to the area you are viewing.</p>
<h3>Searching for places online</h3>
-<p>Looking up a place sends what you typed to a third-party service, so it is
- never done while typing. Instead, the last row of the result list offers it
- — <em>Search online for "…"</em>, with the name of the service underneath —
- and the search runs when that row is pressed or selected with Enter.</p>
+<p>Looking up a place sends what you typed to a third-party service. For this
+ reason, it never happens while you type. Instead, the last row of the result
+ list offers the search. That row reads <em>Search online for "…"</em>, with the
+ name of the service below it. The search runs only when you press that row or
+ select it with Enter.</p>
<p>Trilium uses Nominatim, the place search run by the OpenStreetMap
- Foundation. It needs no account and no API key, and it is named on every row
- that belongs to it: the row that offers the search, the one that says a
- search is running, and the one that reports that nothing was found or that
+ Foundation. It needs no account and no API key. Its name is shown on every
+ row that belongs to it: the row that offers the search, the row that says a
+ search is running, and the row that reports that nothing was found or that
the service could not be reached.</p>
-<p>The search prefers what the map is showing. Places inside the current view
- are looked for first and listed above the rest, so searching for a shop
- while looking at your own town finds the branch in that town rather than one
- of the same name on another continent. The view is treated as at least 25 km
- across, so searching while zoomed into a single street still covers the town
- around it.</p>
+<p>The search prefers the area you are viewing. Places inside the current view
+ are searched for first and listed above the others. If you search for a shop
+ while looking at your own town, you therefore find the branch in that town,
+ and not one with the same name on another continent. The view is always
+ treated as at least 25 km across, so a search made while zoomed into a single
+ street still covers the town around it.</p>
<h3>Going to a point</h3>
-<p>Coordinates typed or pasted into the search bar are offered as a <em>Go to</em> row
- above everything else, and taking it flies the map to that exact spot and
- marks it, so it can be kept as a marker in the same way a searched place
- can.</p>
+<p>If you type or paste coordinates into the search bar, a <em>Go to</em> row is
+ offered above all the other results. Selecting it moves the map to that exact
+ spot and marks it. You can then keep it as a marker, in the same way you keep
+ a place found by searching.</p>
<p>A point has no name of its own. It only has the coordinates you typed. The
note is therefore given the same name as any other new note, which is the name
you also get from the <em>Add marker</em> button and from the + button in the
@@ -96,11 +98,11 @@
the marker is named by that template instead.</p>
<p>The forms understood are:</p>
<ul>
- <li>A plain pair, <code spellcheck="false">45.9432, 24.9668</code> — what both Google Maps and
- OpenStreetMap give when asked for a place's coordinates, and what the
- <code spellcheck="false">#geolocation</code> attribute holds.</li>
- <li>The <code spellcheck="false">geo:</code> link the map itself offers a place under, from the
- <em>Open location</em> action.</li>
+ <li>A plain pair, such as <code spellcheck="false">45.9432, 24.9668</code>. This is what Google
+ Maps and OpenStreetMap both give you when you ask for the coordinates of a
+ place, and it is also what the <code spellcheck="false">#geolocation</code> attribute holds.</li>
+ <li>The <code spellcheck="false">geo:</code> link that the map itself offers for a place, through
+ the <em>Open location</em> action.</li>
<li>The address of a place on Google Maps or OpenStreetMap, pasted whole.</li>
</ul>
<p>A pair that is not a place on Earth, such as <code spellcheck="false">1234, 5678</code>, is not
@@ -109,43 +111,44 @@
<p>Results are gathered under headings, and each group is ordered by distance
from the middle of the map:</p>
<ul>
- <li><em>On this map</em> — notes already on the map, whatever their distance.</li>
- <li><em>Nearby</em> — places found within about 25 km of the view.</li>
- <li><em>Far away</em> — everything else.</li>
+ <li><em>On this map</em>: notes that are already on the map, whatever their distance.</li>
+ <li><em>Nearby</em>: places found within about 25 km of the view.</li>
+ <li><em>Far away</em>: all the other places.</li>
</ul>
-<p>The headings only appear when more than one of the three has anything in it.
- Every row that stands somewhere shows how far off it is, in kilometres or
- miles according to your locale, and a place found online is given its name
- on the first line and its address on the second.</p>
+<p>The headings only appear when at least two of the three groups contain
+ something. Every row that has a position shows how far away it is, in
+ kilometres or miles according to your locale. A place found online shows its
+ name on the first line and its address on the second.</p>
<h3>Selecting a result</h3>
<p>Selecting a note already on the map moves to its marker and opens the note
beside the map, as clicking the marker would.</p>
<p>Selecting a place found online moves the map to it and marks it with a
- temporary pin, distinct in colour from the map's own markers. The map is
- framed by the ground the place covers, so a country fills the view while a
- house is shown at street level. Where the service reports a boundary — a
- country, a county, a park — that boundary is outlined under the pin.</p>
+ temporary pin. The pin has a different colour from the map's own markers. The
+ map is fitted to the area that the place covers, so a country fills the view,
+ while a house is shown at street level. Some places have a boundary, such as a
+ country, a county or a park. When the service reports one, that boundary is
+ outlined under the pin.</p>
<p>A panel then opens with the place's full address and its coordinates: in the
top-right corner on desktop, and at the bottom of the map on mobile, where the
top is kept for the search bar and the result counter. Pressing the
coordinates copies them to the clipboard.</p>
<h3>Keeping a place as a marker</h3>
<p>Press <em>Add as marker</em> in that panel to keep the place. A child note
- is created under the map, named as the place is named and with its
- <code spellcheck="false">#geolocation</code> attribute already set, and the note opens beside the
- map so it can be edited straight away. The temporary pin goes, the place now
- being a marker like any other.</p>
+ is created under the map. It takes the name of the place, and its
+ <code spellcheck="false">#geolocation</code> attribute is already set. The note opens beside the
+ map, so you can edit it straight away. The temporary pin disappears, because
+ the place is now a marker like any other.</p>
<p>The button is not offered on a map that cannot be edited, where the panel
can still be read.</p>
<p>Press the panel's close button, or the Escape key, to send the place away
without keeping it. The pin goes with it.</p>
<h3>Stepping through the results</h3>
-<p>Once a result has been selected, a counter appears under the search bar with
- a previous and a next button. These step through everything the search
- offered, in the order it was listed, so several results can be compared
- without asking for the list again. Pressing the counter itself returns the
- map to the result it is standing on, which is useful after moving the map
- away from it.</p>
+<p>Once you select a result, a counter appears under the search bar, with a
+ previous and a next button. These buttons move through everything the search
+ offered, in the order it was listed. You can therefore compare several results
+ without opening the list again. Pressing the counter itself moves the map back
+ to the current result, which is useful after you have moved the map away from
+ it.</p>
<h3>The keyboard</h3>
<ul>
<li><strong>Enter</strong> runs the online search when its row is the one
@@ -207,34 +210,34 @@
museums and other places around the area being viewed. Once the map is
zoomed in far enough for these to be drawn, they can be clicked:</p>
<ol>
- <li>Look for the places drawn in orange — the same colour a searched place
- is pinned in. Those are the ones that can be clicked, and they are drawn
- nearly solid, while the rest of the map's places stay a faint grey
- background.</li>
- <li>Rest the mouse on one of them. Its name appears above it, and the cursor
- turns into a pointer. The map draws these places as bare icons, so hovering
- is how their names are read — showing them all at once would crowd out the
- titles of your own markers.</li>
- <li>Click it. The same panel used for a searched place appears, showing the
- place's name and its coordinates, and a pin is placed on it.</li>
- <li>Press <em>Add as marker</em> to keep it. The note is created with the
- place's name as its title, and the icon matching the kind of place it
- is.</li>
+ <li>Look for the places drawn in orange. This is the same colour used for a
+ place found by searching. These are the places you can click. They are drawn
+ almost solid, while the other places on the map stay a faint grey.</li>
+ <li>Rest the mouse on one of them. Its name appears above it, and the mouse
+ cursor changes to a pointer. The map draws these places as icons without
+ names, so you read a name by hovering over it. If all the names were shown
+ at once, they would crowd out the titles of your own markers.</li>
+ <li>Click it. The same panel used for a place found by searching appears. It
+ shows the name of the place and its coordinates, and a pin is placed on the
+ map.</li>
+ <li>Press <em>Add as marker</em> to keep it. The note is created with the name
+ of the place as its title, and with the icon that matches the kind of place
+ it is.</li>
</ol>
<p>Places are read from the map data that has already been downloaded, so
clicking one does not send anything to the internet.</p>
<p>Some things to keep in mind:</p>
<ul>
- <li>Places that have no name in the map data, such as benches or parking
- spaces, show no name and are not clickable. Clicking them does nothing, as
- clicking the map elsewhere.</li>
- <li>The markers of the map take precedence: where one stands over a place,
- clicking it opens the note, not the place.</li>
- <li>This does not work with the raster (OpenStreetMap) style, whose places
- are part of the map image, nor with the <em>Neutrino</em> style, which
- draws no places.</li>
- <li>In read-only mode a place can still be clicked and read, but not kept
- as a marker.</li>
+ <li>Places with no name in the map data, such as benches or parking spaces,
+ show no name and cannot be clicked. Clicking them does nothing, just like
+ clicking an empty part of the map.</li>
+ <li>The map's own markers come first. If a marker covers a place, clicking it
+ opens the note and not the place.</li>
+ <li>This does not work with the raster (OpenStreetMap) style, because its
+ places are part of the map image. It also does not work with the
+ <em>Neutrino</em> style, which draws no places.</li>
+ <li>In read-only mode you can still click a place and read it, but you cannot
+ keep it as a marker.</li>
</ul>
<h2>How the location of the markers is stored</h2>
<p>The location of a marker is stored in the <code spellcheck="false">#geolocation</code> attribute
@@ -422,9 +425,9 @@ class="admonition note">
<li>The add button at the bottom of the map.</li>
<li>Repositioning markers.</li>
<li>Editing from the contextual menu (removing locations or adding new items).</li>
- <li>Keeping a place as a marker, whether it was found by searching or clicked
- on the map. Both still work, and a place can still be looked at and its
- coordinates copied.</li>
+ <li>Keeping a place as a marker, whether you found it by searching or clicked
+ it on the map. You can still search and click, and you can still look at a
+ place and copy its coordinates.</li>
</ul>
<p>To set a map as read-only, go to&nbsp;<a class="reference-link" href="#root/_help_8YBEPzcpUgxw">Note buttons</a>&nbsp;→ <em>Editable</em> → <em>Read-only</em> (on
the new layout, or in Basic Properties on the&nbsp;<a class="reference-link"
diff --git a/docs/User Guide/User Guide/Collections/Geo Map.md b/docs/User Guide/User Guide/Collections/Geo Map.md
index 5d8cbb3113..1f1b6267b9 100644
--- a/docs/User Guide/User Guide/Collections/Geo Map.md
+++ b/docs/User Guide/User Guide/Collections/Geo Map.md
@@ -19,7 +19,7 @@ If the map could not be drawn because WebGL could not be initialized, an error m
## Interaction
-* At the top-left there is the search bar, which looks through the notes already on the map and, when asked, through an online place search. While a search's results are being stepped through, a counter with previous/next buttons appears under it.
+* At the top-left there is the search bar. It searches the notes already on the map, and it can also search for places online when you ask it to. While you move through the results of a search, a counter with previous and next buttons appears under it.
* At the bottom-center there is a central toolbar which provides editing features: adding new markers on the map and importing GPX tracks.
* At the bottom-right there are the viewport items:
* Zoom in/out
@@ -42,32 +42,32 @@ The position on the map and the zoom are saved inside the map note and restored
## Searching the map
-The search bar at the top-left of the map looks in two places: the notes already on the map, and — when asked — an online place search.
+The search bar at the top-left of the map searches in two places. It always searches the notes that are already on the map. It can also search for places online, but only when you ask it to.
### Searching the notes already on the map
-Type in the search bar and the map's own notes are matched by their title as you type. Accents are ignored on both sides, so typing `zurich` finds _Zürich Hauptbahnhof_, and each word is looked for on its own, so `hotel paris` finds _Paris Hotel_. Notes without a `#geolocation` attribute are not offered, since there would be nowhere to go. GPS tracks are offered, even though they carry no such attribute: selecting one brings its whole route into view.
+Type in the search bar, and the notes on the map are matched by their title as you type. Accents are ignored, both in what you type and in the titles, so `zurich` finds _Zürich Hauptbahnhof_. Each word is searched for on its own, so `hotel paris` finds _Paris Hotel_. Notes without a `#geolocation` attribute are not offered, since there would be nowhere to go. GPS tracks are offered, even though they carry no such attribute: selecting one brings its whole route into view.
-Where more notes match than the list has room for, the ones nearest to what the map is showing are offered.
+If more notes match than the list can show, you are offered the ones closest to the area you are viewing.
### Searching for places online
-Looking up a place sends what you typed to a third-party service, so it is never done while typing. Instead, the last row of the result list offers it — _Search online for "…"_, with the name of the service underneath — and the search runs when that row is pressed or selected with Enter.
+Looking up a place sends what you typed to a third-party service. For this reason, it never happens while you type. Instead, the last row of the result list offers the search. That row reads _Search online for "…"_, with the name of the service below it. The search runs only when you press that row or select it with Enter.
-Trilium uses Nominatim, the place search run by the OpenStreetMap Foundation. It needs no account and no API key, and it is named on every row that belongs to it: the row that offers the search, the one that says a search is running, and the one that reports that nothing was found or that the service could not be reached.
+Trilium uses Nominatim, the place search run by the OpenStreetMap Foundation. It needs no account and no API key. Its name is shown on every row that belongs to it: the row that offers the search, the row that says a search is running, and the row that reports that nothing was found or that the service could not be reached.
-The search prefers what the map is showing. Places inside the current view are looked for first and listed above the rest, so searching for a shop while looking at your own town finds the branch in that town rather than one of the same name on another continent. The view is treated as at least 25 km across, so searching while zoomed into a single street still covers the town around it.
+The search prefers the area you are viewing. Places inside the current view are searched for first and listed above the others. If you search for a shop while looking at your own town, you therefore find the branch in that town, and not one with the same name on another continent. The view is always treated as at least 25 km across, so a search made while zoomed into a single street still covers the town around it.
### Going to a point
-Coordinates typed or pasted into the search bar are offered as a _Go to_ row above everything else, and taking it flies the map to that exact spot and marks it, so it can be kept as a marker in the same way a searched place can.
+If you type or paste coordinates into the search bar, a _Go to_ row is offered above all the other results. Selecting it moves the map to that exact spot and marks it. You can then keep it as a marker, in the same way you keep a place found by searching.
A point has no name of its own. It only has the coordinates you typed. The note is therefore given the same name as any other new note, which is the name you also get from the _Add marker_ button and from the + button in the note tree. The note opens with that name selected, so you can type over it. If the map has a <a class="reference-link" href="../Advanced%20Usage/Default%20Note%20Title.md">titleTemplate</a> label, the marker is named by that template instead.
The forms understood are:
-* A plain pair, `45.9432, 24.9668` — what both Google Maps and OpenStreetMap give when asked for a place's coordinates, and what the `#geolocation` attribute holds.
-* The `geo:` link the map itself offers a place under, from the _Open location_ action.
+* A plain pair, such as `45.9432, 24.9668`. This is what Google Maps and OpenStreetMap both give you when you ask for the coordinates of a place, and it is also what the `#geolocation` attribute holds.
+* The `geo:` link that the map itself offers for a place, through the _Open location_ action.
* The address of a place on Google Maps or OpenStreetMap, pasted whole.
A pair that is not a place on Earth, such as `1234, 5678`, is not offered.
@@ -76,23 +76,23 @@ A pair that is not a place on Earth, such as `1234, 5678`, is not offered.
Results are gathered under headings, and each group is ordered by distance from the middle of the map:
-* _On this map_ — notes already on the map, whatever their distance.
-* _Nearby_ — places found within about 25 km of the view.
-* _Far away_ — everything else.
+* _On this map_: notes that are already on the map, whatever their distance.
+* _Nearby_: places found within about 25 km of the view.
+* _Far away_: all the other places.
-The headings only appear when more than one of the three has anything in it. Every row that stands somewhere shows how far off it is, in kilometres or miles according to your locale, and a place found online is given its name on the first line and its address on the second.
+The headings only appear when at least two of the three groups contain something. Every row that has a position shows how far away it is, in kilometres or miles according to your locale. A place found online shows its name on the first line and its address on the second.
### Selecting a result
Selecting a note already on the map moves to its marker and opens the note beside the map, as clicking the marker would.
-Selecting a place found online moves the map to it and marks it with a temporary pin, distinct in colour from the map's own markers. The map is framed by the ground the place covers, so a country fills the view while a house is shown at street level. Where the service reports a boundary — a country, a county, a park — that boundary is outlined under the pin.
+Selecting a place found online moves the map to it and marks it with a temporary pin. The pin has a different colour from the map's own markers. The map is fitted to the area that the place covers, so a country fills the view, while a house is shown at street level. Some places have a boundary, such as a country, a county or a park. When the service reports one, that boundary is outlined under the pin.
A panel then opens with the place's full address and its coordinates: in the top-right corner on desktop, and at the bottom of the map on mobile, where the top is kept for the search bar and the result counter. Pressing the coordinates copies them to the clipboard.
### Keeping a place as a marker
-Press _Add as marker_ in that panel to keep the place. A child note is created under the map, named as the place is named and with its `#geolocation` attribute already set, and the note opens beside the map so it can be edited straight away. The temporary pin goes, the place now being a marker like any other.
+Press _Add as marker_ in that panel to keep the place. A child note is created under the map. It takes the name of the place, and its `#geolocation` attribute is already set. The note opens beside the map, so you can edit it straight away. The temporary pin disappears, because the place is now a marker like any other.
The button is not offered on a map that cannot be edited, where the panel can still be read.
@@ -100,7 +100,7 @@ Press the panel's close button, or the Escape key, to send the place away withou
### Stepping through the results
-Once a result has been selected, a counter appears under the search bar with a previous and a next button. These step through everything the search offered, in the order it was listed, so several results can be compared without asking for the list again. Pressing the counter itself returns the map to the result it is standing on, which is useful after moving the map away from it.
+Once you select a result, a counter appears under the search bar, with a previous and a next button. These buttons move through everything the search offered, in the order it was listed. You can therefore compare several results without opening the list again. Pressing the counter itself moves the map back to the current result, which is useful after you have moved the map away from it.
### The keyboard
@@ -144,19 +144,19 @@ This works for:
When a vector map style is used, the map itself draws the shops, cafés, museums and other places around the area being viewed. Once the map is zoomed in far enough for these to be drawn, they can be clicked:
-1. Look for the places drawn in orange — the same colour a searched place is pinned in. Those are the ones that can be clicked, and they are drawn nearly solid, while the rest of the map's places stay a faint grey background.
-2. Rest the mouse on one of them. Its name appears above it, and the cursor turns into a pointer. The map draws these places as bare icons, so hovering is how their names are read — showing them all at once would crowd out the titles of your own markers.
-3. Click it. The same panel used for a searched place appears, showing the place's name and its coordinates, and a pin is placed on it.
-4. Press _Add as marker_ to keep it. The note is created with the place's name as its title, and the icon matching the kind of place it is.
+1. Look for the places drawn in orange. This is the same colour used for a place found by searching. These are the places you can click. They are drawn almost solid, while the other places on the map stay a faint grey.
+2. Rest the mouse on one of them. Its name appears above it, and the mouse cursor changes to a pointer. The map draws these places as icons without names, so you read a name by hovering over it. If all the names were shown at once, they would crowd out the titles of your own markers.
+3. Click it. The same panel used for a place found by searching appears. It shows the name of the place and its coordinates, and a pin is placed on the map.
+4. Press _Add as marker_ to keep it. The note is created with the name of the place as its title, and with the icon that matches the kind of place it is.
Places are read from the map data that has already been downloaded, so clicking one does not send anything to the internet.
Some things to keep in mind:
-* Places that have no name in the map data, such as benches or parking spaces, show no name and are not clickable. Clicking them does nothing, as clicking the map elsewhere.
-* The markers of the map take precedence: where one stands over a place, clicking it opens the note, not the place.
-* This does not work with the raster (OpenStreetMap) style, whose places are part of the map image, nor with the _Neutrino_ style, which draws no places.
-* In read-only mode a place can still be clicked and read, but not kept as a marker.
+* Places with no name in the map data, such as benches or parking spaces, show no name and cannot be clicked. Clicking them does nothing, just like clicking an empty part of the map.
+* The map's own markers come first. If a marker covers a place, clicking it opens the note and not the place.
+* This does not work with the raster (OpenStreetMap) style, because its places are part of the map image. It also does not work with the _Neutrino_ style, which draws no places.
+* In read-only mode you can still click a place and read it, but you cannot keep it as a marker.
## How the location of the markers is stored
@@ -287,7 +287,7 @@ When a map is [read-only](../Basic%20Concepts%20and%20Features/Notes/Read-Only%2
* The add button at the bottom of the map.
* Repositioning markers.
* Editing from the contextual menu (removing locations or adding new items).
-* Keeping a place as a marker, whether it was found by searching or clicked on the map. Both still work, and a place can still be looked at and its coordinates copied.
+* Keeping a place as a marker, whether you found it by searching or clicked it on the map. You can still search and click, and you can still look at a place and copy its coordinates.
To set a map as read-only, go to <a class="reference-link" href="../Basic%20Concepts%20and%20Features/UI%20Elements/Note%20buttons.md">Note buttons</a> → _Editable_ → _Read-only_ (on the new layout, or in Basic Properties on the <a class="reference-link" href="../Basic%20Concepts%20and%20Features/UI%20Elements/Ribbon.md">Ribbon</a> for the old layout).