Refresh Manual of Style into a more canonical ReSpec document

[tidoust]

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.

[nigelmegitt]

Enabling PR Preview here would make it easier for people to review.

[nigelmegitt]

Thanks @tidoust !

[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 pre sections, they don't exist in either document.

[nigelmegitt]

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.

[nigelmegitt]

Any reason not to link to the fragment id, i.e. in full https://www.w3.org/TR/international-specs/#personal_name_examples ?

[tidoust]

Isn't that what is being done here already? The data-cite attribute is ReSpec's way of linking to a fragment (when the underlying term is not part of the cross-references database). Or should I drop in [[[INTERNATIONAL-SPECS]]], which introduces another link that may be more confusing than anything else?

[nigelmegitt]

I was thinking it would make sense to drop the ([[INTERNATIONAL-SPECS]], section 10.3.5) instead, since you're already linking to it in a more robust way.

[tidoust]

Ah, I don't disagree but then I'm also trying to make the Manual of Style follow its own guidelines ;) Citing a reference from within a document has "After the link, link to the reference in the references section, and indicate section, page, or whatever is useful for those when the link is unavailable (e.g., when printed)". That's what I'm trying to do here.

We may want to update that guideline, and/or improve the spec editing tools to better handle such references.

[nigelmegitt]

Agree, I think the important thing is to direct the reader to the most specific location possible in the document. Here, something like the following would seem to meet that Citing a reference guidance, though I'm not sure it's more elegant overall, so I agree the guidance might need to be updated:

Suggested change

	<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>
	<li>When creating user stories or other examples that feature people, choose example names that come from different cultures and regions. Further guidance is provided by [[[INTERNATIONAL-SPECS]]] in the section (<a data-cite="INTERNATIONAL-SPECS#personal_name_examples">Using personal names in examples</a>).</li>

[tidoust]

This does not "link to the reference in the references section". I guess I'm proposing to keep the reference consistent with other such references in the document for now, and revisit the guidance afterwards. Would that work?

[nigelmegitt]

Sorry, I don't use the [[[SPEC]]] notation much and misunderstood the Respec docs - I thought they would link to the references section. Sigh.

In that case, how about:

Suggested change

	<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>
	<li>When creating user stories or other examples that feature people, choose example names that come from different cultures and regions. Further guidance is provided by [[[INTERNATIONAL-SPECS]]] ([[INTERNATIONAL-SPECS]]) in the section (<a data-cite="INTERNATIONAL-SPECS#personal_name_examples">Using personal names in examples</a>).</li>

I think that matches the guidance now, and avoids the numbered section link.

[TallTed]

Hopefully clearing up one piece of common misunderstanding, which seems to stem from visual blurring of 2 vs 3 square brackets.

The [[[SPEC-NAME]]] notation (3 square brackets) gets rendered as the title of the document, with href to the document URI.

The [[SPEC-NAME]] notation (2 square brackets) gets rendered as the SPEC-NAME of the document, with href to the document cite in the references section.

[nigelmegitt]

Thanks @TallTed I discovered that through a local trial too. I can see why it's commonly misunderstood - there are two independent variables being controlled by one syntax tweak. It is not intuitive that the hrefs should point to different places in the way that they do.

[tidoust]

Hmm, why parentheses around the section name?

[nigelmegitt]

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

[tidoust]

I updated the link. These references remain brittle because ReSpec does not have a good way to link to section headings across specs for now (tracked in speced/respec#2708).

[plehegar]

modulo the comments from @nigelmegitt , this looks fine to me.