Support for transclusion. Install manuals and new overview.

docs/en/manuals/collection-proxy.md

@@ -26,7 +26,7 @@ All communication with collection proxies regarding loading and unloading is don
 
 ## Worlds
 
-Through collection proxies is it possible to switch the top level collection, or to load more than one top level collection into the engine. When doing so it is important to know that each top level collection is a separate physical world. Physics interactions (collisions, triggers, ray-casts) only happen between objects belonging to the same collection. There is no physics interaction between objects belonging to different top level collections.
+Through collection proxies it is possible to load more than one top level collection, or *game world* into the engine. When doing so it is important to know that each top level collection is a separate physical world. Physics interactions (collisions, triggers, ray-casts) only happen between objects belonging to the same collection. There is no physics interaction between objects belonging to different top level collections.
 
 In the following example we have split the game world into two collections that we dynamically load through collection proxies. The loading and unloading of the two collections is controlled by a game object called "loader" that we put in our main collection, "worlds". We configure the game to automatically load the "worlds.collection" file at startup (see [Project settings documentation](/manuals/project-settings) for details). The "worlds" collection will hold the "loader" object as well as the GUI elements that allow us to move our character around.
 

docs/en/manuals/install.md

@@ -0,0 +1,10 @@
+---
+title: Installing Defold
+brief: This manual explains how to download and install the Defold editor for your operating system.
+---
+
+# Installing Defold
+
+Installation of the Defold editor is quite straightforward. Download the version built for your operating system, extract it and copy the software to a suitable location.
+
+:[install](../shared/install.md)

docs/en/manuals/overview.md

@@ -0,0 +1,75 @@
+---
+title: Editor overview
+brief: This manual gives an overview on how the editor look and works, and how to navigate in it.
+---
+
+# Editor overview
+
+The editor allows you to browse and manipulate all files in your game project in an efficient manner. Editing files brings up a suitable editor and shows all relevant information about the file in separate views.
+
+:[overview](../shared/overview.md)
+
+## The scene editor
+
+Defold contains a number of editors, but the Scene Editor is the one used the most. All Game Objects and Collections, as well as some component types, are created and edited in this editor.
+
+![Select object](images/scene_editing/scene_editing_select.png)
+
+## Selecting objects
+
+Click on objects in the main window to select them. The rectangle surrounding the object in the editor view will highlight green to indicate what item is selected.
+
+You can also select objects by:
+
+- <kbd>Click and drag</kbd> to select all objects inside the selection region.
+- <kbd>Click</kbd> objects in the Outline view.
+
+Hold <kbd>Shift</kbd> or <kbd>⌘</kbd> (Mac) or <kbd>Ctrl</kbd> while clicking to expand the selection.
+
+## The Move tool
+
+To move objects, use the *Move Tool*. It is accessible through the menu <kbd>Scene ▸ Move Tool</kbd> or by pressing the <kbd>W</kbd> key.
+
+![Scene menu](images/scene_editing/scene_editing_scene.png)
+
+The selected object now shows three manipulation points that are used to move the object. Click and drag in the green square to move the object freely:
+
+![Move object](images/scene_editing/scene_editing_move.png)
+
+You can also move the object along just one selected axis by clicking and dragging along the corresponding arrow. Clicking and dragging on the red arrow allows movement on the *X* axis only whereas clicking and dragging on the green arrow allows movement on the *Y* axis only.
+
+Move against the grid
+: Hold <kbd>Shift</kbd> when using the move tool to snap the center of the game object to the grid. The default grid size is set to 100. If you wish to alter the size of the grid, you can specify a custom grid size in the preferences. Select <kbd>Defold Editor ▸ Preferences...</kbd>
+
+    ![Grid size](images/scene_editing/scene_editing_grid.png)
+
+## Rotate Tool
+
+The *Rotate Tool* is accessible through the menu <kbd>Scene ▸ Rotate Tool</kbd> or by pressing the <kbd>E</kbd> key.
+
+![Rotate object](images/scene_editing/scene_editing_rotate.png)
+
+This tool consists of three handles that you can manipulate. If you are working on 2D objects, you would probably only want to use the handle that rotates around the *Z* axis, which is the blue circle around the object. Click and drag on the circle to rotate the object.
+
+If you want to rotate around the *X* or *Y* axis, click and drag on the green and red circles. Since the view is peripendicular to those axis, the circles only appear as two lines crossing the object: a green horizontal one and a red vertical.
+
+## Scale Tool
+
+The *Scale Tool* is accessed through the menu <kbd>Scene ▸ Scale Tool</kbd> or by pressing the <kbd>R</kbd> key.
+
+![Scale object](images/scene_editing/scene_editing_scale.png)
+
+Click the red or green handle and drag to scale the object. Game objects can be scaled freely along the *X* and *Y* axis, causing the object to stretch or compress visually.
+
+::: sidenote
+Currently, sprites can not be scaled in the editor. They do, however, support *runtime* free-form scaling. See the [2D Graphics documentation](/manuals/2dgraphics/) for details.
+:::
+
+## Selecting what is showing in the Scene Editor
+
+It is often convenient to be able to disable the visual rendering of certain types of information in the Scene Editor, especially when you are working on a complicated collection with lots of objects containing physics, triggers and layers upon layers of graphical assets. The Scene Editor allows you to enable and disable the rendering of different types of information in the editor. Select the <kbd>Scene ▸ Show</kbd> submenu and then chose what you want to see in the editor.
+
+![Showing information](images/scene_editing/scene_editing_show.png)
+
+The choices you make are stored in the editor and apply to all Scene Editor instances. Your choices are rememberered between sessions too so if you close the Defold editor down and start it up the next day, your Show settings will be intact.
+

docs/en/manuals/scene-editing.md

@@ -3,80 +3,4 @@ title: The Defold scene editor
 brief: Defold contains a number of editors, but the Scene Editor is the one used the most. This manual explains how to use it.
 ---
 
-# Scene editing
-
-Defold contains a number of editors, but the Scene Editor is the one used the most. All Game Objects and Collections, as well as some component types, are created and edited in this editor.
-
-## Viewport Navigation
-
-Pan
-: <kbd>Alt</kbd> + <kbd>Middle button</kbd> (three button mouse) or <kbd>Option + Ctrl</kbd> + <kbd>Mouse button</kbd> (one button mouse)
-
-Zoom
-: <kbd>Alt</kbd> + <kbd>Right button</kbd> (three button mouse) or <kbd>Ctrl</kbd> + <kbd>Mouse button</kbd> (one button). If your mouse has a scroll wheel, it can be used to zoom.
-
-If you have a mouse wheel, it can be used to zoom the view. In OS X, two finger swipes up and down on the trackpad are equivalent to rolling the mouse wheel, so you can use those gestures to zoom.
-
-To reset the view to where the whole scene is visible in the window, select <kbd>Scene ▸ Frame Objects</kbd>{.menu} from the menu or press <kbd>F</kbd>.
-
-## Selecting objects
-
-Click on objects in the main window to select them. The rectangle surrounding the object in the editor view will highlight green.
-
-![Select object](images/scene_editing/scene_editing_select.png)
-
-In addition you can select objects by:
-
-- Clicking an empty area in the view where there is no object, then drag to select all objects inside the drawn region.
-- Click objects in the Outline view.
-- Hold [[Shift]] and click to select multiple objects in the editor view. You can also hold <kbd>⌘</kbd> (Mac) or <kbd>Ctrl</kbd> (PC/Linux) while clicking.
-- Click one object in the Outline view, then hold <kbd>Shift</kbd> and click a second object to select the two objects and everyone in between.
-- Hold <kbd>⌘</kbd> (Mac) or <kbd>Ctrl</kbd> (PC/Linux) and click to select multiple objects in the Outline view.
-
-## The Move tool
-
-To move objects, use the *Move Tool*. It is accessible through the menu <kbd>Scene ▸ Move Tool</kbd> or by pressing the <kbd>W</kbd> key.
-
-![Scene menu](images/scene_editing/scene_editing_scene.png)
-
-The selected object now shows three manipulation points that are used to move the object. Click and drag in the green square to move the object freely:
-
-![Move object](images/scene_editing/scene_editing_move.png)
-
-You can also move the object along just one selected axis by clicking and dragging along the corresponding arrow. Clicking and dragging on the red arrow allows movement on the *X* axis only whereas clicking and dragging on the green arrow allows movement on the *Y* axis only.
-
-Move against the grid
-: Hold <kbd>Shift</kbd> when using the move tool to snap the center of the game object to the grid. The default grid size is set to 100. If you wish to alter the size of the grid, you can specify a custom grid size in the preferences. Select <kbd>Defold Editor ▸ Preferences...</kbd>
-
-    ![Grid size](images/scene_editing/scene_editing_grid.png)
-
-## Rotate Tool
-
-The *Rotate Tool* is accessible through the menu <kbd>Scene ▸ Rotate Tool</kbd> or by pressing the <kbd>E</kbd> key.
-
-![Rotate object](images/scene_editing/scene_editing_rotate.png)
-
-This tool consists of three handles that you can manipulate. If you are working on 2D objects, you would probably only want to use the handle that rotates around the *Z* axis, which is the blue circle around the object. Click and drag on the circle to rotate the object.
-
-If you want to rotate around the *X* or *Y* axis, click and drag on the green and red circles. Since the view is peripendicular to those axis, the circles only appear as two lines crossing the object: a green horizontal one and a red vertical.
-
-## Scale Tool
-
-The *Scale Tool* is accessed through the menu <kbd>Scene ▸ Scale Tool</kbd> or by pressing the <kbd>R</kbd> key.
-
-![Scale object](images/scene_editing/scene_editing_scale.png)
-
-Click the red or green handle and drag to scale the object. Game objects can be scaled freely along the *X* and *Y* axis, causing the object to stretch or compress visually.
-
-::: sidenote
-Currently, sprites can not be scaled in the editor. They do, however, support *runtime* free-form scaling. See the [2D Graphics documentation](/manuals/2dgraphics/) for details.
-:::
-
-## Selecting what is showing in the Scene Editor
-
-It is often convenient to be able to disable the visual rendering of certain types of information in the Scene Editor, especially when you are working on a complicated collection with lots of objects containing physics, triggers and layers upon layers of graphical assets. The Scene Editor allows you to enable and disable the rendering of different types of information in the editor. Select the <kbd>Scene ▸ Show</kbd> submenu and then chose what you want to see in the editor.
-
-![Showing information](images/scene_editing/scene_editing_show.png)
-
-The choices you make are stored in the editor and apply to all Scene Editor instances. Your choices are rememberered between sessions too so if you close the Defold editor down and start it up the next day, your Show settings will be intact.
-
+This manual has been replaced by the [overview manual](/manuals/overview).

docs/en/manuals/test.md

@@ -1,9 +1,9 @@
 ---
-title: Defold documentation typography test
-brief: This document uses all Markdown features (Commonmark + extensions) that the Defold docs use.
+title: Defold markdown test
+brief: This document uses all Markdown features (Commonmark + a couple of extensions) that the Defold docs use.
 ---
 
-# Defold documentation typography
+# Defold markdown test
 
 All defold manuals and tutorials are written in Markdown. This document outlines how to use the various formatting for a consistent look on all documents.
 
@@ -119,3 +119,11 @@ Note that images are usually rendered centered in their own paragraph. Apply cla
 
 ![A small image of sorts](images/test/small.png){.inline}
 ![A small image of sorts](images/test/small.png){.inline}
+
+## Transclusion
+
+Pieces of text that are used in multiple places can be transcluded into a document. See https://github.com/jamesramsay/hercule for details on the transcluder plugin used.
+
+:[link](../shared/test.md)
+
+The end

docs/en/shared/install.md

@@ -0,0 +1,54 @@
+## Downloading
+
+If you haven't already downloaded and installed the Defold editor, it's time to do that.
+
+Log in to the [Defold Dashboard](//dashboard.defold.com) where you will find a "Download editor" menu button:
+
+![download editor](../shared/images/dashboard_download.png)
+
+Click "Download editor" and select the right package for your computer:
+
+* MacOS
+* Windows
+* Linux (32 bit)
+* Linux (64 bit)
+
+There are also pre-release builds of the brand new [Editor 2](/editor-two) avaliable.
+
+## Installation
+
+Installation on MacOS
+: The downloaded file is a DMG image containing the program.
+
+  1. Locate the file "Defold-macosx.cocoa.x86_64.dmg" and double click it to open the image.
+  2. Drag the folder "Defold-macosx.cocoa.x86_64" to the "Applications" folder link.
+
+  To start the editor, open the folder "Defold-macosx.cocoa.x86_64" in your "Applications" folder and <kbd>double click</kbd> the file "Defold".
+
+  ![Defold MacOS](../shared/images/macos_content.png)
+
+Installation on Windows
+: The downloaded file is a ZIP archive that needs to be extracted:
+
+  1. Locate the archive file "Defold-win32.win32.x86.zip", <kbd>press and hold</kbd> (or <kbd>right-click</kbd>) the folder, select *Extract All*, and then follow the instructions to extract the archive to a folder named "Defold-win32.win32.x86".
+  2. Move the folder "Defold-win32.win32.x86" to "C:\Program Files (x86)\"
+  
+  To start the editor, open the folder "Defold-win32.win32.x86" and <kbd>double click</kbd> the file "Defold.exe".
+
+  ![Defold windows](../shared/images/windows_content.png)
+
+Installation on Linux
+: The downloaded file is a ZIP archive that needs to be extracted:
+
+  1. From a terminal, locate the archive file "Defold-linux.gtk.x86.zip" (32 bit) or "Defold-linux.gtk.x86_64.zip" (64 bit) and unzip it to a target Directory.
+
+     ```bash
+     $ unzip Defold-linux.gtk.x86_64.zip -d Defold
+     ``` 
+
+  To start the editor, change directory to where you extracted the application, then run the `Defold-linux.sh` shell script.
+
+  ```bash
+  $ cd Defold
+  $ ./Defold-linux.sh
+  ``` 

docs/en/shared/new_project.md

@@ -0,0 +1,11 @@
+## Creating a new game project
+
+Before you begin working on your game, you should set up storage for the game assets and code. The easiest way is to create a project on the Defold Dashboard. Doing so creates a Git repository on our cloud servers where your work is stored.
+
+1. Go to the [Defold Dashboard](//www.defold.com/dashboard/).
+2. Click New Project.
+3. Choose a name for the project and select *Start from a blank slate*.
+4. Click *Save* and you're done.
+
+![Add project](../shared/images/add_project.png)
+

docs/en/shared/overview.md

@@ -0,0 +1,40 @@
+## The editor views
+
+The Defold editor is separated into a set of panes, or views, that display specific information.
+
+![Editor 2](../shared/images/editor2_overview.png)
+
+The old editor looks different but works very much the same, only with less functionality.
+
+![Editor 1](../shared/images/editor1_overview.png)
+
+1. The *Assets* view, or *Project Explorer* (editor 1), lists all the files that are part of your project. You click and scroll to navigate the list. All file oriented operations can be made in this view:
+
+   - <kbd>Double click</kbd> a file to open it in an editor for that file type.
+   - <kbd>Drag and drop</kbd> to add files from elsewhere on your disk to the project or move files and folders to new locations in the project.
+   - <kbd>Right click</kbd> to open a pop up menu from where you can create new files or folders, rename, delete, track file dependencies and more.
+
+2. The *Editor* view in the center shows the currently open file in an editor for that file type.
+
+   In all visual editors you can navigate with the camera:
+
+   - Pan: <kbd>Alt + left mouse button</kbd>.
+   - Pan (editor 1): <kbd>Alt + Middle button</kbd> (three button mouse) or <kbd>Option + Ctrl + Mouse button</kbd> (one button mouse)
+   - Zoom: <kbd>Alt + Right button</kbd> (three button mouse) or <kbd>Ctrl + Mouse button</kbd> (one button). If your mouse has a scroll wheel, it can be used to zoom.
+   - Rotate in 3D (editor 2): <kbd>Ctrl + left mouse button</kbd>.
+
+   The menu <kbd>Scene</kbd> contains tools to move, rotate and scale the currently selected object, options to frame the view to the current selection and to realign the camera. Editor 2 contains a toolbar in the top right where you find the move, rotate and scale tools.
+
+3. The *Outline* shows the content of the file currently being edited, but in a hierarchial tree structure. The outline reflects the editor view and allows you to perform operations on your items:
+   - <kbd>Click</kbd> to select an item. Hold <kbd>Shift</kbd> or <kbd>Option</kbd> to expand the selection.
+   - <kbd>Drag and drop</kbd> to move items. Drop a game object on another game object in a collection to child it.
+   - <kbd>Right click</kbd> to open a pop up menu from where you can add items, delete selected items etc.
+
+5. The *Properties* view shows properties associated with the currently selected item, like Position, Rotation, Animation etc, etc.
+
+6. The *Console* shows any error output or purposeful printing that you do while your game is running. Alongside the console are tabs containing the *Curve Editor* which is used when editing curves in the particle editor, the *Build Errors* view that shows build errors, and the *Search Results* view that displays search results.
+
+7. The *Changed Files* view lists any files that has been changed, added or deleted in your project. By synchronizing the project regularly you can bring your local copy in sync with what is stored in the project Git repository, that way you can collaborate within a team, and you won’t lose your work if unfortune strikes. Some file oriented operations can be performed in this view:
+
+   - <kbd>Double click</kbd> a file to open a diff view of the file. Editor 2 opens the file in a suitable editor, just like in the assets view.
+   - <kbd>Right click</kbd> a file to open a pop up menu from where you can open a diff view, revert all changes done to the file, find the file on the filesystem and more (editor 2).

docs/en/shared/test.md

@@ -0,0 +1,5 @@
+This file can be used to test transclusion. This whole file will be transcluded as is, with whitespace preservation.
+
+Note that any file references need are relative to the document where the file is inserted.
+
+![shared image](../shared/images/logo.png)

gulpfile.js

@@ -26,6 +26,7 @@ var md_deflist = require('markdown-it-deflist')
 var md_sub = require('markdown-it-sub');
 var md_sup = require('markdown-it-sup');
 var md_katex = require('markdown-it-katex');
+var hercule = require('hercule');
 
 var exec = require('child_process').exec;
 
@@ -174,9 +175,45 @@ function langMap(jsonfile) {
         });
 }
 
+// Support for transclusion via :[](file.md) syntax
+function gulpHercule() {
+    return through.obj( function(file, encoding, callback) {
+      if (file.isNull()) {
+        return callback(null, file);
+      }
+
+      if (file.isBuffer()) {
+        var options = { 'source': file.path }
+        hercule.transcludeString(file.contents.toString(encoding), options, function(err, output) {
+          if (err) {
+            // Handle exceptions like dead links
+            process.stderr.write('ERROR: ' + err.message + ' (' + err.path + ')\n');
+            process.exit(1);
+          }
+          file.contents = new Buffer(output);
+          return callback(null, file);
+        })
+      }
+
+      if (file.isStream()) {
+        var transcluder = new hercule.TranscludeStream(options);
+        transcluder.on('error', (err) => {
+            // Handle exceptions like dead links
+            process.stderr.write('ERROR: ' + err.message + ' (' + err.path + ')\n');
+            process.exit(1);
+        });
+
+        file.contents = file.contents.pipe(transcluder);
+        return callback(null, file);
+      }
+    });
+};
+
+
 // Build docs
 gulp.task('build', ['assets'], function () {
     gulp.src('docs/**/*.md')
+        .pipe(gulpHercule())
         .pipe(tap(markdownToJson))
         .pipe(langMap('languages.json'))
         .pipe(gulp.dest("build"))
@@ -227,6 +264,7 @@ gulp.task('watch', function () {
 
     return gulp.src('docs/**/*.md')
         .pipe(watch('docs/**/*.md'))
+        .pipe(gulpHercule())
         .pipe(tap(markdownToPreviewHtml))
         .pipe(print())
         .pipe(gulp.dest("build/preview"));

package.json

@@ -17,7 +17,9 @@
     "gulp-tap": "^0.1.3",
     "gulp-util": "^3.0.8",
     "gulp-watch": "^4.3.6",
+    "hercule": "^4.1.0",
     "highlight.js": "^9.10.0",
+    "lodash": "^4.17.4",
     "markdown-it": "^8.3.1",
     "markdown-it-attrs": "^0.8.0",
     "markdown-it-container": "^2.0.0",