The differences between smart tags, custom XML markups, and structured document tags are unclear. In particular, 2.5.1 (Custom XML and Smart Tags) and 2.5.2 (Structured Document Tags) of Part 4 are almost the same.

Clarify the differences. Some tutorial (e.g., as a non-normative appendix) would be very helpful.

Part 4 Clause 2.5.1 and Clause 2.5.2

te

Proposed Disposition of DIS 29500 Comment JP-0073 (Modified: 2007-12-05) Agreed; this is the result of an editorial error that repeated the text from §2.5.2 in §2.5.1. The following text will replace all the existing text in Part 4, §2.5.1: 2.5.1 Custom XML and Smart Tags The first example of customer-defined semantics that can be embedded in a WordprocessingML document are smart tags. Customers can establish sets of smart tags that allow semantic labels to be added around an arbitrary run or set of runs within a document to provide information about the type of data contained within. [Example: Consider the following text in a WordprocessingML document, with a smart tag around the stock symbol 'CNTS' (where the smart tag is displayed using a purple dotted underline): This is a stock symbol: CNTS This text would translate to the following WordprocessingML markup: <w:p w:rsidR="00672474" w:rsidRDefault="00672474"> <w:r> <w:t xml:space="preserve">This is a stock symbol: </w:t> </w:r> <w:smartTag w:uri="http://www.example.com" w:element="stockticker"> <w:r> <w:t>CNTS</w:t> </w:r> </w:smartTag> </w:p> As shown above, the smart tag is delimited by the smartTag element, which surrounds the run (or runs) which contain the text which is part of the smart tag. end example] The smart tag itself carries two required pieces of information, which together contain the customer semantics for this smart tag: The first of these is the namespace for this smart tag (contained in the uri attribute). This allows the smart tag to specify a URI which should identifies the namespace of this smart tag to a consumer. It is intended to be used to specify a family of smart tags to which this one belongs. [Example: In the sample above, the smart tag belongs to the http://www.example.com namespace. end example] The second of these is the element name for this smart tag (contained in the element attribute). This allows the smart tag to specify a name which identifies this type of smart tag within its namespace and again available to a consumer. It is intended to be used to specify a unique name for this type of smart tag. [Example: In the sample above, the smart tag specifies that its data is of type stockticker . end example] The next example of customer-defined semantics which can be embedded in a WordprocessingML document is custom XML markup. Custom XML markup allows the application of the XML elements defined in any valid schema syntax (XML Schema, NVDL, etc.) to be applied to the contents of a WordprocessingML document in one of two locations: around a paragraph or set of paragraphs (at the block level); or around an arbitrary run or set of runs within a document (at the inline level) to provide semantics to that content within the context and structures defined by the associated schema definition. The distinction between custom XML markup and smart tags is that custom XML markup is based on a specified schema. As a result, the custom XML elements can be validated against the schema. Also, as shown below, custom XML markup can be used at the block-level as well as on the inline (run) level. [Example: Consider a simple XML Schema which defines two elements: a root element of invoice, and a child element of customerName - the first defining that this file's contents are an invoice, and the second specifying that the enclosed text as a customer's name: This output would translate to the following WordprocessingML markup: <w:customXml w:uri="http://www.example.com/2006/invoice" w:element="invoice"> <w:p> <w:r> <w:t>This is an invoice.</w:t> </w:r> </w:p> <w:p> <w:r> <w:t xml:space="preserve">And this is a customer name: </w:t> </w:r> <w:customXml w:uri="http://www.example.com/2006/invoice" w:element="customerName"> <w:r> <w:t>Tristan Davis</w:t> </w:r> </w:customXml> </w:p> </w:customXml> As shown above, each of the XML elements from the customer-supplied XML schema is represented within the document output as a customXml element. end example] Similar to the smart tag example above, a custom XML element in a document has two required attributes. The first is the uri attribute, whose contents specify the namespace of the custom XML element in the document. In the example above, the elements each belong to the http://www.example.com/2006/invoice namespace. The second is the element attribute, whose contents specify the name of the custom XML element at this location in the document. In the example above, the root element is called invoice and the child element is called customerName. As well as the required information specified above, custom XML elements can also specify any number of attributes (as specified in the associated XML Schema) on the element. To add this information, the customXmlPr (properties on the custom XML element) specify one or more attr elements. [Example: Using the example above, we can add a type attribute to the customerName element as follows: <w:customXml w:uri="http://www.example.com/2006/invoice" w:element="customerName"> <w:customXmlPr> <w:attr w:uri="http://www.example.com/2006/invoice" w:name="type" w:val="individual"/> </w:customXmlPr> <w:r> <w:t>Tristan Davis</w:t> </w:r> </w:customXml> The resulting XML, as seen above, simply adds an attr element which specifies the attribute for the custom XML element. end example]