Merge pull request #682 from pietervdvn/riQQ-patch-1

Editorial improvements in "Making your own theme" docs

Docs/Making_Your_Own_Theme.md

@@ -10,8 +10,8 @@ Requirements
 Before you start, you should have the following qualifications:
 
 - You are a longtime contributor and do know the OpenStreetMap tagging scheme very well.
-- You are not afraid of editing a .JSON-file
+- You are not afraid of editing a JSON file
-- You're theme will add well-understood tags (aka: the tags have a wiki page, are not controversial and are objective)
+- Your theme will add well-understood tags (aka: the tags have a wiki page, are not controversial and are objective)
 - You are in contact with your local OpenStreetMap community and do know some other members to discuss tagging and to
   help testing
 
@@ -27,21 +27,21 @@ get started.
 
 However, the custom theme generator is extremely buggy and built before some updates. This means that some features
 are _not_ available through the custom theme generator. The custom theme generator is good to get the basics of the
-theme set up, but you will have to edit the raw JSON-file anyway afterwards.
+theme set up, but you will have to edit the raw JSON file anyway afterwards.
 
 [A quick tutorial for the custom theme generator can be found here](https://www.youtube.com/watch?v=nVbFrNVPxPw).
 
 Loading your theme
 ------------------
 
-If you have your .json file, there are three ways to distribute your theme:
+If you have your JSON file, there are three ways to distribute your theme:
 
-- Take the entire JSON-file and [base64](https://www.base64encode.org/) encode it. Then open up the
+- Take the entire JSON file and [base64](https://www.base64encode.org/) encode it. Then open up the
-  url `https://mapcomplete.osm.be?userlayout=true#<base64-encoded-json-here>`. Yes, this URL will be huge; and updates
+  URL `https://mapcomplete.osm.be?userlayout=true#<base64-encoded-json-here>`. Yes, this URL will be huge; and updates
   are difficult to distribute as you have to send a new URL to everyone. This is however excellent to have a 'quick and
   dirty' test version up and running as these links can be generated from the customThemeGenerator and can be quickly
   shared with a few other contributors.
-- Host the JSON file on a publicly accessible webserver (e.g. github) and open
+- Host the JSON file on a publicly accessible webserver (e.g. GitHub) and open
   up `https://mapcomplete.osm.be?userlayout=<url-to-the-raw.json>`
 - Ask to have your theme included into the official MapComplete - requirements below
 
@@ -58,42 +58,42 @@ Your theme has to be:
 3) Make sure there are somewhat decent icons. Note that there is _no_ styleguide at the moment though.
 
 The preferred way to add your theme is via a Pull Request. A Pull Request is less work for the maintainer (which makes
-it really easy and for me to add it) and your name will be included in the git history (so you'll be listed as
+it really easy for me to add it) and your name will be included in the git history (so you'll be listed as
-contributor). If that is not possible, send the .Json-file and assets, e.g. as a zip in an issue, per email, ...
+contributor). If that is not possible, send the JSON file and assets, e.g. as a zip in an issue, per email, ...
 
 *Via a pull request:*
 
 1) Fork this repository
-2) Go to `assets/themes` and create a new directory `yourtheme`
+2) Go to `assets/themes` and create a new directory named `yourtheme`
-3) Create a new file `yourtheme.json`, paste the theme configuration in there. You can find your theme configuration in
+3) Create a new file named `yourtheme.json`, paste the theme configuration in there. You can find your theme configuration in
    the customThemeBuilder (the tab with the *Floppy disk* icon)
 4) Copy all the images into this new directory. **No external sources are allowed!** External image sources leak privacy
    or can break.
     - Make sure the license is suitable, preferable a Creative Commons license or CC0-license.
     - If an SVG version is available, use the SVG version
-    - Make sure all the links in `yourtheme.json` are updated. You can use `./assets/themes/yourtheme/yourimage.svg`
+    - Make sure all the links in `yourtheme.json` are updated. You can use a relative link like `./assets/themes/yourtheme/yourimage.svg`
-      instead of the HTML link
+      instead of an HTML link
-    - Create a file `license_info.json` in the theme directory, which contains metadata on every artwork source
+    - Create the file `license_info.json` in the theme directory, which contains metadata on every artwork source
-5) Add your theme to the code base: add it into "assets/themes" and make sure all the images are there too. Running '
+5) Add your theme to the code base: add it into `assets/themes` and make sure all the images are there too. Running `
-   ts-node scripts/fixTheme <path to your theme>' will help downloading the images and attempts to get the licenses if
+   ts-node scripts/fixTheme <path to your theme>` will help downloading the images and attempts to get the licenses if
-   on wikimedia.
+   on Wikimedia.
 6) Add some finishing touches, such as a social image.
    See [this blog post](https://www.h3xed.com/web-and-internet/how-to-use-og-image-meta-tag-facebook-reddit) for some
-   hints
+   hints.
 7) Test your theme: run the project as described in [development_deployment](Development_deployment.md)
 8) Happy with your theme? Time to open a Pull Request!
 9) Thanks a lot for improving MapComplete!
 
-The .JSON-format
+The theme JSON format
 ----------------
 
-There are three important levels in the .JSON-file:
+There are three important levels in the JSON file:
 
 - The toplevel describes the metadata of the entire theme. It contains the `title`, `description`, `icon`... of the
   theme. The most important object is `layers`, which is a list of objects describing layers.
 - A `layer` describes a layer. It contains the `name`, `icon`, `tags of objects to download from overpass`, and
-  especially the `icon` and a way to ask dynamically render tags and ask questions. A lot of those fields (`icon`
+  especially the `icon` and a way to dynamically render tags and ask questions. A lot of those fields (`icon`
-  , `title`, ...) are actually a `TagRendering`
+  , `title`, ...) are actually a `TagRendering`.
 - A `TagRendering` is an object describing a relationship between what should be shown on screen and the OSM-tagging. It
   works in two ways: if the correct tag is known, the appropriate text will be shown. If the tag is missing (and a
   question is defined), the question will be shown.
@@ -103,43 +103,43 @@ Every field is documented in the source code itself - you can find them here:
 - [The top level `LayoutConfig`](https://github.com/pietervdvn/MapComplete/blob/master/Models/ThemeConfig/Json/LayoutConfigJson.ts)
 - [A layer object `LayerConfig`](https://github.com/pietervdvn/MapComplete/blob/master/Models/ThemeConfig/Json/LayerConfigJson.ts)
 - [The `TagRendering`](https://github.com/pietervdvn/MapComplete/blob/master/Models/ThemeConfig/Json/TagRenderingConfigJson.ts)
-- At last, the exact semantics of tags is documented [here](Tags_format.md)
+- At last, the exact semantics of tags are documented [here](Tags_format.md)
 
-A JSON-schema file is available in Docs/Schemas - use LayoutConfig.schema.json to validate a theme file.
+A JSON schema file is available in `Docs/Schemas` - use `LayoutConfig.schema.json` to validate a theme file.
 
 ### MetaTags
 
-There are few tags available that are calculated for convenience - e.g. the country an object is located
+There are a few tags available that are calculated for convenience - e.g. the country an object is located
-at. [An overview of all these metatags is available here](CalculatedTags.md)
+in. [An overview of all these metatags is available here](CalculatedTags.md).
 
 ### TagRendering groups
 
-A tagRendering can have a `group`-attribute, which acts as a tag. All tagRenderings with the same group name will be
+A `tagRendering` can have a `group`-attribute, which acts as a tag. All `tagRendering`s with the same group name will be
 rendered together, in the same order as they were defined.
 
-For example, if the defined tagrenderings have groups `A A B A A B B B`, the group order is `A B` and first all
+For example, if the defined `tagRendering`s have groups `A A B A A B B B`, the group order is `A B` and first all
-tagrenderings from group A will be rendered (thus numbers 0, 1, 3 and 4) followed by the question box for this group.
+`tagRendering`s from group A will be rendered (thus numbers 0, 1, 3 and 4) followed by the question box for this group.
-Then, all the tagRenderings for group B will be shown, thus number 2, 5, 6 and 7, again followed by their questionbox.
+Then, all the `tagRendering`s for group B will be shown, thus number 2, 5, 6 and 7, again followed by their question box.
 
-Additionally, every tagrendering will receive a the groupname as class in the HTML, which can be used to hook up custom
+Additionally, every `tagRendering` will receive the group name as class in the HTML, which can be used to hook up custom
 CSS.
 
-If no group tag is given, the group is `` (empty string)
+If no group tag is given, the group is `` (empty string).
 
 ### Deciding the questions position
 
 By default, the questions are shown just beneath their group.
 
-To override this behaviour, one can add a tagrendering with id `questions` to move the questions up.
+To override this behaviour, one can add a `tagRendering` with id `questions` to move the questions up.
 
-To add a title to the questions, one can add a `render` and a condition.
+To add a title to the questions, one can add a `render` and a `condition`.
 
-To change the behaviour of the questionbox to show _all_ questions at once, one can use a helperArgs in the freeform
+To change the behaviour of the question box to show _all_ questions at once, one can use the `helperArgs` field in the `freeform`
-field with option `showAllQuestions`.
+field with the option `showAllQuestions`.
 
 For example, to show the questions on top, use:
 
-```
+```json
 "tagRenderings": [
     { "id": "questions" }
     { ... some tagrendering ... }
@@ -149,13 +149,13 @@ For example, to show the questions on top, use:
 
 To show _all_ the questions of a group at once in the middle of the tagrenderings, with a header, use:
 
-```
+```json
 "tagRenderings": [
     { 
       "id": "questions" ,
       "group": "groupname",
       "render": {
-        "en": "<h3>Technical questions</h3>The following questions are very technical!<br />{questions}
+        "en": "<h3>Technical questions</h3>The following questions are very technical!<br />{questions}"
       },
       "freeform": {
         "key": "questions",
@@ -174,12 +174,12 @@ Some hints
 
 ### Everything is HTML
 
-All the texts are actually *HTML*-snippets, so you can use `<b>` to add bold, or `<img src=...>` to add images to
+All the texts are actually *HTML* snippets, so you can use `<b>` to add bold, or `<img src=...>` to add images to
 mappings or tagrenderings.
 
 Some remarks:
 
-- links are disabled when answering a question (e.g. a link in a mapping) as it should trigger the answer - not trigger
+- links are disabled when answering a question (e.g. a link in a `mapping`) as it should trigger the answer - not trigger
   to open the link.
 - If you include images, e.g. to clarify a type, make sure these are _icons_ or _diagrams_ - not actual pictures! If
   users see a picture, they think it is a picture of _that actual object_, not a type to clarify the type. An icon is
@@ -232,10 +232,10 @@ Instead, make one layer for one kind of object and change the icon based on attr
 
 Using layers as filters - this doesn't work!
 
-Use the `filter`-functionality instead
+Use the `filter`-functionality instead.
 
-### Not reading the .JSON-specs
+### Not reading the theme JSON specs
 
 There are a few advanced features to do fancy stuff available, which are documented only in the spec above - for
-example, reusing background images and substituting the colours or HTML-rendering. If you need advanced stuff, read it
+example, reusing background images and substituting the colours or HTML rendering. If you need advanced stuff, read it
 through!