Update fp-019-term-stability.md

Addresses Chris M's suggestions

Author: nataled

principles/fp-019-term-stability.md

@@ -21,7 +21,7 @@ Recommendations and Requirements
 
 If changing a term definition would change its referents, then instead a new term MUST be created with a new IRI and the new definition. Minor changes to the definition for clarity, grammar, and/or proper punctuation that do not change the referents are permitted. What is considered a 'minor change' will likely need to be considered on a case-by-case basis; it is left to the ontology developers to decide. However, any feedback from users MUST be taken into account.
 
-Conditions under which a term must be deprecated according to this principle, or for which term deprecation should be considered, include:
+The creation of a new term/definition implies that the old term should possibly be deprecated/obsoleted. Conditions under which a term MUST be deprecated according to this principle, or for which term deprecation SHOULD be considered, include:
 
 1) The old textual definition misses its intended target. This includes cases where the term refers to non-existent referents (as might happen, for example, when new research reveals that the referent does not exist in reality).
 1) The original term definition is considered sufficiently “damaged” (too vague, too restrictive, too misused or too misunderstood).
@@ -37,24 +37,24 @@ Detailed procedures for obsoleting a term are described on the OBO Academy page
 1) Mark the term as obsolete
   - OWL format: Add an "owl:deprecated" annotation property with value of "true^xsd:boolean"
   - OBO format: Add an "is_obsolete: true" tag
-2) Prepend the string "obsolete " (including the space) to the term label
+2) Prepend the string "obsolete " (including the space) to the term label <i>and</i> the `editor preferred term` (IAO:0000111), if present
   - NOTE: To be consistent with [Principle 12](https://obofoundry.org/principles/fp-012-naming-conventions.html) "Naming Conventions", the syntax/format MUST be precisely as given above (that is, the exact string as shown, lowercase and space included, with no other punctuation before or after). Thus, the following are disallowed: "Obsolete {label}", "obsolete_{label}", "OBSOLETE {label}" (and variations thereof).
 3) Remove all existing logical axioms from the term
-4) Remove or replace all usages of the term elsewhere in the ontology
+4) Remove or replace all usages of the term elsewhere in the ontology. For example, if an ontology has A part-of B, and B has been deprecated with replacement by C, then the corrected axiom would be A part-of C. Likewise, if A part-of B, and B part-of C, if B is deprecated, then any part-of axiom involving B MUST be removed; that is, by stating instead A part-of C.
 
 It is not necessary (and not advisable) to delete the textual definition.
 
 <i><b>To obsolete a term, the ontology developer</b></i> SHOULD:
 1) Indicate any exact term replacement:
-   -  OWL: Use the "term replaced by" annotation property from OMO ([IAO:0100001](http://purl.obolibrary.org/obo/IAO_0100001)) with the value set to the IRI of the relevant term
-   -  OBO: Use the "replaced_by:" tag with the value set to the CURIE of the relevant term
+   -  OWL: Use the `term replaced by` annotation property from OMO ([IAO:0100001](http://purl.obolibrary.org/obo/IAO_0100001)) with the value set to the IRI of the relevant term
+   -  OBO: Use the `replaced_by:` tag with the value set to the CURIE of the relevant term
 2) Indicate any inexact term replacements:
-   -  OWL: Use the "oboInOwl:consider" annotation property with the value set to the full IRI(s) of the relevant term(s)
+   -  OWL: Use the `oboInOwl:consider` annotation property with the value set to the full IRI(s) of the relevant term(s)
 ```
    <oboInOwl:consider rdf:resource="http://purl.obolibrary.org/obo/OBI_0001544")>
 ``` 
 
-   -  OBO: Use the "consider:" tag with the value set to the CURIE(s) of the relevant term(s)
+   -  OBO: Use the `consider:` tag with the value set to the CURIE(s) of the relevant term(s)
 ```
    consider: OBI:0001544
 ```
@@ -68,8 +68,8 @@ Note that some older implementations in OWL used the CURIE method as shown below
 
 1) Prepend the string "OBSOLETE. " (this precise string, including the space) to the term definition. NOTE: This MUST be implemented consistently. That is, if applied at all, it has to be applied to every obsoleted term definition.
 2) Indicate the reason(s) for obsoleting:
-  -  OWL: Use the "has obsolescence reason" annotation property from OMO ([IAO:0000231](http://purl.obolibrary.org/obo/IAO_0000231)) with the value set to the IRI of one of the individuals of the "obsolescence reason specification" term [IAO:0000225](http://purl.obolibrary.org/obo/IAO_0000225). See below for example.
-  -  OBO: Use "relationship:" with the CURIE for the annotation property (IAO:0000231) and a CURIE for the specific reason (an individual from the "obsolescence reason specification" term [IAO:0000225](http://purl.obolibrary.org/obo/IAO_0000225)). See below for example. Note that older implementations often used alternative methods (described after the examples). These methods are still valid, but are not preferred.
+  -  OWL: Use the `has obsolescence reason` annotation property from OMO ([IAO:0000231](http://purl.obolibrary.org/obo/IAO_0000231)) with the value set to the IRI of one of the individuals of the "obsolescence reason specification" term [IAO:0000225](http://purl.obolibrary.org/obo/IAO_0000225). See below for example.
+  -  OBO: Use `relationship:` with the CURIE for the annotation property (IAO:0000231) and a CURIE for the specific reason (an individual from the "obsolescence reason specification" term [IAO:0000225](http://purl.obolibrary.org/obo/IAO_0000225)). See below for example. Note that older implementations often used alternative methods (described after the examples). These methods are still valid, but are not preferred.
 
 Examples
 -------
@@ -98,10 +98,10 @@ relationship: IAO:0000231 IAO:0000227
 is_obsolete: true
 replaced_by: OBI:0001544
 ```
-For OBO format, there are multiple alternatives:
-1) Use "property_value:" instead of "relationship:".
-1) Use a free text "comment:". 
-1) Use the annotation property label (with underscores) instead of the CURIE "IAO:0000231", and the obsolescence reason label instead of the relevant CURIE. Note that the underscore version of the property label will need to be created in the ontology:
+Obsolescence reasons have, historically, been indicated multiple ways. In addition to the preferred methods shown above, the following alternatives are in current use:
+1) As a free text comment (`rdfs:comment` in OWL or `comment:` in OBO). 
+1) In OBO format, using a `property_value:` tag instead of a `relationship:` tag.
+1) In OBO format, using an annotation property label-as-identifier (with underscores) instead of the CURIE `IAO:0000231`, and the obsolescence reason label instead of the relevant CURIE. Note that the underscore version of the property label will need to be created in the ontology:
 ```
 [Typedef]
 id: has_obsolescence_reason
@@ -127,8 +127,8 @@ Criteria for review
 -------
 
 The OBO Dashboard will show:
-- An ERROR if any obsolete term (that is, a term with an "owl:deprecated" property or "is_obsolete: true" tag) does not also have 'obsolete ' (that exact string, lowercase and space included, with no other punctuation) prepended to the label
-- An ERROR if any obsolete term (as indicated by term label or definition) lacks an "owl:deprecated" property or "is_obsolete: true" tag
+- An ERROR if any obsolete term (that is, a term with an `owl:deprecated` property or `is_obsolete: true` tag) does not also have 'obsolete ' (that exact string, lowercase and space included, with no other punctuation) prepended to the label
+- An ERROR if any obsolete term (as indicated by term label or definition) lacks an `owl:deprecated` property or `is_obsolete: true` tag
 - An ERROR if an obsolete term has, itself, any logical axioms (including any subClassOf/is_a declarations) or if it is referenced by logical axioms from other terms
 - A WARN if there is at least one term with 'OBSOLETE. ' prepended to the definition but not all obsolete terms are likewise prepended