MCE -- treatment of examples in document

Thu Jan 2 23:45:12 CET 2014

> the location/use/cross-referencing of examples needs to be revisited in a holistic fashion
Having looked up from the trees to see the forest, I will chime in with a terribly useful "I agree".

I looked at the ISO Directives Part 2 and various W3C and ISO/IEC standards to see if there is a common way to handle this.  W3C (XML, XMLNS, XSD) uses inline example, but visually offset, and few of them.  I browsed some SC 34 and other ISO/IEC standards I had handy (parts of 13250, 9075, 19757) and they also used inline, not visually offset (per ISO Directives formatting), and few of them.  One had an annex with a few large example programs.  All uses I saw of the ISO Directives style examples (see 6.5.1 in Directives Part 2) were either short statements or a short code/XML/etc. snippet with no or a very short statement about it, not the lengthy explanations we have.

I see two extremes - all/most examples inline vs. terse text with references to all/most examples in an appendix.  My initial thought is the latter appeals from a cleanliness (of reading) point of view since example text looks just like any other normative prose at a glance.  I'm not sure if having to jump to an examples clause all the time is ideal, though.  I'm going to test out leaving examples that are short or directly relevant to the normative prose (e.g., common cases to show basic usage) inline and move edge cases and larger examples to the annex, which will need to be reorganized.  Please let me know if you have other opinions or suggestions.

I'm working on a "tidying up" change-tracked version of WD 1.0 that standardizes use of spaces(1), formatting of XML snippets(2) and whatever I come up with for examples.  I'm doing each category of change with a different author name so they can be viewed/hidden and accepted/rejected in bulk, as Rex has done in the past.

(1) We have a mix of one, two and three spaces after sentences.  I prefer the traditional typesetting/typewriter use of two spaces, but modern opinion and style manuals seem to be against me.  I've changed them all to one.  Also, there was a scattering of nonbreaking space characters which I changed to regular spaces.
(2) I again tried to find a convention and couldn't.  The more often used scheme appears to have attributes immediately after an element name and, if wrapped to another line, double indentation for those subsequent lines of attributes (so as to offset them from following child elements that are single indented from the parent with the many attributes).

John

-----Original Message-----
From: Arms, Caroline [mailto:caar at loc.gov] 
Sent: Tuesday, August 13, 2013 7:55 AM
To: SC34
Subject: MCE -- treatment of examples in document

After today's call I have extracted these points on examples from my message of yesterday.

Sections 8 and 10 have examples that are mainly edge cases.  More typical examples are in Annex A and could possibly be included in or referenced from the main text.  After the technical substance is finalized, it has been agreed that the location/use/cross-referencing of examples needs to be revisited in a holistic fashion.  These were the places in which things seemed particularly awkward to me.

Page 15 in draft .91.  8.5
   I think it would be good to have a typical example (i.e. one with Choice and Fallback elements), not just edge cases.  Or to refer to Annex A, Example A.5.

Page 22.  10.2
    Example starting on page 22 is essentially two examples in one -- from reading the text.  I think it would be clearer to start with the more typical example and follow by the related edge case that the markup chunk represents.

   Caroline

Caroline Arms
Library of Congress Contractor
Co-compiler of Sustainability of Digital Formats resource http://www.digitalpreservation.gov/formats/

** Views expressed are personal and not necessarily those of the institution ** ________________________________________
From: eb2mmrt at gmail.com [eb2mmrt at gmail.com] On Behalf Of MURATA Makoto [eb2m-mrt at asahi-net.or.jp]
Sent: Tuesday, August 13, 2013 5:11 AM
To: SC34
Subject: Proposed text for Clause 9

Dear colleagues,

Here is a proposed rewrite of Clause 9.  It is based on Francis' wording but has been modified and further expanded by two examples.  Thanks. > Francis.

Regards,
Makoto
-----------------------------------------------------------------------------

9. Extension elements defined by a markup specification (informative)

A markup specification that uses Markup Compatibility elements and attributes to allow extensions in namespaces other than those defined by the markup specification may also define one or more specific extension elements in the namespaces that it defines. [Note: If the markup specification includes a schema, any extension elements would normally be constrained by the schema to occur only in specific markup contexts. end note].

If an MCE processor is configured to recognise extension elements, it preserves them together with their attributes and contents.  See Clause 9 for details.

[Example:

https://subversion.assembla.com/svn/IS29500/trunk/Part3/TestData/ExtensionElements/example1.xml

In this example, the e1:foo element contains the unknown:foo element.
Suppose that a markup configuration contains an expanded name ("http://www.example.com/e1", "foo") and that an application configuration does not contain "http://www.example.com/unknown".
Then, the element e1:foo is an application-defined extension element.
Although the unknown:foo element does not belong to an understood or ignorable namespace, the MCE processor preserves it and does not report any errors. end example]

[Example:

https://subversion.assembla.com/svn/IS29500/trunk/Part3/TestData/ExtensionElements/example2.xml

In this example, Markup Compatibility elements and attributes occur within the extensionElement element, which is the only child of the root element example.  Suppose that a markup configuration contains an expanded name ("http://www.example.com/e1", "extensionElement").
Then, the MCE processor preserves the extensionElement element.
Therefore, MCE elements and attributes within it, namely mce:Ignorable="i1", mce:ProcessContent="i1:bar1", mce:MustUnderstand="e1", mce:AlternateConent, mce:Choice, and mce:Fallback, appear in the output document.  end example]

After receiving the output of an MCE processor, application programs may further invoke an MCE processor to handle Markup Compatibility elements and attributes within extension elements.