Add initial inline docs, build script for doc.json

build.js

@@ -2,13 +2,18 @@ var fs = require('fs'),
     path = require('path'),
     glob = require('glob'),
     YAML = require('js-yaml'),
+    marked = require('marked'),
     _ = require('./js/lib/lodash'),
     jsonschema = require('jsonschema'),
     fieldSchema = require('./data/presets/schema/field.json'),
     presetSchema = require('./data/presets/schema/preset.json');
 
+function readtxt(f) {
+    return fs.readFileSync(f, 'utf8');
+}
+
 function read(f) {
-    return JSON.parse(fs.readFileSync(f));
+    return JSON.parse(readtxt(f));
 }
 
 function r(f) {
@@ -19,6 +24,10 @@ function rp(f) {
     return r('presets/' + f);
 }
 
+function stringify(o) {
+    return JSON.stringify(o, null, 4);
+}
+
 function validate(file, instance, schema) {
     var result = jsonschema.validate(instance, schema);
     if (result.length) {
@@ -39,58 +48,80 @@ var translations = {
     presets: {}
 };
 
-var fields = {};
-glob.sync(__dirname + '/data/presets/fields/*.json').forEach(function(file) {
-    var field = read(file),
-        id = path.basename(file, '.json');
+function generateDocumentation() {
+    var docs = [];
+    glob.sync(__dirname + '/data/doc/*.md').forEach(function(file) {
+        var text = readtxt(file),
+            title = text.split('\n')[0]
+                .replace('#', '').trim();
+        docs.push({
+            text: marked(text),
+            title: title
+        });
+    });
+    fs.writeFileSync('data/doc.json', stringify(docs));
+}
 
-    validate(file, field, fieldSchema);
+function generateFields() {
+    var fields = {};
+    glob.sync(__dirname + '/data/presets/fields/*.json').forEach(function(file) {
+        var field = read(file),
+            id = path.basename(file, '.json');
 
-    translations.fields[id] = {label: field.label};
-    if (field.strings) {
-        for (var i in field.strings) {
-            translations.fields[id][i] = field.strings[i];
+        validate(file, field, fieldSchema);
+
+        translations.fields[id] = {label: field.label};
+        if (field.strings) {
+            for (var i in field.strings) {
+                translations.fields[id][i] = field.strings[i];
+            }
         }
-    }
 
-    fields[id] = field;
-});
-fs.writeFileSync('data/presets/fields.json', JSON.stringify(fields, null, 4));
+        fields[id] = field;
+    });
+    fs.writeFileSync('data/presets/fields.json', stringify(fields));
+}
 
-var presets = {};
-glob.sync(__dirname + '/data/presets/presets/**/*.json').forEach(function(file) {
-    var preset = read(file),
-        id = file.match(/presets\/presets\/([^.]*)\.json/)[1];
+function generatePresets() {
+    var presets = {};
+    glob.sync(__dirname + '/data/presets/presets/**/*.json').forEach(function(file) {
+        var preset = read(file),
+            id = file.match(/presets\/presets\/([^.]*)\.json/)[1];
 
-    validate(file, preset, presetSchema);
+        validate(file, preset, presetSchema);
 
-    translations.presets[id] = {
-        name: preset.name,
-        terms: (preset.terms || []).join(',')
-    };
+        translations.presets[id] = {
+            name: preset.name,
+            terms: (preset.terms || []).join(',')
+        };
 
-    presets[id] = preset;
-});
-fs.writeFileSync('data/presets/presets.json', JSON.stringify(presets, null, 4));
+        presets[id] = preset;
+    });
+    fs.writeFileSync('data/presets/presets.json', stringify(presets));
+    fs.writeFileSync('data/presets.yaml', YAML.dump({en: {presets: translations}}));
+}
 
-fs.writeFileSync('data/presets.yaml', YAML.dump({en: {presets: translations}}));
+generateDocumentation();
+generateFields();
+generatePresets();
 
-fs.writeFileSync('data/data.js', 'iD.data = ' + JSON.stringify({
+fs.writeFileSync('data/data.js', 'iD.data = ' + stringify({
     deprecated: r('deprecated.json'),
     discarded: r('discarded.json'),
     keys: r('keys.json'),
     imagery: r('imagery.json'),
+    docs: r('doc.json'),
     presets: {
         presets: rp('presets.json'),
         defaults: rp('defaults.json'),
         categories: rp('categories.json'),
         fields: rp('fields.json')
     }
-}, null, 4) + ';');
+}) + ';');
 
 // Push changes from data/core.yaml into data/locales.js
 var core = YAML.load(fs.readFileSync('data/core.yaml', 'utf8'));
 var presets = YAML.load(fs.readFileSync('data/presets.yaml', 'utf8'));
 var en = _.merge(core, presets);
-var out = 'locale.en = ' + JSON.stringify(en.en, null, 4) + ';';
+var out = 'locale.en = ' + stringify(en.en) + ';';
 fs.writeFileSync('data/locales.js', fs.readFileSync('data/locales.js', 'utf8').replace(/locale.en =[^;]*;/, out));

data/doc.json

@@ -0,0 +1,10 @@
+[
+    {
+        "text": "<h1>Mapping Buildings</h1>\n<p>OpenStreetMap is the world&#39;s largest database of buildings. You can create\nand improve this database.</p>\n<h2>Selecting</h2>\n<p>You can select a building by clicking on its border. This will highlight the\nbuilding and open a small tools menu and a sidebar showing more information\nabout the building.</p>\n<h2>Modifying</h2>\n<p>Sometimes buildings are incorrectly placed or have incorrect tags.</p>\n<p>To move an entire building, select it, then click the &#39;Move&#39; tool. Move your\nmouse to shift the building, and click when it&#39;s correctly placed.</p>\n<p>To fix the specific shape of a building, click and drag the points that form\nits border into better places.</p>\n<h2>Creating</h2>\n<p>One of the main questions around adding buildings to the map is that\nOpenStreetMap records buildings both as shapes and points. The rule of thumb\nis to <em>map a building as a shape whenever possible</em>, and map companies, homes,\namenities, and other things that operate out of buildings as points placed\nwithin the building shape.</p>\n<p>Start drawing a building as a shape by clicking the &#39;Area&#39; button in the top\nleft of the interface, and end it either by pressing &#39;Return&#39; on your keyboard\nor clicking on the first point drawn to close the shape.</p>\n<h2>Deleting</h2>\n<p>If a building is entirely incorrect - you can see that it doesn&#39;t exist in satellite\nimagery and ideally have confirmed locally that it&#39;s not present - you can delete\nit, which removes it from the map. Be cautious when deleting features -\nlike any other edit, the results are seen by everyone and satellite imagery\nis often out of date, so the road could simply be newly built.</p>\n<p>You can delete a building by clicking on it to select it, then clicking the\ntrash can icon or pressing the &#39;Delete&#39; key.</p>\n",
+        "title": "Mapping Buildings"
+    },
+    {
+        "text": "<h1>Mapping Roads</h1>\n<p>You can create, fix, and delete roads with this editor. Roads can be all\nkinds: paths, highways, trails, cycleways, and more - any often-crossed\nsegment should be mappable.</p>\n<h2>Selecting</h2>\n<p>Click on a road to select it. An outline should become visible, along\nwith a small tools menu on the map and a sidebar showing more information\nabout the road.</p>\n<h3>Modifying</h3>\n<p>Often you&#39;ll see roads that aren&#39;t aligned to the imagery behind them\nor a GPS track.</p>\n<p>First click on the road you want to change. This will highlight it and show\n&#39;control points along it&#39; that you can drag to better locations. If\nyou want to add new control points for more detail, double-click a part\nof the road without a point, and one will be added.</p>\n<p>If the road connects to another road, but doesn&#39;t properly connect on\nthe map, you can drag one of its control points onto the other road in\norder to join them. Having roads connect is important for the map\nand essential for providing driving directions.</p>\n<p>You can also click the &#39;Move&#39; tool or type <code>M</code> to move the entire road at\none time, and then click again to save that movement.</p>\n<h2>Deleting</h2>\n<p>If a road is entirely incorrect - you can see that it doesn&#39;t exist in satellite\nimagery and ideally have confirmed locally that it&#39;s not present - you can delete\nit, which removes it from the map. Be cautious when deleting features -\nlike any other edit, the results are seen by everyone and satellite imagery\nis often out of date, so the road could simply be newly built.</p>\n<p>You can delete a road by clicking on it to select it, then clicking the\ntrash can icon or pressing the &#39;Delete&#39; key.</p>\n<h2>Creating</h2>\n<p>Found somewhere there should be a road but there isn&#39;t? Click the &#39;Line&#39;\nicon in the top-left of the editor or press the key &#39;2&#39; to start drawing\na line.</p>\n<p>Click on the start of the road on the map to start drawing. If the road\nconnects to another road, first, click on the place where they connect.</p>\n<p>Then click on points along the road so that it follows the right path, according\nto satellite imagery or GPS. When you&#39;re done drawing the road, double-click\nor press &#39;Return&#39; or &#39;Enter&#39; on your keyboard.</p>\n",
+        "title": "Mapping Roads"
+    }
+]

data/doc/building.md

@@ -0,0 +1,43 @@
+# Mapping Buildings
+
+OpenStreetMap is the world's largest database of buildings. You can create
+and improve this database.
+
+## Selecting
+
+You can select a building by clicking on its border. This will highlight the
+building and open a small tools menu and a sidebar showing more information
+about the building.
+
+## Modifying
+
+Sometimes buildings are incorrectly placed or have incorrect tags.
+
+To move an entire building, select it, then click the 'Move' tool. Move your
+mouse to shift the building, and click when it's correctly placed.
+
+To fix the specific shape of a building, click and drag the points that form
+its border into better places.
+
+## Creating
+
+One of the main questions around adding buildings to the map is that
+OpenStreetMap records buildings both as shapes and points. The rule of thumb
+is to _map a building as a shape whenever possible_, and map companies, homes,
+amenities, and other things that operate out of buildings as points placed
+within the building shape.
+
+Start drawing a building as a shape by clicking the 'Area' button in the top
+left of the interface, and end it either by pressing 'Return' on your keyboard
+or clicking on the first point drawn to close the shape.
+
+## Deleting
+
+If a building is entirely incorrect - you can see that it doesn't exist in satellite
+imagery and ideally have confirmed locally that it's not present - you can delete
+it, which removes it from the map. Be cautious when deleting features -
+like any other edit, the results are seen by everyone and satellite imagery
+is often out of date, so the road could simply be newly built.
+
+You can delete a building by clicking on it to select it, then clicking the
+trash can icon or pressing the 'Delete' key.

data/doc/road.md

@@ -0,0 +1,53 @@
+# Mapping Roads
+
+You can create, fix, and delete roads with this editor. Roads can be all
+kinds: paths, highways, trails, cycleways, and more - any often-crossed
+segment should be mappable.
+
+## Selecting
+
+Click on a road to select it. An outline should become visible, along
+with a small tools menu on the map and a sidebar showing more information
+about the road.
+
+### Modifying
+
+Often you'll see roads that aren't aligned to the imagery behind them
+or a GPS track.
+
+First click on the road you want to change. This will highlight it and show
+'control points along it' that you can drag to better locations. If
+you want to add new control points for more detail, double-click a part
+of the road without a point, and one will be added.
+
+If the road connects to another road, but doesn't properly connect on
+the map, you can drag one of its control points onto the other road in
+order to join them. Having roads connect is important for the map
+and essential for providing driving directions.
+
+You can also click the 'Move' tool or type `M` to move the entire road at
+one time, and then click again to save that movement.
+
+## Deleting
+
+If a road is entirely incorrect - you can see that it doesn't exist in satellite
+imagery and ideally have confirmed locally that it's not present - you can delete
+it, which removes it from the map. Be cautious when deleting features -
+like any other edit, the results are seen by everyone and satellite imagery
+is often out of date, so the road could simply be newly built.
+
+You can delete a road by clicking on it to select it, then clicking the
+trash can icon or pressing the 'Delete' key.
+
+## Creating
+
+Found somewhere there should be a road but there isn't? Click the 'Line'
+icon in the top-left of the editor or press the key '2' to start drawing
+a line.
+
+Click on the start of the road on the map to start drawing. If the road
+connects to another road, first, click on the place where they connect.
+
+Then click on points along the road so that it follows the right path, according
+to satellite imagery or GPS. When you're done drawing the road, double-click
+or press 'Return' or 'Enter' on your keyboard.

package.json

@@ -29,5 +29,8 @@
   },
   "engines": {
     "node": "~0.8.20"
+  },
+  "dependencies": {
+    "marked": "~0.2.8"
   }
 }