Checked a bunch of documents. Completed doctest. Styling of tables.

docs/en/manuals/2dgraphics.md

@@ -219,7 +219,7 @@ The game object now contains the Tile Map and you can place or spawn the game ob
 
 ## Texture Filtering and Sampling
 
-Defold supports two different ways to do texture sampling. The method governs the visual result in cases when a _texel_ (a pixel in a texture) is not perfectly aligned with a screen pixel--. This happens when you move a Sprite containing the texture seamlessly (say 0.2 pixels in any direction), if your camera is moving seamlessly or if your camera zooms in or out:
+Defold supports two different ways to do texture sampling. The method governs the visual result in cases when a _texel_ (a pixel in a texture) is not perfectly aligned with a screen pixel. This happens when you move a Sprite containing the texture seamlessly (say 0.2 pixels in any direction), if your camera is moving seamlessly or if your camera zooms in or out:
 
 Nearest
 : The nearest texel will be picked to color the screen pixel. This sampling method should be chosen if you want a perfect one-to-one pixel mapping from your textures to what you see on screen. With nearest filtering everything will snap from pixel to pixel when moving which looks twitchy if the Sprite moves slowly.

docs/en/manuals/application-lifecycle.md

@@ -1,7 +1,5 @@
 Application lifecycle
 =====================
-:location: documentation manuals concepts
-:type: manual
 
 This document details the lifecycle of Defold games and applications.
 
@@ -11,11 +9,11 @@ The lifecycle of a Defold application or game is on the large scale very simple.
 
 In many cases only a rudimentary understanding of Defold's inner workings is necessary. However, you might run into edge cases where the exact order Defold carries out its tasks becomes vital. This document describes how the engine runs an application from start to finish.
 
-The application starts by initializing everything that is needed to run the engine. It loads the main collection and calls `[init()](/ref/go#init)` on all loaded components that has an `init()` Lua function (script components and GUI components with GUI scripts). This allows you to do custom initialization.
+The application starts by initializing everything that is needed to run the engine. It loads the main collection and calls [`init()`](/ref/go#init) on all loaded components that has an `init()` Lua function (script components and GUI components with GUI scripts). This allows you to do custom initialization.
 
-The application then enters the update loop where the application will spend a majority of its lifetime. Each frame, game objects and the components they contain are updated. Any script and GUI script `[update()](/ref/go#update)` functions are called. During the update loop messages are dispatched to its recipients, sounds are played and all graphics is rendered.
+The application then enters the update loop where the application will spend a majority of its lifetime. Each frame, game objects and the components they contain are updated. Any script and GUI script [`update()`](/ref/go#update) functions are called. During the update loop messages are dispatched to its recipients, sounds are played and all graphics is rendered.
 
-At some point the applications lifecycle will come to an end. Before the application quits the engine steps out of the update loop and enters a finalization stage. It prepares all loaded game objects for deletion. All object components’ `[final()](/ref/go#final)` functions are called, which allows for custom cleanup. Then the objects are deleted and the main collection is unloaded.
+At some point the applications lifecycle will come to an end. Before the application quits the engine steps out of the update loop and enters a finalization stage. It prepares all loaded game objects for deletion. All object components’ [`final()`](/ref/go#final) functions are called, which allows for custom cleanup. Then the objects are deleted and the main collection is unloaded.
 
 ## Initialization
 
@@ -35,12 +33,12 @@ The order game object component `init()` functions are called is unspecified. Yo
 
 Since your `init()` code can post new messages, tell factories to spawn new objects, mark objects for deletion and do all sorts of things the engine performs a full "post-update" pass next. This pass carries out message delivery, the actual factory game object spawning and object deletion. Note that the post-update pass includes a  "dispatch messages" sequence that not only sends any queued messages but also handles messages sent to collection proxies. Any subsequent updates on the proxies (enable and disable, loading and mark for unloading) is performed during those steps.
 
-Studying the diagram above reveals that it is fully possible to load a [collection proxy](/manuals/collection-proxy) during `init()`, ensure all its contained objects are initialized, and then unload the collection through the proxy--all this before the first component `update()` is called, i.e. before the engine has left the initialization stage and entered the update loop:
+Studying the diagram above reveals that it is fully possible to load a [collection proxy](/manuals/collection-proxy) during `init()`, ensure all its contained objects are initialized, and then unload the collection through the proxy---all this before the first component `update()` is called, i.e. before the engine has left the initialization stage and entered the update loop:
 
 ```lua
 function init(self)
-        print("init()")
-        msg.post("#collectionproxy", "load")
+    print("init()")
+    msg.post("#collectionproxy", "load")
 end
 
 function update(self, dt)
@@ -49,14 +47,14 @@ function update(self, dt)
 end
 
 function on_message(self, message_id, message, sender)
-        if message_id == hash("proxy_loaded") then
-                print("proxy_loaded. Init, enable and then unload.")
-                msg.post("#collectionproxy", "init")
-                msg.post("#collectionproxy", "enable")
-                msg.post("#collectionproxy", "unload")
-                -- The proxy collection objects’ init() and final()
-                -- is called before we reach this object’s update()
-          end
+    if message_id == hash("proxy_loaded") then
+        print("proxy_loaded. Init, enable and then unload.")
+        msg.post("#collectionproxy", "init")
+        msg.post("#collectionproxy", "enable")
+        msg.post("#collectionproxy", "unload")
+        -- The proxy collection objects’ init() and final() functions
+        -- are called before we reach this object’s update()
+    end
 end
 ```
 
@@ -68,7 +66,7 @@ The update loop runs through a long sequence once every frame. The update sequen
 
 ## Input
 
-Input is is read from available devices, mapped against [input bindings](/manuals/input) and then dispatched. Any game object that has acquired input focus gets input sent to all its component `on_input()` functions. A game object with a script component and a GUI component with a GUI script will get input to both components’ `on_input()` functions--given that they are defined and that they have acquired input focus.
+Input is is read from available devices, mapped against [input bindings](/manuals/input) and then dispatched. Any game object that has acquired input focus gets input sent to all its component `on_input()` functions. A game object with a script component and a GUI component with a GUI script will get input to both components’ `on_input()` functions---given that they are defined and that they have acquired input focus.
 
 Any game object that has acquired input focus and that contain collection proxy components dispatches input further to components in the proxy collection belonging to game objects that has acquired input focus. This process continues recursively down enabled collection proxies within enabled collection proxies.
 
@@ -88,7 +86,7 @@ Transforms are then done, applying any game object movement, rotation and scalin
 
 ## Render update
 
-The render update block dispatches messages to the @render socket (camera component "set_view_projection" messages, "set_clear_color" messages etc). The render script `update()` is then called.
+The render update block dispatches messages to the `@render` socket (camera component `set_view_projection` messages, `set_clear_color` messages etc). The render script `update()` is then called.
 
 ## Post update
 
@@ -96,13 +94,13 @@ After the updates, a post update sequence is run. It unloads from memory collect
 
 Any factory components that has been told to spawn a game object will do that next. Finally, game objects that are marked for deletion are actually deleted.
 
-The last steps in the update loop involves dispatching @system messages ("exit", "reboot" messages, toggling the profiler, starting and stopping video capture etc). Then graphics is rendered. During the graphics rendering, video capture is done, as is any rendering of the visual profiler (see the [Debugging documentation](/manuals/debugging).)
+The last steps in the update loop involves dispatching `@system` messages (`exit`, `reboot` messages, toggling the profiler, starting and stopping video capture etc). Then graphics is rendered. During the graphics rendering, video capture is done, as is any rendering of the visual profiler (see the [Debugging documentation](/manuals/debugging).)
 
 ## Frame rate and collection time step
 
-The number of frame updates per seconds (which equals the number of update-loop runs per second) can be set in the project settings, or programmatically by sending an "set_update_frequency" message to the `@system` socket. In addition, it is possible to set the _time step_ for collection proxies individually by sending a "set_time_step" message to the proxy. Changing a collection's time step does not affect the frame rate. It has an effect on the physics update time step as well as the "dt" variable passed to `update().` Also note that altering the time step does not alter the number of times `update()` will be called each frame--it is always exactly once.
+The number of frame updates per seconds (which equals the number of update-loop runs per second) can be set in the project settings, or programmatically by sending an "set_update_frequency" message to the `@system` socket. In addition, it is possible to set the _time step_ for collection proxies individually by sending a `set_time_step` message to the proxy. Changing a collection's time step does not affect the frame rate. It has an effect on the physics update time step as well as the "dt" variable passed to `update().` Also note that altering the time step does not alter the number of times `update()` will be called each frame---it is always exactly once.
 
-(See [Collection proxy](/manuals/collection-proxy) and [set_time_step](/ref/collection-proxy#set_time_step) for details)
+(See the [Collection proxy manual](/manuals/collection-proxy) and [`set_time_step`](/ref/collection-proxy#set_time_step) for details)
 
 ## Finalization
 

docs/en/manuals/camera.md

@@ -1,15 +1,12 @@
 Cameras
 =======
-:toc: macro
-
-toc::[]
 
 Defold contains a primitive camera component. This manual describes its functionality and intended use.
 
 A camera is a component type that you use to provide a view into your game world. Cameras are very simple objects that in essence does the following:
 
-1. They have a location in space -- either 2D or 3D.
-2. They can be moved around in space -- by moving the containing game object.
+1. They have a location in space---either 2D or 3D.
+2. They can be moved around in space---by moving the containing game object.
 3. They provide the render script with the data necessary to render with computed view and projection matrices.
 
 Cameras in OpenGL are expressed as coordinate systems with a viewer, or eye, position, a near and a far clipping plane. The near clipping plane equals the viewing plane, or the screen.
@@ -31,7 +28,7 @@ The camera component has a set of properties that defines the camera frustum.
 ![Camera properties](images/cameras/cameras_properties.png)
 
 ::: important
-The current default FOV value is misleading. It is not expressed in degrees but in radians. For a 45 degree FOV, change the value to 0.785 (PI / 4).
+The current default FOV value is misleading. It is not expressed in degrees but in radians. For a 45 degree FOV, change the value to 0.785 (𝛑 / 4).
 :::
 
 aspect_ratio

docs/en/manuals/collection-proxy.md

@@ -70,11 +70,11 @@ msg.post("world2:manager#script", "spawn_player")
 
 So a collection you want to load through a proxy should be renamed to a unique name. If you don’t give it a unique name the engine will signal a name collision error:
 
-----
+```txt
 ERROR:GAMEOBJECT: The collection 'default' could not be created since there is already a socket with the same name.
 WARNING:RESOURCE: Unable to create resource: build/default/worlds/world1.collectionc
 ERROR:GAMESYS: The collection /worlds/world1.collectionc could not be loaded.
-----
+```
 
 ## Loading
 
@@ -89,23 +89,27 @@ The proxy will send back a message "proxy_loaded" when the loading is done. You
 
 ```lua
 function on_message(self, message_id, message, sender)
-        if message_id == hash("proxy_loaded") then
-                -- New world is loaded. Init and enable it.
-                msg.post(sender, "init")
-                msg.post(sender, "enable")
-                ...
+    if message_id == hash("proxy_loaded") then
+        -- New world is loaded. Init and enable it.
+        msg.post(sender, "init")
+        msg.post(sender, "enable")
+        ...
+    end
+end
 ```
 
 Alternatively your logic can check the origin of the message an act accordingly. The collection proxy that sent the "proxy_loaded" is indicated in the fragment part of the sender URL:
 
 ```lua
 function on_message(self, message_id, message, sender)
-        if message_id == hash("proxy_loaded") and sender.fragment == hash("myproxy1") then
-                -- "myproxy1" is loaded. Let’s init and enable it.
-                ...
+    if message_id == hash("proxy_loaded") and sender.fragment == hash("myproxy1") then
+        -- "myproxy1" is loaded. Let’s init and enable it.
+        ...
+    end
+end
 ```
 
-Initializing the collection through the proxy with the "init" message will recursively initialize all the objects contained in the collection. Enabling the collection through the proxy with the "enable" message recursively enables all the objects contained in the collection.
+Initializing the collection through the proxy with the `init` message will recursively initialize all the objects contained in the collection. Enabling the collection through the proxy with the `enable` message recursively enables all the objects contained in the collection.
 
 (See [Application lifecycle](/manuals/application-lifecycle) for details on the lifespan of an object)
 
@@ -145,59 +149,47 @@ Here’s the setup in the "world2" collection:
 
 The "exit" sign is placed in the exact same coordinates in both collections giving one tile of overlap between them. Also notice that there is a "player" object in "world2" as well as in "world1". Because each collection is its own physics world we need a separate player in each and we just make sure to transfer the position and input control from one player object to the other when we move between the worlds.
 
-So, when the player hits the trigger in "world1" we start by loading "world2":
-
 ```lua
 function on_message(self, message_id, message, sender)
-        if message_id == hash("trigger_response") and message.enter then
-                -- Player hits the world switch trigger.
-                -- Load the next world as referenced through the
-                -- previously constructed url.
-                msg.post(self.url, "load")
-                ...
-```
-We then enable the collection when it’s loaded:
-
-```lua
-        elseif message_id == hash("proxy_loaded") then
-                -- New world is loded. Enable it.
-                msg.post(sender, "enable")
-```
-
-And then it’s time to switch the player object. We start by sending the current player a message requesting the data we need, which is the current position of the player object:
-
-```lua
-                -- We have to transfer the position of the player
-                -- to the player in the other world.
-                local currentsocket = ""
-                -- We can't use the hashed properties to build
-                -- strings:
-                if self.selfworld == hash("world1") then
-                        currentsocket = "world1"
-                elseif self.selfworld == hash("world2") then
-                        currentsocket = "world2"
-                end
-                msg.post(currentsocket .. ":" .. "/player#script", "request_player")
-```
-
-We get a response back and pass the player data to the player in the newly loaded collection:
-
-```lua
-        elseif message_id == hash("player_response") then
-                -- We're getting player position back.
-                -- Now we have to apply it to the other world's player.
-                local othersocket = ""
-                if self.otherworld == hash("world1") then
-                        othersocket = "world1"
-                elseif self.otherworld == hash("world2") then
-                        othersocket = "world2"
-                end
-                -- Pass along the message we got back.
-                msg.post(othersocket .. ":" .. "/player#script", "inherit_player", message)
+    if message_id == hash("trigger_response") and message.enter then -- <1>
+        -- Player hits the world switch trigger.
+        -- Load the next world as referenced through the
+        -- previously constructed url.
+        msg.post(self.url, "load")
+    elseif message_id == hash("proxy_loaded") then -- <2>
+        -- New world is loded. Enable it.
+        msg.post(sender, "enable")
+        -- We have to transfer the position of the player -- <3>
+        -- to the player in the other world.
+        local currentsocket = ""
+        -- We can't use the hashed properties to build
+        -- strings:
+        if self.selfworld == hash("world1") then
+            currentsocket = "world1"
+        elseif self.selfworld == hash("world2") then
+            currentsocket = "world2"
+        end
+        msg.post(currentsocket .. ":" .. "/player#script", "request_player")
+    elseif message_id == hash("player_response") then -- <4>
+        -- We're getting player position back.
+        -- Now we have to apply it to the other world's player.
+        local othersocket = ""
+        if self.otherworld == hash("world1") then
+                othersocket = "world1"
+        elseif self.otherworld == hash("world2") then
+                othersocket = "world2"
         end
+        -- Pass along the message we got back.
+        msg.post(othersocket .. ":" .. "/player#script", "inherit_player", message)
+    end
+end
 ```
+1. When the player hits the trigger in "world1" we start by loading "world2":
+2. We then enable the collection when it’s loaded:
+3. Then it’s time to switch the player object. We start by sending the current player a message requesting the data we need, which is the current position of the player object:
+4. We get a response back and pass the player data to the player in the newly loaded collection:
 
-The message "inherit_player" just inherits the position sent so the new player is repositioned to the same spot where the old player was (in the trigger, which is fine. It won’t detect the new player since they are parts of two different collections, and physical worlds)
+The message `inherit_player` just inherits the position sent so the new player is repositioned to the same spot where the old player was (in the trigger, which is fine. It won’t detect the new player since they are parts of two different collections, and physical worlds)
 
 If we run the game we can move from "world1" to "world2", but the player object in "world1" is still present, and will fall through the world of "world2".
 
@@ -219,9 +211,16 @@ msg.post("loader#world1", "final")
 msg.post("loader#world1", "unload")
 ```
 
-Disabling the collection through the proxy with "disable" sends recursively disables all the objects in the collection. Finalizing the collection through the proxy with a "final" message recursively finalizes all the objects in the collection and "unload" removes the collection from memory.
+`disable`
+: This message disables the collection through the proxy. It recursively disables all the objects in the collection loaded through the proxy.
+
+`final`
+: Finalizes the collection through the proxy. It recursively finalizes all the objects in the collection.
+
+`unload`
+: This message removes the collection from memory. If you don’t need the finer grained control, you can send the `unload` message without first disabling and finalizing the collection. The proxy will then automatically disable and finalize the collection before it’s unloaded.
 
-When the proxy has unloaded the collection it will send back a "proxy_unloaded" message:
+When the proxy has unloaded the collection it will send back a `proxy_unloaded` to the script that sent the `unload` message:
 
 ```lua
 if message_id == hash("unload_level") then
@@ -232,10 +231,9 @@ if message_id == hash("unload_level") then
 elseif message_id == hash("proxy_unloaded") then
     -- Ok, the level is unloaded
     ...
+end
 ```
 
-If you don’t need the finer grained control, you can send the "unload" message without first disabling and finalizing the collection. The proxy will then automatically disable and finalize the collection before it’s unloaded.
-
 Now back to our platformer example where the only thing we need to do is to send the messages to the right proxy. We do that right after we send the request for data to the new player object:
 
 ```lua
@@ -266,9 +264,10 @@ If we want to receive input action in objects belonging to either "world1" or "w
 
 ```lua
 function init(self)
-        -- Acquire input so collection objects will receive it.
-        msg.post(".", "acquire_input_focus")
-        ...
+    -- Acquire input so collection objects will receive it.
+    msg.post(".", "acquire_input_focus")
+    ...
+end
 ```
 
 Any object in either "world1" or "world2" (that is loaded) can now send "acquire_input_focus" and start receiving input actions. (For more information on input, see [Input](/manuals/input))
@@ -294,13 +293,13 @@ To see what's happening when changing the time step, we can create an object wit
 
 ```lua
 function update(self, dt)
-        print("update() with timestep (dt) " .. dt)
+    print("update() with timestep (dt) " .. dt)
 end
 ```
 
 With a time step of 0.2, we get the following result in the console:
 
-----
+```txt
 INFO:DLIB: SSDP started (ssdp://192.168.0.102:54967, http://0.0.0.0:62162)
 INFO:ENGINE: Defold Engine 1.2.37 (6b3ae27)
 INFO:ENGINE: Loading data from: build/default
@@ -314,10 +313,10 @@ DEBUG:SCRIPT: update() with timestep (dt) 0
 DEBUG:SCRIPT: update() with timestep (dt) 0
 DEBUG:SCRIPT: update() with timestep (dt) 0
 DEBUG:SCRIPT: update() with timestep (dt) 0.016666667535901
-----
+```
 
-`update()` is still called 60 times a second, but the "dt" value changes. We see that only 1/5 (0.2) of the calls to `update()` will have a "dt" of 1/60 (corresponding to 60 FPS) -- the rest is zero. All physics simulations will also be updated according to that dt and advance only in one fifth of the frames.
+`update()` is still called 60 times a second, but the "dt" value changes. We see that only 1/5 (0.2) of the calls to `update()` will have a "dt" of 1/60 (corresponding to 60 FPS)---the rest is zero. All physics simulations will also be updated according to that dt and advance only in one fifth of the frames.
 
-See [set_time_step](/ref/collection-proxy#set_time_step) for more details.
+See [`set_time_step`](/ref/collection-proxy#set_time_step) for more details.
 
 (Some of the graphic assets used are made by Kenney: http://kenney.nl/assets)

docs/en/manuals/doctest.md

@@ -1,211 +0,0 @@
-= Typography test
-:source-highlighter: coderay
-
-This document is intended to test typography and styling of generated Asciidoc documents that are built against Defold Bootstrap 3 stylesheets.
-
-We begin by making sure we cover the usual typographic things like *stronger text*. There is also the thing with _slanted text that might be italic and nice_ but not always, depending on font.
-
-There is also the concept of em-dash that needs to be there--used quite a lot! Then sometimes there is a need to call out `go.function_word()` things and `variable` names.
-
-*_Bold italic text_* goes like this but who ever would want to use that? Also, we need to [be able to link to other documents](introduction). Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-It is also convenient to be able to refer to command input and menu selections. For instance, to perform an action might require that you select "View > Zoom > Reset", or perhaps menu:File[Open Project], or menu:Meny[Item 1 > Sub 1 > Sub 2 > Sub 3] and then pressing <kbd>Option + C</kbd> or <kbd>SPACE</kbd> for that matter.
-
-[quote, Whoever said this thing, The book of many wisdoms]
-____
-Here comes a pretty long quotation rant from someone who believes himself (or herself) to be famous enough to warrant a quote in a document like this. Pretty poor sod if you ask me.
-____
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-## A second level headline
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Define
-: A term like this. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
-
-
-Another term
-: Second term just like this. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
-
-
-Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-## A second level headline that goes on for some time so it becomes long
-
-::: sidenote
-Oh, I almost forgot to add one of those!
-:::
-
-Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-::: important
-Oh, I almost forgot to add one of those!
-:::
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-[WARNING]
-:::
-Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
-:::
-
-## A third level headline that is a bit longer
-
-First a short paragraph, then a bullet list.
-
-* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
-* Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-** Sub bullets
-** Another sub-bullet
-** Let's do a third for good measure
-* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
-* Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-- Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-.. Sublist entries should work here too.
-.. Right? I think they are pretty useful.
-.. If you agree, let's agree to agree.
-- Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
-- Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-==== Fourth level headline that you should not really use
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-```lua
-local pieces = { "ground0", "ground1", "ground2", "ground3",
-                    "ground4", "ground5", "ground6" } <!--1-->
-
-function init(self) -- <2>
-    self.speed = 6
-end
-
--- Here is a comment to test how they look
--- and a second line of text.
-function update(self, dt) -- <3>
-    for i, p in ipairs(pieces) do -- <4>
-        local pos = go.get_position(p)
-        if pos.x <> -228 then -- <5>
-            pos.x = 1368 + (pos.x + 228)
-        end
-        pos.x = pos.x - self.speed
-        go.set_position(pos, p)
-    end
-end
-```
-<1> Store the id:s of the ground game objects in a Lua table so we can iterate over them.
-<2> The `init()` function is called when the game object comes to life in the game. We initiate a object local member variable that contains the speed of the ground.
-<3> `update()` is called once each frame, typically 60 times per second.
-<4> Iterate over all the ground game objects.
-<5> Store the current position in a local variable, then if the current object is on the leftmost edge, move it to the rightmost edge.
-
-It is also very nice to be able to intruct people on command line input, like this:
-
-----
-$ wget http://ftp.us.debian.org/debian/pool/main/o/openssl/libssl0.9.8_0.9.8o-4squeeze14_i386.deb  # <1>
-$ sudo dpkg -i libssl0.9.8_0.9.8o-4squeeze14_i386.deb
-----
-<1> Some note here as well.
-
-## Let's do images
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-![A large image of sorts](images/doctest/large.png)
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-![A medium image of sorts](images/doctest/medium.png)
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-![A small image of sorts](images/doctest/small.png)
-![A small image of sorts](images/doctest/small.png)
-
-## Table time!
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-|===
-|Shortcut |Purpose
-
-|<kbd>F11</kbd>
-|Toggle fullscreen
-
-|<kbd>Ctrl`T</kbd>
-|Open a new tab
-
-Then another tab should be opened and switched to some magic state, I believe.
-
-|<kbd>Ctrl`Shift`N</kbd>
-|New incognito window
-
-|<kbd>Ctrl ` `</kbd>
-|Increase zoom
-|===
-
-
-[cols="2,6,2,2,2"]
-|===
-||Description|Type|go.get()|go.bananas()
-
-5`| *GAME OBJECT PROPERTIES*
-
-|*position*
-|The local position of the game object.
-|vector3
-|yes
-|yes
-
-|*rotation*
-|The local rotation of the game object, expressed as a quartenion.
-|quat
-|yes
-|yes
-
-|*euler*
-|The local rotation of the game object, expressed as Euler angles in degrees.
-|vector4
-|yes
-|yes
-
-|*scale*
-|The local uniform scale of the game object, expressed as a multiplier. 1 is 100% (original) scale.
-|number
-|yes
-|yes
-
-5`|&nbsp;
-
-5`|*SPRITE COMPONENT PROPERTIES*
-
-|*size*
-|The non scaled size of the sprite--its size as taken from the source atlas.
-|vector3
-|yes
-|no
-
-|*scale*
-|Non uniform scaling of the sprite, expressed as a vector where each component contains a multiplier along each axis. To double the size in x and y, provide vmath.vector3(2.0, 2.0, 0)
-|vector3
-|yes
-|yes
-
-|===
-
-

docs/en/test.md

@@ -0,0 +1,107 @@
+# Defold documentation typography
+
+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.
+
+Try to write as talking to the user. Keep the language direct and active and refrain from stating opinions unless it is important to the matter. Try to write paragraphs that flow and do not break them unnecessarily.
+
+You do have some typographic markers to your disposal. The simplest one is the *emphasis* marker. It puts some stress to a word, marking it as important. This marker should also be used to call attention to specific things that the user can encounter in Defold, like the names of properties, buttons etc. For example, a sprite component's *Position*, a button that says *Save...* etc. Do not use the **bold text** emphasis. Do not ***ever*** mark anything with both bold and emphasis.
+
+Generally, when using quotes you can type straight quotes (`""`) and they get automatically converted to "nice typographically correct quotes". Also, the en and em-dashes are nice things to be able to type easily. You do that by typing `--` for en-dash and `---` for em-dash. So now you can get nicely typeset numeric intervals like 23--24, and if you want an em-dash as punctuation in a sentence---that's easy too. Just remember not to put spaces around them. A nice ellipsis character is also automatically inserted whenever you type more than two spaces in a row...
+
+Keystrokes, like the combination <kbd>⌘ + T</kbd> are written surrounded by `<kbd>` tags, as are any references to menu options, like <kbd>File ▸ Save As...</kbd>. Note the small right-pointing triangle that makes menu options stand out a little.
+
+For subscript and superscript you type `~subscript~` and `^superscript^`. For example: <code>X~N~ = y^N^ + O~N~</code> where `N` is a variable. For clarity, maths formulas can be put inside `<code>` tags.
+
+For things that the user will type, like function names, message names, string values and similar, use the `code marker`. For instance, `go.some_function()` or a `variable` name, a `message_name` or a `"string value"`. For larger chunks of code or configuration text, use the code fences with language specification to enable syntax highlighting:
+
+```lua
+local pieces = { "ground0", "ground1", "ground2", "ground3",
+                    "ground4", "ground5", "ground6" } -- <1>
+
+function init(self) -- <2>
+    self.speed = 6
+end
+
+-- This is a comment to the functionality of the function
+function update(self, dt)
+    for i, p in ipairs(pieces) do -- <3>
+        local pos = go.get_position(p)
+        if pos.x <> -228 then
+            pos.x = 1368 + (pos.x + 228)
+        end
+        pos.x = pos.x - self.speed
+        go.set_position(pos, p)
+    end
+end
+```
+1. Note that the `-- <1>` in the source is changed to a numeric callout that is not part of
+   the source code anymore.
+2. Depending on the source language you type the callout differently. In a C like language
+   you would type `// <2>`
+3. In a shell-like language you would type `# <3>`.
+
+## Two levels of headings, lists and tables
+
+Do not use more than two levels of headings. If you need to describe specific things that you feel calls for a third level heading, use a definition list instead:
+
+Some thing
+: Here you can explain what "Some thing" is, what it does and whatnot. You have access to all of markdown in the description, just make sure to indent properly:
+  - A bullet point
+  - Another bullet
+
+Another thing to explain
+: Here you explain that other thing to explain. Try to be specific and avoid vague language when you describe things.
+
+Definition lists are great when you can put a name to each item. Sometimes a bullet list is better, or a numbered list. You can mix and match these:
+
+- Bullet list, indicated with either `-` or a `*` or a `+` at the start of the line.
+- Another item.
+- A third item. We can also make sub-items, either bullets or numbers:
+    1. A numbered sub-item. Number list items are written either `1.` or `1)`.
+    2. The numbers are increased automatically from the first one.
+- A fourth bullet item. This marks the end of the list.
+
+23. Let's create a numbered list that starts on the number 23.
+1. Another item. Note that this gets the number 24 no matter what I type.
+0. And this gets the number 25 no matter what I type.
+
+Definition lists are good for free flow explanation of things. Sometimes a table would do the job better though. Left-aligned:
+
+| Shortcut                  | Purpose               | Context        |
+| ------------------------- | --------------------- | -------------- |
+| <kbd>F11</kbd>            | Toggle fullscreen     | In application |
+| <kbd>⌘ + T</kbd>         | Open a new tab        | In application |
+| <kbd>⌘ + Shift + N</kbd> | New incognito window  | In application |
+
+Or right-aligned
+
+| Shortcut                  | Purpose               | Context        |
+| ------------------------: | --------------------: | -------------: |
+| <kbd>F11</kbd>            | Toggle fullscreen     | In application |
+| <kbd>⌘ + T</kbd>         | Open a new tab        | In application |
+| <kbd>⌘ + Shift + N</kbd> | New incognito window  | In application |
+
+
+## Notes and images
+
+There are two types of notes that you can insert in the text. Since this is not a printed medium the idea of a footnote doesn't really work. Instead we keep the notes together with the text. Use the `::: sidenote` block for these.
+
+::: sidenote
+The `::: sidenote` block is good for adding footnote-like information to the text. It can be used to add further explanation that is not vital or point to other resources. They are shown to the side of the text they preceed.
+:::
+
+When you really want to make the user aware of something, use the `::: important` block:
+
+::: important
+This is a block of text that the user will not miss. Use these sparingly for things that really needs a lot of attention. If you find that your document is littered with these, you might want to group the information a bit.
+:::
+
+Images are inserted in the document like this:
+
+![A large image of sorts](manuals/images/doctest/large.png)
+
+Note that images are rendered inline if they are part of the same paragragh. This is useful if you want to line up several images like this:
+
+![A small image of sorts](manuals/images/doctest/small.png)
+![A small image of sorts](manuals/images/doctest/small.png)
+

docs/sass/defold-md.sass

@@ -122,6 +122,7 @@ body
     line-height: 1.6em
     padding: 1.4em
     background-color: $dark-grey
+    overflow: auto
 
     .callout
       color: $text-black
@@ -133,17 +134,20 @@ body
     .hljs-built_in
       color: #d19a66
 
+    .hljs-title
+      font-weight: 400
+
     .k, .kd, .o, .hljs-keyword, .nt
-        color:  #e06c75
+      color:  #e06c75
 
     .s, .s2, .hljs-string
-        color: #98c379
+      color: #98c379
 
     .c1, .hljs-comment
-        color: #abb2bf
+      color: #abb2bf
 
     [data-pseudo-content]::before
-        content: attr(data-pseudo-content)
+      content: attr(data-pseudo-content)
 
   code
     font-family: 'Source Code Pro', monospace
@@ -153,4 +157,13 @@ body
   kbd
     font-family: Source Sans Pro, sans-serif
     background-color: $light-grey
-    padding: 0.1em 0.4em
+    padding: 0.02em 0.4em
+
+  table
+    margin-top: .625rem
+    margin-bottom: 2.5rem
+    width: 100%
+    border: 1px solid #d8dde6
+
+    tr:nth-child(odd)
+      background-color: #f7f8fa

gulpfile.js

@@ -39,7 +39,7 @@ md = new markdown({
       try {
         var hl = hljs.highlight(lang, str).value;
         // Callouts hack!
-        return hl.replace(/-- &lt;([0-9]+)&gt;/g, '<span class="callout" data-pseudo-content="$1"></span>');
+        return hl.replace(/(?:--|\/\/|#) &lt;([0-9]+)&gt;/g, '<span class="callout" data-pseudo-content="$1"></span>');
       } catch (__) {}
     }
     return ''; // use external default escaping

lib/lua.js

@@ -44,7 +44,7 @@ module.exports = {
             'collectgarbage dofile error getfenv getmetatable ipairs load loadfile loadstring' +
             'module next pairs pcall print rawequal rawget rawset require select setfenv' +
             'setmetatable tonumber tostring type unpack xpcall arg self ' +
-            // Defold builtins
+            // Defold and lua builtins
             'base bit builtins camera collectionfactory collectionproxy coroutine crash debug facebook factory go gui http iac iap image io json label math model msg os package particlefx physics push render resource sound spine sprite string sys table tilemap vmath webview window zlib'
         },
         contains: COMMENTS.concat([