From 7456af16c96f18cabe74bd85be7c174f87670b07 Mon Sep 17 00:00:00 2001 From: Francois Daoust Date: Thu, 26 Feb 2026 22:57:58 +0100 Subject: [PATCH 1/2] Refresh Manual of Style into a more canonical ReSpec document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ReSpec offers various features that the Manual of Style wasn't using or was using inconsistently. In particular, the document used a mix of hardcoded references and references handled by ReSpec (through Specref), leading to multiple "References" appendices, which were confusing. This update is meant to be editorial in nature, although I had to drop some materials that is no longer current as part of the refresh. Changes it introduces: - Replaced hardcoded list of references with actual references, using local biblio for entries that are not known to Specref. I refreshed the entries where appropriate. - Dropped the External links appendix, which seemed counter-productive and conflicting with the list of references for no good reason. - Turned non inline examples into actual example blocks. - Turned notes into actual note blocks. - Turned normative statements into informative ones as the document is informative in essence... or it would benefit from a more substantive rewrite). Also made sure to flag occurrences of RFC 2119 so that ReSpec doesn't interpret them as such (using HTML comments, coz' c'est comme ça). This helped silence remaining ReSpec warning about the missing conformance section. As far as I can tell, Pubrules no longer has any TR template. I dropped that part. I also dropped mentions of services that no longer exist, including BIB-EXTRACT and Excalibur. --- manual-of-style/index.html | 650 ++++++++++++++----------------------- 1 file changed, 251 insertions(+), 399 deletions(-) diff --git a/manual-of-style/index.html b/manual-of-style/index.html index 6608e931..bf52e64d 100644 --- a/manual-of-style/index.html +++ b/manual-of-style/index.html @@ -29,7 +29,147 @@ href: 'https://lists.w3.org/Archives/Public/spec-prod/' }] }], - xref: [ "i18n-glossary" ] + xref: [ "i18n-glossary" ], + localBiblio: { + "CHECKLINK": { + title: "W3C Link Checker", + href: "https://validator.w3.org/checklink", + publisher: "W3C" + }, + "CHICAGO": { + title: "The Chicago Manual of Style", + href: "https://www.chicagomanualofstyle.org/home.html", + publisher: "The University of Chicago" + }, + "CLICK-HERE": { + href: "https://www.w3.org/QA/Tips/noClickHere", + title: "Don't use \"click here\" as link text", + authors: [ + "Aaron Swartz" + ], + publisher: "W3C Quality Assurance Activity", + date: "2001" + }, + "CSSVALIDATE": { + title: "W3C CSS Validation Service", + href: "https://jigsaw.w3.org/css-validator/", + publisher: "W3C" + }, + "GREGG": { + title: "The Gregg Reference Manual", + href: "https://www.mheducation.ca/product/the-gregg-reference-manual-9781264928033-can-group", + authors: [ + "William A. Sabin", + "Linda C. Gardner", + "G. Wendy Strashok" + ], + publisher: "McGraw Hill" + }, + "I18N-GUIDELINES": { + title: "Editorial guidelines for i18n docs", + href: "https://www.w3.org/International/i18n-activity/guidelines/editing" + }, + "IPRFAQ": { + href: "https://www.w3.org/copyright/intellectual-rights/", + title: "Intellectual Property FAQ", + publisher: "W3C", + date: "2024" + }, + "ISPELL": { + href: "https://www.cs.hmc.edu/~geoff/ispell.html", + title: "International Ispell", + authors: [ + "G. Kuenning et al." + ] + }, + "M-W": { + href: "https://www.merriam-webster.com/", + title: "Merriam-Webster's Collegiate Dictionary, Twelfth Edition", + publisher: "Merriam-Webster", + date: "2025" + }, + "PERSISTENCE": { + title: "Persistence Policy", + href: "https://www.w3.org/policies/uri-persistence/", + authors: [ + "T. Berners-Lee" + ], + publisher: "W3C", + date: "1999" + }, + "PLURAL": { + href: "http://xml.coverpages.org/properSpellingForPluralOfDTD.html", + title: "Infrequently Asked Questions Concerning the Proper Spelling of 'DTD' in its Plural Form", + authors: [ + "R. Cover" + ], + date: "Updated 4 January 2001 or later" + }, + "PUBRULES": { + title: "Technical Report Publication Policy", + href: "https://www.w3.org/pubrules/doc", + authors: [ + "The W3C Team" + ], + publisher: "W3C" + }, + "REGISTER-1": { + title: "Register an Internet Media Type for a W3C Specification", + href: "https://www.w3.org/guide/editor/mediatypes", + authors: [ + "Philippe le Hégaret" + ], + date: "2019" + }, + "REGISTER-2": { + title: "TAG Position on Use of Unregistered Media Types in W3C Recommendations", + href: "https://lists.w3.org/Archives/Public/www-tag/2006Aug/0012", + authors: [ + "N. Mendelsohn" + ], + date: "4 August 2006" + }, + "SPEC-PROD": { + title: "Public archives of the spec-prod@w3.org mailing-list", + href: "https://lists.w3.org/Archives/Public/" + }, + "STYLE-GUIDE": { + title: "Style Guide for Online Hypertext", + href: "https://www.w3.org/Provider/Style/", + authors: [ + "T. Berners-Lee" + ], + publisher: "W3C", + date: "1992-1998" + }, + "TITLES": { + title: "Please use titles, not addresses, as link text", + href: "https://lists.w3.org/Archives/Public/www-html-editor/2000JanMar/0103", + authors: [ + "D. Connolly" + ], + date: "10 February 2000" + }, + "TR": { + title: "W3C standards and drafts", + href: "https://www.w3.org/TR/", + publisher: "W3C" + }, + "TRANSLATE": { + title: "Translations at W3C", + href: "https://www.w3.org/Consortium/Translation/", + publisher: "W3C" + }, + "VALIDATE": { + title: "W3C Markup Validation Service", + href: "https://validator.w3.org/", + publisher: "W3C" + }, + "WCAG-Overview": { + title: "WCAG 2 Overview", + href: "https://www.w3.org/WAI/standards-guidelines/wcag/" + } + } }; @@ -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

-

Note. It is the editor's responsibility to ensure +

It is the editor's responsibility to ensure that documents are valid before requesting publication.

Accessibility

@@ -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.