wiki-archive/twiki/data/TIP/TIPDocsFiles.txt

%META:TOPICINFO{author="RogerHyam" date="1149417597" format="1.1" version="1.1"}%
%META:TOPICPARENT{name="DocsCoreDocs"}%
---+ TDWG Standards Files Specification

    <div id="header">
      <dl>
        <dt>Date:</dt>
        <dd>25 December 2005</dd>

        <dt>Contributors:</dt>
        <dd id="contributors"> Roger Hyam (TDWG Infrastructure Project) &lt;<a
            href="mailto:roger@tdwg">roger@tdwg</a>&gt;</dd>
        <dt>Abstract:</dt>
        <dd>This documents defines the form TDWG standards should take, what files they can contain
          and what they should be called. Standards are either administrative standards,
          applicability statements or specifications. Each one is an archive made up of two or more
          files. Files within a standard are either normative (type 1) files or non-normative (type
          2). File names should be simple, with a restricted set of letters and other characters.
          Files should be in an open format with commonly available parsers. Every standard must
          contain a cover page document.</dd>
        <dt>Part of TDWG Standard:</dt>

        <dd>
          <a href="http://www.tdwg.hyam.net/standards/tdwg_admin_files"
            >http://www.tdwg.hyam.net/standards/tdwg_admin_files</a>
        </dd>
        <dt>Legal:</dt>
        <dd id="legal">Link to legals come here.</dd>
      </dl>
    </div>
    
---++ Table of contents
%TOC%

---++ Introduction

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
      "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

    
---+++ Motivation

Historically TDWG Standards have taken diverse forms. They have included controlled vocabularies (such as lists of approved abbreviations) or transfer formats specified as XML Schema or even geographic regions specified on paper. TDWG Standards can therefore be made up of multiple files of different formats. The motivation behind this standard is to specify how these files should be presented. Other standards specify the content of the files more closely (see the Human Readable Documents and Cover Page standards).

This specification is aimed at developers of other TDWG standards.

    
---+++ Rationale

Users see a standard as a single 'product'. It is therefore important that, although TDWG standards may contain multiple files, they are presented to the user as a single entity and can be downloaded as a single archive. Because they need to be robust across multiple environments file names are tightly specified. To supply a uniform meta data interface all standards must contain a cover page file.
   
---+++ Types of standards and documents

TDWG standards consist of several documents that are held as files within a single archive.

There are three types of standard:
   1.       Administrative standards control the TDWG standards process.
   2.       Applicability statements on the use of existing TDWG and non TDWG standards.
   3.       De novo specifications for data modeling and data exchange.

All standards are treated the same no matter what their type.

There are 3 types of document:
    *       Type 1 documents are the normative parts of a standard.
    *       Type 2 documents are parts of the standard that are non-normative (informative)
    *       Type 3 documents are not part of the standard and may contain tutorials, introductory
              overviews, etc.

The three different document types are illustrated in Diagram 1 and Table 1.

{ Diagram Here }

Diagram 1: Illustrating the three types of document.
    
Table 1: Enumeration of document Types.      
 
 <table>
      <thead>
        <tr>
          <th/>
          <th>Type 1 </th>
          <th>Type 2</th>
          <th>Type 3</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>Normative</th>
          <td>Yes</td>
          <td>No</td>
          <td>No</td>
        </tr>
        <tr>
          <th>Part of a standard</th>
          <td>Yes</td>
          <td>Yes</td>
          <td>No</td>
        </tr>
        <tr>
          <th>Function</th>
          <td>Defines</td>
          <td>Explains and justifies</td>
          <td>Helps and Supports </td>
        </tr>
        <tr>
          <th>Versioned with Standard</th>
          <td>Yes</td>
          <td>Yes</td>
          <td>No</td>
        </tr>
        <tr>
          <th> Controlled by TDWG Process </th>
          <td>Yes</td>
          <td>Yes</td>
          <td>No</td>
        </tr>
        <tr>
          <th>Document format </th>
          <td>Tightly Controlled </td>
          <td>Tightly Controlled </td>
          <td>Not Controlled </td>
        </tr>
        <tr>
          <th>Language </th>
          <td>English </td>
          <td>English + translations</td>
          <td>Any</td>
        </tr>
      </tbody>
    </table>
This document specifies how Type 1 and Type 2 documents should be named and structured. It does not govern Type 3 documents.

---++ Contents of Standards
At a minimum, each standard must contain:
   * The normative (prescriptive) form of the standard itself. (e.g. XML Schema or human readable text).
   * A 'Cover Page' document that summarizes the content and context of the standard. (see Cover Page) 

Each standard may also contain:
    *       A 'Motivations' document that describes the reasons for the standards existence.
    *       A 'Rationale' document that describes why the standard takes the form it does.
    *       A 'Change History' document that describes how this version has changed since the last
              version.

For simpler standards the latter three documents (Motivations, Rationale and Change History) can be subsumed as sections of the Cover Page document (in which case they must then follow the tight formatting rules specified for that document) or as subsections of one of the human readable documents present in the standard.    

Standards may contain any number of other files provided they are of an appropriate format (see below). 

---++ Packaging of Standards

Standards take the form of a logical folder/directory but may be distributed as a zip or tar archive file. The name of the archive must be the file name of the standard followed by a period and the appropriate suffix if the standard is compressed.
   
---++ Naming of Standards

All standards have two names.
   * Full Name: Used in the cover page and as the title of the main document if it is human readable. The name must be in English.
   * File Name: A valid file name (according to the rules below) based on a shortened version of the full name.

A standards full name should be derived  [FIXME - Process Group]

A standards file name must start with &#8216;tdwg_&#8217; followed by an abbreviation to indicate the standards type (one of &#8216;admin_&#8217;, &#8216;applic_&#8217; or &#8216;spec_&#8217;) followed by a shortened version of the title (see below). Examples:
   * tdwg_admin_human_readable
   * tdwg_spec_tcs
   * tdwg_spec_abcd

A standard&#8217;s file name must be unique within the scope of TDWG standards.

---++ Versioning of Standards

Standards are not versions. Once they have been accepted it becomes static.

---++ File Formats

For archival reasons all files in a standard must be in an open format for which parsers are commonly available. For this purpose an open format is defined as being one for which it would be possible to write a parser on the basis of a published specification without having to rely on code libraries for which the source code is not available or to pay a license fee. The definition of &#8216;commonly available&#8217; is left to the discretion of the Executive Committee.

Formats that are currently considered to be acceptable include:
   * ASCII Text
   * XML
   * HTML
   * Portable Document Format (PDF)
   * Portable Network Graphic (PNG)

Formats that are currently considered not to be acceptable include:
   * Microsoft Word
   * Microsoft Access
   * Microsoft Excel

---++ File Naming
The following rules govern file names used in standards and for standards archives:
   * Names must start with a letter.
   * Letters must be lower case.
   * No spaces (replace with underscore).
   * No non ASCII characters.
   * No periods other than the one used to separate the suffix.
   * Suffix should be the commonly used suffix for file type and the three letter version where possible e.g. jpg rather than jpeg and xsl rather than xslt.