1 Universal Business Language (UBL) 3Embedded Documentation 4Working Draft 01, 26 June, 2002 5Document identifier: 6draft-gregory-embedded-01.doc 7Location: http://www.oasis-open.org/committees/ubl/ndrsc/drafts/[WRONG!] 9Editors: 10Lisa Seaburg, AEON Consulting 11Arofan Gregory, Commerce One arofan.gregory@commerceone.com 12 13Contributors: 14 15Abstract: 16This document outlines the design principles around the use of embedded 17documentation in the XML schema that is the UBL library 18Status: 19This is the first draft 20Copyright © 2001, 2002 The Organization for the Advancement of 21Structured Information Standards [OASIS] 1wd-ublndrsc-ndrdoc-13 31 May 2002 22Table of Contents 23 1.1 Introduction .2 24 1.2 Template for XHTML documentation 25 1.3 UBL-Specific Keywords 26 1.4 Use of the xsd:documentation Element within UBL Schema Constructs .5 272 XHTML Basic 28 2.1 The XHTML Basic Document Type 293 References 14 30Appendix A Notices 15 31 321.1 Introduction 33For UBL schema modules Documentation shall be embedded directly in the schema modules 34This section describes the use of the xsd:documentation element for providing embedded 35documentation Other sections address the issues around what the content of documentation 36should be at various points within the schema module, within the parameters described here 37UBL requires the use of embedded documentation for two reasons: 38 • Ease of maintenance – the file containing the module schema also contains the documentation, allowing comparison at a glance, and editing within a single screen • Ease of use – especially in auto-generation scenarios, having the structural content described by the schema instance itself and the relevant humanreadable documentation makes the auto-generation of documentation much easier 39 40 41 42 43 44 45Rather than create a set of UBL-specific tags for documentation, XHTML Basic has been selected 46as a widely-understood and implemented markup that can be conventionally used by UBL to 47provide all needed information in a form that is easy to present and process 48The main convention here is the use of the CLASS attribute on the DIV element, with a controlled 49set of UBL-specific nametokens to indicate the specific type of documentation being provided 50This information includes a set of properties that relate to the modeling methodology by which 51UBL is produced 52Note that while the normative version of UBL schema modules is required to contain embedded 53documentation as described here, it is expected that such documentation will be stripped out of 54the schema modules for use in low-memory production implementations 55The use of the xsd:source attribute on the xsd:documentation element is deprecated, as it defeats 56the purpose of keeping all of the relevant documentation inside the schema module This attribute 6wd-ublndrsc-ndrdoc-13 10 31 May 2002 57is intended to hold the URI of the source of the documentation content, which is unnecessary in 58this case 591.2 Template for XHTML documentation 60The template for embedded documentation within the UBL schema modules is presented here 61This template should be followed wherever embedded documentation is required to appear within 62the schema modules (element declarations, complex type declarations, attribute declarations, 63simple type declarations, etc.) as described elsewhere in this document 64Note that in this sample, [KEYWORD] indicates one of the controlled set of nametokens 65designated for indicating the different UBL-specific types of documentation [ANY] indicates that 66any XHTML Basic element name may appear in that space, used in conformance with the 67XHTML Basic DTD There are conventional restrictions on the use of these elements in some of 68the UBL-specific documentation types, as described below 69 70 71 72 73 74 75 76 77 78 79Note that there will typically be a series of XHTML:DIV elements appearing inside the UBL use of 80the xsd:documentation element, rather than just two as pictured in the example above 81The order of the XHTML divisions typed with UBL-specific keywords is unimportant, so long as all 82needed types of divisions are provided in the appropriate places However, each type of division 83will appear once and only once in the designated position within the documentation element of 84the schema module 85 86 871.3 UBL-Specific Keywords 88The following is a list of the possible values of the CLASS attribute appearing within the 89conventional UBL use of the DIV element in XHTML basic These values are name tokens, rather 90than strings 11wd-ublndrsc-ndrdoc-13 12 13 14 15 31 May 2002 91Note that for purposes of automation and familiarity, these nametokens are taken from two 92sources: the UN/CEFACT Core Components Technical Specification, where the value provided 93corresponds to a modeling value described in that system In places where no such construct 94exists, the name will be taken from the UBL modeling methodology In both cases, any single 95whitespace character or string of contiguous whitespace characters appearing in the names 96taken from these sources will be replaced by a single underscore (Thus, “UBL Name” becomes 97“UBL_Name”) 98 Name Token Description Source UBL_UID The unique identifier for the construct in UBL UBL Methodology XCBL_Name Gives the corresponding element name in xCBL 3.0 Only for development/design purposes – not publication UBL Methodology UBL_Name The assigned UBL name UBL Methodology BIE Dictionary Entry Name CCTS Object Class CCTS Property Qualifier CCTS Property Term CCTS Representation Term CCTS Type UBL Methodology Business Terms CCTS Occurrence CCTS Basic/Aggregate CCTS UBL Definition CCTS Code_Lists_and_Standards CCTS Analyst_Notes UBL Methodology 16wd-ublndrsc-ndrdoc-13 17 18 19 20 Value Permitted XHTML Basic Markup 31 May 2002 Candidate_CC_ID CCTS Context_Business_Process CCTS Context_Region_Geopolitical CCTS Context_Official_Constraints CCTS Context_Product CCTS Context_Industry CCTS Context_BP_Role CCTS Context_Supporting_Role CCTS Context_System_Constraint CCTS Editors_Notes UBL Methodology Length UBL Methodology pattern UBL Methodology enumeration UBL Methodology inclusive UBL Methodology exclusive UBL Methodology digits UBL Methodology 99 100 1011.4 Use of the xsd:documentation Element within UBL Schema 102 Constructs 103[THIS SECTION PROVIDES A DESCRIPTION OF WHERE DOCUMENTATION ELEMENTS 104SHOULD APPEAR WITHIN THE VARIOUS SCHEMA DECLARATIONS, AND WHICH OF THE 105NAMED DIVISIONS IS REQUIRD AND?OR PERMITTED WITHIN EACH.] 106 107 108 21wd-ublndrsc-ndrdoc-13 22 23 24 25 31 May 2002 1092 XHTML Basic 110XHTML Basic is based on HTML and developed as a language for authoring Web content It is 111designed to provide a document type that can be shared across communities, and also be to very 112basic, not containing every feature available within other versions of HTML It includes: text; 113hyperlinks, basic forms, basic tables; images, and meta data information 114The following section provides a brief overview to the constructs permitted within XHTML Basic 115as used by UBL embedded documentation For a more complete discussion of XHTML Basic, 116please see [PROVIDE REFERENCE TO VERSION OF XHTML BASIC] Some of the following 117content has been adapted from that source 1182.1 The XHTML Basic Document Type 119The XHTML Basic document type is defined as a set of XHTML modules All XHTML modules are 120defined in the "Modularization of XHTML" specification [XHTMLMOD] 121XHTML Basic consists of the following XHTML modules: 122Structure Module* 123 body, head, html, title 124Text Module* 125 126 abbr, acronym, address, blockquote, br, cite, code, dfn, div, em, h1, h2, h3, h4, h5, h6, kbd, p, pre, q, samp, span, strong, var 127Hypertext Module* 128 a 129List Module* 130 dl, dt, dd, ol, ul, li 131Basic Forms Module 132 form, input, label, select, option, textarea 133Basic Tables Module 134 caption, table, td, th, tr 135Image Module 136 img 26wd-ublndrsc-ndrdoc-13 27 28 29 30 31 May 2002 137Object Module 138 object, param 139Metainformation Module 140 meta 141Link Module 142 link 143Base Module 144 base 145(*) = This module is a required XHTML Host Language module 146NOTE: Since the HTML event handler attributes are not included in XHTML Basic, form controls 147outside forms may not function as expected by the user 148The XHTML Basic XML 1.0 DTD: 149 151 152 153 175 Peter Stark 176 177 Revision: 178mimasa Exp $ SMI $Id: xhtml-basic10.dtd,v 2.13 2000/12/18 12:56:23 179 180 > 181 188 189 190 197 198 199 36wd-ublndrsc-ndrdoc-13 37 38 39 40 31 May 2002 200 202 203 204 205 217 218 219 220 221 225 226 227 228 229 41wd-ublndrsc-ndrdoc-13 42 43 44 45 31 May 2002 231 232 233 234 235 238 239 242%xhtml-framework.mod; 243 244 251 252 255%xhtml-text.mod; 256 257 260%xhtml-hypertext.mod; 46wd-ublndrsc-ndrdoc-13 47 48 49 50 10 31 May 2002 261 262 265%xhtml-list.mod; 266 267 269 270 271 272 276%xhtml-image.mod;]]> 277 278 279 280 284%xhtml-table.mod;]]> 285 286 287 288 51wd-ublndrsc-ndrdoc-13 52 53 54 55 11 31 May 2002 292%xhtml-form.mod;]]> 293 294 295 296 300%xhtml-link.mod;]]> 301 302 303 304 308%xhtml-meta.mod;]]> 309 310 311 312 316%xhtml-base.mod;]]> 317 318 319 320 324%xhtml-param.mod;]]> 325 326 327 328 332%xhtml-object.mod;]]> 333 334 337%xhtml-struct.mod; 338 339 341 61wd-ublndrsc-ndrdoc-13 62 63 64 65 13 31 May 2002 3423 References 343XHTML™ Basic, W3C Recommendation 19 December 2000: http://www.w3.org/TR/2000/REC344xhtml-basic-20001219 345 66wd-ublndrsc-ndrdoc-13 67 68 69 70 14 31 May 2002 346Appendix A Notices 347OASIS takes no position regarding the validity or scope of any intellectual property or other rights 348that might be claimed to pertain to the implementation or use of the technology described in this 349document or the extent to which any license under such rights might or might not be available; 350neither does it represent that it has made any effort to identify any such rights Information on 351OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS 352website Copies of claims of rights made available for publication and any assurances of licenses 353to be made available, or the result of an attempt made to obtain a general license or permission 354for the use of such proprietary rights by implementors or users of this specification, can be 355obtained from the OASIS Executive Director 356OASIS invites any interested party to bring to its attention any copyrights, patents or patent 357applications, or other proprietary rights which may cover technology that may be required to 358implement this specification Please address the information to the OASIS Executive Director 359Copyright © The Organization for the Advancement of Structured Information Standards [OASIS] 3602001 All Rights Reserved 361This document and translations of it may be copied and furnished to others, and derivative works 362that comment on or otherwise explain it or assist in its implementation may be prepared, copied, 363published and distributed, in whole or in part, without restriction of any kind, provided that the 364above copyright notice and this paragraph are included on all such copies and derivative works 365However, this document itself does not be modified in any way, such as by removing the 366copyright notice or references to OASIS, except as needed for the purpose of developing OASIS 367specifications, in which case the procedures for copyrights defined in the OASIS Intellectual 368Property Rights document must be followed, or as required to translate it into languages other 369than English 370The limited permissions granted above are perpetual and will not be revoked by OASIS or its 371successors or assigns 372This document and the information contained herein is provided on an “AS IS” basis and OASIS 373DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 374ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY 375RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 376PARTICULAR PURPOSE 71wd-ublndrsc-ndrdoc-13 72 73 74 75 15 31 May 2002 ... UBL schema modules Documentation shall be embedded directly in the schema modules 34This section describes the use of the xsd :documentation element for providing embedded 3 5documentation Other... hold the URI of the source of the documentation content, which is unnecessary in 58this case 591.2 Template for XHTML documentation 60The template for embedded documentation within the UBL schema... the relevant humanreadable documentation makes the auto-generation of documentation much easier 39 40 41 42 43 44 45Rather than create a set of UBL-specific tags for documentation, XHTML Basic