doc/sysid.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>OpenSP - System identifiers</TITLE>
   5 </HEAD>
   6 <BODY>
   7 <H1>System identifiers</H1>
   8 <P>
   9 There are two kinds of system identifier: formal system identifiers
  10 and simple system identifiers.  A system identifier that does not
  11 start with <SAMP>&lt;</SAMP> will always be interpreted as a simple
  12 system identifier.  A simple system identifier will always be
  13 interpreted either as a filename or as a URL.
  14
  15 <H2>Formal system identifiers</H2>
  16 <P>
  17 Formal system identifiers are based on the
  18 System Identifier facility defined in ISO/IEC 10744 (HyTime) Technical
  19 Corrigendum 1, Annex D.
  20 A system identifier that is a formal system
  21 identifier consists of a sequence of one or more storage object
  22 specifications.  The objects specified by the storage object
  23 specifications are concatenated to form the entity.  A storage object
  24 specification consists of an SGML start-tag in the reference concrete
  25 syntax followed by character data content.  The generic identifier of
  26 the start-tag is the name of a storage manager.  The content is a
  27 storage object identifier which identifies the storage object in a
  28 manner dependent on the storage manager.  The start-tag can also
  29 specify attributes giving additional information about the storage
  30 object.  Numeric character references are recognized in storage object
  31 identifiers and attribute value literals in the start-tag.  Record
  32 ends are ignored in the storage object identifier as with SGML.  A
  33 system identifier will be interpreted as a formal system identifier if
  34 it starts with a <SAMP>&lt;</SAMP> followed by a storage manager name,
  35 followed by either <SAMP>></SAMP> or white-space; otherwise it will be
  36 interpreted as a simple system identifier.  A storage object
  37 identifier extends until the end of the system identifier or until the
  38 first occurrence of <SAMP>&lt;</SAMP> followed by a storage manager
  39 name, followed by either <SAMP>></SAMP> or white-space.
  40 <P>
  41 The following storage managers are available:
  42 <DL>
  43 <DT>
  44 <A NAME="osfile"><SAMP>osfile</SAMP></A>
  45 <DD>
  46 The storage object identifier is a filename.  If the filename is
  47 relative it is resolved using a base filename.  Normally the base
  48 filename is the name of the file in which the storage object
  49 identifier was specified, but this can be changed using the
  50 <SAMP>base</SAMP> attribute.  The filename will be searched for first
  51 in the directory of the base filename.  If it is not found there, then
  52 it will be searched for in directories specified with the
  53 <SAMP>-D</SAMP> option in the order in which they were specified on
  54 the command line, and then in the list of directories specified by the
  55 environment variable <SAMP>SGML_SEARCH_PATH</SAMP>.  The list
  56 is separated by colons under Unix and by semi-colons under MSDOS.
  57 <DT>
  58 <SAMP>osfd</SAMP>
  59 <DD>
  60 The storage object identifier is an integer specifying a file
  61 descriptor. Thus a system identifier of <SAMP>&lt;osfd>0</SAMP> will
  62 refer to the standard input (<CODE>STDIN</code>), 1 to standard output
  63 (<code>STDOUT</code>), and 2 to standard error
  64 (<code>STDERR</code>). Arbitrary file descriptors may be used so you
  65 could say <samp>&lt;osfd&gt;3</samp> to get an extra input or output
  66 stream independant of the usual three. This is useful, e.g., for
  67 generating catalog entries or SGML declarations on the fly. You can
  68 use an osfd storage object anywhere you can use a sysid, including on
  69 the command line.
  70 <DT>
  71 <SAMP>url</SAMP>
  72 <DD>
  73 The storage object identifier is a URL.  Only the <SAMP>http</SAMP>
  74 scheme is currently supported and not on all systems.
  75 <DT>
  76 <SAMP>neutral</SAMP>
  77 <DD>
  78 The storage manager is the storage manager of storage object in which
  79 the system identifier was specified (the <I>underlying storage
  80 manager</I>).  However if the underlying storage manager does not
  81 support named storage objects (ie it is <SAMP>osfd</SAMP>), then the
  82 storage manager will be <SAMP>osfile</SAMP>.  The storage object
  83 identifier is treated as a relative, hierarchical name separated by
  84 slashes (<SAMP>/</SAMP>) and will be transformed as appropriate for
  85 the underlying storage manager.
  86 <DT>
  87 <SAMP>literal</SAMP>
  88 <DD>
  89 The bit combinations of the storage object identifier are
  90 the contents of the storage object.
  91 </DL>
  92 <P>
  93 The following attributes are supported:
  94 <DL>
  95 <DT>
  96 <SAMP>records</SAMP>
  97 <DD>
  98 This describes how records are delimited in the storage object:
  99 <DL>
 100 <DT><SAMP>cr</SAMP>
 101 <DD>
 102 Records are terminated by a carriage return.
 103 <DT>
 104 <SAMP>lf</SAMP>
 105 <DD>
 106 Records are terminated by a line feed.
 107 <DT>
 108 <SAMP>crlf</SAMP>
 109 <DD>
 110 Records are terminated by a carriage return followed by a line feed.
 111 <DT>
 112 <SAMP>find</SAMP>
 113 <DD>
 114 Records are terminated by whichever of
 115 <SAMP>cr</SAMP>,
 116 <SAMP>lf</SAMP>
 117 or
 118 <SAMP>crlf</SAMP>
 119 is first encountered in the storage object.
 120 <DT>
 121 <SAMP>asis</SAMP>
 122 <DD>
 123 No recognition of records is performed.
 124 </DL>
 125 <P>
 126 The default is <SAMP>find</SAMP> except for NDATA entities for which
 127 the default is <SAMP>asis</SAMP>.  This attribute is not applicable to
 128 the <SAMP>literal</SAMP> storage manager.
 129 <P>
 130 When records are recognized in a storage object, a record start is
 131 inserted at the beginning of each record, and a record end at the end
 132 of each record.  If there is a partial record (a record that doesn't
 133 end with the record terminator) at the end of the entity, then a
 134 record start will be inserted before it but no record end will be
 135 inserted after it.
 136 <P>
 137 The attribute name and <SAMP>=</SAMP> can be omitted for this attribute.
 138 <DT>
 139 <SAMP>zapeof</SAMP>
 140 <DD>
 141 This specifies whether a Control-Z character that occurs as the final byte
 142 in the storage object should be stripped.
 143 The following values are allowed:
 144 <DL>
 145 <DT><SAMP>zapeof</SAMP>
 146 <DD>
 147 A final Control-Z should be stripped.
 148 <DT><SAMP>nozapeof</SAMP>
 149 <DD>
 150 A final Control-Z should not be stripped.
 151 </DL>
 152 <P>
 153 The default is <SAMP>zapeof</SAMP> except for NDATA entities, entities
 154 declared in storage objects with <SAMP>zapeof=nozapeof</SAMP> and
 155 storage objects with <SAMP>records=asis</SAMP>.  This attribute is not
 156 applicable to the <SAMP>literal</SAMP> storage manager.
 157 <P>
 158 The attribute name and <SAMP>=</SAMP> can be omitted for this
 159 attribute.
 160 <DT>
 161 <A NAME="encoding"><SAMP>encoding</SAMP></A>
 162 <DD>
 163 The encoding attribute specifies the encoding of the storage object.
 164 This attribute is used when the encoding is independent of the
 165 document character set.
 166 The value must be the <A HREF="charset.htm#encodings">name of an encoding</A>.
 167 This attribute is not applicable to the
 168 <SAMP>literal</SAMP> storage manager.
 169 <DT>
 170 <A NAME="bctf"><SAMP>bctf</SAMP></A>
 171 <DD>
 172 The BCTF attribute specifies that the encoding of the storage
 173 object.
 174 This attribute is used when the encoding is
 175 document character set dependent.
 176 The value must be the <A HREF="charset.htm#bctfs">name of a BCTF</A>.
 177 This attribute is not applicable to the
 178 <SAMP>literal</SAMP> storage manager.
 179 <DT>
 180 <SAMP>tracking</SAMP>
 181 <DD>
 182 This specifies whether line boundaries should be tracked for this
 183 object: a value of <SAMP>track</SAMP> specifies that they should; a
 184 value of <SAMP>notrack</SAMP> specifies that they should not.  The
 185 default value is <SAMP>track</SAMP>.  Keeping track of where line
 186 boundaries occur in a storage object requires approximately one byte
 187 of storage per line and it may be desirable to disable this for very
 188 large storage objects.
 189 <P>
 190 The attribute name and
 191 <SAMP>=</SAMP>
 192 can be omitted for this attribute.
 193 <DT>
 194 <SAMP>base</SAMP>
 195 <DD>
 196 When the storage object identifier specified in the content of the
 197 storage object specification is relative, this specifies the base
 198 storage object identifier relative to which that storage object
 199 identifier should be resolved.
 200 When not specified a storage object identifier is interpreted
 201 relative to the storage object in which it is specified,
 202 provided that this has the same storage manager.
 203 This applies both to system identifiers specified in SGML
 204 documents and to system identifiers specified in the catalog entry
 205 files.
 206 <DT>
 207 <SAMP>smcrd</SAMP>
 208 <DD>
 209 The value is a single character that will be recognized in storage
 210 object identifiers (both in the content of storage object
 211 specifications and in the value of <SAMP>base</SAMP> attributes) as a
 212 storage manager character reference delimiter when followed by a
 213 digit.  A storage manager character reference is like an SGML numeric
 214 character reference except that the number is interpreted as a
 215 character number in the inherent character set of the storage manager
 216 rather than the document character set.  The default is for no
 217 character to be recognized as a storage manager character reference
 218 delimiter.  Numeric character references cannot be used to prevent
 219 recognition of storage manager character reference delimiters.
 220 <DT>
 221 <SAMP>fold</SAMP>
 222 <DD>
 223 This applies only to the <SAMP>neutral</SAMP> storage manager.  It
 224 specifies whether the storage object identifier should be folded to
 225 the customary case of the underlying storage manager if storage object
 226 identifiers for the underlying storage manager are case sensitive.
 227 The following values are allowed:
 228 <DL>
 229 <DT><SAMP>fold</SAMP>
 230 <DD>
 231 The storage object identifier will be folded.
 232 <DT>
 233 <SAMP>nofold</SAMP>
 234 <DD>
 235 The storage object identifier will not be folded.
 236 </DL>
 237 <P>
 238 The default value is <SAMP>fold</SAMP>.  The attribute name and
 239 <SAMP>=</SAMP> can be omitted for this attribute.
 240 <P>
 241 For example, on Unix filenames are case-sensitive and the customary
 242 case is lower-case.  So if the underlying storage manager were
 243 <SAMP>osfile</SAMP> and the system was a Unix system, then
 244 <SAMP>&lt;neutral>FOO.SGM</SAMP> would be equivalent to
 245 <SAMP>&lt;osfile>foo.sgm</SAMP>.
 246 </DL>
 247 <H2>Simple system identfiers</H2>
 248 <P>
 249 A simple system identifier is interpreted as a storage object
 250 identifier with a storage manager that depends on where the system
 251 identifier was specified: if it was specified in a storage object
 252 whose storage manager was <SAMP>url</SAMP> or if the system identifier
 253 looks like an absolute URL in a supported scheme, the storage manager
 254 will be <SAMP>url</SAMP>; otherwise the storage manager will be
 255 <SAMP>osfile</SAMP>.  The storage manager attributes are defaulted as
 256 for a formal system identifier.  Numeric character references are not
 257 recognized in simple system identifiers.
 258 </BODY>
 259 </HTML>