doc/nsgmls.htm

   1 <!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html>
   3 <head>
   4    <title>ONSGMLS</title>
   5 </head>
   6 <body>
   7
   8 <h1>ONSGMLS</h1>
   9
  10 <h4>
  11 An SGML System Conforming to International Standard ISO 8879 --
  12 Standard Generalized Markup Language</h4>
  13
  14 <h4>
  15 An SGML Extended Facilities system conforming to Annex A of International
  16 Standard ISO/IEC 10744 -- Hypermedia/Time-based Structuring Language</h4>
  17
  18 <h2>
  19 SYNOPSIS</h2>
  20 <tt>onsgmls</tt> [ <tt>option...</tt> ] <tt><i>sysid</i>...</tt>
  21 <h2>
  22 DESCRIPTION</h2>
  23 Onsgmls parses and validates the SGML document whose document entity is
  24 specified by the
  25 <a href="sysid.htm">system identifiers</a><tt> <i>sysid</i>...</tt>
  26 and prints on the standard output a simple text representation of its Element
  27 Structure Information Set. (This is the information set which a structure-controlled
  28 conforming SGML application should act upon.) If more than one system identifier
  29 is specified, then the corresponding entities will be concatenated to form
  30 the document entity. Thus the document entity may be spread amongst several
  31 files; for example, the SGML declaration, prolog and document instance
  32 set could each be in a separate file. If no system identifiers are specified,
  33 then nsgmls will read the document entity from the standard input. A command
  34 line system identifier of
  35 <tt>-</tt> can be used to refer to the standard
  36 input. (Normally in a system identifier,
  37 <tt>&lt;osfd>0</tt> is used to
  38 refer to standard input.)
  39 <h2>
  40 OPTIONS</h2>
  41 The following options are available:
  42 <dl>
  43 <dt><tt>-a<i>name</i></tt>, <tt>--activate=<i>name</i></tt></dt>
  44
  45 <dd>
  46 Make link type or doctype <i><tt>name</tt></i> active. Not all ESIS
  47 information is output in this case: the active LPDs are not explicitly
  48 reported, although each link attribute is qualified with its link type name; there is no information
  49 about result elements; when there are multiple link rules applicable to
  50 the current element, nsgmls always chooses the first. You cannot mix
  51 active link types and doctypes. Only one active doctype can be specified.</dd>
  52
  53 <dt><tt>-b<i>name</i></tt>, <tt>--bctf=<i>name</i></tt></dt>
  54 <dt><tt>-b<i>name</i></tt>, <tt>--encoding=<i>name</i></tt></dt>
  55
  56 <dd>
  57 This determines the encoding used for output. If in <a href="charset.htm#fixed">fixed
  58 character set mode</a> it specifies the name of an encoding; if not, it
  59 specifies the name of a BCTF.</dd>
  60
  61 <dt><tt>-B</tt>, <tt>--batch-mode</tt></dt>
  62
  63 <dd>
  64 Batch mode. Parse each <i><tt>sysid...</tt></i> specified on the command
  65 line separately, rather than concatenating them. This is useful mainly
  66 with <tt>-s</tt>.
  67 <p><br>If <tt>-t<i>filename</i></tt> is also specified, then the specified
  68 <i><tt>filename</tt></i> will be prefixed to the <i><tt>sysid</tt></i>
  69 to make the filename for the RAST result for each <i><tt>sysid</tt></i>.</dd>
  70
  71 <dt><a NAME="optc"></a><tt>-c<i>sysid</i></tt>, <tt>--catalog=<i>sysid</i></tt></dt>
  72
  73 <dd>
  74 Map public identifiers and entity names to system identifiers using the
  75 catalog entry file whose system identifier is
  76 <i><tt>sysid</tt></i>. Multiple
  77 <tt>-c</tt>
  78 options are allowed. If there is a catalog entry file called
  79 <tt>catalog</tt>
  80 in the same place as the document entity, it will be searched for immediately
  81 after those specified by
  82 <tt>-c</tt>.</dd>
  83
  84 <dt><a NAME="optC"></a><tt>-C</tt>, <tt>--catalogs</tt></dt>
  85
  86 <dd>
  87 The <tt><i>filename</i>...</tt> arguments specify catalog files rather
  88 than the document entity. The document entity is specified by the first
  89 <tt>DOCUMENT</tt>
  90 entry in the catalog files.</dd>
  91
  92 <dt><a NAME="optD"></a><tt>-D<i>directory</i></tt>, <tt>--directory=<i>directory</i></tt></dt>
  93
  94 <dd>
  95 Search <i><tt>directory</tt></i> for files specified in system identifiers.
  96 Multiple <tt>-D</tt> options are allowed. See the description of the
  97 <tt>osfile</tt> storage manager for more information about file searching.</dd>
  98
  99 <dt><tt>-e</tt>, <tt>--open-entities</tt></dt>
 100
 101 <dd>
 102 Describe open entities in error messages. Error messages always include
 103 the position of the most recently opened external entity.</dd>
 104
 105 <dt><tt>-E<i>number</i></tt>, <tt>--max-errors=<i>number</i></tt></dt>
 106
 107 <dd>
 108 Onsgmls will exit after <tt><i>number</i></tt> errors. If <tt><i>number</i></tt>
 109 is 0, there is no limit on the number of errors. The default is 200.</dd>
 110
 111 <dt><tt>-f<i>file</i></tt>, <tt>--error-file=<i>file</i></tt></dt>
 112
 113 <dd>
 114 Redirect errors to <i><tt>file</tt></i>. This is useful mainly with shells
 115 that do not support redirection of stderr.</dd>
 116
 117 <dt><tt>-g</tt>, <tt>--open-elements</tt></dt>
 118
 119 <dd>
 120 Show the generic identifiers of open elements in error messages.</dd>
 121
 122 <dt><tt>-h</tt>, <tt>--help</tt></dt>
 123
 124 <dd>
 125 Show a help message and exit.
 126
 127 <dt>
 128 <a NAME="opti"></a><tt>-i<i>name</i></tt>, <tt>--include=<i>name</i></tt></dt>
 129
 130 <dd>
 131 Pretend that
 132
 133 <pre>&lt;!ENTITY % <i>name</i> "INCLUDE"></pre>
 134 occurs at the start of the document type declaration subset in the SGML
 135 document entity. Since repeated definitions of an entity are ignored, this
 136 definition will take precedence over any other definitions of this entity
 137 in the document type declaration. Multiple <tt>-i</tt> options are allowed.
 138 If the SGML declaration replaces the reserved name <tt>INCLUDE</tt> then
 139 the new reserved name will be the replacement text of the entity. Typically
 140 the document type declaration will contain
 141 <pre>&lt;!ENTITY % <i>name</i> "IGNORE"></pre>
 142 and will use <tt>%<i>name</i>;</tt> in the status keyword specification
 143 of a marked section declaration. In this case the effect of the option
 144 will be to cause the marked section not to be ignored.</dd>
 145
 146 <dt><tt>-n</tt>, <tt>--error-numbers</tt></dt>
 147
 148 <dd>
 149 Show message numbers in error messages.</dd>
 150
 151 <dt><tt>-o<i>option</i></tt>, <tt>--option=<i>option</i></tt></dt>
 152
 153 <dd>
 154 Output additional information according to
 155 <i><tt>option</tt></i>:
 156
 157 <dl>
 158 <dt>
 159 <tt>entity</tt></dt>
 160
 161 <dd>
 162 Output definitions of all general entities not just for data or subdoc
 163 entities that are referenced or named in an ENTITY or ENTITIES attribute.</dd>
 164
 165 <dt>
 166 <tt>id</tt></dt>
 167
 168 <dd>
 169 Distinguish attributes whose declared value is ID.</dd>
 170
 171 <dt>
 172 <tt>line</tt></dt>
 173
 174 <dd>
 175 Output
 176 <tt>L</tt> commands giving the current line number and filename.</dd>
 177
 178 <dt>
 179 <tt>included</tt></dt>
 180
 181 <dd>
 182 Output an
 183 <tt>i</tt> command for included subelements.</dd>
 184
 185 <dt>
 186 <tt>empty</tt></dt>
 187
 188 <dd>
 189 Output an <tt>e</tt> command for elements which are not allowed to have
 190 an end-tag, that is those with a declared content of empty or with a content
 191 reference attribute.</dd>
 192
 193 <dt>
 194 <tt>notation-sysid</tt></dt>
 195
 196 <dd>
 197 Output an <tt>f</tt> command before an <tt>N</tt> command, if a system
 198 identifier could be generated for that notation.</dd>
 199
 200 <dt>
 201 <tt>nonsgml</tt></dt>
 202
 203 <dd>
 204 In <a href="charset.htm#fixed">fixed character set mode</a>, output <tt>\%</tt>
 205 escape sequences for non-SGML data characters. Non-SGML data characters
 206 can result from numeric character references.</dd>
 207
 208 <dt>
 209 <tt>data-attribute</tt></dt>
 210
 211 <dd>
 212 Output the notation name and attributes for DATA attributes. Otherwise,
 213 DATA attributes are treated like CDATA attributes. For more details, see clause
 214 4.4.3 of <A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K
 215 of ISO 8879</A>.</dd>
 216
 217 <dt>
 218 <tt>comment</tt></dt>
 219
 220 <dd>
 221 Output an <tt>_</tt> command with the contents of a comment. Multiple comments
 222 in a single comment declaration will result in multiple distinct <tt>_</tt>
 223 commands, just as if the comments were each in a separate comment
 224 declaration.</dd>
 225
 226 <dt>
 227 <tt>omitted</tt></dt>
 228
 229 <dd>
 230
 231 Output an <tt>o</tt> command before a command which was implied by the input
 232 document, but omitted from the actual markup. This currently affects
 233 <tt>(</tt>, <tt>)</tt>, and <tt>A</tt> commands.</dd>
 234
 235 <dt>
 236 <tt>tagomit</tt></dt>
 237
 238 <dd>
 239 As <tt>omitted</tt>, but only for <tt>(</tt> and <tt>)</tt> commands.</dd>
 240
 241 <dt>
 242 <tt>attromit</tt></dt>
 243
 244 <dd>
 245 As <tt>omitted</tt>, but only for <tt>A</tt> commands.</dd>
 246 </dl>
 247 Multiple
 248 <tt>-o</tt> options are allowed.</dd>
 249
 250 <dt><tt>-p</tt>, <tt>--only-prolog</tt></dt>
 251
 252 <dd>
 253 Parse only the prolog. Onsgmls will exit after parsing the document type
 254 declaration. Implies <tt>-s</tt>.</dd>
 255
 256 <dt><a NAME="optR"></a><tt>-R</tt>, <tt>--restricted</tt></dt>
 257
 258 <dd>
 259 Restrict file reading. This option is intended for use with onsgmls-based
 260 Web tools (e.g., CGI scripts) to prevent reading of arbitrary
 261 files on the Web server. With this option enabled, onsgmls will not
 262 read any local files unless they are located in a directory (or
 263 subdirectory) specified by the <tt>-D</tt> option or included in the
 264 SGML_SEARCH_PATH environment variable. As a further security
 265 precaution, this option limits filenames to the characters
 266 A-Z, a-z, 0-9, '/', '.', '_', '-' and does not allow filenames
 267 containing "..".</dd>
 268
 269 <dt><tt>-s</tt>, <tt>--no-output</tt></dt>
 270
 271 <dd>
 272 Suppress output. Error messages will still be printed.</dd>
 273
 274 <dt><tt>-t<i>file</i></tt>, <tt>--rast-file=<i>file</i></tt></dt>
 275
 276 <dd>
 277 Output to <i><tt>file</tt></i> the RAST result as defined by ISO/IEC 13673:1995
 278 (actually this isn't quite an IS yet; this implements the Intermediate
 279 Editor's Draft of 1994/08/29, with changes to implement ISO/IEC JTC1/SC18/WG8
 280 N1777). The normal output is not produced.</dd>
 281
 282 <dt><tt>-v</tt>, <tt>--version</tt></dt>
 283
 284 <dd>
 285 Print the version number.</dd>
 286
 287 <dt><a NAME="optw"></a><tt>-w<i>type</i></tt>, <tt>--warning=<i>type</i></tt></dt>
 288
 289 <dd>
 290 Control warnings and errors. Multiple <tt>-w</tt> options are allowed.
 291 The following values of <i><tt>type</tt></i> enable warnings:
 292
 293 <dl>
 294 <dt>
 295 <tt>xml</tt></dt>
 296
 297 <dd>
 298 Warn about constructs that are not allowed by <a href="http://www.w3.org/TR/1998/REC-xml-19980210">XML</a>.
 299 The warnings can be enabled <a href="xmlwarn.htm">individually.</a></dd>
 300
 301 <dt>
 302 <tt>mixed</tt></dt>
 303
 304 <dd>
 305 Warn about mixed content models that do not allow #PCDATA anywhere.</dd>
 306
 307 <dt>
 308 <tt>sgmldecl</tt></dt>
 309
 310 <dd>
 311 Warn about various dubious constructions in the SGML declaration.</dd>
 312
 313 <dt>
 314 <tt>should</tt></dt>
 315
 316 <dd>
 317 Warn about various recommendations made in ISO 8879 that the document does
 318 not comply with. (Recommendations are expressed with ``should'', as distinct
 319 from requirements which are usually expressed with ``shall''.)</dd>
 320
 321 <dt>
 322 <tt>default</tt></dt>
 323
 324 <dd>
 325 Warn about defaulted references.</dd>
 326
 327 <dt>
 328 <tt>duplicate</tt></dt>
 329
 330 <dd>
 331 Warn about duplicate entity declarations.</dd>
 332
 333 <dt>
 334 <tt>undefined</tt></dt>
 335
 336 <dd>
 337 Warn about undefined elements: elements used in the DTD but not defined.</dd>
 338
 339 <dt>
 340 <tt>unclosed</tt></dt>
 341
 342 <dd>
 343 Warn about unclosed start and end-tags.</dd>
 344
 345 <dt>
 346 <tt>empty</tt></dt>
 347
 348 <dd>
 349 Warn about empty start and end-tags.</dd>
 350
 351 <dt>
 352 <tt>net</tt></dt>
 353
 354 <dd>
 355 Warn about net-enabling start-tags and null end-tags.</dd>
 356
 357 <dt>
 358 <tt>min-tag</tt></dt>
 359
 360 <dd>
 361 Warn about minimized start and end-tags. Equivalent to combination of
 362 <tt>unclosed</tt>, <tt>empty</tt> and <tt>net</tt> warnings.</dd>
 363
 364 <dt>
 365 <tt>unused-map</tt></dt>
 366
 367 <dd>
 368 Warn about unused short reference maps: maps that are declared with a short
 369 reference mapping declaration but never used in a short reference use
 370 declaration in the DTD.</dd>
 371
 372 <dt>
 373 <tt>unused-param</tt></dt>
 374
 375 <dd>
 376 Warn about parameter entities that are defined but not used in a DTD. Unused
 377 internal parameter entities whose text is <tt>INCLUDE</tt> or <tt>IGNORE</tt>
 378 won't get the warning.</dd>
 379
 380 <dt>
 381 <tt>notation-sysid</tt></dt>
 382
 383 <dd>
 384 Warn about notations for which no system identifier could be generated.</dd>
 385
 386 <dt>
 387 <tt>all</tt></dt>
 388
 389 <dd>
 390 Warn about conditions that should usually be avoided (in the opinion of
 391 the author). Equivalent to:
 392 <tt>mixed</tt>,
 393 <tt>should</tt>,
 394 <tt>default</tt>,
 395 <tt>undefined</tt>,
 396 <tt>sgmldecl</tt>,
 397 <tt>unused-map</tt>,
 398 <tt>unused-param</tt>,
 399 <tt>empty</tt>
 400 and
 401 <tt>unclosed</tt>.</dd>
 402
 403 <dt>
 404 <tt>immediate-recursion</tt></dt>
 405
 406 <dd>
 407 Warn about immediately recursive elements. For more details, see clause
 408 2.2.5 of <A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K
 409 of ISO 8879</A>.</dd>
 410
 411 <dt>
 412 <tt>fully-declared</tt></dt>
 413
 414 <dd>
 415 Warn if the document instance fails to be fully-declared.
 416 This has the effect of changing the SGML declaration to specify
 417 <tt>IMPLYDEF ATTLIST NO ELEMENT NO ENTITY NO NOTATION NO</tt>.
 418 For more details, see clause 2.2.1 of
 419 <A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K
 420 of ISO 8879</A>.</dd>
 421
 422 <dt>
 423 <tt>fully-tagged</tt></dt>
 424
 425 <dd>
 426 Warn if the document instance fails to be fully-tagged.
 427 This has the effect of changing the SGML declaration to specify
 428 <tt>DATATAG NO</tt>, <tt>RANK NO</tt>, <tt>OMITTAG NO</tt>,
 429 <tt>SHORTTAG STARTTAG EMPTY NO</tt> and
 430 <tt>SHORTTAG ATTRIB OMITNAME NO</tt>.
 431 For more details, see clause 2.2.2 of
 432 <A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K
 433 of ISO 8879</A>.</dd>
 434
 435 <dt>
 436 <tt>amply-tagged</tt>, <tt>amply-tagged-recursive</tt></dt>
 437
 438 <dd>
 439 Warn if the document instance fails to be amply-tagged. Implicitly defined
 440 elements may be immediately recursive if <tt>-recursive</tt> is specified.
 441 This has the effect of changing the SGML declaration to specify
 442 <tt>DATATAG NO</tt>, <tt>RANK NO</tt>, <tt>OMITTAG NO</tt>,
 443 <tt>SHORTTAG ATTRIB OMITNAME NO</tt> and either
 444 <tt>IMPLYDEF ELEMENT ANYOTHER</tt> or
 445 <tt>IMPLYDEF ELEMENT YES</tt>.
 446 For more details, see clause 2.2.4 of
 447 <A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K
 448 of ISO 8879</A>.</dd>
 449
 450 <dt>
 451 <tt>type-valid</tt></dt>
 452
 453 <dd>
 454 Warn if the document instance fails to be type-valid.
 455 This has the effect of changing the SGML declaration to specify
 456 <tt>VALIDITY YES</tt>.
 457 For more details, see clause 2.2.3 of
 458 <A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K
 459 of ISO 8879</A>.</dd>
 460
 461 <dt>
 462 <tt>entity-ref</tt></dt>
 463
 464 <dd>
 465 Warn about references to non-predefined entities.
 466 This has the effect of changing the SGML declaration to specify
 467 <tt>ENTITIES REF NONE</tt>.
 468 For more details, see clause 2.3.2 of
 469 <A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K
 470 of ISO 8879</A>.</dd>
 471
 472 <dt>
 473 <tt>external-entity-ref</tt></dt>
 474
 475 <dd>
 476 Warn about references to external entities. This includes references to an
 477 external DTD subset.
 478 This has the effect of changing the SGML declaration to specify
 479 <tt>ENTITIES REF INTERNAL</tt>.
 480 For more details, see clause 2.3.3 of
 481 <A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K
 482 of ISO 8879</A>.</dd>
 483
 484 <dt>
 485 <tt>integral</tt></dt>
 486
 487 <dd>
 488 Warn if the document instance is not integrally stored. i
 489 This has the effect of changing the SGML declaration to specify
 490 <tt>ENTITIES INTEGRAL YES</tt>.
 491 For more details, see clause 2.3.1 of
 492 <A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K
 493 of ISO 8879</A>.</dd>
 494 </dl>
 495 A warning can be disabled by using its name prefixed with
 496 <tt>no-</tt>.
 497 Thus
 498 <tt>-wall -wno-duplicate</tt> will enable all warnings except those
 499 about duplicate entity declarations.
 500 <p>The following values for
 501 <i><tt>warning_type</tt></i> disable errors:
 502 <dl>
 503 <dt>
 504 <tt>no-idref</tt></dt>
 505
 506 <dd>
 507 Do not give an error for an ID reference value which no element has as
 508 its ID. The effect will be as if each attribute declared as an ID reference
 509 value had been declared as a name.</dd>
 510
 511 <dt>
 512 <tt>no-significant</tt></dt>
 513
 514 <dd>
 515 Do not give an error when a character that is not a significant character
 516 in the reference concrete syntax occurs in a literal in the SGML declaration.
 517 This may be useful in conjunction with certain buggy test suites.</dd>
 518
 519 <dt>
 520 <tt>no-valid</tt></dt>
 521
 522 <dd>
 523 Do not require the document to be type-valid. This has the effect of changing
 524 the SGML declaration to specify <tt>VALIDITY NOASSERT</tt> and <tt>IMPLYDEF
 525 ATTLIST YES ELEMENT YES ENTITY YES NOTATION YES</tt>. An option of
 526 <tt>-wvalid</tt> has the effect
 527 of changing the SGML declaration to specify <tt>VALIDITY TYPE</tt> and
 528 <tt>IMPLYDEF ATTLIST NO ELEMENT NO ENTITY NO NOTATION NO</tt>.
 529 If neither <tt>-wvalid</tt> nor
 530 <tt>-wno-valid</tt> are specified, then the <tt>VALIDITY</tt> and <tt>IMPLYDEF</tt>
 531 specified in the SGML declaration will be used.</dd>
 532
 533 <dt>
 534 <tt>no-afdr</tt></dt>
 535
 536 <dd>
 537 Do not give errors when AFDR meta-DTD notation features are used in the
 538 DTD. These errors are normally produced when parsing the DTD, but suppressed
 539 when parsing meta-DTDs.</dd>
 540 </dl></dd>
 541
 542 <dt><tt>-x</tt>, <tt>--references</tt></dt>
 543
 544 <dd>
 545 Show information about relevant clauses (from ISO 8879:1986) in error messages.</dd>
 546
 547 </dl>
 548 The following options are also supported for backwards compatibility with
 549 sgmls:
 550 <dl>
 551 <dt>
 552 <tt>-d</tt></dt>
 553
 554 <dd>
 555 Same as
 556 <tt>-wduplicate</tt>.</dd>
 557
 558 <dt>
 559 <tt>-l</tt></dt>
 560
 561 <dd>
 562 Same as
 563 <tt>-oline</tt>.</dd>
 564
 565 <dt>
 566 <tt>-m<i>sysid</i></tt></dt>
 567
 568 <dd>
 569 Same as <tt>-c</tt>.</dd>
 570
 571 <dt>
 572 <tt>-r</tt></dt>
 573
 574 <dd>
 575 Same as
 576 <tt>-wdefault</tt>.</dd>
 577
 578 <dt>
 579 <tt>-u</tt></dt>
 580
 581 <dd>
 582 Same as
 583 <tt>-wundef</tt>.</dd>
 584 </dl>
 585
 586 </body>
 587 </html>