use of modal verbs in Guidelines

[TEITechnicalCouncil]

Lou noted at https://sourceforge.net/p/tei/bugs/287/#c52c that we commonly use "should" for things that are "highly recommended/mandatory". First of all, I find "highly recommended" and "mandatory" to be quite different things: in my opinion, if you go against a practice, the former would still validate according to a schema, whereas the latter would not.

But more to the point, I think we should fully embrace the use of modal verbs and constructions as in BCP 14: http://tools.ietf.org/html/bcp14

This means searching through the Guidelines for modal verbs and constructions, reading each one in context, and determining whether to fix it. A huge project.

If we accept this, we should add a reference to this RFC document to http://www.tei-c.org/Activities/Council/Working/tcw24.xml .

Original comment by: @kshawkin

[TEITechnicalCouncil]

This issue was originally assigned to SF user: jcummings Current user is: jamescummings

[TEITechnicalCouncil]

Council decided that Kevin will add the reference to the RFC in tcw24 and fix the usage at https://sourceforge.net/p/tei/bugs/287/#c52c . I will also check for passage in the introduction to the Guidelines on "how to read these Guidelines" and add a link to the RFC there as well.

Original comment by: @kshawkin

[TEITechnicalCouncil]

• assigned_to: Kevin Hawkins

Original comment by: @kshawkin

[TEITechnicalCouncil]

Implemented main changes at http://sourceforge.net/p/tei/code/12525/ , linking to BCP 14 (the stable identifier) instead of RFC 2119 (which could be superseded). Still need to scour the Guidelines for modal constructions to verify that they conform to BCP 14.

Original comment by: @kshawkin

[TEITechnicalCouncil]

• status: open --> pending-later
• Priority: 5 --> 1(low)

Original comment by: @kshawkin

[TEITechnicalCouncil]

There's a typo in what I introduced in r12525.

Original comment by: @kshawkin

[TEITechnicalCouncil]

Commented out that paragraph for now. It doesn't seem useful, certainly at this point in the chapter. The Guidelines don't use modal verbs as precisely as IETF specifications, as the rest of the lengthy discussion in this chapter surely makes clear.

Original comment by: @lb42

[TEITechnicalCouncil]

• Description has changed:

Diff:

--- old
+++ new
@@ -1,4 +1,4 @@
-Lou noted at https://sourceforge.net/p/tei/bugs/287/#c52c that we commonly use "should" for things that are "highly recommended/mandatory".  First of all, I find "highly recommended" and "mandatory" to be quite different things: if you go against the practice, the former still validates according to a schema, whereas the latter does not.
+Lou noted at https://sourceforge.net/p/tei/bugs/287/#c52c that we commonly use "should" for things that are "highly recommended/mandatory".  First of all, I find "highly recommended" and "mandatory" to be quite different things: in my opinion, if you go against a practice, the former would still validate according to a schema, whereas the latter would not.

 But more to the point, I think we should fully embrace the use of modal verbs and constructions as in RFC 2119:

Original comment by: @kshawkin

[TEITechnicalCouncil]

• Description has changed:

Diff:

--- old
+++ new
@@ -1,8 +1,6 @@
 Lou noted at https://sourceforge.net/p/tei/bugs/287/#c52c that we commonly use "should" for things that are "highly recommended/mandatory".  First of all, I find "highly recommended" and "mandatory" to be quite different things: in my opinion, if you go against a practice, the former would still validate according to a schema, whereas the latter would not.

-But more to the point, I think we should fully embrace the use of modal verbs and constructions as in RFC 2119:
-
-http://www.ietf.org/rfc/rfc2119.txt
+But more to the point, I think we should fully embrace the use of modal verbs and constructions as in BCP 14: http://tools.ietf.org/html/bcp14

 This means searching through the Guidelines for modal verbs and constructions, reading each one in context, and determining whether to fix it.  A huge project.

Original comment by: @kshawkin

[TEITechnicalCouncil]

Since #ABTEI2 says "very few features are mandatory", chapter AB already allows that there are mandatory things in the Guidelines. The goal of my paragraph inserted into AB at http://sourceforge.net/p/tei/code/12525/ was to give a disclaimer that there are in fact instances in the Guidelines where we have written "should" for something is mandatory, despite what I (and I imagine others) would have expected even if we had never read RFC 2119. This seems to me like a useful statement to have, even if it's something that we would eventually remove once we clean things up.

Despite the agreement of Council in April 2013, should we leave out the paragraph in chapter AB and just trust that users will figure things out if they disregard a "should" statement but find that their document doesn't validate?

Original comment by: @kshawkin

[TEITechnicalCouncil]

If, as people keep telling me, the prose trumps the schema definitions, then it seems to me we should either be rigorous in our use of modals, or at the very least, explain that we are not being rigorous. It's mad to have something mandatory (per the schema) but expressed in the prose in a way that makes it seem optional, and then insist that the prose is king.

Original comment by: @martindholmes

[TEITechnicalCouncil]

Agreed to review use of "should" and turn any that are mandatory into "must"

Original comment by: @lb42

[TEITechnicalCouncil]

• status: pending-later --> pending
• assigned_to: Kevin Hawkins --> James Cummings
• Group: AMBER --> GREEN

Original comment by: @jamescummings

[jamescummings]

Since this is a periodic check, I'll go through large parts of more newly added prose and review our use of modal verbs again.

[jamescummings]

Went through and did some of this prior to release 3.4.0. For the record I was searching for case-insensitive use of (must|must not|should|should not|may|require|shall|shall not|recommend|optional|suggest)' got as far as end of 'CO'. I'll pick up from after CO after the release. (There are 4-5K hits to check.)

[ebeshero]

I'm appending this reference to this ancient ticket that we should try to resolve! https://www.rfc-editor.org/rfc/inline-errata/rfc2119.html