Docs: fix markdown in various files, update the README mildly

Review URL: https://codereview.chromium.org/678693003

README.md

@@ -17,7 +17,7 @@ theme layer that gives each widget a concrete visual and interactive design.
 Elements
 --------
 
-The Sky engine contains a handful of primitive elements and the tools with which
+The Sky engine contains [a handful of primitive elements](specs/markup.md) and the tools with which
 to create custom elements.  The following elements are built into the engine:
 
  - ``script``: Executes script
@@ -27,9 +27,10 @@ to create custom elements.  The following elements are built into the engine:
  - ``template``: Captures descendants for use as a template
  - ``content``: Visually projects descendents of the shadow host
  - ``shadow``: Visually projects older shadow roots of the shadow host
- - ``image``: Displays an image
+ - ``img``: Displays an image
  - ``a``: Links to another Mojo application
  - ``title``: Briefly describes the current application state to the user
+ - ``t``: Preserve whitespace (by default, whitespace nodes are dropped)
 
 ### Additional Elements ###
 
@@ -64,10 +65,19 @@ For example, the ``AnnualReport`` constructor uses the ``BalanceSheet`` class
 exported by that module.
 
 ```html
-<import href=”/sky/framework” />
-<import href=”/another/module.sky” as=”foo” />
+SKY MODULE
+<import src=”/sky/framework” />
+<import src=”/another/module.sky” as=”foo” />
 <sky-element name=”my-element”>
-  [ ... custom element definition ... ]
+class extends SkyElement {
+  constructor () {
+    this.addEventListener('click', (event) => this.updateTime());
+    this.createShadowTree().appendChild('Click to show the time');
+  }
+  updateTime() {
+    this.shadowTree.firstChild.replaceWith(new Date());
+  }
+}
 </sky-element>
 <script>
 class AnnualReport {
@@ -114,9 +124,10 @@ As an example, the following is a sketch of a module that wraps Mojo's
 ``network_service`` in a simpler functional interface:
 
 ```html
-<import href=”mojo://shell” as=”shell” />
-<import href="/mojo/network/network_service.mojom.sky" as="net" />
-<import href="/mojo/network/url_loader.mojom.sky" as="loader" />
+SKY MODULE
+<import src=”mojo://shell” as=”shell” />
+<import src="/mojo/network/network_service.mojom.sky" as="net" />
+<import src="/mojo/network/url_loader.mojom.sky" as="loader" />
 <script>
 module.exports = function fetch(url) {
   return new Promise(function(resolve, reject) {
@@ -150,6 +161,6 @@ and the specification are in flux, but hopefully they'll converge over time.
 Contributing
 ------------
 
-Instructions for building and testing Sky are contained in [HACKING.md]. For
+Instructions for building and testing Sky are contained in [HACKING.md](HACKING.md). For
 coordination, we use the ``#mojo`` IRC channel on
 [Freenode](https://freenode.net/).

specs/README.md

@@ -7,20 +7,20 @@ they can refer to binary resources like images and fonts.
 Sky files
 ---------
 
-Conventional MIME type: ```text/sky```, though this type is neither
+Conventional MIME type: ``text/sky``, though this type is neither
 necessary nor sufficient to indicate that a file is a Sky file; only
 the signature matters for type dispatch of Sky files.
 
-Conventional extension: ```.sky```
+Conventional extension: ``.sky``
 
 Signatures:
 
 For application files, one of the following:
- ```23 21 6d 6f 6a 6f 20 6d 6f 6a 6f 3a 73 6b 79 0a``` ("```#!mojo mojo:sky\n```")
- ```23 21 6d 6f 6a 6f 20 6d 6f 6a 6f 3a 73 6b 79 0d``` ("```#!mojo mojo:sky\r```")
- ```23 21 6d 6f 6a 6f 20 6d 6f 6a 6f 3a 73 6b 79 20``` ("```#!mojo mojo:sky ```")
+ ``23 21 6d 6f 6a 6f 20 6d 6f 6a 6f 3a 73 6b 79 0a`` ("``#!mojo mojo:sky\n``")
+ ``23 21 6d 6f 6a 6f 20 6d 6f 6a 6f 3a 73 6b 79 0d`` ("``#!mojo mojo:sky\r``")
+ ``23 21 6d 6f 6a 6f 20 6d 6f 6a 6f 3a 73 6b 79 20`` ("``#!mojo mojo:sky ``")
 
 For module files, one of the following:
- ```53 4b 59 20 4d 4f 44 55 4c 45 0a``` ("```SKY MODULE\n```")
- ```53 4b 59 20 4d 4f 44 55 4c 45 0d``` ("```SKY MODULE\r```")
- ```53 4b 59 20 4d 4f 44 55 4c 45 20``` ("```SKY MODULE ```")
+ ``53 4b 59 20 4d 4f 44 55 4c 45 0a`` ("``SKY MODULE\n``")
+ ``53 4b 59 20 4d 4f 44 55 4c 45 0d`` ("``SKY MODULE\r``")
+ ``53 4b 59 20 4d 4f 44 55 4c 45 20`` ("``SKY MODULE ``")

specs/apis.md

@@ -4,7 +4,7 @@ APIS
 The Sky core API
 ----------------
 
-```
+```javascript
 module 'sky:core' {
 
   // EVENTS
@@ -218,7 +218,7 @@ implementations of the APIs to JavaScript.
 Sky IDL works more or less the same as Web IDL but the syntax is a bit
 different.
 
-```
+```javascript
 module 'sky:modulename' {
 
   // this is a comment
@@ -267,18 +267,18 @@ module 'sky:modulename' {
 
 The following types are available:
 
-* ```Integer``` - WebIDL ```long long```
-* ```Float``` - WebIDL ```double```
-* ```String``` - WebIDL ```USVString```
-* ```Boolean``` - WebIDL ```boolean```
-# ```Object``` - WebIDL ```object```
-* ```InterfaceName``` - an instance of the interface InterfaceName
-* ```Promise<Type>``` - WebIDL ```Promise<T>```
-* ```Array<Type>``` - WebIDL ```sequence<T>```
-* ```Dictionary``` - unordered set of name-value String-String pairs with no duplicate names
-* ```Type?``` - union of Type and the singleton type with value "null" (WebIDL nullable)
-* ```(Type1 or Type2)``` - union of Type1 and Type2 (WebIDL union)
-* ```any``` - union of all types (WebIDL ```any```)
+* ``Integer`` - WebIDL ``long long``
+* ``Float`` - WebIDL ``double``
+* ``String`` - WebIDL ``USVString``
+* ``Boolean`` - WebIDL ``boolean``
+# ``Object`` - WebIDL ``object``
+* ``InterfaceName`` - an instance of the interface InterfaceName
+* ``Promise<Type>`` - WebIDL ``Promise<T>``
+* ``Array<Type>`` - WebIDL ``sequence<T>``
+* ``Dictionary`` - unordered set of name-value String-String pairs with no duplicate names
+* ``Type?`` - union of Type and the singleton type with value "null" (WebIDL nullable)
+* ``(Type1 or Type2)`` - union of Type1 and Type2 (WebIDL union)
+* ``any`` - union of all types (WebIDL ``any``)
 
 Methods that return nothing (undefined, in JS) use the keyword "void"
 instead of a type.
@@ -301,7 +301,7 @@ TODO(ianh): Define in detail how this actually works
 
 Notes
 -----
-```
+```javascript
 global object = {} // with Math, RegExp, etc
 
 magical imports:

specs/markup.md

@@ -204,11 +204,10 @@ Sky Markup: Global Attributes
 
 The following attributes are available on all elements:
 
-id="" (any value)
-class="" (any value, space-separated)
-style="" (declaration part of a Sky style rule)
-lang="" (language code)
-dir="" (ltr or rtl only)
-
-contenteditable="" (subject to future developments)
-tabindex="" (subject to future developments)
+* ``id=""`` (any value)
+* ``class=""`` (any value, space-separated)
+* ``style=""`` (declaration part of a Sky style rule)
+* ``lang=""`` (language code)
+* ``dir=""`` (ltr or rtl only)
+* ``contenteditable=""`` (subject to future developments)
+* ``tabindex=""`` (subject to future developments)

specs/modules.md

@@ -30,7 +30,7 @@ Module API
 Within a script in a module, the ```module``` identifier is bound to
 the ```Module``` object that represents the module:
 
-```
+```javascript
 interface Module : EventTarget {
   constructor (Application application, Document document); // O(1)
   attribute any exports; // O(1) // defaults to the module's document