From aec4ccfe4b0e115820f82e9c632fbe80861849d8 Mon Sep 17 00:00:00 2001 From: Tony Ruscoe Date: Wed, 12 Jan 2022 16:56:30 +0000 Subject: [PATCH] Update format for numbered sections and whitespace --- htmlcssguide.html | 151 +++++++++++++++++++++++----------------------- javaguide.css | 29 +++++++++ 2 files changed, 105 insertions(+), 75 deletions(-) diff --git a/htmlcssguide.html b/htmlcssguide.html index 43c29e4..7421739 100644 --- a/htmlcssguide.html +++ b/htmlcssguide.html @@ -11,7 +11,7 @@

Google HTML/CSS Style Guide

-

1 Background

+

Background

This document defines formatting and style rules for HTML and CSS. It aims at improving collaboration, code quality, and enabling supporting infrastructure. @@ -19,17 +19,16 @@ It applies to raw, working files that use HTML and CSS, including GSS files. Tools are free to obfuscate, minify, and compile as long as the general code quality is maintained.

-

2 General

+

General

-

2.1 General Style Rules

+

General Style Rules

-

2.1.1 Protocol

+

Protocol

Use HTTPS for embedded resources where possible.

-

Always use HTTPS (https:) for images and other media -files, style sheets, and scripts, unless the respective files are not available -over HTTPS.

+

Always use HTTPS (https:) for images and other media files, style sheets, and +scripts, unless the respective files are not available over HTTPS.

<!-- Not recommended: omits the protocol -->
 <script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
@@ -53,9 +52,9 @@ over HTTPS.

 @import 'https://fonts.googleapis.com/css?family=Open+Sans';
-

2.2 General Formatting Rules

+

General Formatting Rules

-

2.2.1 Indentation

+

Indentation

Indent by 2 spaces at a time.

@@ -72,7 +71,7 @@ over HTTPS.

} -

2.2.2 Capitalization

+

Capitalization

Use only lowercase.

@@ -96,7 +95,7 @@ color: #E5E5E5; color: #e5e5e5; -

2.2.3 Trailing Whitespace

+

Trailing Whitespace

Remove trailing white spaces.

@@ -110,9 +109,9 @@ color: #e5e5e5; <p>Yes please. -

2.3 General Meta Rules

+

General Meta Rules

-

2.3.1 Encoding

+

Encoding

Use UTF-8 (no BOM).

@@ -123,10 +122,10 @@ mark.

charset="utf-8">. Do not specify the encoding of style sheets as these assume UTF-8.

-

(More on encodings and when and how to specify them can be found in Handling -character encodings in HTML and CSS.)

+

(More on encodings and when and how to specify them can be found in +Handling character encodings in HTML and CSS.)

-

2.3.2 Comments

+

Comments

Explain code as needed, where possible.

@@ -137,7 +136,7 @@ why is respective solution used or preferred?

demand fully documented code. Mileage may vary heavily for HTML and CSS code and depends on the project’s complexity.)

-

2.3.3 Action Items

+

Action Items

Mark todos and action items with TODO.

@@ -160,11 +159,11 @@ depends on the project’s complexity.)

</ul> -

3 HTML

+

HTML

-

3.1 HTML Style Rules

+

HTML Style Rules

-

3.1.1 Document Type

+

Document Type

Use HTML5.

@@ -174,21 +173,19 @@ depends on the project’s complexity.)

application/xhtml+xml, lacks both browser and infrastructure support and offers less room for optimization than HTML.)

-

Although fine with HTML, do not close void elements, i.e. write <br>, not -<br />.

+

Although fine with HTML, do not close void elements, i.e. write <br>, not <br +/>.

-

3.1.2 HTML Validity

+

HTML Validity

Use valid HTML where possible.

Use valid HTML code unless that is not possible due to otherwise unattainable performance goals regarding file size.

-

- -Use tools such as the W3C HTML validator -to test. -

+

Use tools such as the +W3C HTML validator +to test.

Using valid HTML is a measurable baseline quality attribute that contributes to learning about technical requirements and constraints, and that ensures proper @@ -206,7 +203,7 @@ HTML usage.

<article>This is only a test.</article> -

3.1.3 Semantics

+

Semantics

Use HTML according to its purpose.

@@ -225,7 +222,7 @@ code efficiency reasons.

<a href="recommendations/">All recommendations</a> -

3.1.4 Multimedia Fallback

+

Multimedia Fallback

Provide alternative contents for multimedia.

@@ -249,7 +246,7 @@ no alternative text, as in alt="".)

<img src="spreadsheet.png" alt="Spreadsheet screenshot."> -

3.1.5 Separation of Concerns

+

Separation of Concerns

Separate structure from presentation from behavior.

@@ -292,13 +289,13 @@ templates than it is to update style sheets and scripts.

<p>It’s awesome! -

3.1.6 Entity References

+

Entity References

Do not use entity references.

There is no need to use entity references like &mdash;, &rdquo;, or -&#x263a;, assuming the same encoding (UTF-8) is used for files and editors -as well as among teams.

+&#x263a;, assuming the same encoding (UTF-8) is used for files and editors as +well as among teams.

The only exceptions apply to characters with special meaning in HTML (like < and &) as well as control or “invisible” characters (like no-break spaces).

@@ -311,12 +308,13 @@ The currency symbol for the Euro is &ldquo;&eur;&rdquo;. The currency symbol for the Euro is “€”. -

3.1.7 Optional Tags

+

Optional Tags

Omit optional tags (optional).

For file size optimization and scannability purposes, consider omitting optional -tags. The HTML5 specification +tags. The +HTML5 specification defines what tags can be omitted.

(This approach may require a grace period to be established as a wider guideline @@ -342,7 +340,7 @@ tags, not just a selection.)

<p>Qed. -

3.1.8 type Attributes

+

type Attributes

Omit type attributes for style sheets and scripts.

@@ -351,7 +349,8 @@ tags, not just a selection.)

Specifying type attributes in these contexts is not necessary as HTML5 implies text/css -and text/javascript +and +text/javascript as defaults. This can be safely done even for older browsers.

<!-- Not recommended -->
@@ -372,9 +371,9 @@ as defaults. This can be safely done even for older browsers.

 <script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
-

3.2 HTML Formatting Rules

+

HTML Formatting Rules

-

3.2.1 General Formatting

+

General Formatting

Use a new line for every block, list, or table element, and indent every such child element.

@@ -413,7 +412,7 @@ instead of an error.)

</table> -

3.2.2 HTML Line-Wrapping

+

HTML Line-Wrapping

Break long lines (optional).

@@ -443,7 +442,7 @@ additional spaces from the original line.

</md-progress-circular> -

3.2.3 HTML Quotation Marks

+

HTML Quotation Marks

When quoting attributes values, use double quotation marks.

@@ -458,28 +457,26 @@ values.

<a class="maia-button maia-button-secondary">Sign in</a> -

4 CSS

+

CSS

-

4.1 CSS Style Rules

+

CSS Style Rules

-

4.1.1 CSS Validity

+

CSS Validity

Use valid CSS where possible.

Unless dealing with CSS validator bugs or requiring proprietary syntax, use valid CSS code.

-

- -Use tools such as the W3C CSS validator -to test. -

+

Use tools such as the +W3C CSS validator +to test.

Using valid CSS is a measurable baseline quality attribute that allows to spot CSS code that may not have any effect and can be removed, and that ensures proper CSS usage.

-

4.1.2 ID and Class Naming

+

ID and Class Naming

Use meaningful or generic ID and class names.

@@ -513,7 +510,7 @@ document or template changes.

.alt {} -

4.1.3 ID and Class Name Style

+

ID and Class Name Style

Use ID and class names that are as short as possible but as long as necessary.

@@ -532,14 +529,15 @@ understandability and code efficiency.

.author {} -

4.1.4 Type Selectors

+

Type Selectors

Avoid qualifying ID and class names with type selectors.

Unless necessary (for example with helper classes), do not use element names in conjunction with IDs or classes.

-

Avoiding unnecessary ancestor selectors is useful for performance reasons.

+

Avoiding unnecessary ancestor selectors is useful for +performance reasons.

/* Not recommended */
 ul#example {}
@@ -551,11 +549,12 @@ div.error {}
 .error {}
-

4.1.5 Shorthand Properties

+

Shorthand Properties

Use shorthand properties where possible.

-

CSS offers a variety of shorthand +

CSS offers a variety of +shorthand properties (like font) that should be used whenever possible, even in cases where only one value is explicitly set.

@@ -578,7 +577,7 @@ font: 100%/1.6 palatino, georgia, serif; padding: 0 1em 2em; -

4.1.6 0 and Units

+

0 and Units

Omit unit specification after “0” values, unless required.

@@ -590,7 +589,7 @@ margin: 0; padding: 0; -

4.1.7 Leading 0s

+

Leading 0s

Omit leading “0”s in values.

@@ -599,7 +598,7 @@ padding: 0; 
font-size: .8em;
-

4.1.8 Hexadecimal Notation

+

Hexadecimal Notation

Use 3 character hexadecimal notation where possible.

@@ -614,7 +613,7 @@ color: #eebbcc; color: #ebc; -

4.1.9 Prefixes

+

Prefixes

Prefix selectors with an application-specific prefix (optional).

@@ -629,7 +628,7 @@ easier, for example in search and replace operations.

#maia-note {} /* Maia */ -

4.1.10 ID and Class Name Delimiters

+

ID and Class Name Delimiters

Separate words in ID and class names by a hyphen.

@@ -649,7 +648,7 @@ and scannability.

.ads-sample {} -

4.1.11 Hacks

+

Hacks

Avoid user agent detection as well as CSS “hacks”—try a different approach first.

@@ -663,9 +662,9 @@ resistance. That is, allowing and making it easy to use detection and hacks means using detection and hacks more frequently—and more frequently is too frequently.

-

4.2 CSS Formatting Rules

+

CSS Formatting Rules

-

4.2.1 Declaration Order

+

Declaration Order

Alphabetize declarations.

@@ -686,11 +685,12 @@ text-align: center; text-indent: 2em; -

4.2.2 Block Content Indentation

+

Block Content Indentation

Indent all block content.

-

Indent all block content, +

Indent all +block content, that is rules within rules as well as declarations, so to reflect hierarchy and improve understanding.

@@ -704,7 +704,7 @@ improve understanding.

} -

4.2.3 Declaration Stops

+

Declaration Stops

Use a semicolon after every declaration.

@@ -725,7 +725,7 @@ reasons.

} -

4.2.4 Property Name Stops

+

Property Name Stops

Use a space after a property name’s colon.

@@ -744,12 +744,13 @@ h3 { } -

4.2.5 Declaration Block Separation

+

Declaration Block Separation

Use a space between the last selector and the declaration block.

Always use a single space between the last selector and the opening brace that -begins the declaration block.

+begins the +declaration block.

The opening brace should be on the same line as the last selector in a given rule.

@@ -772,7 +773,7 @@ rule.

} -

4.2.6 Selector and Declaration Separation

+

Selector and Declaration Separation

Separate selectors and declarations by new lines.

@@ -793,7 +794,7 @@ h3 { } -

4.2.7 Rule Separation

+

Rule Separation

Separate rules by new lines.

@@ -809,7 +810,7 @@ body { } -

4.2.8 CSS Quotation Marks

+

CSS Quotation Marks

Use single ('') rather than double ("") quotation marks for attribute selectors and property values.

@@ -835,9 +836,9 @@ html { } -

4.3 CSS Meta Rules

+

CSS Meta Rules

-

4.3.1 Section Comments

+

Section Comments

Group sections by a section comment (optional).

diff --git a/javaguide.css b/javaguide.css index 10cd730..39a7bc6 100644 --- a/javaguide.css +++ b/javaguide.css @@ -570,3 +570,32 @@ li.toc_entry a { .toc td.two_columns { border-width: 0px; } + +/* Numbered sections */ + +h1 { + counter-reset: h2; +} + +h2.numbered { + counter-reset: h3; +} + +h3.numbered { + counter-reset: h4; +} + +h2.numbered::before { + content: counter(h2) ' '; + counter-increment: h2; +} + +h3.numbered::before { + content: counter(h2) '.' counter(h3) ' '; + counter-increment: h3; +} + +h4.numbered::before { + content: counter(h2) '.' counter(h3) '.' counter(h4) ' '; + counter-increment: h4; +}