runt18 / html-2

Working Draft of the HTML specification

HTML

This is the repository for the Working Draft of the HTML specification. This repository is managed by the W3C Web Platform Working Group.

Editorial Documentation

The specification is built using Bikeshed. If you would like to propose edits, please make sure that they result in a specification that will build correctly, by testing in your own clone of the repository.

1. Install bikeshed
2. From the HTML folder open a command prompt
3. run bikeshed update: bikeshed update
4. run bikeshed: bikeshed spec

For the multipage version, one can do as follows:

1. Install multipage
2. Follow the instructions there to regenerate the HTML files

There are some conventions for linking to things. For example,

• For definitions of standard terms, use <a>term known to bikeshed</a>
• For definitions of elements use <{img}>
• For definitions of attributes use <{img/alt}>
• For WebIDL terms use {{HTMLImageElement/alt}}
• For Normative references use [[!shortname]] where shortname is the W3C "shortname" of the spec
• For informative references use [[shortname]]

And we try to follow these best-practices:

• For spec text that differs from WHATWG and must not be overwritten is indicated by wrapping in a comment: <!-- W3C START - DO NOT OVERWRITE--> protected text <!-- W3C END -->

• Line wrap at column 100 to keep lines easily readable

• Replace tab characters by 2 spaces (use 2 as the tab stop interval)

• Avoid breaking <a> (or <dfn>) text content across line breaks (note this is an exception to the above 100 character line-wrap best-practice). E.g., prefer:

  here is a
  <a>link that is not broken across lines</a>
  making it easy to search/replace :)

  vs.

  here is a <a>link that is sadly broken across
  lines</a> making it much harder to search/replace

• Use bikeshed definition list syntax where possible. E.g., prefer:

  ```bikeshed
  : define term
  :: term's definition
  ```
  vs.
  
  ```html
  <dl>
    <dt>define term</dt>
    <dd>term's definition</dd>
  </dl>
  ```
  (unless the `<dl>` needs a class attribute for styling i.e., `<dl class="domintro">`)
  

• Prefer markdown syntax for its brevity and readability. In particular:

  ```markdown
  * unordered list item
  ```  
  vs.
  
  ```html
  <ul>
    <li>unordered list item</li>
  </ul>
  ```
  ----
  
  ```markdown
  1. ordered list item
  ```
  vs.
  
  ```html
  <ol>
    <li>ordered list item</li>
  </ol>
  ```
  ----
  
  ```markdown
  newline separator
  
  between paragraphs
  ```
  vs.
  
  ```html
  <p>newline separator</p>
  
  <p>between paragraphs</p>
  ```
  

Contributing to this Repository

Use the standard fork, branch, and pull request workflow to propose changes to the specification. Please make branch names informative - by including the issue or bug number for example.

Please read CONTRIBUTING.md, about licensing contributions.

To make changes to the specification:

1. Edit single-page.bs (or one of the include files it references) in the master branch. Do not edit the HTML files in the gh-pages branch. These are built automatically.
2. Edit the Acknowledgements section in the master branch to include your name.
3. Ideally run bikeshed on single-page.bs to make sure there are no errors (run bikeshed spec).
4. Create a pull request but do not include the single-page.html file
5. When the editors merge and commit your pull request Travis-CI will build the HTML files

The following considerations should be kept in mind when making a pull request:

• Editorial changes that improve the readability of the spec or correct spelling or grammatical mistakes are welcome.
• Ideally new features should be proposed in a new specification and not as additions to the HTML spec. The Web Platform WG charter requires that the WG only adopt new proposals after they have been through an incubation phase. Please consider the WICG's Intent to Migrate template when proposing new features.
• Normative changes to the spec should aim to improve interoperability amongst browsers. Such changes should be accompanied by a test case to show that the change does this. It may also include links to bug trackers for browsers showing that there is an intent to adopt the new behaviour.
• Normative changes to the spec should be associated with a bug or issue that describes the reason for the change.

HTML branching and versioning

The master branch of this repository always contains the work in progress version of the HTML specification. This branch always welcomes substantive and editorial changes and pull requests.

The master branch is always exposed at https://www.w3.org/TR/html/.

Once a year, the HTML editors create a new <version> branch for the HTML specification. It only contains features that the Working Group believes can be shipped as part of the W3C Recommendation. That branch becomes associated with a specific version of the HTML specification. For a limited period of time, the Editor Team only accepts editorial changes or removal of features at risks in this branch. It becomes frozen once that version of HTML becomes a W3C Recommendation. Unless you're targetting a specific version of HTML (and really, you shouldn't), pull requests MUST always be made against the master branch.

The <version> branches are exposed as /TR/html<version>/ .

Old HTML repository

The old HTML repo is available for archival purposes.