Contents

  1. About
  2. References
    1. Spec Templates
    2. Spec File Naming
  3. Question List for Mary
    1. Spec Templates
    2. Version Control
    3. Spec File Naming
    4. Other Best Practices
    5. Note to Mary: Errata We Found
  4. Spec Filenames
    1. XRD 1.0
    2. XRI 3.0
      1. Part 1: Syntax
      2. Part 2: Resolution
      3. Part 3: http: and https: Bindings
      4. Part 4: info: Binding
  5. Front Matter
  6. Acknowledgements
  7. Examples from Other Specs
    1. SAML 2.0
      1. Core
      2. Bindings
      3. Metadata
    2. DITA 1.1
      1. Overview
      2. Architecture
      3. Language
      4. DTDs
      5. Schemas

About

This page is used to coordinate templates, filenames, frontmatter, and other info as needed by XRI TC spec editors.

References

Spec Templates

Spec File Naming

Question List for Mary

Spec Templates

  1. Of the four spec template options list at OASIS Templates and Guidelines, do you recommend one or is it purely a matter of editor preference? The templates are all the same; it's a matter of which tools the editor(s) prefer to use. I will say that I am unable to get really decent HTML out of OpenDocument, unfortunately (valid, but not correct).

  1. Once the editors for a spec choose one, can they later switch to a different template and designate that one as authoritative? You can designate authoritative on a release basis; I wouldn't recommend switching among Word/OpenDocument/XHTML environments. You're only inviting trouble.

Version Control

  1. What best practices have other TCs used for revision control when multiple editors are working on a spec? Does anyone use SVN? SVN was never intended to be used for version control of binary document formats. Word processing apps typically support a "master document" concept where the document is divided into components (chapters? sections? as appropriate) and the "master document" pulls them all together. I strongly recommend assigning editors unique parts of the document.

Spec File Naming

  1. In the OASIS Spec URI Generator, it is not clear what the component parts are intended to be. We assume it is supposed be read in conjunction with the Specification URIs and URI Design (is the latter still current?), but the terminology does not line up. Specifically, there is no mention in the docs about the terms specification abbreviation, specific version filename and generic version filename that appear in the generator. There are no formal requirements related to the actual filename. However, it is suggested (and hence built into the URI generator) that you follow a convention that's been in place for quite some time.

  1. Given that, are the filenames in the Proposed Spec File Names section below correct? they are acceptable; it's considered best practice (but not required) to include the stage in the filename to avoid confusion.

  1. What's a generic version filename?

  2. Since it's not the name of the TC, do we have to spell out Extensible Resource Descriptor (XRD) 1.0? Where? Certainly the specification title. I'm guessing you'll want to use 'xrd' for the pathname and filename components.

  3. What is actually required in terms of spec naming and formatting to submit a multi-part specification for a single OASIS Standard vote? In other words, do the spec titles themselves need to say, "Part x:..."? The specification must be a single "document" - that is, think of an aircraft maintenance manual, an encyclopedia, or the California State Code. A single document that is so large a single book can't realistically hold it, so it's broken down into volumes, or parts. There will be a master document which will contain the cover page for the specification, along with URIs, and all other metadata, copyright notice, TOC (including TOCs for each of the separate "parts"), Introduction section (including all references), conformance section,appendices, acknowledgements, etc. Each component will have the same specification title followed by a subtitle (Part I - syntax, Part II - resolution, etc.) Sections should continue (that is, part I may have sections 1-12, part II would have sections 13-18, etc.)

Other Best Practices

  1. What other common mistakes to first-time OASIS spec editor teams make? They don't follow the template. They change the typeface. They change the point size. They change colors. They don't properly construct the URIs. Their hypertext links are broken. Please use the template. Download the template and create a new document based on that template. Do not begin with an old spec. Do not try to match the styles from the template in a document of your own making. Use the template. Did I say to use the template? ;-) Oh, and make sure whenever you're entering an URI that there's a real hypertext link behind the text that actually corresponds to what you've typed.

  1. What other advice do you have for the XRI and XDI editor teams? Ask questions.

Note to Mary: Errata We Found

  1. Section 3.2 of OASIS Spec Template Guidelines appears to be out of date – it mentions only four spec stages when now there are five (WD, CD, PR, CS, OS). Typically the spec sent out for public review is a Committee Draft. The stage exists but most often is not explicitly identified on the cover page.

  2. In that same doc, there appears to be a missing section 3.4.5 Previous Approved Version according to the guidelines in Specification URIs. Approved Version and Previous Approved Version have been deprecated.

  3. Section 7 of that same doc does not mention that the Conformance section needs to be the LAST numbered section in a spec, but the OASIS Word Template says it does. Which is right? They are both right. You must have a conformance section. It must be the last numbered section in the spec. ;-)

Spec Filenames

The XRI TC practice is that spec filenames for specific versions of a spec (vs. the "Latest Version" alias) MUST append one of the following strings to the end of the filename (and before any file extension) to indicate the specification stage (where XX is an integer):

XRD 1.0

This version (example for Working Draft 01): 

http://docs.oasis-open.org/xri/xrd/v1.0/WD01/xrd-1.0-wd01.doc
http://docs.oasis-open.org/xri/xrd/v1.0/WD01/xrd-1.0-wd01.html
http://docs.oasis-open.org/xri/xrd/v1.0/WD01/xrd-1.0-wd01.pdf

Latest version: 

http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.doc
http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html
http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.pdf

XRI 3.0

Part 1: Syntax

This version (example for Working Draft 01): 

http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-syntax-3.0-wd01.doc
http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-syntax-3.0-wd01.html
http://docs.oasis-open.org/xri/xri/v3.0/WD01/ xri-syntax-3.0-wd01.pdf

Latest version: 

http://docs.oasis-open.org/xri/xri/v3.0/xri-syntax-3.0.doc
http://docs.oasis-open.org/xri/xri/v3.0/xri-syntax-3.0.html
http://docs.oasis-open.org/xri/xri/v3.0/xri-syntax-3.0.pdf

Part 2: Resolution

This version (example for Working Draft 01): 

http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-resolution-3.0-wd01.doc
http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-resolution-3.0-wd01.html
http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-resolution-3.0-wd01.pdf

Latest version: 

http://docs.oasis-open.org/xri/xri/v3.0/xri-resolution-3.0.doc
http://docs.oasis-open.org/xri/xri/v3.0/xri-resolution-3.0.html
http://docs.oasis-open.org/xri/xri/v3.0/xri-resolution-3.0.pdf

Part 3: http: and https: Bindings

This version (example for Working Draft 01): 

http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-http-and-https-binding-3.0-wd01.doc
http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-http-and-https-binding-3.0-wd01.html
http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-http-and-https-binding-3.0-wd01.pdf

Latest version: 

http://docs.oasis-open.org/xri/xri/v3.0/xri-http-and-https-binding-3.0.doc
http://docs.oasis-open.org/xri/xri/v3.0/xri-http-and-https-binding-3.0.html
http://docs.oasis-open.org/xri/xri/v3.0/xri-http-and-https-binding-3.0.pdf

Part 4: info: Binding

This version (example for Working Draft 01): 

http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-info-binding-3.0-wd01.doc
http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-info-binding-3.0-wd01.html
http://docs.oasis-open.org/xri/xri/v3.0/WD01/xri-info-binding-3.0-wd01.pdf

Latest version: 

http://docs.oasis-open.org/xri/xri/v3.0/xri-info-binding-3.0.doc
http://docs.oasis-open.org/xri/xri/v3.0/xri-info-binding-3.0.html
http://docs.oasis-open.org/xri/xri/v3.0/xri-info-binding-3.0.pdf

Front Matter

This section will have more info about any other frontmatter that must be consistent across all the specs.

Acknowledgements

This section will have more info about the acknowledgements appendix that should be consistent across all the specs.

Examples from Other Specs

SAML 2.0

File Naming:

Component

Value

TC Name

security

Spec Abbreviation

saml

Spec Version

v2.0

Specific Version Filename

saml-core-2.0.os.pdf (example)

Generic Version Filename?

saml-core-2.0 (what's a generic version filename?) a "generic" filename doesn't have a stage component (os, cd, cs, etc.)

Core

Bindings

Metadata

DITA 1.1

This is a multi-part spec submitted as a single OASIS Standard.

Overview

Architecture

Language

DTDs

Schemas

InfoForEditors (last edited 2009-08-12 18:07:18 by localhost)