usr/src/cmd/man/src/util/nsgmls.src/doc/nsgmls.htm

   1 <!-- SCCS keyword
   2 #pragma ident   "%Z%%M% %I%     %E% SMI"
   3 -->
   4 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
   5 <HTML>
   6 <HEAD>
   7 <TITLE>NSGMLS</TITLE>
   8 </HEAD>
   9 <BODY>
  10 <H1>NSGMLS</H1>
  11 <H4>
  12 An SGML System Conforming to
  13 International Standard ISO 8879 --<BR>
  14 Standard Generalized Markup Language
  15 </H4>
  16 <H2>
  17 SYNOPSIS
  18 </H2>
  19 <P>
  20 <SAMP>nsgmls</SAMP>
  21 [
  22 <SAMP>-BCdeglprsuv</SAMP>
  23 ]
  24 [
  25 <SAMP>-a<VAR>linktype</VAR></SAMP>
  26 ]
  27 [
  28 <SAMP>-b<VAR>bctf</VAR></SAMP>
  29 ]
  30 [
  31 <SAMP>-c<VAR>sysid</VAR></SAMP>
  32 ]
  33 [
  34 <SAMP>-D<VAR>directory</VAR></SAMP>
  35 ]
  36 [
  37 <SAMP>-E<VAR>max_errors</VAR></SAMP>
  38 ]
  39 [
  40 <SAMP>-f<VAR>file</VAR></SAMP>
  41 ]
  42 [
  43 <SAMP>-i<VAR>name</VAR></SAMP>
  44 ]
  45 [
  46 <SAMP>-o<VAR>output_option</VAR></SAMP>
  47 ]
  48 [
  49 <SAMP>-t<VAR>file</VAR></SAMP>
  50 ]
  51 [
  52 <SAMP>-w<VAR>warning_type</VAR></SAMP>
  53 ]
  54 [
  55 <SAMP><VAR>sysid</VAR>...</SAMP>
  56 ]
  57 <H2>DESCRIPTION</H2>
  58 <P>
  59 Nsgmls parses and validates
  60 the SGML document whose document entity is specified by the
  61 <A HREF="sysid.htm">system identifiers</A>
  62 <SAMP><VAR>sysid</VAR>...</SAMP>
  63 and prints on the standard output a simple text representation of its
  64 Element Structure Information Set.
  65 (This is the information set which a structure-controlled
  66 conforming SGML application should act upon.)
  67 If more than one system identifier is specified,
  68 then the corresponding entities will be concatenated to form
  69 the document entity.
  70 Thus the document entity may be spread amongst several files;
  71 for example, the SGML declaration, prolog and document
  72 instance set could each be in a separate file.
  73 If no system identifiers are specified, then
  74 nsgmls
  75 will read the document entity from the standard input.
  76 A command line system identifier of
  77 <SAMP>-</SAMP>
  78 can be used to refer to the standard input.
  79 (Normally in a system identifier,
  80 <SAMP>&lt;osfd>0</SAMP>
  81 is used to refer to standard input.)
  82 <H2>OPTIONS</H2>
  83 <P>
  84 The following options are available:
  85 <DL>
  86 <DT>
  87 <SAMP>-a<VAR>linktype</VAR></SAMP>
  88 <DD>
  89 Make link type
  90 <SAMP><VAR>linktype</VAR></SAMP>
  91 active.
  92 Not all ESIS information is output in this case:
  93 the active LPDs are not explicitly reported,
  94 although each link attribute is qualified with
  95 its link type name;
  96 there is no information about result elements;
  97 when there are multiple link rules applicable to the
  98 current element,
  99 nsgmls
 100 always chooses the first.
 101 <DT>
 102 <SAMP>-b<VAR>bctf</VAR></SAMP>
 103 <DD>
 104 Use the <A HREF="sysid.htm#bctf">BCTF</A> named
 105 <SAMP><VAR>bctf</VAR></SAMP>
 106 for output.
 107 <DT>
 108 <SAMP>-B</SAMP>
 109 <DD>
 110 Batch mode.
 111 Parse each <SAMP><VAR>sysid...</VAR></SAMP> specified on the command
 112 line separately, rather than concatenating them.
 113 This is useful mainly with <SAMP>-s</SAMP>.
 114 <P>
 115 If <SAMP>-t<VAR>filename</VAR></SAMP> is also specified, then
 116 the specified <SAMP><VAR>filename</VAR></SAMP> will be prefixed
 117 to the <SAMP><VAR>sysid</VAR></SAMP> to make the filename
 118 for the RAST result for each <SAMP><VAR>sysid</VAR></SAMP>.
 119 <DT>
 120 <SAMP>-c<VAR>sysid</VAR></SAMP>
 121 <DD>
 122 Map public identifiers and entity names to system identifiers
 123 using the catalog entry file whose system identifier is
 124 <SAMP><VAR>sysid</VAR></SAMP>.
 125 Multiple
 126 <SAMP>-c</SAMP>
 127 options are allowed.
 128 If there is a catalog entry file called
 129 <SAMP>catalog</SAMP>
 130 in the same place as the document entity,
 131 it will be searched for immediately after those specified by
 132 <SAMP>-c</SAMP>.
 133 <DT>
 134 <A NAME="optC"><SAMP>-C</SAMP></A>
 135 <DD>
 136 The
 137 <SAMP><VAR>filename</VAR>...</SAMP>
 138 arguments specify catalog files rather than the document entity.
 139 The document entity is specified by the first
 140 <SAMP>DOCUMENT</SAMP>
 141 entry in the catalog files.
 142 <DT>
 143 <A NAME="optD"><SAMP>-D<VAR>directory</VAR></SAMP></A>
 144 <DD>
 145 Search
 146 <SAMP><VAR>directory</VAR></SAMP>
 147 for files specified in system identifiers.
 148 Multiple
 149 <SAMP>-D</SAMP> options
 150 are allowed.
 151 See the description of the
 152 <SAMP>osfile</SAMP>
 153 storage manager for more information about file searching.
 154 <DT>
 155 <SAMP>-e</SAMP>
 156 <DD>
 157 Describe open entities in error messages.
 158 Error messages always include the position of the most recently
 159 opened external entity.
 160 <DT>
 161 <SAMP>-E<VAR>max_errors</VAR></SAMP>
 162 <DD>
 163 Nsgmls
 164 will exit after
 165 <SAMP><VAR>max_errors</VAR></SAMP>
 166 errors.
 167 If
 168 <SAMP><VAR>max_errors</VAR></SAMP>
 169 is 0, there is no limit on the number of errors.
 170 The default is 200.
 171 <DT>
 172 <SAMP>-f<VAR>file</VAR></SAMP>
 173 <DD>
 174 Redirect errors to
 175 <SAMP><VAR>file</VAR></SAMP>.
 176 This is useful mainly with shells that do not support redirection
 177 of stderr.
 178 <DT>
 179 <SAMP>-g</SAMP>
 180 <DD>
 181 Show the generic identifiers of open elements in error messages.
 182 <DT>
 183 <A NAME="opti"><SAMP>-i<VAR>name</VAR></SAMP></A>
 184 <DD>
 185 Pretend that
 186 <PRE>
 187 &lt;!ENTITY % <VAR>name</VAR> "INCLUDE">
 188 </PRE>
 189 <P>
 190 occurs at the start of the document type declaration subset
 191 in the SGML document entity.
 192 Since repeated definitions of an entity are ignored,
 193 this definition will take precedence over any other definitions
 194 of this entity in the document type declaration.
 195 Multiple
 196 <SAMP>-i</SAMP>
 197 options are allowed.
 198 If the SGML declaration replaces the reserved name
 199 <SAMP>INCLUDE</SAMP>
 200 then the new reserved name will be the replacement text of the entity.
 201 Typically the document type declaration will contain
 202 <PRE>
 203 &lt;!ENTITY % <VAR>name</VAR> "IGNORE">
 204 </PRE>
 205 <P>
 206 and will use
 207 <SAMP>%<VAR>name</VAR>;</SAMP>
 208 in the status keyword specification of a marked section declaration.
 209 In this case the effect of the option will be to cause the marked
 210 section not to be ignored.
 211 <DT>
 212 <SAMP>-o<VAR>output_option</VAR></SAMP>
 213 <DD>
 214 Output additional information accordig to
 215 <SAMP><VAR>output_option</VAR></SAMP>:
 216 <DL>
 217 <DT>
 218 <SAMP>entity</SAMP>
 219 <DD>
 220 Output definitions of all general entities
 221 not just for data or subdoc entities that are referenced or named in an
 222 ENTITY or ENTITIES attribute.
 223 <DT>
 224 <SAMP>id</SAMP>
 225 <DD>
 226 Distinguish attributes whose declared value is ID.
 227 <DT>
 228 <SAMP>line</SAMP>
 229 <DD>
 230 Output
 231 <SAMP>L</SAMP>
 232 commands giving the current line number and filename.
 233 <DT>
 234 <SAMP>included</SAMP>
 235 <DD>
 236 Output an
 237 <SAMP>i</SAMP>
 238 command for included subelements.
 239 <DT>
 240 <SAMP>notation-sysid</SAMP>
 241 <DD>
 242 Output an <SAMP>f</SAMP> command before an <SAMP>N</SAMP> command,
 243 if a system identifier could be generated for that notation.
 244 </DL>
 245 <P>
 246 Multiple
 247 <SAMP>-o</SAMP>
 248 options are allowed.
 249 <DT>
 250 <SAMP>-p</SAMP>
 251 <DD>
 252 Parse only the prolog.
 253 Nsgmls
 254 will exit after parsing the document type declaration.
 255 Implies
 256 <SAMP>-s</SAMP>.
 257 <DT>
 258 <SAMP>-s</SAMP>
 259 <DD>
 260 Suppress output.
 261 Error messages will still be printed.
 262 <DT>
 263 <SAMP>-t<VAR>file</VAR></SAMP>
 264 <DD>
 265 Output to
 266 <SAMP><VAR>file</VAR></SAMP>
 267 the RAST result as defined by
 268 ISO/IEC 13673:1995 (actually this isn't quite an IS yet;
 269 this implements the Intermediate Editor's Draft of 1994/08/29,
 270 with changes to implement ISO/IEC JTC1/SC18/WG8 N1777).
 271 The normal output is not produced.
 272 <DT>
 273 <SAMP>-v</SAMP>
 274 <DD>
 275 Print the version number.
 276 <DT>
 277 <A NAME="optw"><SAMP>-w<VAR>type</VAR></SAMP></A>
 278 <DD>
 279 Control warnings and errors.
 280 Multiple
 281 <SAMP>-w</SAMP>
 282 options are allowed.
 283 The following values of
 284 <SAMP><VAR>type</VAR></SAMP>
 285 enable warnings:
 286 <DL>
 287 <DT>
 288 <SAMP>mixed</SAMP>
 289 <DD>
 290 Warn about mixed content models that do not allow #pcdata anywhere.
 291 <DT>
 292 <SAMP>sgmldecl</SAMP>
 293 <DD>
 294 Warn about various dubious constructions in the SGML declaration.
 295 <DT>
 296 <SAMP>should</SAMP>
 297 <DD>
 298 Warn about various recommendations made in ISO 8879 that the document
 299 does not comply with.
 300 (Recommendations are expressed with ``should'', as distinct from
 301 requirements which are usually expressed with ``shall''.)
 302 <DT>
 303 <SAMP>default</SAMP>
 304 <DD>
 305 Warn about defaulted references.
 306 <DT>
 307 <SAMP>duplicate</SAMP>
 308 <DD>
 309 Warn about duplicate entity declarations.
 310 <DT>
 311 <SAMP>undefined</SAMP>
 312 <DD>
 313 Warn about undefined elements: elements used in the DTD but not defined.
 314 <DT>
 315 <SAMP>unclosed</SAMP>
 316 <DD>
 317 Warn about unclosed start and end-tags.
 318 <DT>
 319 <SAMP>empty</SAMP>
 320 <DD>
 321 Warn about empty start and end-tags.
 322 <DT>
 323 <SAMP>net</SAMP>
 324 <DD>
 325 Warn about net-enabling start-tags and null end-tags.
 326 <DT>
 327 <SAMP>min-tag</SAMP>
 328 <DD>
 329 Warn about minimized start and end-tags.
 330 Equivalent to combination of
 331 <SAMP>unclosed</SAMP>,
 332 <SAMP>empty</SAMP>
 333 and
 334 <SAMP>net</SAMP>
 335 warnings.
 336 <DT>
 337 <SAMP>unused-map</SAMP>
 338 <DD>
 339 Warn about unused short reference maps: maps that are declared with a
 340 short reference mapping declaration but never used in a short
 341 reference use declaration in the DTD.
 342 <DT>
 343 <SAMP>unused-param</SAMP>
 344 <DD>
 345 Warn about parameter entities that are defined but not used in a DTD.
 346 Unused internal parameter entities whose text is
 347 <SAMP>INCLUDE</SAMP>
 348 or
 349 <SAMP>IGNORE</SAMP>
 350 won't get the warning.
 351 <DT>
 352 <SAMP>notation-sysid</SAMP>
 353 <DD>
 354 Warn about notations for which no system identifier could be generated.
 355 <DT>
 356 <SAMP>all</SAMP>
 357 <DD>
 358 Warn about conditions that should usually be avoided
 359 (in the opinion of the author).
 360 Equivalent to:
 361 <SAMP>mixed</SAMP>,
 362 <SAMP>should</SAMP>,
 363 <SAMP>default</SAMP>,
 364 <SAMP>undefined</SAMP>,
 365 <SAMP>sgmldecl</SAMP>,
 366 <SAMP>unused-map</SAMP>,
 367 <SAMP>unused-param</SAMP>,
 368 <SAMP>empty</SAMP>
 369 and
 370 <SAMP>unclosed</SAMP>.
 371 </DL>
 372 <P>
 373 A warning can be disabled by using its name prefixed with
 374 <SAMP>no-</SAMP>.
 375 Thus
 376 <SAMP>-wall -wno-duplicate</SAMP>
 377 will enable all warnings except those about duplicate entity
 378 declarations.
 379 <P>
 380 The following values for
 381 <SAMP><VAR>warning_type</VAR></SAMP>
 382 disable errors:
 383 <DL>
 384 <DT>
 385 <SAMP>no-idref</SAMP>
 386 <DD>
 387 Do not give an error for an ID reference value
 388 which no element has as its ID.
 389 The effect will be as if each attribute declared as
 390 an ID reference value had been declared as a name.
 391 <DT>
 392 <SAMP>no-significant</SAMP>
 393 <DD>
 394 Do not give an error when a character that is not a significant
 395 character in the reference concrete syntax occurs in a literal in the
 396 SGML declaration.  This may be useful in conjunction with certain
 397 buggy test suites.
 398 </DL>
 399 </DL>
 400 <P>
 401 The following options are also supported for backwards compatibility
 402 with sgmls:
 403 <DL>
 404 <DT>
 405 <SAMP>-d</SAMP>
 406 <DD>
 407 Same as
 408 <SAMP>-wduplicate</SAMP>.
 409 <DT>
 410 <SAMP>-l</SAMP>
 411 <DD>
 412 Same as
 413 <SAMP>-oline</SAMP>.
 414 <DT>
 415 <SAMP>-m<VAR>sysid</VAR></SAMP>
 416 <DD>
 417 Same as <SAMP>-c</SAMP>.
 418 <DT>
 419 <SAMP>-r</SAMP>
 420 <DD>
 421 Same as
 422 <SAMP>-wdefault</SAMP>.
 423 <DT>
 424 <SAMP>-u</SAMP>
 425 <DD>
 426 Same as
 427 <SAMP>-wundef</SAMP>.
 428 </DL>
 429 <H2>ENVIRONMENT</H2>
 430 <DL>
 431 <DT>
 432 <SAMP>SP_BCTF</SAMP>
 433 <DD>
 434 If this is set to one of
 435 <SAMP>identity</SAMP>,
 436 <SAMP>utf-8</SAMP>,
 437 <SAMP>euc-jp</SAMP> and <SAMP>sjis</SAMP>, then that BCTF will be used as the
 438 default BCTF for everything (including file input, file output,
 439 message output, filenames, environment variable names, environment
 440 variable values and command line arguments).  Note that setting
 441 <SAMP>SP_BCTF</SAMP> to <SAMP>unicode</SAMP>
 442 will not work.
 443 </DL>
 444 <P>
 445 <ADDRESS>
 446 James Clark<BR>
 447 jjc@jclark.com
 448 </ADDRESS>
 449 </BODY>
 450 </HTML>