diff --git a/.pr-preview.json b/.pr-preview.json
new file mode 100644
index 00000000..8abf307f
--- /dev/null
+++ b/.pr-preview.json
@@ -0,0 +1,4 @@
+{
+ "src_file": "manual-of-style/index.html",
+ "type": "respec"
+}
\ No newline at end of file
diff --git a/manual-of-style/index.html b/manual-of-style/index.html
index 6608e931..f412bc82 100644
--- a/manual-of-style/index.html
+++ b/manual-of-style/index.html
@@ -3,7 +3,7 @@
W3C Manual of Style
-
@@ -39,8 +179,7 @@
This manual is a guide containing best current practice, written for editors and authors of W3C technical reports. No requirements
for W3C publications are in this document. All requirements for W3C
-publications are in W3C
-Publication Rules.
+publications are in W3C [[[PUBRULES]]].
@@ -50,11 +189,9 @@
Introduction
Written for editors and authors of W3C technical reports, this
-document assumes that the reader is familiar with the Style Guide for Online
-Hypertext [STYLE-GUIDE]. It is a companion to the
-REQUIRED Technical Report Publication
-Policy [PUBRULES],
+document assumes that the reader is familiar with the
+[[[STYLE-GUIDE]]] [[STYLE-GUIDE]]. It is a companion to the
+mandatory [[[PUBRULES]]] [[PUBRULES]],
called "pubrules" for short. Following the advice in this manual has
benefits:
@@ -73,10 +210,7 @@
Introduction
reference material. Readability across a wide variety of browsers and
platforms is far more important than using jazzy features. At some
point, what we write becomes history and is preserved on the web
-through the W3C Persistence
-Policy [PERSISTENCE].
+through the W3C [[[PERSISTENCE]]] [[PERSISTENCE]].
Validation
@@ -84,36 +218,32 @@
Validation
Make sure there are no broken links in your documents at the time
of publication. Some services on the web may help you with this,
-including the W3C Link Checker [CHECKLINK]. Append ",checklink" to a W3C
+including the [[[CHECKLINK]]] [[CHECKLINK]]. Append ",checklink" to a W3C
URI to invoke the link
checker.
-
Make sure your technical report validates in the W3C Markup
-Validation Service [VALIDATE]. Append ",validate" to a W3C
+
Make sure your technical report validates in the [[[VALIDATE]]]
+ [[VALIDATE]]. Append ",validate" to a W3C
URI to invoke the
validator.
-
Make sure your technical report validates in the W3C
-CSS Validation
-Service [CSSVALIDATE]. Append ",cssvalidate" to a
+
Make sure your technical report validates in the [[[CSSVALIDATE]]]
+[[CSSVALIDATE]]. Append ",cssvalidate" to a
W3C URI to invoke the
CSS validator.
Make sure any examples in your document validate as well.
-
Note. It is the editor's responsibility to ensure
+
It is the editor's responsibility to ensure
that documents are valid before requesting publication.
Follow the [[[WCAG]]] [[WCAG]]. See also [[[WCAG-Overview]]]
+ [[WCAG-Overview]] for an introduction to the guidelines. Can
simpler words express your ideas? Is your text marked up with
structural elements? Are alternatives provided for auditory and visual
content? See also evaluation tools.
@@ -122,9 +252,9 @@
Accessibility
Internationalization
-
Follow the guidelines in Internationalization Best Practices for Spec Developers [[INTERNATIONAL-SPECS]] when producing your specification. You might also find it helpful to complete a self-review early in the development process. If your specification touches on more complex issues, you can also reach out to the Internationalization Working Group for guidance.
+
Follow the guidelines in [[[INTERNATIONAL-SPECS]]] [[INTERNATIONAL-SPECS]] when producing your specification. You might also find it helpful to complete a self-review early in the development process. If your specification touches on more complex issues, you can also reach out to the Internationalization Working Group for guidance.
-
Internationalization terminology, particularly terms related to Unicode, can be rather precise. To help avoid problems with the need to define these, import the [[Infra]] standard and [[I18N-GLOSSARY]]. Use the terms found in these documents instead of creating your own and link your use of these terms to the definitions found in these documents. Instructions on how to do this can be found in an appendix of the [[I18N-GLOSSARY]].
+
Internationalization terminology, particularly terms related to Unicode, can be rather precise. To help avoid problems with the need to define these, import the [[[Infra]]] [[Infra]] standard and [[[I18N-GLOSSARY]]] [[I18N-GLOSSARY]]. Use the terms found in these documents instead of creating your own and link your use of these terms to the definitions found in these documents. Instructions on how to do this can be found in an appendix of the [[[I18N-GLOSSARY]]].
Write for a global audience
@@ -135,7 +265,7 @@
Write for a global audience
Avoid idioms that are U.S.- or English-specific in favor of more descriptive language.
Choose examples that reflect a global audience. For example:
-
When creating user stories or other examples that feature people, choose example names that come from different cultures and regions. You can find suggestions here in [[INTERNATIONAL-SPECS]].
+
When creating user stories or other examples that feature people, choose example names that come from different cultures and regions. You can find example names in [[[INTERNATIONAL-SPECS]]] ([[INTERNATIONAL-SPECS]], section 10.3.5).
Choose more generic terms for field names, such as "postal code" instead of (U.S.-specific) "ZIP code" or "given name" instead of "first name".
In general, use [=locale-neutral=] representations of data values, such as dates, numbers, currency values, and so forth.
@@ -145,7 +275,7 @@
Write for a global audience
For time and date values, choose an unambiguous representation:
For date values that appear in prose, spell out the month (for example, 6 May 2003 or September 23, 2016). All numeric dates such as 5/6/03 or 6/5/03 are ambiguous. Some cultures will read the first example as "June 5" while other cultures will read the second example as that date.
-
For date values that appear in data, use a format derived from ISO8601, such as those found in [[RFC3339]] or those found in XML Schema Part 2: Datatypes ([[XMLSchema-2]]).
+
For date values that appear in data, use a format derived from [[ISO8601]], such as those found in [[[RFC3339]]] [[RFC3339]] or those found in XML Schema Part 2: Datatypes ([[XMLSchema-2]], section 3.2.9).
@@ -153,7 +283,9 @@
Write for a global audience
Unicode
-
Use U+XXXX syntax to represent [=Unicode code points=] in the specification. These are space separated when appearing in a sequence. No additional decoration is needed. Note that a [=code point=] may contain four, five, or six hexadecimal digits. When fewer than four digits are needed, the code point number is zero filled.
+
Use U+XXXX syntax to represent [=Unicode code points=] in the specification. These are space separated when appearing in a sequence. No additional decoration is needed.
+
+
A [=code point=] may contain four, five, or six hexadecimal digits. When fewer than four digits are needed, the code point number is zero filled.