Refresh Manual of Style into a more canonical ReSpec document#407
Refresh Manual of Style into a more canonical ReSpec document#407
Conversation
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.
|
Enabling PR Preview here would make it easier for people to review. |
PR Preview only works for a single spec per repository, but then the Manual of Style is the only spec in the guidebook. This also fixes the link to ReSpec (needs to be called with `defer` instead of `async`).
|
Thanks @tidoust ! |
|
PR Preview is not going to work for this specific PR. In the meantime, here's a (dynamically generated) diff. Note: The diff tool seems to force new lines in some of |
nigelmegitt
left a comment
nigelmegitt
left a comment
There was a problem hiding this comment.
Looks good to me - there are I think 3 places (I commented on 2 of them) where it might be a good idea to include a direct link to a referenced document, including a fragment ID, to get to the intended section, rather than specifying in text a section number, which might be more likely to change over time. But it's not a big deal.
| <li>Choose examples that reflect a global audience. For example: | ||
| <ul> | ||
| <li>When creating user stories or other examples that feature people, choose example names that come from different cultures and regions. You can find suggestions <a href="https://www.w3.org/TR/international-specs/#personal_name_examples">here</a> in [[INTERNATIONAL-SPECS]].</li> | ||
| <li>When creating user stories or other examples that feature people, choose example names that come from different cultures and regions. You can find <a data-cite="INTERNATIONAL-SPECS#personal_name_examples">example names</a> in [[[INTERNATIONAL-SPECS]]] ([[INTERNATIONAL-SPECS]], section 10.3.5).</li> |
There was a problem hiding this comment.
Any reason not to link to the fragment id, i.e. in full https://www.w3.org/TR/international-specs/#personal_name_examples ?
| Document</a></cite> ([<cite><a href="#ref-PROCESS">PROCESS</a></cite>] | ||
| section 6.3.11) for instructions on modifying a W3C Recommendation.</p> | ||
| <p>See the [[[W3C-PROCESS]]] ([[W3C-PROCESS]], section 6.3.10) | ||
| for instructions on modifying a W3C Recommendation.</p> |
There was a problem hiding this comment.
Again, using a fragment ID would probably make this less brittle - in this case the full URL would be https://www.w3.org/policies/process/#revising-rec
|
modulo the comments from @nigelmegitt , this looks fine to me. |
3 participants
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:
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.