Write a style guide about html HOT 23 CLOSED

CONTRIBUTING.md or STYLE.md

Note: Having a file named CONTRIBUTING.md brings a minor benefit: "whenever someone opens a pull request or creates an issue, they will see a link to that file".

from html.

This would be great, but if anyone would write a format.py that just enforces all the style that we care about, we could save a lot of time pointing at the style guideline. At least I love it when code projects do this, as it takes away focus from something fundamentally uninteresting.

from html.

Let's try to write things down that we know of so far:

• 100 chars, 1 character indent
• Citations generally reference the specification by name in the sentence, then use the ref syntax at the end, after the period at the end of the paragraph. Example: The File API uses this to release <code data-x="blob protocol">blob:</code> URLs. <ref spec=FILEAPI>
  • Do we use cite around spec names? Only sometimes... I guess we should try to do so in general though going forward.
• Wrap sections that are not relevant to developers in elements marked with w-nodev. A <div w-nodev> ... </div> will do for multiple elements in a row.
• To add new references, follow the pattern at the end of the file, and be sure to place them in the alphabetized position. Prefer living documents or editor's drafts to dead specs, and prefer HTTPS to HTTP URLs.
• Add some guidance about Bikeshed and Shepherd and data-noexport and such?

What else has caught people out?

from html.

• When wrapping lines, no effort is made to keep elements or attributes on the same line, i.e. one should break between attributes and in the middle of an attribute value if that is what maximizes the line length. (Anything more clever is harder to write a script for, too.)

from html.

• When an opening tag is not followed by whitespace, all of its children are wrapped together and not indented further even if on multiple lines. (Relevant because Emacs will want to indent the lines more.)

from html.

• 's for possessive (always, even when it looks unnatural to you)
• bitrate (not bit-rate)
• whitespace (not white-space or white space)

from html.

Ugh, the W3C style guide is apparently clear that the preferred spelling is "white space". Would be cool if HTML's styleguide was consistent.

from html.

Pending resolution of #654, stick with en-GB-hixie.

from html.

@tabatkins it seems that's not really followed, though, e.g. css-syntax has 46 "whitespace" and 2 "white space"...

from html.

I knew you'd bring up Syntax. ^_^ Yes, I'm not following it very well in that spec, but @fantasai can point you to the style-guide requiring "white space".

from html.

HTML currently uses "whitespace" a lot and "white space" only in a few examples. Encoding uses "whitespace" and DOM imports that.

So I'd prefer to stick with whitespace, of course mostly because it happens to match what I'm used to.

from html.

Yeah, English removes spaces and hyphens over time. Wherever that's likely to happen, we should stick with the term English likely ends up with, thus, "whitespace", not "white space" or "white-space". And ideally we do this before implementations ship something (see "fullscreen").

from html.

I'm quite familiar with the evolution of English terms, and am fine with either ab initio. I was just pointing out that the W3C styleguide recommends one particular form.

from html.

Pointing at style guide, as requested: https://www.w3.org/2001/06/manual/#Terms
(I don't have an opinion on this. But consistency seems like a nice goal.)

from html.

I don't really see a need for consistency between standards orgs.

from html.

Other things that have come up recently:

• colorspace (not color space)
• metadata (not meta data)

from html.

It will affect auto-cross-linking in some cases, so that might be something worth considering.

from html.

Created https://wiki.whatwg.org/wiki/Style as a start.

from html.

In https://codereview.chromium.org/2492733003/ web vs. Web came up and I notice DOM and HTML disagree.

from html.

https://en.wikipedia.org/wiki/World_Wide_Web is very confused on when to capitalize it and when not. Seems easier to me to just lowercase it, but some people really care about the distinction between "web" and "Web", and "internet" and "Internet".

from html.

FWIW, I also like to lowercase it, but then I'm Swedish and we capitalize less than many languages.

from html.

• Use Oxford comma. (#2111 (comment))

from html.

Added web to https://wiki.whatwg.org/wiki/Style. Going to close this since we have a style guide now. We might move it to whatwg.org at some point in the future I suppose.

from html.