onsgmls.1

'\" t
.\"     Title: onsgmls
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/>
.\"      Date: November 2002
.\"    Manual: Reference
.\"    Source: OpenSP
.\"  Language: English
.\"
.TH "ONSGMLS" "1" "November 2002" "OpenSP" "Reference"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
onsgmls \- An SGML/XML parser and validator
.SH "SYNOPSIS"
.HP \w'\fBonsgmls\fR\ 'u
\fBonsgmls\fR [\fB\-BCdeghlnpRrsuvx\fR] [\fB\-a\fR\fB\fIlinktype\fR\fR] [\fB\-A\fR\fB\fIarchitecture\fR\fR] [\fB\-b\fR\fB\fIbctf\fR\fR] [\fB\-c\fR\fB\fIsysid\fR\fR...] [\fB\-D\fR\fB\fIdirectory\fR\fR] [\fB\-E\fR\fB\fImax_errors\fR\fR] [\fB\-f\fR\fB\fIfile\fR\fR] [\fB\-i\fR\fB\fIname\fR\fR] [\fB\-o\fR\fB\fIoutput_option\fR\fR...] [\fB\-t\fR\fB\fIfile\fR\fR] [\fB\-w\fR\fB\fIwarning_type\fR\fR...] [\fB\fIsysid\fR\fR...]
.SH "DESCRIPTION"
.PP
\fBonsgmls\fR
parses and validates the SGML document whose document entity is specified by the system identifiers
.HP \w'\ 'u [\fIsysid\fR...]
and prints on the standard output a simple text representation of its Element Structure Information Set\&. (This is the information set which a structure\-controlled conforming SGML application should act upon\&.) If more than one system identifier is specified, then the corresponding entities will be concatenated to form the document entity\&. Thus the document entity may be spread among several files; for example, the SGML declaration, prolog and document instance set could each be in a separate file\&. If no system identifiers are specified, then onsgmls will read the document entity from the standard input\&. A command line system identifier of \- can be used to refer to the standard input\&. (Normally in a system identifier, <OSFD>0 is used to refer to standard input\&.)
.PP
Part of an SGML System Conforming to International Standard ISO 8879 \-\- Standard Generalized Markup Language\&. An SGML Extended Facilities system conforming to Annex A of Internal Standard ISO/IEC 10744 \-\- Hypermedia/Time\-based Structuring Language
.PP
The following options are available:
.PP
\fB\-a\fR\fB\fIlinktype\fR\fR, \fB\-\-activate=\fR\fB\fIlinktype\fR\fR
.RS 4
Make link type
\fIlinktype\fR
active\&. Not all ESIS information is output in this case: the active LPDs are not explicitly reported, although each link attribute is qualified with its link type name; there is no information about result elements; when there are multiple link rules applicable to the current element, onsgmls always chooses the first\&.
.RE
.PP
\fB\-A\fR\fB\fIarchitecture\fR\fR, \fB\-\-architecture=\fR\fB\fIarchitecture\fR\fR
.RS 4
Parse with respect to architecture
\fIarchitecture\fR\&.
.RE
.PP
\fB\-b\fR\fB\fIbctf\fR\fR, \fB\-\-bctf=\fR\fB\fIbctf\fR\fR, \fB\-b\fR\fB\fIencoding\fR\fR, \fB\-\-encoding=\fR\fB\fIencoding\fR\fR
.RS 4
This determines the encoding used for output\&. If in fixed character set mode it specifies the name of an encoding; if not, it specifies the name of a BCTF\&.
.RE
.PP
\fB\-B\fR, \fB\-\-batch_mode\fR
.RS 4
Batch mode\&. Parse each
.HP \w'\ 'u [\fB\fIsysid\fR\fR...]
specified on the command line separately, rather than concatenating them\&. This is useful mainly with
\fB\-s\fR\&.
.sp
If
\fB\-t\fR\fB\fIfilename\fR\fR
is also specified, then the specified filename will be prefixed to the
\fIsysid\fR
to make the filename for the RAST result for each
\fIsysid\fR\&.
.RE
.PP
\fB\-c\fR\fB\fIsysid\fR\fR, \fB\-\-catalog=\fR\fB\fIsysid\fR\fR
.RS 4
Map public identifiers and entity names to system identifiers using the catalog entry file whose system identifier is sysid\&. Multiple
\fB\-c\fR
options are allowed\&. If there is a catalog entry file called catalog in the same place as the document entity, it will be searched for immediately after those specified by
\fB\-c\fR\&.
.RE
.PP
\fB\-C\fR, \fB\-\-catalogs\fR
.RS 4
The
.HP \w'\ 'u [\fB\fIfilename\fR\fR...]
arguments specify catalog files rather than the document entity\&. The document entity is specified by the first DOCUMENT entry in the catalog files\&.
.RE
.PP
\fB\-D\fR\fB\fIdirectory\fR\fR, \fB\-\-directory=\fR\fB\fIdirectory\fR\fR
.RS 4
Search
\fIdirectory\fR
for files specified in system identifiers\&. Multiple
\fB\-D\fR
options are allowed\&. See the description of the osfile storage manager for more information about file searching\&.
.RE
.PP
\fB\-e\fR, \fB\-\-open\-entities\fR
.RS 4
Describe open entities in error messages\&. Error messages always include the position of the most recently opened external entity\&.
.RE
.PP
\fB\-E\fR\fB\fImax_errors\fR\fR, \fB\-\-max\-errors=\fR\fB\fImax_errors\fR\fR
.RS 4
onsgmls will exit after
\fImax_errors\fR
errors\&. If
\fImax_errors\fR
is 0, there is no limit on the number of errors\&. The default is 200\&.
.RE
.PP
\fB\-f\fR\fB\fIfile\fR\fR, \fB\-\-error\-file=\fR\fB\fIfile\fR\fR
.RS 4
Redirect errors to
\fIfile\fR\&. This is useful mainly with shells that do not support redirection of stderr\&.
.RE
.PP
\fB\-g\fR, \fB\-\-open\-elements\fR
.RS 4
Show the generic identifiers of open elements in error messages\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Show a help message and exit\&.
.RE
.PP
\fB\-i\fR\fB\fIname\fR\fR, \fB\-\-include=\fR\fB\fIname\fR\fR
.RS 4
Pretend that
.sp
<!ENTITY %
\fIname\fR
"INCLUDE">
.sp
occurs at the start of the document type declaration subset in the SGML document entity\&. Since repeated definitions of an entity are ignored, this definition will take precedence over any other definitions of this entity in the document type declaration\&. Multiple \-i options are allowed\&. If the SGML declaration replaces the reserved name INCLUDE then the new reserved name will be the replacement text of the entity\&. Typically the document type declaration will contain
.sp
<!ENTITY %
\fIname\fR
"IGNORE">
.sp
and will use %\fIname\fR; in the status keyword specification of a marked section declaration\&. In this case the effect of the option will be to cause the marked section not to be ignored\&.
.RE
.PP
\fB\-n\fR, \fB\-\-error\-numbers\fR
.RS 4
Show message numbers in error messages\&.
.RE
.PP
\fB\-o\fR\fB\fIoutput_option\fR\fR, \fB\-\-option=\fR\fB\fIoutput_option\fR\fR
.RS 4
Output additional information according to
\fIoutput_option\fR:
.sp
\fBentity\fR
Output definitions of all general entities not just for data or subdoc entities that are referenced or named in an ENTITY or ENTITIES attribute\&.
.sp
\fBid\fR
Distinguish attributes whose declared value is ID\&.
.sp
\fBline\fR
Output L commands giving the current line number and filename\&.
.sp
\fBincluded\fR
Output an i command for included sub\-elements\&.
.sp
\fBempty\fR
Output an e command for elements which are not allowed to have an end\-tag, that is those with a declared content of empty or with a content reference attribute\&.
.sp
\fBnotation\-sysid\fR
Output an f command before an N command, if a system identifier could be generated for that notation\&.
.sp
\fBnonsgml\fR
In fixed character set mode, output \e% escape sequences for non\-SGML data characters\&. Non\-SGML data characters can result from numeric character references\&.
.sp
\fBdata\-attribute\fR
Output the notation name and attributes for DATA attributes\&. Otherwise, DATA attributes are treated like CDATA attributes\&. For more details see clause 4\&.4\&.3 of Annex K of ISO 8879\&.
.sp
\fBcomment\fR
Output an _ command with the contents of a comment\&. Multiple comments in a single comment declaration will result in multiple distinct _ commands, just as if the comments were each in a separate comment declaration\&.
.sp
\fBomitted\fR
Output an o command before a command which was implied by the input document, but omitted from the actual markup\&. This currently affects (,), and A commands\&.
.sp
\fBtagomit\fR
As
\fBomitted\fR, but only for ( and ) commands\&.
.sp
\fBattromit\fR
As
\fBomitted\fR, but only for A commands\&.
.sp
Multiple
\fB\-o\fR
options are allowed\&.
.RE
.PP
\fB\-p\fR, \fB\-\-only\-prolog\fR
.RS 4
Parse only the prolog\&.
\fBonsgmls\fR
will exit after parsing the document type declaration\&. Implies
\fB\-s\fR\&.
.RE
.PP
\fB\-R\fR, \fB\-\-restricted\fR
.RS 4
Restrict file reading\&. This option is intended for use with onsgmls\-based Web tools (e\&.g\&. CGI scripts) to prevent reading of arbitrary files on the Web server\&. With this option enabled,
\fBonsgmls\fR
will not read any local files unless they are located in a directory (or subdirectory) specified by the
\fB\-D\fR
option or included in the SGML_SEARCH_PATH environment variable\&. As a further security precaution, this option limits filesnames to the characters A\-Z, a\-z, 0\-9, \'?\', \'\&.\', \'_\', \'\-\' and does not allow filenames containing "\&.\&."\&. On systems with MS\-DOS file names \':\' and \'\e\' are also allowed\&.
.RE
.PP
\fB\-s\fR, \fB\-\-no\-output\fR
.RS 4
Suppress output\&. Error messages will still be printed\&.
.RE
.PP
\fB\-t\fR\fB\fIfile\fR\fR, \fB\-\-rast\-file=\fR\fB\fIfile\fR\fR
.RS 4
Output to
\fIfile\fR
the RAST result as defined by ISO/IEC 13673:1995 (actually this isn\'t quite an IS yet; this implements the Intermediate Editor\'s Draft of 1994/08/29, with changes to implement ISO/IEC JTC1/SC18/WG8 N1777)\&. The normal output is not produced\&.
.RE
.PP
\fB\-v\fR, \fB\-\-version\fR
.RS 4
Print the version number\&.
.RE
.PP
\fB\-w\fR\fB\fItype\fR\fR, \fB\-\-warning=\fR\fB\fItype\fR\fR
.RS 4
Control warnings and errors\&. Multiple
\fB\-w\fR
options are allowed\&. The following values of type enable warnings:
.sp
\fBxml\fR
Warn about constructs that are not allowed by XML\&.
.sp
\fBmixed\fR
Warn about mixed content models that do not allow #PCDATA anywhere\&.
.sp
\fBsgmldecl\fR
Warn about various dubious constructions in the SGML declaration\&.
.sp
\fBshould\fR
Warn about various recommendations made in ISO 8879 that the document does not comply with\&. (Recommendations are expressed with "should", as distinct from requirements which are usually expressed with "shall"\&.)
.sp
\fBdefault\fR
Warn about defaulted references\&.
.sp
\fBduplicate\fR
Warn about duplicate entity declarations\&.
.sp
\fBundefined\fR
Warn about undefined elements: elements used in the DTD but not defined\&.
.sp
\fBunclosed\fR
Warn about unclosed start and end\-tags\&.
.sp
\fBempty\fR
Warn about empty start and end\-tags\&.
.sp
\fBnet\fR
Warn about net\-enabling start\-tags and null end\-tags\&.
.sp
\fBmin\-tag\fR
Warn about minimized start and end\-tags\&. Equivalent to combination of unclosed, empty and net warnings\&.
.sp
\fBunused\-map\fR
Warn about unused short reference maps: maps that are declared with a short reference mapping declaration but never used in a short reference use declaration in the DTD\&.
.sp
\fBunused\-param\fR
Warn about parameter entities that are defined but not used in a DTD\&. Unused internal parameter entities whose text is INCLUDE or IGNORE won\'t get the warning\&.
.sp
\fBnotation\-sysid\fR
Warn about notations for which no system identifier could be generated\&.
.sp
\fBall\fR
Warn about conditions that should usually be avoided (in the opinion of the author)\&. Equivalent to: mixed, should, default, undefined, sgmldecl, unused\-map, unused\-param, empty and unclosed\&.
.sp
\fBimmediate\-recursion\fR
Warn about immediately recursive elements\&. For more detais see clause 2\&.2\&.5 of Annex K of ISO 8879\&.
.sp
\fBfully\-declared\fR
Warn if the document instance fails to be fully declared\&. This has the effect of changing the SGML declaration to specify IMPLYDEF ATTLIST NO ELEMENT NO ENTITY NO NOTATION NO\&. For more details see clause 2\&.2\&.1 of Annex K of ISO 8879\&.
.sp
\fBfully\-tagged\fR
Warn if the document instance fails to be fully\-tagged\&. This has the effect of changing the SGML declaration to specify DATATAG NO, RANK NO, OMITTAG NO, SHORTTAG STARTTAG EMPTY NO and SHORTTAG ATTRIB OMITNAME NO\&. For more details see clause 2\&.2\&.2 of Annex K of ISO 8879\&.
.sp
\fBamply\-tagged, amply\-tagged\-recursive\fR
Warn if the doucment instance fails to be amply\-tagged\&. Implicitly defined elements may be immediately recurisve if
\fBamply\-tagged\-recursive\fR
is specified\&. This has the effect of changing the SGML declaration to specify DATATAG NO, RANK NO, OMITTAG NO, SHORTTAG ATTRIB OMITNAME NO and either IMPLYDEF ELEMENT ANYOTHER or IMPLYDEF ELEMENT YES\&. For more details see clause 2\&.2\&.4 of Annex K of ISO 8879\&.
.sp
\fBtype\-valid\fR
Warn if the document instance fails to be type\-valid\&. This has the effect of changing the SGML declaration to specify VALIDITY YES\&. For more details see clause 2\&.2\&.3 of Annex K of ISO 8879\&.
.sp
\fBentity\-ref\fR
Warn about references to non\-predefined entities\&. This has the effect of changing the SGML declaration to specify ENTITIES REF NONE\&. For more details see clause 2\&.3\&.2 of Annex K of ISO 8879\&.
.sp
\fBexternal\-entity\-ref\fR
Warn about references to external entities\&. This includes references to an external DTD subset\&. This has the effect of changing the SGML declaration to specify ENTITIES REF INTERNAL\&. For more details see clause 2\&.3\&.3 of Annex K of ISO 8879\&.
.sp
\fBintegral\fR
Warn if the document instance is not integrally stored\&. This has the effect of changing the SGML declaration to specify ENTITIES INTEGRAL YES\&. For more details see clause 2\&.3\&.1 of Annex K of ISO 8879\&.
.sp
A warning can be disabled by using its name prefixed with no\-\&. Thus
\fB\-wall\fR
\fB\-wno\-duplicate\fR
will enable all warnings except those about duplicate entity declarations\&.
.sp
The following values for
\fIwarning_type\fR
disable errors:
.sp
\fBno\-idref\fR
Do not give an error for an ID reference value which no element has as its ID\&. The effect will be as if each attribute declared as an ID reference value had been declared as a name\&.
.sp
\fBno\-significant\fR
Do not give an error when a character that is not a significant character in the reference concrete syntax occurs in a literal in the SGML declaration\&. This may be useful in conjunction with certain buggy test suites\&.
.sp
\fBno\-valid\fR
Do not require the document to be type\-valid\&. This has the effect of changing the SGML declaration to specify VALIDITY NOASSERT and IMPLYDEF ATTLIST YES ELEMENT YES\&. An option of
\fB\-wvalid\fR
has the effect of changing the SGML declaration to specify VALIDITY TYPE and IMPLYDEF ATTLIST NO ELEMENT NO\&. If neither
\fB\-wvalid\fR
nor
\fB\-wno\-valid\fR
are specified, then the VALIDITY and IMPLYDEF specified in the SGML declaration will be used\&.
.sp
\fBno\-afdr\fR
Do not give errors when AFDR meta\-DTD notation features are used in the DTD\&. These errors are normally produced when parsing the DTD, but suppressed when parsing meta\-DTDs\&.
.RE
.PP
\fB\-x\fR, \fB\-\-references\fR
.RS 4
Show information about relevant clauses (from ISO 8879:1986) in error messages\&.
.RE
.PP
The following options are also supported for backward compatibility with sgmls:
.PP
\fB\-d\fR
.RS 4
Same as
\fB\-wduplicate\fR\&.
.RE
.PP
\fB\-l\fR
.RS 4
Same as
\fB\-oline\fR\&.
.RE
.PP
\fB\-m\fR\fB\fIsysid\fR\fR
.RS 4
Same as
\fB\-c\fR\&.
.RE
.PP
\fB\-r\fR
.RS 4
Same as
\fB\-wdefault\fR\&.
.RE
.PP
\fB\-u\fR
.RS 4
Same as
\fB\-wundef\fR\&.
.RE
.SH "SEE ALSO"
.PP
\fBospent(1)\fR,
\fBospam(1)\fR,
\fBosgmlnorm(1)\fR,
\fBosx(1)\fR
.SH "AUTHORS"
.PP
\fBJames Clark\fR
.RS 4
Author.
.RE
.PP
\fBIan Castle\fR <\&ian.castle@openjade.org\&>
.RS 4
Author.
.RE
.SH "COPYRIGHT"
.br