Item: Sample TIM-2.0.5 document
From: ftp://ftp.isogen.com/pub/tcif/ipi_tedd/ipi95001/mtext/main.sgm
Date: March 27, 1997
]>
TCIF-IPI-95-001:issue1:instance3
TEDD-Package-3.0
Telecommunications Industry Forum
TCIF-IPI-95-001
E
1995/11
The Telecommunications Electronic Document Delivery (TEDD) Package
The TEDD Package
Copyright (c) 1995, ATIS. This document is printed and distributed by the
Alliance for Telecommunications Industry Solutions ("ATIS") on behalf of the
Telecommunications Industry Forum ("TCIF"). Participants in TCIF are hereby
authorized to reproduce and distribute this document within their own business
organizations and to others for TCIF-related business provided that this notice
continues to appear in the reproduced documentation. Reproduction and
distribution for resale is prohibited.
TIM-2.0.5
Originally TIM-1.1.2
Issue 1 of a TCIF Guideline
Instance 1 created 95/11/06
TCIF-IPI-95-001:issueE:instance2
TCIF-IPI-4:issueB:instance1
IPI-4
B
SR-3031
1
IPI-95-004
1
Donald F. Pratt, (908) 699-4012, dfp@pekoe.ims.bellcore.com
Trademark Acknowledgments
COMMON LANGUAGE is a registered trademark of Bellcore
Contents
List of Figures
List of Exhibits
List of Tables
Introduction
Purpose and Scope of Document.
This document defines and describes the Telecommunications Electronic Document
Delivery (TEDD) package.
A TEDD package is a set of files and directories that are arranged, named, and
constrained to permit automated exchange of technical documentation in an
application-independent electronic form among organizations in the telecommunications industry.
The Telecommunications Industry Forum (TCIF) has been seeking voluntary industry
guidelines for electronic document delivery since 1988, when the benefits of electronic
information over paper — in availability, usability, and cost — were becoming apparent.
All members of the TCIF recognize the value of voluntary guidelines that avoid duplication
of systems and effort in the operations of telecommunications service providers. This
document provides such guidelines for the packaging of electronic
information products that may be provided in addition to or in place of paper documents.
If a document provider and a document recipient both use the same electronic formats for
documents (MS Word 6.0 text and WMF graphics, PageMaker 5 with TIFF graphics,
HTML 2.0 with GIF graphics, etc.), they should feel free to exchange documents in those
shared formats, but such a match will occur only occasionally. More often, they will need
to find a common ground. The TEDD package and related guidelines provide just that.
These guidelines are voluntary, subject to agreement of both the supplier and the recipient.
They are an option, not a requirement. They have the advantages over other options of
having been designed for interchange and having been tested by the participating members
of the TCIF Information Product Interchange Committee. Moreover, many of the
participants are making efforts to incorporate these guidelines into their documentation
processes and develop tools, some proprietary and some shared, to implement them.
Related guidelines to be published by the IPI Committee will describe the recommended
file formats for interchange of text, graphic, and other content of an electronic document.
Document providers who package their electronic documents according to the full set of
guidelines will be assured that, in most cases, recipients will be able to use them as intended
without special instructions, consultations, or technical support. Recipients prepared to
receive these packages will be able to follow the same steps to distribute, store, and use
documents from all participating providers. This means in particular that it will be possible
to use the same hardware, software, and procedures to view documents from all suppliers.
Neither these guidelines nor any other under development by the IPI Committee specify
a delivery medium for TEDD packages. Means of delivery (tape, diskette, CD-ROM,
transmission, ftp, etc.) will always need to be
agreed upon by originator and recipient.
Issues A through E of these Guidelines were drafts for review and comment during testing
and balloting. Having been adopted, these Guidelines are being published as Issue 1.
Organization of this Document
Section 1 provides an introduction to this document.
Section 2 describes the TEDD package in detail.
Section 3 describes the DocID SGML Document Type Definition used to encode
document-identification information in a TEDD package.
Referenced Standards
These guidelines are based on the following standards:
ISO 8879, Information processing — Text and office systems — Standard Generalized
Markup Language (SGML). Certain required and optional files in a TEDD package
conform to Document Type Definitions defined in conforming SGML syntax.
ISO/IEC 646, Information technology — ISO 7-bit coded character set for information
interchange. All text files in a TEDD package use the G0 character set of ISO 646,
equivalent to ASCII.
ISO 9660, Information processing — Volume and file structure of CD-ROM for
information interchange. The "strict naming convention" for TEDD filenames conforms to
ISO 9660 Level 1.
ISO/IEC 9070, Information technology — SGML support facilites — Registration
procedures for public text owner identifiers. Resource files used by a TEDD package
conform to the definition in Annex A of SGML formal public identifiers, and will
eventually be registered according to ISO 9070.
ISO 639, Codes for the representation of names of languages. Languages used in TEDD
package contents are identified according to this standard.
Also referenced:
Coded Representation of the North American Telecommunication Industry Manufacturers,
Suppliers, and Related Service Companies, Bellcore ST-STS-002006, and Common
Language Bellcore and Regional Holding Company Codes, BR 751-100-175. Document
identifiers use COMMON LANGUAGE[®](REGTM) codes for the owners of documents.
Related Document
IPI-95-004, available December 1995, describes Telecommunications Industry Markup (TIM),
the markup language recommended for marked text as defined here
[ (Section 2.2.3, page 2-7)](SECTION).
Future IPI documents will deal with graphics and multimedia file formats.
Acronyms
The following acronyms are used within this document:
ASCII
American Standard Code for Information Interchange, which defines the 7-bit
encodings of the characters seen on a standard computer keyboard, plus control
characters (128 characters in all). In this document ASCII is referenced as ISO 646.
Text and marked-text files in a TEDD package must contain only ASCII characters.
DTD
Document Type Definition, a specification for the SGML markup of a particular
type or class of document. These guidelines contain a simple DTD
[ (Exhibit 3-1, page 3-1)](EXHIBIT)
for the contents of the docid file that identifies the document in a TEDD
package. IPI-95-002 contains the TIM DTD, which specifies the markup recommended
for technical documents interchanged in TEDD packages.
HP-PCL
Hewlett-Packard Printer Control Language, one of several possible formats
for printer-ready files in a TEDD package.
HTML
Hypertext Markup Language, an informal standard for markup of documents
accessible on the World Wide Web. Recent versions of HTML have been defined in
SGML DTDs. HTML is oriented toward general-purpose browsers, so it does not
provide thestructural and semantic detail found in specialized DTDs like TIM.
ISO
International Organization for Standardization.
SGML
Standard Generalized Markup Language, an international standard (ISO 8879)
for markup of text components of documents. Normally the textual content of a
document interchanged in a TEDD package would be marked up according to one or
another SGML DTD — most likely TIM, possibly HTML or something else. The
docid file is also SGML. Because it is rigorously defined, SGML allows automated
translation into other markup languages, rigorous or not; conversely, translation into
SGML from a less rigorously defined language usually requires cleanup.
TEDD
Telecommunications Electronic Document Delivery, describing the package
that contains the components of a document interchanged according to these
guidelines.
TIFF
Tagged Image File Format, one of several possible formats for raster-graphic files
in a TEDD package.
TIM
Telecommunications Industry Markup, the SGML DTD developed by the TCIF
IPI Committee and recommended by the Committee for markup of the text in
documents interchanged in TEDD packages. It is defined and described in IPI-95-002.
TEDD Directories and Files
This section describes the organization of a Telecommunications Electronic Document
Delivery (TEDD) package. A TEDD package provides a specific way to organize electronic
documents for intercorporate exchange.
Naming of directories and files
A TEDD package is organized as a hierarchical collection of directories containing data
files. Some files and directories in a TEDD package have specific names designated in this
section. Others will be named by document producers. In order to facilitate cross-platform
transfer, however, all file and directory names in a conforming TEDD package should meet
the filename requirements stipulated below.
A given TEDD package will use one of two conventions for naming directories and files:
a
strict naming convention
that will allow the package to be moved into an MS-DOS
environment, or an
extended naming convention
that will not work in an MS-DOS
environment. Either naming convention will work with most other common operating
systems: UNIX, MacIntosh, and mainframe. Document producers and recipients should
agree on which naming convention they will use before document exchange occurs.
The strict naming convention
Under the strict naming convention:
Each directory name and file name will consist either of a
basename alone or of a
basename followed by a
period (.) followed by a
suffix.
Each basename may consist of up to
8 characters.
Each suffix may consist of up to
3 characters.
Basenames and suffixes must begin with a letter or a digit and may be composed of
letters (A-Z), digits (0-9), and underscores (_). No other characters may be used.
Letters must be either all lower-case or all upper-case throughout a TEDD package
(e.g., "FILEA.TXT" or "filea.txt," but not "FileA.txt").
This naming convention is equivalent to ISO-9660 Level 1, except that lower-case letters
are allowed as an alternative to upper-case. All directory and file names in a TEDD package
must be either upper-case-only or lower-case-only. Lower case is recommended.
Note that in the strict naming convention it is not possible to distinguish between files by
the case used in file names, since all file names in a package must use the same case.
The extended naming convention
Under the extended naming convention:
Each directory name and file name will consist either of a
basename alone or of a
basename followed by a
period (.) followed by a
suffix.
Each basename may consist of up to 32 characters.
Each suffix may consist of up to 8 characters.
Basenames and suffixes must begin with a letter or a digit and may be composed of
upper- and lower-case letters, digits, hyphens (-), and underscores (_).
Case distinctions among letters in file names distinguish separate names
(that is, the names "FILEA.TXT" and "fileA.txt" identify two different files.)
Document producers who choose to create TEDD packages using the extended naming
convention should be prepared to convert all file names to the strict naming convention for
customers who need MS-DOS-compatible names. There is no specific requirement that
extended-convention file names remain unique when truncated to 8.3 characters, but some
systematic way to convert from extended to strict file names while maintaining uniqueness
is advantageous.
File-naming example: Bellcore documents
Bellcore documents have identifiers of up to 25 characters, and the first 8 (or even 11) are
unlikely to be unique. Most documents also have an issue number, up to 3 characters, and
some have a "tag-along" (revision level, bulletin, or supplement) number,
also up to 3 characters. Several non-alphanumeric characters are allowed to appear in an
identifier; alphabetical characters are always upper-case.
Bellcore wishes to be able to name its TEDD document-root directories so that the
document ID and issue and tag-along numbers can be determined from the name (this is a
convenience, not a requirement of TEDD). But it also wishes to be able to conform to the
requirements of the strict naming convention when customers request it.
Therefore it has adopted the naming convention
shown in Table [2-1](TABLE). Under this strategy, the full file names can
be truncated to 8.3 characters and conform to the strict naming
convention and ISO 9660 Level 1, while remaining unique.
Example of TEDD file naming:
Bellcore's convention for document root directories
Basename char 1-6
Basename char 7-31
Period
Suffix char 1-3
Suffix char 4-7
000001
SR-3031
.
001
000002
BD-PICS_DCPR-REQ3_4-1
.
001
R001
6-character
left-padded
number
assigned
sequentially
(guaranteed
to be unique).
Bellcore's document ID, with
characters not legal in TEDD
file names (e.g., "/" and ".")
replaced by "_". Not padded
(terminated by "."). Shortened
to "SR," "BD," etc., to
conform to strict naming
convention.
Omitted if
there is no
issue
number
and no
tag-along
number.
3-character
left-padded
issue number
("000" if
there is a tag-
along ID but
no issue
number).
Tag-along ID:
R=revision level,
B=bulletin, or
S=supplement,
plus 3-char. tag-
along number.
Omitted for strict
convention.
Standard filename suffixes
TEDD-package file names should use the standardized suffixes listed in the table below for
data files whenever possible. Document producers may define additional unique suffixes
for data types not standardized. Nonstandard suffixes should be defined in a
readme
file contained in the TEDD Package.
Filename suffixes and directory names for TEDD data
types
Filename Suffix
Data Type
Directory Name
.afp
Advance Function Printing Data Stream
cdoc[a](FNOTE) or
binary[b](FNOTE)
.au
Audio file
au
.bmp
Windows Bitmap
bmp
.c3
CCITT Group 3 fax
fax
.c4
CCITT Group 4 fax
fax
.cgb
CGM Binary
cgm
.cgc
CGM Clear Text
cgm
.cgm
CGM Character
cgm
.eps
Encapsulated PostScript
ps
.eqn
troff eqn markup
troff
.gif
GIF (Compuserve GIF)
gif
.htm
HTML (SGML) markup
mtext[c](FNOTE) or
html
.jpg
JFIF (JPEG)
jpeg
.mid
MIDI
midi
.mov
Video file
mov
.mpg
MPEG
mpeg
.mt
MT SGML markup
mtext
.pbm
Portable BitMap
ppm
.pcl
HP PCL printer file
cdoc[a](FNOTE) or
binary[b](FNOTE)
.pct
QuickDraw PICT
pict
.pcx
PC Paintbrush
pcx
.pdf
Portable Document File
cdoc[a](FNOTE) or
binary[b](FNOTE)
.pgm
Portable GrayMap
ppm
.pic
troff pic graphic
troff
.ppm
Portable PixMap
ppm
.ps
PostScript
cdoc[a](FNOTE) (if complete document) or
ps (if included file)
.q
Q text markup
mtext
.qt
Quicktime video
qt
.rtf
Rich Text Format
rtf
.sun
SunRaster
sun
.tbl
troff tbl markup
troff
.tex
TeX or LaTex
tex
.tif
TIFF
tiff
.tim
TIM SGML markup
mtext
.txt
Flat character text
txt
.wav
WAVe audio
wav
.xwd
X/Windows Dump
xwd
(Other)
Other (binary) data file
binary[b](FNOTE)
(Other)
Other (ASCII/ISO 646) data file
other[b](FNOTE)
Only one file type may be included in the
cdoc
directory
Alternative is to use a directory with same name as filename suffix.
mtext directory must not be empty, but may be linked to
html directory.
There is no special directory for source files (FrameMaker, Interleaf, Microsoft Word, etc.),
or browser files (Dynatext, Superbook, WorldView, etc.), which generally would not be
included in a TEDD package, but which, if they were, would be in the
binary
or
other
directory.
Organization of a simple one-document package
A TEDD package is organized as a hierarchical collection of directories containing data
files. Directories and files are organized primarily by function and data type. Some
files and directories are required, some are optional. A TEDD package may contain either
a single document or a number of documents, and it may contain additional resources
(libraries of DTDs, SGML entities, graphics, etc.). This section describes the simplest type
of TEDD package: a one-document package that contains no resources packaged separately
from the document itself. Section [2.3, page 2-9](SECTION),
describes more complex packages.[1](FNOTE)
Information that is less than a complete document (a uniquely identified information product) cannot constitute
a TEDD package under the current version of these guidelines. This means that revisions to a document must be
incorporated into the document, and the whole document directory structure with all constituent files redelivered
in a new TEDD package. A more flexible revision model is under development.
A simple one-document package consists of a single TEDD document. Every TEDD
document itself consists of a document-root directory and a set of subdirectories and files,
as shown in Figure [2-1, page 2-6](FIGURE).
A single-document TEDD package
A required directory named
adm
("administration") contains files with information
necessary or useful for the management of documents as a whole. In particular, it contains
a file called
docid
used to identify the document.
A required directory named
mtext
("marked text") contains files with versions of document
contents that employ textual markup languages, especially SGML languages. It should
always include a file with the basename
main
that contains or points to the main body of
document text in an appropriate markup language. An extension such as
tim
or
q
specifies
which markup language[ (Table 2-2, page 2-3)](TABLE). Files included in the mtext directory should
be application-independent and interchange-oriented: At this time only SGML files
(including HTML) are considered appropriate.
An optional directory named
cdoc
("canonical document") contains files from which the
exact paper document (or other "official" version) can be reproduced. Only one type of file
— HP-PCL, PostScript, WorldView, etc. — may be included in a given cdoc directory (and
there may be at most one
cdoc
directory within a document root directory), so that there is
no doubt about what constitutes the canonical document.
Additional optional directories contain various versions of document components — e.g.,
raster and vector graphics. Each of these directories is named for the
type of data representations it contains. For example, a directory named
tiff
would contain
TIFF versions of some document components.
The remainder of this section describes these files and directories in more detail.
The document root directory
Every document has a root directory that is the parent directory for all document
components. The name of the root directory is the choice of the document producer, but the
root directory name must be unique in its local context (i.e., among its peer directories) and
must satisfy requirements for file and directory names. Note that the root directory will not
be named in all circumstances — for example, if a TEDD package exists on a tape and
consists only of one document with no additional libraries, the document-root directory
may be the same as the root directory of the tape.
Normally, documents represented in TEDD form will employ SGML markup, and
many of these documents will need to specify file names for various SGML entities (e.g.,
graphic files, entity-reference files). By convention the document root directory of the
active TEDD document may be referred to in an SGML file by the string #DOC-ROOT.
For example, an element <Graphic> might identify a file in the following manner:
<Graphic file="#DOC-ROOT/tiff/graphic1.tif">
(The file attribute is hypothetical; it does not exist in TIM SGML.) Note that the package root
directory of a complex TEDD package (Section [2.3.1](SECTION)) may be
referred to by the string #PKG-ROOT. The document root directory and package root directory are
equivalent in a single-document package, but #PKG-ROOT should
not
be used to refer to
that directory, since single-document packages may become parts of multidocument
packages, and then #PKG-ROOT will no longer refer to the same directory.
Administrative information: the
adm
directory
Every TEDD document must include one directory named
adm
("administration") which is a direct child of
the document-root directory.
It contains information used to identify and manage
document packages. At a minimum each
adm
directory will contain a
docid
file that
identifies the TEDD package and the document it contains. The
docid
file itself contains
SGML markup that specifies the document's number, title, owner, and publication date, as
well as other information. For a complete description of the SGML markup contained in
the docid file, see Section [3](SECTION).
Primary textual components: the
mtext
directory
Any TEDD Document will include files that contain text representations of some document
contents using SGML markup languages (or other markup languages). These files should
be placed in a directory named
mtext
(for "marked text") that is a direct child of the
document root directory.
Each TEDD package must include one file that contains a marked-text representation of the
document body using a markup type agreed to by the document producer and the document
recipient. The file may contain all document contents directly or it may employ "inclusion"
mechanisms appropriate to its type. The file must have the basename
main
and the suffix
appropriate to the markup type. Some common markup types are listed in Table
[2-2](TABLE).
Most likely, a TEDD package will use TIM markup for its textual mainstream, and so it will have an
mtext
directory that includes the file
main.tim. The
main.tim
file will contain a valid
TelDoc document instance. The
main.tim
file may contain the entire contents of the
TelDoc
document instance directly or it may use SGML entity references to organize a set
of files that together contain the entire document instance. Separate SGML files containing
only portions of the document (e.g., an alternative SGML representation of a table) should
also be in the
mtext
directory.
The
mtext
directory should contain only document files. Declaration
files such as DTDs and entity sets should be in the
lib
directory of a complex TEDD package
[ (Section 2.3.3)](SECTION).
Canonical document representations: the
cdoc
directory
The electronic form of a document delivered in a TEDD package may or may not be
considered by its owner to be the "official" form. Sometimes a document producer may
wish to supply a viewable version of the document that is in a different, "official" electronic
form, or files that can be used to print or view a copy of a document producer's "official"
paper document. If so, the files containing this representation should be placed in a
directory named
cdoc (for "canonical document"), which is a direct child of the document
root directory. Typically the data will
take the form of the page-description language
(HP-PCL, InterPress, PostScript, etc.) used to print the paper document.
Alternatively, it may be in a form meant for on-line viewing with a particular "browser"
application (Acrobat, FrameViewer, Olias, etc.).
Often the data that can be used to print the document will exist entirely in one file. When
this is the case, it is recommended that this file be named with the basename
cdoc
and a
suffix that indicates the type of data contained in the file (e.g.,
cdoc.ps). When the document
comprises several print files, they should be named so that their sequence is obvious —
cdoc1.ps,
cdoc2.ps, etc.
Flat-character text: the
txt
directory
Any TEDD package may include files that contain flat-character representations of some
of the document contents. If so, these files must be placed in a directory named
txt
which is a direct child of the document root directory, and should use the filename suffix
.txt. A
document producer might use this directory, for example, to include flat-character versions
of document tables, preformatted for 80-column character displays.
Flat character text should employ the 7-bit International Reference Version (IRV) character
set defined in ISO 646 minus the characters usually used as control characters
(characters with decimal values 0-8, 11-12, 14-32, or 127)[2](FNOTE). More specifically, flat-
character text should use only characters declared in the described character-set portion of
the SGML declaration used to establish the Reference Concrete Syntax for SGML as
defined in ISO 8879.
The only difference between ISO 646 and ASCII is the substitution of the international currency symbol (¤) for
the dollar sign ($). And, in fact, that character should be rendered "$" in a TEDD document unless another symbol
is specified (this should be noted in a
readme
file).
CHARSET BASESET "ISO 646-1983//CHARSET International Reference Version (IRV)//ESC 2/5 4/0"DESCSET 0 9 UNUSED 9 2 9 11 2 UNUSED 13 1 13 14 18 UNUSED 32 95 32 127 1 UNUSED
(Character 9 is tab, character 10 is linefeed, and character 13 is carriage return.) All
characters in flat-character text, including white-space characters, are considered
significant data. Flat-character text contains no markup of any sort, including any
references to special characters. A text file with notations for special characters, subscripts
and superscripts, etc., must be placed in the mtext directory; its notation, if not standard,
should be described in a readme file.
Other document components
In addition to the files described above, most TEDD documents will include
files providing a variety of representations of
portions of the document's
contents. A document producer might include, for example, document graphics in various
vector and/or raster formats.
A separate directory should be created for each separate data representation used to encode
document components. The directory's name should be as shown in Table
[2-2, page 2-3](TABLE). If the file type is not listed there, the file
should be in either the
binary
or
other
directory,
or in directory whose name is exactly the same as the filename suffix used to indicate the
data representation in question. For example, while a TIFF file (listed in Table [2-2](TABLE)) should
have a filename suffix of
.tif
and be in a directory named
tiff, a Corel Draw file with a suffix
.cdr
(not listed in Table [2-2](TABLE)) should be in either the catch-all
binary
directory or in a
directory named
cdr. If it's anywhere else, it might not be found.
Note that these guidelines allow and encourage a document producer to include multiple representations
of the same document contents. For example, a document producer might include a raster
and a flat-character version of a document table, as well as two different SGML versions,
so that various recipients using browsers with different capabilities will be likely to find
at least one usable representation.
A TEDD document is organized primarily by the type of data representation contained in a
file, not by the semantics of the files' contents or their sequence in the document.
Therefore, a TIFF version of the table will be found in the
tiff
directory with TIFF versions of other document components, while a
flat-character version of the same table would be in the
txt
directory and SGML versions would be in the
mtext
directory. It is other aspects of the data contained in the TEDD
document (e.g., the defined semantics of a particular SGML language), not the TEDD file
hierarchy, that indicate semantic and sequential relationships among the data in the separate files.
Complex TEDD packages
A single TEDD package may contain any number of documents, and it may contain a
library of resources, including DTDs or files shared by multiple documents. Either of these
conditions (multiple document root directories, or a
lib
directory) make the package a
"complex" TEDD package requiring another layer in the directory structure, with its own
adm
directory and
docid
file. (Note that if a document is published as a core document plus
revisions, supplements, etc., each separately published part of the document will need a
document directory structure, with its own document root directory. This
means that complex TEDD packages are likely to be common.)
At the highest level in its hierarchy, an TEDD package will look as shown in
Figure [2-2, page 2-10](FIGURE).
The top level of a TEDD package
The package root directory
Every TEDD package has a root directory that is the parent directory for all other
components in the data package. If the root directory is named, the name is the choice of
the document producer, but the root directory name must be unique in its local context (i.e.
among its peer directories) and must satisfy requirements for directory names. Note that the
root directory will not be named in all circumstances — for example, if a TEDD package
exists on a tape, the package root directory may be the same as the root directory of the tape.
Many documents represented in TEDD form will employ SGML markup languages, and
many of these documents will need to specify file names for various SGML entities (e.g.
graphic files, entity-reference files). By convention the package root directory of a
multidocument package may be referred to in an SGML file by the string #PKG-ROOT.
(Note that the document root directory for a given document, as described in
Section [2.2.1](SECTION),
may be referred to by the string #DOC-ROOT.) For example, a graphic file might be
identified in the following manner in an SGML entity reference:
<!ENTITY logo SYSTEM "#PKG-ROOT/lib/gif/logo.gif" NDATA GIF>
Administrative information: the
adm
directory
Every multi-document TEDD package must include one directory named
adm
which is a
direct child of the package root directory. This is in addition to the
adm
subdirectory of each document root directory.
Each
adm
directory must contain one file named
docid
which contains a valid DocID
SGML document instance that identifies the package as a whole.
The
adm
("administration") directory contains information used to identify and manage
document packages. At a minimum each
adm
directory will contain a
docid
file that
identifies the overall TEDD package. The
docid
file itself contains SGML markup that
specifies the package number and owner, plus other information that depends on the nature
of the package. Some of the information will be like that in a single-document
docid
file, but some will differ: For a complete description of the
docid
file, see Section [3](SECTION).
The lib directory
A complex TEDD package may contain an optional directory named
lib (for "library") to
hold reusable resources. If, for example, a document producer used the same disclaimer
from document to document, it could place the disclaimer in the
lib directory (or one of its
subdirectories) and refer to it appropriately in each separate document (e.g., through the use
of an SGML entity reference).
Depending on the needs of a given TEDD package, a
lib directory may be simple (with no
subdirectories) or complex, as shown in Figure [2-3, page 2-12](FIGURE).
lib directory organization
If a
lib
directory contains only a few files, it need not employ subdirectories. If, however,
a document producer needs to pass a complex library, it is recommended that the
lib
directory be subdivided into appropriate subdirectories. These subdirectories and the files
they contain should use the same names and organizational conventions as document
directories whenever possible — that is, a library of TIFF files should be placed in a
directory called
tiff, a library of SGML-marked text files should be placed in a directory
called
mtext, etc. A document producer who wishes to include files of SGML declarations
(DTDs, entity reference sets, etc.) should create a directory called
sgml to hold them.
Note that an
sgml directory may exist only as a subdirectory of a
lib directory, not as a
subdirectory of a document root directory (SGML files there must be in the
mtext directory).
Special circumstances
Large files
Large file sizes may be a problem for some recipients. If a
main.xxx
file is larger than 3 megabytes, originators should be prepared to put some of its content into
files that can be included by reference. Similarly, if a print file in the
cdoc
directory would be over
3 MB, originators should be prepared to create smaller print files according to the sections
or other subdivisions of the document.
Release notes (readme's)
for other special circumstances
A document producer should document in
readme
files any anomalies and any
assumptions or conventions used in the construction of the TEDD package other than those
stated in these guidelines. Any directory in a TEDD package may contain a
readme file. Comments that apply to the organization or contents
of an entire TEDD package should be placed in a
readme file in the package-root directory.
Comments that apply to the organization or contents of an entire document should be
placed in a
readme file in the document-root directory. Comments specific to files within
a particular directory should be placed in a
readme file in that directory.
Document Identification
Introduction
Each TEDD package contains a file called
docid
in its
adm
directory. And if it is a complex
package (explained in Section [2.3](SECTION)), there is another
docid
file in the
adm
directory of each
document root directory. The
docid
file contains an SGML
DocID
document instance.
The
DocID
instance provides information that uniquely identifies the document in
question, as well as other information potentially useful to document-management agents.
This section describes the DocID document type and the elements that make it up.
The DocID DTD
Valid
DocID
markup should conform to the SGML declaration set identified by the
public identifier "-//USA/TCIF//DTD DOCID-3//EN" [ (Exhibit 3-1)](EXHIBIT).
Sample
docid
files are provided in [Section 3.6](SECTION).
Entity names in SGML files may contain
hyphens (-) but not underscores (_), per ISO 8879.
Under the strict naming convention, file names in TEDD packages may contain underscores
but not hyphens, per ISO 9660. Entities do not name files
directly, so this is not a problem to systems, although it
may be confusing to humans.
The DocID DTD (line numbers are not part of the file).
<!-- DTD for DocID ("document identification") markup.< Release: @(#) 3.1.4 95/11/07 (docid_3.dtd). Typical invocation: <!DOCTYPE DocID PUBLIC "-//USA/TCIF//DTD DOCID-3//EN" [ ]>--><!-- In version 3.1.4, the copyright notice and disclaimer were updated. In version 3.1.3, the Publisher element was added. In version 3.1.2, DocNo.u was made an option for RelDoc, SubDoc, etc. In version 3.1.1, TitleGroup was made mandatory, to match TIM. In version 3.1.0, the AltNo, ISN, and EDocRepl elements were added, the various title elements were renamed to conform to TIM, and the Abstract element was renamed Abs. The Company element was redefined to be the common name of the originating company, and the COMMON LANGUAGE code for the company was required to be delimited by "-" in the EDocID element. In version 3.0.1, the Facets element was removed, the DN.ed element (edition) was added, and comment dates were made year/month/day. In version 2.0.1, the Facets element was added and the Keyword element renamed Keywords to avoid misinterpretation. The content model of DocRepl was made consistent with those of SubDoc, RelDoc, etc. Line spacing and element capitalization were made consistent. Also, the Ti.short element was added and the content model of TitleGroup redefined for consistency with the TIM DTD. In version 1.1.7, the DN.rvl element was added, for Revision Level - i.e., a file containing the base document plus interfiled revisions (all revisions up to Revision N, the number used in DN.rvl). --><!ENTITY % cdc "(#PCDATA)" -- Core-text data-content. Redeclaration of PCDATA, in case we need to add to it. --><!ELEMENT Docid -- Document Identification -- - O (EdocID,Class,Company,(DocNo|DocNo.u),DocDate, TitleGroup,AltNo*,Publisher?,ISN*,Country*,Copyrt?, Lang*,(SuperDoc|SubDoc)*,Status*,PropStat?, EdocRepl*,DocRepl*,ProdDsc*,DocDsc?,RelDoc*, Contact*,Au*,Abs?,Keywords?) ><!ELEMENT EdocID -- Unique Electronic Document ID -- - O (%cdc;)* ><!ELEMENT Class -- Document Instance Class -- - O (%cdc;)* ><!ELEMENT Company -- Company Code -- - O (%cdc;)* ><!ELEMENT DocDate -- Document Publication Date -- - O (%cdc;)* ><!ELEMENT TitleGroup -- Title Group -- - O (SuperTitle*,Title,SubTitle*,ShortTitle?) ><!ELEMENT Title -- Title -- - O (%cdc;)* ><!ELEMENT SubTitle -- Subtitle -- - O (%cdc;)* ><!ELEMENT SuperTitle -- Supertitle -- - O (%cdc;)* ><!ELEMENT ShortTitle -- Short Title -- - O (%cdc;)* ><!-- Document Number Elements --><!ENTITY % dn.z -- Optional document number subfields -- "DN.iss|DN.ed|DN.addm|DN.rev|DN.rvl|DN.vol|DN.apdx| DN.bull|DN.supp|DN.rlse|DN.lang| DN.date|DN.prod|DN.country|DN.customer" ><!ELEMENT DocNo.u -- Document Number (unfielded) -- - O (%cdc;)* ><!ELEMENT DocNo -- Document Number -- - O (DN.base,(%dn.z)*) ><!ELEMENT DN.base -- Base Document Number -- O O (%cdc;)* ><!ELEMENT DN.iss -- Issue -- - O (%cdc;)* ><!ELEMENT DN.ed -- Edition -- - O (%cdc;)* ><!ELEMENT DN.addm -- Addendum -- - O (%cdc;)* ><!ELEMENT DN.rev -- Revision -- - O (%cdc;)* ><!ELEMENT DN.rvl -- Revision level (for base document that incorporates interfiled revisions up through the revision of the same #) -- - O (%cdc;)* ><!ELEMENT DN.vol -- Volume -- - O (%cdc;)* ><!ELEMENT DN.apdx -- Appendix -- - O (%cdc;)* ><!ELEMENT DN.bull -- Bulletin -- - O (%cdc;)* ><!ELEMENT DN.supp -- Supplement -- - O (%cdc;)* ><!ELEMENT DN.rlse -- Release -- - O (%cdc;)* ><!ELEMENT DN.lang -- Language -- - O (%cdc;)* ><!ELEMENT DN.date -- Date -- - O (%cdc;)* ><!ELEMENT DN.prod -- Product -- - O (%cdc;)* ><!ELEMENT DN.country -- Country -- - O (%cdc;)* ><!ELEMENT DN.customer -- Customer -- - O (%cdc;)* ><!-- Optional Document Identification Elements --><!ELEMENT AltNo -- Alternative Identifier (e.g., Part #) -- - O (%cdc;)* ><!ELEMENT Publisher -- Publisher (if different from Company) -- - O (%cdc;)* ><!ELEMENT ISN -- ISBN or ISSN standard number -- - O (%cdc;)* ><!ELEMENT Country -- Country Codes -- - O (%cdc;)* ><!ELEMENT Copyrt -- Copyright Information -- - O (%cdc;)* ><!ELEMENT Lang -- Language Codes -- - O (%cdc;)* ><!ELEMENT SuperDoc -- Superdocument of current document -- - O ((DocNo|DocNo.u),(Title|TitleGroup)?) ><!ELEMENT SubDoc -- Subdocument of current document -- - O ((DocNo|DocNo.u),(Title|TitleGroup)?) ><!ELEMENT Status -- Document Status -- - O (%cdc;)* ><!ELEMENT PropStat -- Proprietary Status -- - O (%cdc;)* ><!ELEMENT EdocRepl -- EdocID of replaced document -- - O (%cdc;)* ><!ELEMENT DocRepl -- Document Replaced by this document -- - O ((DocNo|DocNo.u),(Title|TitleGroup)?) ><!ELEMENT ProdDsc -- Product Description -- - O (%cdc;)* ><!ELEMENT DocDsc -- Document Description -- - O (%cdc;)* ><!ELEMENT RelDoc -- Related Document -- - O ((DocNo|DocNo.u),(Title|TitleGroup)?) ><!ELEMENT Contact -- Contact -- - O (%cdc;)* ><!ELEMENT Au -- Author -- - O %cdc; ><!ENTITY % adc "%cdc;" -- Content model for abstract. Parameterized to allow redefinition. --><!ELEMENT Abs -- Abstract -- - O (%adc;)* ><!ELEMENT Keywords -- Keywords pertaining to document subject matter -- - O (%cdc;)* ><!-- Entity declaration sets for special characters that may be used --><!ENTITY % ISOgrk1 PUBLIC "ISO 8879-1986//ENTITIES Greek Letters//EN"><!ENTITY % ISOnum PUBLIC "ISO 8879-1986//ENTITIES Numeric and Special Graphic//EN"><!ENTITY % ISOtech PUBLIC "ISO 8879-1986//ENTITIES General Technical//EN"><!ENTITY % ISOpub PUBLIC "ISO 8879-1986//ENTITIES Publishing//EN">%ISOgrk1; %ISOnum; %ISOtech; %ISOpub;
The SGML Declaration
The DocID DTD employs the SGML declaration that is listed below. It is the one recommended
by the Information Products Interchange (IPI) Committee of the Telecommunications
Industry Forum (TCIF). The TCIF declaration upgrades many SGML quantities and
capacities beyond those listed in ISO 8879 for a basic SGML document.
Conforming DocID-processing applications must be capable of supporting the provided
SGML declaration and must not require functionality beyond that declared in this
declaration.
The TCIF SGML declaration
(line numbers are not part of the file)
<!SGML "ISO 8879:1986" -- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- TCIF SGML Declaration. Version: @(#) 6.0.3 95/06/21 (tcif_6.dcl) This declaration must appear first in the data stream constituting a conforming TCIF SGML document. The stream should also include a TCIF DTD. The components of the declaration are introduced by the keywords CHARSET (BASESET DESCSET), CAPACITY, SCOPE, SYNTAX, FEATURES, APPINFO. ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 94/12/02 --CHARSET BASESET "ISO 646-1983//CHARSET International Reference Version (IRV)//ESC 2/5 4/0"-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- The character set for SGML is the ISO-standard version ASCII ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 95/06/05 --DESCSET 0 9 UNUSED 9 2 9 11 2 UNUSED 13 1 13 14 18 UNUSED 32 95 32 127 1 UNUSED-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- Characters 0-31 and 127 are control characters, and the DESCSET section specifies that only tab (9), linefeed (10), and carriage return (13) are meaningful. ("0 9 UNUSED" means 9 characters beginning with #0 are not used meaningfully in the data stream.) ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 94/12/02 --CAPACITY SGMLREF TOTALCAP 2000000 ENTCAP 1000000 ENTCHCAP 1000000 ELEMCAP 1000000 GRPCAP 1000000 EXGRPCAP 1000000 EXNMCAP 1000000 ATTCAP 1000000 ATTCHCAP 1000000 AVGRPCAP 1000000 NOTCAP 1000000 NOTCHCAP 1000000 IDCAP 1000000 IDREFCAP 1000000 MAPCAP 1000000 LKSETCAP 1000000 LKNMCAP 1000000-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- Capacities have been increased from the "reference capacity set", so that large documents will not automatically generate parsing errors. (In "basic SGML documents," capacities are set at 35,000.) Roughly, this section means that systems used to validate TCIF SGML documents must be able to store up to 2 million bytes of markup definitions, IDs and IDREFs to ensure that they can accurately parse the data stream. ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 95/06/05 --SCOPE DOCUMENT-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- The scope of this declaration is the entire document. Any DTD or other prolog you include must conform to it, as well as document content - not hard, since this declaration is less restrictive than the default. ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 94/12/02 --SYNTAX-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- This declaration does not use the "reference concrete syntax," which means it won't necessarily be processable by every "conforming SGML application." The differences from the reference syntax are in the QUANTITY subsection, where several sizes and counts are increased. ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 95/06/05 --SHUNCHAR CONTROLS 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 127 255BASESET "ISO 646-1983//CHARSET International Reference Version (IRV)//ESC 2/5 4/0"DESCSET 0 128 0FUNCTION RE 13 RS 10 SPACE 32 TAB SEPCHAR 9NAMING LCNMSTRT "" UCNMSTRT "" LCNMCHAR "-." UCNMCHAR "-." NAMECASE GENERAL YES ENTITY NO-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- Names are automatically converted to upper case, except for entities. ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 94/12/02 --DELIM GENERAL SGMLREF SHORTREF SGMLREFNAMES SGMLREFQUANTITY SGMLREF NAMELEN 64 LITLEN 8192 ATTCNT 256 GRPCNT 253 GRPGTCNT 253 TAGLVL 128-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- Names (of elements, attributes etc.) may be 64 characters, not just 8. There may be 256 attributes in an ATTLIST, not just 40. There may be 256 (not 32) tokens in a group, and 1024 (not 96) in a content model. Elements may be nested to 128 levels, not 24. A literal (a parameter or attribute value in quotes) may be 8192 characters, not just 240. ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 95/06/21 --FEATURESMINIMIZE DATATAG NO OMITTAG NO RANK NO SHORTTAG YESLINK SIMPLE NO IMPLICIT NO EXPLICIT NOOTHER CONCUR NO SUBDOC NO FORMAL YES-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- OMITTAG and SHORTTAG are used in "basic SGML documents," but FORMAL is not. It means public identifiers must defined in a formal way. ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 94/12/02 --APPINFO NONE-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- No application-specific information is specified. ---- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 94/12/02 -->
Required components of the
docid
file
SGML DOCTYPE declaration
Any valid SGML document instance begins with a DOCTYPE (document-type)
declaration. A TEDD
DocID
instance conforming to Issue 1 of these guidelines must begin
with:
<!DOCTYPE DocID PUBLIC "-//USA/TCIF//DTD DOCID-3//EN">
Optionally, it may include additional entity declarations and entity references that allow the use of
characters not in the ASCII character set. Any ISO or TCIF special-character entity
set may be used in addition to the four declared in the last lines of the DocID DTD. Put the
declaration and the entity reference between the square brackets of the declaration below.
<!DOCTYPE docid PUBLIC "-//USA/TCIF//DTD DOCID-3//EN" []>
The DocID document instance: <DocID>
After the DOCTYPE declaration, the
DocID
instance begins. It must begin with
<DocID>
and end with
</DocID>
Between the start-tag and end-tag there must be the six required elements and there may be
others.
Electronic-document identifier: <EdocID>
Each
DocID
instance must contain an
EdocID
element ("electronic-document
identifier") as its first element, with data content sufficient in and of itself to uniquely
identify the TEDD package of which it is a part. In particular, it must distinguish the TEDD
package in question from any other TEDD package containing the same document.
This identifier is needed because it is possible that more than one TEDD package exists for
the same document. For example, a document producer might send a TEDD package for
Document X one week, discover that some part of the package was incorrect or incomplete,
and send an entirely new, corrected TEDD package for the same document the next week.
Alternatively, a document producer might find a way to make its textual markup more
sophisticated and decide to reissue Document X in the new form to interested recipients. In
either case, more than one TEDD package exists for the same document (same document
number, same issue, same contents). Clearly, the data sufficient to uniquely identify a
particular document (e. g., document number) is not sufficient to distinguish among
multiple TEDD packages for the same document. The
EdocID
element contains an identifier that does so distinguish.
To ensure uniqueness of identifiers within the telecommunications industry, the
COMMON LANGUAGE company code designating the company
that owns the document[ (Section 3.4.5, page 3-9)](SECTION) must be the first part of the
EdocID
content. Then there must be a hyphen, "-", since COMMON LANGUAGE company codes vary in
length. Beyond that, the precise contents of the
EdocID
element are the choice of the document producer — it is each company's responsibility to ensure that its
EdocID's are unique.
Company codes can be found in the Bellcore publications
Coded Representation of the North
American Telecommunication Industry Manufacturers, Suppliers, and Related Service
Companies, ST-STS-002006, and
Common Language Bellcore and Regional Holding
Company Codes, BR 751-100-175. If you do not know your company's code, you may call
the COMMON LANGUAGE code administrator at 908-699-5440 or the COMMON
LANGUAGE Hotline at 908-699-5577. Originators without a COMMON LANGUAGE company code
who want to deliver TEDD packages to telecom-industry trading partners will
need to register with the COMMON LANGUAGE administrator and pay a nominal fee for assignment
of a code.
It is strongly recommended, although at this time it is not required, that some form of the
document number be included as part of the
EdocID. Incorporating the document number
with the COMMON LANGUAGE code in a valid SGML NAME (a string that uses letters,
digits, hyphens, and periods only) creates an ID that can be used as the value of the ID
attribute of a TIM
TelDoc
instance or another SGML document instance, and as a prefix
for the IDs of all elements within the document instance. With such a convention in place,
it may be possible to ensure unique and permanent IDs for every potential hyperlink
endpoint across all TEDD-compliant telecom documents.
Examples:
<EdocID>TCIF-IPI-95-001:issueE:instance1</EdocID><EdocID>BR-GR-1383-CORE:issue1:instance1</EdocID>
Note that in the examples the character string up to but not including the first non-NAME
character, ":", could serve as a prefix on element identifiers within the document, ensuring
uniqueness across the entire domain of telecom documents (assuming that two issues or
instances of the same document would not be available in the same information base at the
same time). For convenience, the portion of the EDocID before the first non-NAME
character will be called the NAME string. The highlighted portion of this EDocID is the
NAME string:
<EdocID>TCIF-IPI-95-001:issueE:instance1</EdocID>
Because permanence of IDs across revisions of a document is as important as uniqueness
for the sake of maintaining hyperlinks, the NAME string of the EDocID should contain only
as much of the document identifier as is needed to distinguish that document from entirely
distinct and different documents. For instance, some companies use Issue number to
indicate revisions of a document: they should keep the Issue number outside the NAME
string, as in the example above. Other companies change Issue numbers according to
releases of software — different Issue numbers reflect different software releases, so the
documents are actually different. In those cases, Issue number should be part of the NAME
string:
<EdocID>XYZC-SD-001-001-123-iss2:rev1:instance1</EdocID>
The NAME string should not be more than 58 characters, allowing the addition of a hyphen
and 5 characters for unique IDs within the document. If a document's internal IDs are
longer than 5 characters, the NAME-string limit will have to be less, so that a complete ID
string is never more than 64 characters.
If a complex TEDD package contains multiple documents that together constitute a
distinct, numbered information product, that number should be incorporated into the
EdocID
in the same way. However, if the package contains
a
lib
directory, even if it accompanies a single document
two or more documents that do not constitute a single information product
with its own identifier
then it should have an
EdocID
that clearly indicates that the package is not in itself an
information product. Example:
<EdocID>BR-TEDD-Package123:instance6</EdocID>
The
EdocID
of a complex TEDD package should never be the same as the
EdocID
of any document within it.
TEDD package class: <Class>
Each
DocID
instance must contain a
Class
element as its second element, with data
content that identifies the class of the TEDD document or the TEDD package in question.
The specification of TEDD packages contained in this document will inevitably change
over time as enhancements and modifications for greater effectiveness are made. Thus,
variations of TEDD package data representations will exist. These variations will be
organized as subclasses of the parent class of TEDD package. The
Class
element contains
the class identifier of the TEDD package:
<Class>TEDD_Package-3.0</Class>
Or:
<Class>TEDD_Document-3.0</Class>
Currently the
Class
element of any
DocID
instance must match one of the two
examples above. The number 3 represents the third major release of the DocID DTD.
For a complex TEDD package that conforms to Issue 1 of these Guidelines, the
Class
element of the
DocID
instance found in the TEDD package's
adm
directory must
contain the value "TEDD_Package-3.0".
For each document in an TEDD package that conforms to Issue 1 of these Guidelines, the
Class
element of the
DocID
instance found in the document's
adm
directory must
contain the value "TEDD_Document-3.0".
A single-document TEDD package that conforms to Issue 1 of these Guidelines must use
the value "TEDD_Document-3.0".
Document owner: <Company>
Each
DocID
instance must contain a
Company
element as its third element, containing
the common name (not the COMMON LANGUAGE code) of the company that owns the
document contained in the TEDD package. The exact wording and spelling are left to the
discretion of the document provider. It should be the same in all of that company's TEDD
packages.
Document number: <DocNo> or <DocNo.u>
Each
<DocID>
instance must contain a
DocNo
or a
DocNo.u
element as its fourth
element, containing the official document number, designated by the document producer,
of the document contained in the TEDD package or document root directory.
The
DocNo
element contains subelements specified in the DocID DTD and, if used,
must be used as indicated in [Table 3-1](TABLE).
<Docno> subelements
Element
Contains
<DN.base>
Base document number
<DN.iss>
Issue number
<DN.ed>
Edition number
<DN.addm>
Addendum number
<DN.rev>
Revision number
<DN.rvl>
Revision-level number
<DN.vol>
Volume number
<DN.apdx>
Appendix number
<DN.bull>
Bulletin number
<DN.supp>
Supplement number
<DN.rlse>
Release number
<DN.lang>
Language (used in identifier)
<DN.date>
Date (used in identifier)
<DN.prod>
Product (used in identifier)
<DN.country>
Country (used in identifier)
<DN.customer>
Customer
The
DN.base
element, the base document number, is the only required
document-number field, and it must appear first within the
DocNo
element. The other
subelements are optional and may occur in any order.
Example:
<DocNo><DN.base>GR-1383-CORE</DN.base><DN.iss>1</DN.iss></DocNo>
It is recommended, not required, that the
DocNo.u
element be used only when
DocNo
is inadequate to convey the necessary parts of the document's official identifier. The
DocNo.u
element is unfielded, but should not be unstructured. Consistent rules should
be followed:
<DocNo.u>XRV-331 ISS 1</DocNo.u><DocNo.u>XRV-331 ISS 1 PROD 2</DocNo.u><DocNo.u>XRV-331 ISS 1 PROD 2 RVL 1</;DocNo.u>
A complex TEDD package that does not have its own information-product number should
use a
DocNo.u
element containing the same identifying character string as that in the
EdocID, without the instance number:
<DocNo.u>BR-TEDD-Package27</DocNo.u>
Document date: <DocDate>
Each
DocID
instance must contain a
DocDate
element as its fifth element, containing
the official document publication date, designated by the document producer, for the
document contained in the TEDD package or document root directory. The
DocDate
element must contain the date in numerical year-month-date or year-month form according
to the following grammar:
DocDate := monthspec | dayspecmonthspec := year date_separator monthdayspec := year date_separator month date_separator dayyear := … "1994" | "1995" | "1996" … | … "94" | "95" | "96" … month := "01" | "02" | … | "12"day := "01" | "02" | … | "31"date_separator := "/" | "-"
Note that the date must be expressed in year-month-day format, and that the day is optional.
The year may be expressed in either two-digit format (e.g., 95) or four-digit format (e.g.,
1995). The solidus or the hyphen may be used to separate date fields (e.g., 95/08/01 or
95-08-01).
Examples:
<DocDate>93-08-21</DocDate><DocDate>93/08/21</DocDate><DocDate>1993-08-211</DocDate><DocDate>93-08</DocDate><DocDate>1993/08</DocDate>
A complex TEDD package that does not have its own information-product number should
use the date the overall package was created.
Document title(s): <TitleGroup>
Each
DocID
instance must contain a
TitleGroup
element as its sixth
element, containing an official title, as designated by the document producer, for the
document contained in the TEDD package.
Document titles consist of a parent
TitleGroup
element that contains a single
Title
element preceded by optional
SuperTitle
elements and followed by optional
SubTitle
elements, with an optional
ShortTitle
element at the end.
<TitleGroup><SuperTitle>Information Technology Generic Requirements</SuperTitle><Title>Model T Document Exchange</Title><SubTitle>The MT DTD</SubTitle></TitleGroup>
A
TitleGroup
may contain just a
Title. (The contents of a
TitleGroup
element defined in
the DocID DTD correspond to those of a
TitleGroup
element defined in the TIM DTD.)
A complex TEDD package that does not have its own information-product number should
use a
TitleGroup
element containing a
Title
and one
SubTitle: It should have "Complex
TEDD Package" (exactly!) as the title and any appropriate description as the subtitle:
<TitleGroup><Title>Complex TEDD Package</Title><SubTitle>OTGR Subset 1</SubTitle></TitleGroup>
Optional DocID information
In addition to its required components, a
DocID
instance may contain other information
that a document producer feels will be of use to a document recipient. Several optional
elements may be used to contain information about other documents related to the
document contained in a given TEDD package.
Any or all of these may be omitted, but
when they occur, they must occur in the
order described.
Alternative Identifier: <AltNo>
Some document providers use an alternative identifier for documents, typically called a
part number. Thus optional element is a place to provide that number. Content and format
are left to the document provider:
Example 1:
<AltNo>61635A</AltNo>
Example 2:
<AltNo>Part # 61635A</AltNo>
<Publisher>
If the publisher of a document is different from the telecom-industry document owner
named in the Company element[ (Section 3.4.5)](SECTION), it can be idenitifed with this element.
Content and format are left to the document provider:
<Publisher>Washington, DC: ATIS</Publisher>
International Standard Book or Serial Number: <ISN>
If a document has been assigned an ISBN or ISSN, it can be provided in this
optional element.
Example 1:
<ISN>ISBN 0-19-853737-9</ISN>
Example 2:
<ISN>ISSN 0010-7174</ISN>
<Country>
This optional element is most often used to specify the country or countries for which this
version of the document is produced. Content and format are left to the document provider:
<Country>UK</Country><Country>England</Country>
Copyright: <Copyrt>
A document producer may use the
Copyrt
element to convey copyright information for
the document identified by the
DocID
instance. Specific uses of this element and specific
forms for the information it contains are left to the discretion of the document provider.
Example:
<Copyrt>Copyright (c) 1993, 1995 Bellcore. All Rights Reserved.</Copyrt>
Language: <Lang>
A document producer may use the
Lang
element to convey information about the natural
language(s) used in the text of the document identified by the
DocID
instance. Specific
uses of this element and specific forms for the information it contains are left to the
discretion of the document provider.
Example:
<Lang>EN</Lang>
Use of the ISO-639 codes for languages[ (Table 3-2)](TABLE)
is encouraged but not required here
(use of those codes is specified for language identification in TIM files).
ISO-639 codes for selected languages
Code
Language Name (English/francais/native)
AR
Arabic/arabe/Arabi
DA
Danish/danois/Dansk
DE
German/allemand/Deutsch
EL
Greek/grec/Ellinika
EN
English/anglais
ES
Spanish/espagnol/Espanol
FI
Finnish/finnois/Suomi
FR
French/francais
GA
Irish/irlandais/Gaeilge
HI
Hindi
IN
Indonesian/indonesien
IS
Icelandic/islandais/Islenzk
IT
Italian/italien/Italiano
IW
Hebrew/hebreu/Iwrith
JA
Japanese/japonais/Nihongo
KO
Korean/coreen/Choson-o
NL
Dutch/neerlandais/Nederlands
NO
Norwegian/norvegien/Norsk
PL
Polish/polonais/Polski
PT
Portuguese/portugais/Portugues
RU
Russian/russe/Russkij
SV
Swedish/suedois/Svenska
TR
Turkish/turc/Turkce
UK
Ukrainian/ukrainien/Ukrainska
VI
Vietnamese/vietnamien/Tieng Viet-nam
ZH
Chinese/chinois/Zhongwen
Superdocuments/subdocuments: <SuperDoc> and <SubDoc>
A
SuperDoc
("superdocument") element contains the document number, and optionally
the title, of a parent document for the document identified by the
DocID
instance. For example, many
of the Generic Requirements that Bellcore publishes under separate cover and
separate document number are also logical subsections of a larger Family of Requirements
considered to be a document in its own right and identified by its own document number.
When distributing one of the smaller Generic Requirements, Bellcore can describe this
situation using the
SuperDoc
element.
Example:
<DocNo><DN.base>GR-828-CORE</DN.base><DN.iss>1</DN.iss></DocNo><DocDate>88/11</DocDate><TitleGroup><SuperTitle>Operations Technology Generic Requirements (OTGR)</SuperTitle><Title>Generic Operations Interfaces - OSI Communications Architecture</Title></TitleGroup><SuperDoc><DocNo><DN.base>FR-439</DN.base><DN.iss>2
</DN.iss></DocNo><Title>Operations Technology Generic Requirements
</Title></SuperDoc>
It's likely but not necessary that the document's supertitle and the superdocument's title
will be the same. There can be more than one
SuperDoc
element.
A
SubDoc
("subdocument") element contains the document number, and optionally the
title, of a child document of the document identified by the
DocID
instance. There can
be more than one
SubDoc
element, so any number of subdocuments could be listed.
Ordinarily, recipients will expect subdocuments identified in a
DocID
instance to be included in the same TEDD package.
SuperDoc
and
SubDoc
elements can be mixed in any order. See also
DocRepl
[ (3.5.11)](SECTION)
and
RelDoc
[ (3.5.14)](SECTION).
<Status>
A
DocID
instance may include one or more
Status
elements to contain information
about the status of the document identified by the
DocID
instance. The
Status
element may be used to convey information about such things as the revision status of
document contents or the publication history of the document. Specific uses and specific
forms for the information it contains are left to the discretion of the document producer.
Examples:
<Status>Draft</Status><Status>Revised 93/08/03</Status><Status>Information contained in this document does not
apply beyond 99/12/31.</Status>
Proprietary Status: <PropStat>
A
DocID
instance may include one
PropStat
element to contain
information about the proprietary status of the document identified by the
DocID
instance. Specific uses and specific forms for the information it contains are left to the
discretion of the document producer.
Example:
<PropStat>Confidential - Addressee OnlyBELLCORE PROPRIETARY - INTERNAL USE ONLY</PropStat>
EDoc-replaced element: <EdocRepl>
A
DocID
instance may include one or more
EdocRepl
elements each containing the
EdocID
of a document instance replaced by the current instance. Any number of replaced
document instances can be listed in successive
EdocRepl
elements.
Example:
<EdocID>BR-GR-1383-CORE:issue1:instance2</EdocID>. . .<EdocRepl>BR-GR-1383-CORE:issue1:instance1</EdocRepl>
Document-replaced element: <DocRepl>
A
DocID
instance may include one or more
DocRepl
elements each containing the
document number, and optionally the title, of a document replaced by the document
identified by the
DocID
instance. Any number of replaced documents can be listed in
successive
DocRepl
elements.
Example:
<DocRepl><DocNo><DN.base>SR-4392</DN.base><DN.iss>1
</DN.iss></DocNo><Title>Changes to Bellcore's Document
Identifiers</Title></DocRepl>
Product description: <ProdDsc>
A document producer may use one or more
ProdDsc
elements to contain information
descriptive of the product to which the document identified by the
DocID
instance
applies. Specific uses of this element and specific forms for the information it contains are
left to the discretion of the document provider.
Examples:
<ProdDsc>A Component of Bellcore Intelligent Information
Services</ProdDsc><ProdDsc>Product Family: Enhanced Information Objects In
Orbit (EIEIO)</ProdDsc>
Document description: <DocDsc>
A document producer may use one
DocDsc
element to hold information
describing the document identified by the
DocID
instance for which no other element of
the
DocID
is appropriate. Specific uses of this element and specific forms for the
information it contains are left to the discretion of the document provider.
Example:
<DocDsc>Document Type: Product Functional Specification</DocDsc>
Related documents: <RelDoc>
A
RelDoc
element contains the document number (DocNo
or DocNo.u), and optionally the title (Title
or TitleGroup), of a
document related to the document identified by the
DocID
instance in a way not
described by the
SuperDoc,
SubDoc, and
DocRepl
elements. Any number of
related documents can be listed in successive
RelDoc
elements. Example:
<RelDoc><DocNo><DN.base>IPI-95-002</DN.base></DocNo>
<Title>Telecommunications Industry Markup (TIM)</Title></RelDoc>
<Contact>
A document producer may use a
Contact
element to convey information about an agent
that may be contacted for further information about the document identified by the
DocID
instance. Multiple
Contact
elements should be used for multiple contacts.
Specific uses of this element and specific forms for the information it contains are left to
the discretion of the document provider.
Example:
<Contact>Sheena Ng, Bellcore, 445 South St., Morristown,
NJ, 09760, (201) 829-0000</Contact><Contact>ITGR Bulletin Board: (201) 829-0000 (9600): (201)
829-9999 (14.4)</Contact>
Author: <Au>
A document producer may use an
Au
element to contain information about an author of
the document identified by the
DocID
instance. Multiple
Au
elements should be used
for multiple authors. Specific uses of this element and specific forms for the information it
contains are left to the discretion of the document provider.
Example:
<Au>Fred Waxbean, Bellcore, (201) 829-0000</Au>
Short Abstract: <Abs>
A document producer may use one
Abs
element to convey a one-paragraph,
unformatted abstract of the document content suitable for a catalog or database. Specific
content for this element and specific forms for the information it contains
are left to the discretion of the document provider. There is no length limit.
The abstract will be read as a single paragraph, and tabs and line breaks will be treated as
spaces. There is no provision in the DocID DTD for subelements or any kind of formatting
within the abstract.
<Keywords>
A document producer may use one
Keywords
element to convey a list of keywords
suitable for searching in a catalog or database. Specific format rules for the information it
contains are left to the discretion of the document provider. As with the abstract, there is no length
limit, but also no formatting — tabs and line breaks will be treated as spaces. It is suggested
that commas or semicolons be used to separate distinctly meaningful key terms, which
might be multiple words.
Example:
<Keywords>document numbers, document identifiers,
information product identifiers, numbering, document
control coordinator</Keywords>
Sample DocID instances
Sample 1 — minimal
DocID:
<!DOCTYPE docid PUBLIC "-//USA/TCIF//DTD DOCID-3//EN"><DocID><EdocID>GR-1383-CORE:issue1:instance1</EdocID><Class>TEDD-Document-3.0</Class><Company>Bellcore</Company><DocNo><DN.base>GR-1383-CORE</DN.base><DN.iss>1</DN.iss></DocNo><DocDate>93/08</DocDate><TitleGroup><SuperTitle>Information Technology Generic Requirements</SuperTitle><Title>Model T Document Exchange</Title></TitleGroup></DocID>
Sample 2 — complex-package
DocID:
<!DOCTYPE DocID PUBLIC "-//USA/TCIF//DTD DOCID-3//EN"><DocID><EdocID>BR-TEDD-Package1:instance1</EdocID><Class>TEDD-Package-3.0</Class><Company>Bellcore</Company><DocNo.u>BR-TEDD-Package1</DocNo.u><DocDate>95/03</DocDate><TitleGroup><Title>Complex TEDD Package</Title><SubTitle>SR-3031 plus files for processing</SubTitle></TitleGroup></DocID>
Sample 3 — more elaborate instance:
<!DOCTYPE DocID PUBLIC "-//USA/TCIF//DTD DOCID-3//EN" [<!ENTITY % ISOlat1 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN"><!ENTITY % ISOlat2 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 2//EN">%ISOlat1; %ISOlat2;]><DocID><EdocID>GR-1383-CORE:issue1:instance1</EdocID><Class>TEDD-Document-3.0</Class><Company>Bellcore</Company><DocNo><DN.base>ST-OPT-002009</DN.base><DN.iss>1</DN.iss></DocNo><DocDate>92/06</DocDate><Title>Information Administration Practices: Corporate Data Naming
Guidelines</Title><Copyrt>Copyright (C) 1992 Bellcore</Copyrt><ProdDsc>Science and Technology Series</ProdDsc><RelDoc><DocNo><DN.base>SR-OPT-001826</DN.base></DocNo><Title>Information Modelling Concepts and Guidelines</Title></RelDoc></DocID>
Sample 2 — The
DocID
for Issue E of this document:
<DocID><EdocID>TCIF-IPI-95-001:issue1:instance1</EdocID><Class>TEDD-Package-3.0</Class><Company>Telecommunications Industry Forum</Company><DocNo><DN.base>TCIF-IPI-95-001</DN.base><DN.iss>1</DN.iss></DocNo><DocDate>1995/11</DocDate><TitleGroup><Title>The Telecommunications Electronic Document Delivery (TEDD) Package</Title><ShortTitle>The TEDD Package</ShortTitle></TitleGroup><Copyrt>Copyright 1995, ATIS. This document is printed and distributed by the
Alliance for Telecommunications Industry Solutions ("ATIS") on behalf of the
Telecommunications Industry Forum ("TCIF"). Participants in TCIF are hereby
authorized to reproduce and distribute this document within their own business
organizations and to others for TCIF-related business provided that this notice
continues to appear in the reproduced documentation. Reproduction and
distribution for resale is prohibited.</Copyrt><Status>For ordering information, please contact TCIF at 202-434-8844 (FAX: 202-393-5453).</Status><Status>TIM-1.0.4</Status><Status>Issue 1 of a TCIF Guideline</Status><Status>Instance 1 created 95/11/06</Status><EdocRepl>TCIF-IPI-95-001:issueE:instance2</EdocRepl><EdocRepl>TCIF-IPI-4:issueB:instance1</EdocRepl><DocRepl><DocNo><DN.base>TCIF-IPI-4</DN.base><DN.iss>B</DN.iss></DocNo></DocRepl><DocRepl><DocNo><DN.base>BR-SR-3031</DN.base><DN.iss>1</DN.iss></DocNo></DocRepl><RelDoc><DocNo><DN.base>TCIF-IPI-95-004</DN.base><DN.iss>1</DN.iss></DocNo></RelDoc><Contact>Donald F. Pratt, (908) 699-4012, dfp@pekoe.ims.bellcore.com</Contact></DocID>