sync upstream

README.md

@@ -18,11 +18,71 @@ started, leave a comment on the issue or ask around [on IRC](https://wiki.whatwg
 
 ### Pull requests
 
-See the [whatwg/html README](https://github.com/whatwg/html/blob/master/README.md) for the general
-guidelines. Note that `source` is `dom.bs` and "Acknowledgements" is "Acknowledgments" here (I
-know). Also, the DOM Standard uses [bikeshed](https://github.com/tabatkins/bikeshed) to generate
-`dom.html`. (Do not worry if using that tool is too complicated, your pull request does not need to
-contain the generated HTML.)
+In short, change `dom.bs` and submit your patch, with a
+[good commit message](https://github.com/erlang/otp/wiki/Writing-good-commit-messages). Consider
+reading through the [WHATWG FAQ](https://wiki.whatwg.org/wiki/FAQ) if you are new here.
+
+Please add your name to the Acknowledgments section in your first pull request, even for trivial
+fixes. The names are sorted lexicographically.
+
+To generate `dom.html`, [bikeshed](https://github.com/tabatkins/bikeshed) can be used. (Do not worry
+if using that tool is too complicated, your pull request does not need to contain the generated HTML
+to be accepted.)
+
+#### Formatting
+
+Use a column width of 100 characters.
+
+Do not use newlines inside "inline" elements, even if that means exceeding the column width
+requirement.
+```html
+<p>The
+<dfn method for=DOMTokenList lt=remove(tokens)|remove()><code>remove(<var>tokens</var>&hellip;)</code></dfn>
+method, when invoked, must run these steps:
+```
+is okay and
+  ```html
+<p>The <dfn method for=DOMTokenList
+lt=remove(tokens)|remove()><code>remove(<var>tokens</var>&hellip;)</code></dfn> method, when
+invoked, must run these steps:
+```
+is not.
+
+Using newlines between "inline" element tag names and their content is also forbidden. (This
+actually alters the content, by adding spaces.) That is
+```html
+<a>token</a>
+```
+is fine and
+```html
+<a>token
+</a>
+```
+is not.
+
+An `<li>` element always has a `<p>` element inside it, unless it's a child of `<ul class=brief>`.
+
+If a "block" element contains a single "block" element, do not put it on a newline.
+
+Do not indent for anything except a new "block" element. For instance
+```html
+ <li><p>For each <var>token</var> in <var>tokens</var>, in given order, that is not in
+ <a>tokens</a>, append <var>token</var> to <a>tokens</a>.
+```
+is not indented, but
+```html
+<ol>
+ <li>
+  <p>For each <var>token</var> in <var>tokens</var>, run these substeps:
+
+  <ol>
+   <li><p>If <var>token</var> is the empty string, <a>throw</a> a {{SyntaxError}} exception.
+```
+is.
+
+End tags may be included (if done consistently) and attributes may be quoted (using double quotes),
+though the prevelant theme is to omit end tags and not quote attributes (unless they contain a
+space).
 
 ### Tests