@@ -7,19 +7,19 @@ To that end, here are some style guidelines for writing or modifying rulesets.
77They are intended to help and simplify in places where choices are ambiguous,
88but like all guidelines they can be broken if the circumstances require it.
99
10- Avoid using the left-wildcard (" & lt ; target host='* .example.com'& gt ; " ) unless
10+ Avoid using the left-wildcard (` < target host='*.example.com' /> ` ) unless
1111you intend to rewrite all or nearly all subdomains. Many rules today specify
1212a left-wildcard target, but the rewrite rules only rewrite an explicit list
1313of hostnames.
1414
15- Instead, prefer listing explicit target hosts and a single rewrite from "^http:" to
16- "^https:". This saves you time as a ruleset author because each explicit target
15+ Instead, prefer listing explicit target hosts and a single rewrite from ` "^http:" ` to
16+ ` "^https:" ` . This saves you time as a ruleset author because each explicit target
1717host automatically creates an implicit test URL, reducing the need to add your
1818own test URLs. These also make it easier for someone reading the ruleset to figure out
1919which subdomains are covered.
2020
2121If you know all subdomains of a given domain support HTTPS, go ahead and use a
22- left-wildcard, along with a plain rewrite from "^http:" to "^https:". Make sure
22+ left-wildcard, along with a plain rewrite from ` "^http:" ` to ` "^https:" ` . Make sure
2323to add a bunch of test URLs for the more important subdomains. If you're not
2424sure what subdomains might exist, you can iteratively use google queries and enumerate
2525the list of results like such:
@@ -31,16 +31,16 @@ the list of results like such:
3131... and so on.
3232
3333If there are a handful of tricky subdomains, but most subdomains can handle the
34- plain rewrite from "^http:" to "^https:", specify the rules for the tricky
34+ plain rewrite from ` "^http:" ` to ` "^https:" ` , specify the rules for the tricky
3535subdomains first, and then then plain rule last. Earlier rules will take
3636precedence, and processing stops at the first matching rule. There may be a tiny
3737performance hit for processing exception cases earlier in the ruleset and the
3838common case last, but in most cases the performance issue is trumped by readability.
3939
40- Avoid regexes with long strings of subdomains, e.g. & lt ; rule
41- from="^http://(foo|bar|baz|bananas).example.com" /& gt ; . These are hard to read and
40+ Avoid regexes with long strings of subdomains, e.g. `< rule
41+ from="^http://(foo|bar|baz|bananas).example.com" />` . These are hard to read and
4242maintain, and are usually better expressed with a longer list of target hosts,
43- plus a plain rewrite from "^http:" to "^https:".
43+ plus a plain rewrite from ` "^http:" ` to ` "^https:" ` .
4444
4545Prefer dashes over underscores in filenames. Dashes are easier to type.
4646
@@ -80,30 +80,29 @@ Here is an example ruleset pre-style guidelines:
8080
8181 <rule from="^http://((?:developers|html-differences|images|resources|\w+\.spec|wiki|www)\.)?whatwg\.org/"
8282 to="https://$1whatwg.org/" />
83-
8483</ruleset>
8584```
8685
8786Here is how you could rewrite it according to these style guidelines, including
8887test URLs:
88+
8989```
9090<ruleset name="WHATWG.org">
91- <target host="whatwg.org" />
92- <target host="developers.whatwg.org" />
93- <target host="html-differences.whatwg.org" />
94- <target host="images.whatwg.org" />
95- <target host="resources.whatwg.org" />
96- <target host="*.spec.whatwg.org" />
97- <target host="wiki.whatwg.org" />
98- <target host="www.whatwg.org" />
99-
100- <test url="http://html.spec.whatwg.org/" />
101- <test url="http://fetch.spec.whatwg.org/" />
102- <test url="http://xhr.spec.whatwg.org/" />
103- <test url="http://dom.spec.whatwg.org/" />
104-
105- <rule from="^http:"
106- to="https:" />
107-
91+ <target host="whatwg.org" />
92+ <target host="developers.whatwg.org" />
93+ <target host="html-differences.whatwg.org" />
94+ <target host="images.whatwg.org" />
95+ <target host="resources.whatwg.org" />
96+ <target host="*.spec.whatwg.org" />
97+ <target host="wiki.whatwg.org" />
98+ <target host="www.whatwg.org" />
99+
100+ <test url="http://html.spec.whatwg.org/" />
101+ <test url="http://fetch.spec.whatwg.org/" />
102+ <test url="http://xhr.spec.whatwg.org/" />
103+ <test url="http://dom.spec.whatwg.org/" />
104+
105+ <rule from="^http:"
106+ to="https:" />
108107</ruleset>
109-
108+ ```
0 commit comments