OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Additional thoughts on normative vs non-normative content; formatting versus processing; RFC-2119 keywords

My two cents ...

Normative and non-normative content in a specification

All content in an OASIS specification is normative, with the exception of the following:

  • Introductions
  • Table of contents
  • Examples
  • Notes
  • Appendixes (unless marked as normative)
  • Content in structures other than those above that is explicitly marked "(Non-normative)

OASIS states this in several places, including the keyword guidelines.

Non-normative content is often called "informative," and is defined as "material that may help understand the standard or give examples of its use, but that [doesn't] have to be followed in order to implement the specification or standard."


I think of formatting as a type of rendering/processing that has to do with the presentation layer. It can be controlled by stylesheets or CSS. It is 100% implementation specific, although there are some common typographical conventions that typically apply, such as:

  • Bullets for list items in an unordered list
  • Numbers for list items in an ordered list
  • Placing subscripts and superscript below or above the line

For the DITA 2.0 spec, we have moved all such statements into "Formatting expectations" sections. I could easily be convinced that this content needs to be removed entirely.


I think of processing a bit more broadly than Eliot does. For me, this encompasses the following:

  • Resolution of keys, conrefs, and other DITA features than MUST happen in a particular way in order to yield the same results
  • Rendering of content in such a way to as reduce surprising results and ensure conformity across implementations. Here we make SHOULD statements such as the following:

    • Processors SHOULD render the content of the <shortdesc> element as the initial paragraph of the topic.

      When processors generate link previews that are based on the map context, they SHOULD use the content of
      the <shortdesc> that is located in the map rather than the <shortdesc> that is located in the DITA topic.
      However, processors SHOULD use the content of the <shortdesc> element in the DITA topic when they render
      the topic itself, unless the @copy-to attribute is specified on the topic reference to the element.

    • When used in conjunction with <fig> or <table> elements, processors SHOULD consider the content of a
      <desc> element to be part of the content flow.

      When used in conjunction with <xref> or <link> elements, processors MAY choose to render the content of a
      <desc> element as hover help.

Why do we want to make such SHOULD statements? We want OOB implementations of DITA to yield similar results. If application A renders short descriptions and application B does not, the output is quite dissimilar -- and perhaps the meaning is really changed. Ditto for the content of <desc> elements.

(Yes, the above statements about <desc> need some conditional processing to apply to LwDITA, which has neither <table> or <link> elements.)

For DITA 2.0, we have moved information about processing into "Processing expectations" sections. In the element reference topics, all statements that use RFC-2119 keywords should be in "Processing expectations" sections.

RFC-2119 keywords

The RFC-2119 keywords and what they mean is spelled out in the following topic; please note the meaning of MUST, SHOULD, and MAY:

OASIS elaborates on how Technical Committees should use keywords in the following document, an essential read for all specification editors:

RFC-2119 keywords should be tied into conformance statements.

Comments and discussion very welcome.


Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 622-1501; kriseberlein (skype)

On 2/11/2019 4:06 PM, Eliot Kimber wrote:

I did initially say this:

    - Eliot; processing expectations aren't normative, nor are formatting.

But subsequently was corrected and agreed with the correction that processing and formatting expectations are normative (where not within examples).

I try to make a clear distinction between processing and formatting, where by "processing" I mean data processing applied to the initial source as authored that results in the effective source reflecting the application of filtering, address resolution, and content reference resolution. 

Formatting is then everything that might then be done to the effective source to produce some deliverable, even if that formatting involves applying transforms to the effective source.  Because the end result is some specific deliverable it's all "formatting" from the point of view of the DITA specification. 

Processing requirements are normative and required ("MUST" statements). You cannot have a conforming DITA processor that does not resolve addresses in the way the DITA specification requires, if you do filtering you must produce the results required by the spec, etc., if you implement content reference resolution you must do it as the specification requires. 

Formatting *expectations* are (or can be) normative statements but are never MUST statements, only SHOULD statements, which gives them more weight than non-normative examples or suggestions would be and that's still an important distinction because SHOULD statements express the considered opinion and intent of the TC, while examples are just "here's a way you might do it if you feel like it."

I think I was conflating presentation expectations with examples (which are explicitly not normative). 


Eliot Kimber

ïOn 2/5/19, 11:51 PM, "Nancy Harrison" <dita@lists.oasis-open.org on behalf of nharrison@infobridge-solutions.com> wrote:

            Submitter's message
    1. Kris will add fix to 'xmlnamespace' to list of things to fix in 2.0.
    2. Eliot will send mail to list outlining what change should be made to the XSD shell to fix this.
    3. Eliot and Kris will get footer working for CN cover page.
    Minutes of the OASIS DITA TC
    Tuesday, 5 February 2019
    Recorded by Nancy Harrison
    link to agenda for this meeting:	
    Deb Bissantz, Bill Burns, Kris Eberlein, Carlos Evia, Nancy Harrison, Alan Houser, Scott Hudson, Eliot Kimber, Tom Magliery, Eric Sirois, Michael Priestley
    1. Roll call
            Regrets: Robert Anderson, Stan Doherty, Carsten Brennecke, Chris Nitchie, Keith Schengili-Roberts 
    2. Approve minutes from previous business meeting:
            29 January 2019:
                https://lists.oasis-open.org/archives/dita/201901/msg00066.html (Harrison, 31 January 2019)
                    Correction: https://lists.oasis-open.org/archives/dita/201902/msg00025.html (Eberlein, 05 Feb 2019) 
    moved by Kris, 2nd by Scott, approved by TC
    3. Announcements:
            New TC members: None 
    4. Action items
            21 August 2018
                Kris & Robert: Perform the best edit of multimedia topics that they can do in time available; due 18 September 
            11 September 2018
                Kris: Review conversation with Joe Pairman, e-mails about metadata, and TC discussion in late 2017/early 2018; summarize to TC 
            13 November 2018
                Eliot: Test refactoring of grammar files
                Spec editors incorporate changes from DITAweb review (Significant progress, very near to completion) 
            18 December 2018
                Eliot: Investigate issue re earningAggregationsTopicrefConstraintMod.xsd 
            22 January 2019
                Kris and Robert: Schedule meeting to plan moving forward on implementing complete DITA 2.0 proposals
                Scott: Review stage one proposal about release management domain, decide whether to move it forward (COMPLETED) 
            29 January 2019:
                Robert, Tom, Scott: Review examples that Stan suggests adding to DITA 2.0 spec
                Alan: Contact OASIS about problems with using non-open-source fonts (COMPLETED)
                Kris: Set up regularly scheduled calls between DITA 2.0 and LwDITA spec editors 
    [no new input]
    5. Glitch in DITA 1.3 spec
            https://lists.oasis-open.org/archives/dita/201901/msg00057.html (Susanne Muris, forwarded by Eberlein, 30 January 2019)
    - Kris; I need a volunteer to check this out; error using 'xmlnamespace' instead of 'xmlnsname' in spec
    - Eliot; I just looked at it; we do need to fix it.
    - Kris; in element reference topic?
    - Eliot; in the example for one of those topics.
    - Kris; so it's low-priority, since examples are non-normative.
    ***ActionItem: Kris will add fix to 'xmlnamespace' to list of things to fix in 2.0.
    6. Possible bug in Classification map XSD
            https://lists.oasis-open.org/archives/dita/201902/msg00024.html (Bissantz, 05 February 2019)
            Need volunteer to check this out 
    - Deb; our XSD classification map is failing; we checked with Radu; he entered it as an OT issue, but it's in the XSD.
    - Eliot, it's not in XSD grammar files, but in the XSD shell, and shells are non-normative and we reommend that nobody use the ones we ship.
    - Alan; we recommend that users shouldn't use our shells?
    - Eliot; we say they should create their own, based on the ones in the spec, and give them new names/IDs.
    ***ActionItem: Eliot will send mail to list outlining what change should be made to the XSD shell to fix this.
    7. DITA 2.0 stage two proposals
            Continuing discussion
            Initial discussion
                #29: Rework bookmap design
                    https://lists.oasis-open.org/archives/dita/201902/msg00008.html (Sirois, 04 February 2019) 
    - Eric; main change is addition of booklists in frontmatter so it matches backmatter. Expected processing is that if you specify an amendments element but don't specify an href, processor will scan topics, look for rev history changes, and produce something that matches those changes. This reflects the TC discussion in August 2018, coming out of a request from Stephen Eike (problem report #83).
    - Eric; Robert had suggested putting amendments in booklists, 
    - Kris; for changes to original bookmap. we're working with constraints on how much we want to rework it and break backwards compatibility, given that we're planning to introduce a completely new publication map in 2.0.
    - Eric; it depends on whether we want to do cleanup in 2.0; if we add it to booklists, then it's available both in frontmatter and backmatter. Kris; but this is the rework, not the new pubmap.
    - Eric; I'm fine either way, but I want to point out the discrepancy.
    - Scott; in the bookmap proposal, it was just adding ammendments to frontmatter, rather than adding it to booklists.
    - Eliot; I thought there was a technical reason why we couldn't add amendments to booklists.
    - Eric; that was about not having amendments in frontmatter. Both frontmatter and backmatter contain booklists, so if we move amendments into booklist, it needs to be in for both, which is fine from a technical standpoint. The current solution doesn't break anything. if we move things we're breaking backwards compatibility, but only in a very minor way.
    - Eliot; amendments can be either a reference to a topic or something that can be generated; I'm not sure it should be in booklists, which is meant to be only for generated content.
    - Scott; but a glossary, which is already in booklists, could be hardcoded as well...
    - Eliot; so maybe not best argument
    [to be continued next week, when Robert is here]
    8. Stylesheets
            Updates on committee note:
                Summary of changes
                    https://lists.oasis-open.org/archives/dita/201901/msg00058.html (Eberlein, 31 Jan 2019) 
                Proprietary font
                    https://lists.oasis-open.org/archives/dita/201901/msg00061.html (Houser, 31 january 2019)
                    https://lists.oasis-open.org/archives/dita/201901/msg00063.html (Chet Ensign, 31 January 2019) 
                PDF generated by updated stylesheets
                    https://lists.oasis-open.org/archives/dita/201902/msg00000.html (Eberlein, 01 February 2019)
                    https://lists.oasis-open.org/archives/dita/201902/msg00006.html (Paul Knight, 04 Feb 2019)
                    Need volunteer to help with getting footer on cover 
                HTML5 generated by updated stylesheets
                    https://lists.oasis-open.org/archives/dita/201902/msg00020.html (Eberlein, 05 February 2019) 
            Update on spec:
                Re-branding requirements from OASIS:
                    https://lists.oasis-open.org/archives/dita/201901/msg00049.html (Forwarded by Eberlein, 28 January 2019) 
    - Kris; I've updated stylesheets for PDF; I need help getting footer onto cover. Eliot, could you help with that?
    - Eliot; ok
    ***ActionItem: Eliot and Kris will get footer working for CN cover page.
    [following items 9-12 and 14 are all about LwD; items are listed consecutively, with discussion, which covered multiple items, at end}
    9. Re: [dita] Summary: Status of review of the DITA2.0/LwDITA intersection topics
            What this thread covers Processing = Formatting; ph element in DITA and LwDITA; single-sourcing between LwDITA and DITA
            https://lists.oasis-open.org/archives/dita/201901/msg00038.html (Houser, 26 January 2019)
                https://lists.oasis-open.org/archives/dita/201901/msg00039.html (Eberlein, 26 January 2019)
                https://lists.oasis-open.org/archives/dita/201901/msg00040.html (Houser, 26 January 2019) 
    10. Interoperability of DITA and LwDITA
            https://lists.oasis-open.org/archives/dita/201901/msg00041.html (Eberlein, 26 January 2019)
                https://lists.oasis-open.org/archives/dita/201901/msg00042.html (Evia, 26 January 2019)
                https://lists.oasis-open.org/archives/dita/201901/msg00043.html (Houser, 26 January 2019) 
    11. Misalignment example: LwDITA and DITA shortdesc topics
            https://lists.oasis-open.org/archives/dita/201901/msg00044.html (Eberlein, 26 January 2019) 
    12. Lightweight DITA spec: development strategy
            https://lists.oasis-open.org/archives/dita/201902/msg00001.html (Houser, 3 Feb 2019)
                https://lists.oasis-open.org/archives/dita/201902/msg00002.html (Eberlein, 3 Feb 2019)
                https://lists.oasis-open.org/archives/dita/201902/msg00003.html (Evia, 4 Feb 2019)
                Attachment: Draft LwDITA spec https://lists.oasis-open.org/archives/dita/201902/msg00016.html (Eberlein, 4 Feb 2019) 
    14. October 2018 DITAweb review: Topics that exist in both DITA 2.0 and LwDITA
            https://lists.oasis-open.org/archives/dita/201901/msg00036.html (Eberlein, 26 January 2019)
            (UPDATED) https://lists.oasis-open.org/archives/dita/201901/msg00054.html (Eberlein, 29 January 2019) 
    - Tom; Kris; can you give quick overwiew?
    - Alan; we think the most critical part is #12, schedule strategy.
    - Nancy; I think the most critical is interoperability between Lwd and full DITA.
    - Kris; wrt #9, I had done a bunch of cleanup on the spec based on the web review of the LwD CN in October, of elements that will be in both DITA and LwD. Alan, in his response, brought up the difference between formatting and processing expectations, i.e., how they overlap, and mentioned particularly how the ph element in DITA and LwD are different, and the issues with single-sourcing the topics.
    wrt #10, I changed the topic of the mail to interoperability, seeing misalignment based on current drafts of LwD descriptions. 
    - Alan; that's an accurate summary for those 2 items.
    - Alan; wrt #12, the big picture issue is that we're seeing more interest in developing LwD implementations, e.g., from Adobe and IBM,
    so we want to get it out asap.  We're seeing conflicting goals and constraints between our sense of when LwD needs to be available, and when DITA 2.0 is expected to be available.  OTOH, LwD must be compatible with DITA, and 2.0 is on a diff time frame from what we'd like. so we're looking for the best way to get it out for public review in 2019.
    - Kris; before we can talk about fast tracking, need to see an actual LwD spec.  The reality is that even once TC approves a final version of something, it takes 6 months for OASIS to release. That period is extended if any changes need to be made to spec.
    - Michael; maybe 'fast-track' is the wrong word; we're not asking for fast tracking, but the directive to single-source from 2.0 spec is 'slow-tracking' from our POV.  If we take on the task of editing the full element info in every full DITA element so it's no longer XML-specific, and add stuff, that job is huge. The DITA topics really aren't appropriate for what LwD is trying to do, and who it's trying to appeal to.  We can't take on that task.
    - Kris; this is back to item #10, interoperability. We've discussed what's needed to be consistent between 2.0 and LwD topics, wrt what info other than shortdesc needs to be the same. Specifically, topcis describing common elements need to give the elements the same meaning, usage information, & processing/formatting expectations.
    - Michael; reuse by conref would be one way to get there, but formatting is currently phrased as full DITA, assuming XML source. Our users don't want to see that.
    - Kris; I want to hear from other TC members about interoperability and alignment between the two specs.  
    - Eliot; I agree that whatever language is used in LwD has to be identical to regular DITA; i.e., there can't be anything that appears to be a semantic, normative difference.
    - Alan; but you would need to qualify that for modulo subsetting.
    - Eliot; shouldn't change that.
    - Michael; so there shouldn't be processing expectations in LwD elements for @s that are constrained out of those elements in LwD.
    - Eliot; processing expectations aren't normative, nor are formatting.
    - Michael; so processing expectations can be changed by subsetting, if @s in LwD are omitted, and processing expectations mention those @s.
    - Kris; for element topics common to both, we don't have processing expectations written that way.
    - Tom; not clear what you mean by that.
    - Kris; in 2.0, processing expectations are written so they stand alone in standalone block, not cast in the way that Michael was concerned about. 
    - Michael; yes, it could be handled with an exclusion, but it is a difference.
    - Tom; it's obvious there will be differences related to omissions. 
    - Eliot; LwD can't change processing expectations; if it's irrelevant, that's different from saying it will be different.
    - Michael; I agree that's normatively the same. 
    - Eliot; any @ LwD omits, it's default behaviour will still apply
    - Michael; e.g. if we added shortdesc to map, but don't have copy-to @, so it should be as if copy-to @ not specified?
    - Kris; but that is work spec editors are happy to do.
    - Michael; so can we supply our differences and you'll incorporate them into 2.0?
    - Kris; No. LwD editors should be working with what's already there and modifying them.  It's inappropriate for DITA to match LwD; LwD should editors can modify them to adjust these.
    - Michael; so the term 'element' is a challenge; Markdown user don't like it, because they don't like XML and it's identified with XML. Are you comfortable removing 'element'?
    - Kris; No, I don't think so. DITA and its spec are about an XML vocabulary. 
    - Michael; so we should have 3 sets of processing expectations so can distinguish XDITA, MDITA, & HDITA?
    - Eliot; not necessarily, but syntactic representation; defining a mapping from MDITA to its equivalent to XML. 
    - Michael; a markdown guy won't understand 'element.'
    - Nancy; I disagree, a Markdown u;ser won't understand it, but a Markdown implementor will, may not prefer it, but will almost certainly understand it.
    - Michael; a lot of Markdown folks dislike 'elements' they don't like XML.
    - Tom; what is their language? what is what they use
    - Carlos; we're going for component
    - Tom; is that what they use when they're designing things?
    - Michael; a lot of times they avoid using anything; they talk about blocks, or inlines, or Markdown codes; they have no equivalent to an element.  But we saw 'component' in some of their discussions, so it seemed like someting they would be comfortable with.  
    - Kris; the term 'component' was added during time LwD was getting response during its public review, trying to figure out an non-XML-centric term.  I'm hearing a clear consensus that LwD and 2.0 must be a compatible subset of either 2.0 or 1.3 + multimedia domain. Any objections?
    - Tom; is there any risk if it's both?
    - Carlos; my concern is that the alignment won't work. If we align with the current state of 2.0, and it gets changed down the line, e.g., during its public review, would LwD have to change too?
    - Kris; yes, it will, that's part of the standards process.
    - Alan; maybe the only thing to do is declare that's it's a subset of 1.3+. we can't say it's 2.0.  Either that, or we can't put it out as a spec till later.  Instead, LwD goes out with some stuff, as a preview but not as a spec, and it exposes some parts of DITA 2.0.
    - Kris; I see 2 possibilities for that 1. with 1.3 (with all its 'XML-ness), or
    - Alan; that won't work.
    - Kris; otherwise, LwD meets with where 2.0 is currently, and get re-alighed with 2.0 after 2.0 is released. That takes us back to the original question; if it has to be semantically identical, we need to tackle the thorny way of how we do that, and the best way to do that is single-sourcing.  We can take advantage of conref, conrefpush, and  conrefreplace, but I don't see a way around that method.
    - Tom; I don't know if it's a problem, we would have to lock down topics that have been created for 2.0 with respect to LwD for the 2.0 spec in order to accommodate LwD and 2.0.  So in future, when putting out 2.0, we'd have to not change those topics.
    - Michael;  Alan, rather than them being locked own, if you change something that's a common component, you just need to be aware of it and track it so they can re-align later. 
    - Kris; I can't see us removing XML-centric language from the spec.
    - Michael; so my plan A is that we have parallel sentences, so we don't change logic in rewording, but that processing context has changed.
    - Kris; when I look at draft LwD spec, there are extreme descrepancies between it and stuff that in DITA spec.
    - Alan; example?
    - Kris; current LwD spec makes a statement on bold text; makes normative statements in sections that we never put normative text in (i.e. 'formatting expectations' section).
    - Alan; Carlos and I are not expert spec editors; we need to know what to change,
    [to be continued next week]
    12 noon ET close 
    -- Ms. Nancy Harrison
            Document Name: DITA TC Meeting Minutes 5 February 2019 <https://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_id=64671>
            No description provided.        
            Download Latest Revision <https://www.oasis-open.org/apps/org/workgroup/dita/download.php/64671/latest/minutes20190205.txt>
            Public Download Link <https://www.oasis-open.org/committees/document.php?document_id=64671&wg_abbrev=dita>
            Submitter: Ms. Nancy Harrison
                    Group: OASIS Darwin Information Typing Architecture (DITA) TC
            Folder: Meeting Notes
            Date submitted: 2019-02-05 21:51:03

To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]