--- name: "sgmls" section: "1" platform: "linux" package: "linuxdoc-sgml" version: "1.5-4" release: "Debian 1.2 (Rex)" platforms: ["linux"] url: "https://new.carta.tech/sgmls" --- # sgmls(1) a validating SGML parser An SGML System Conforming to International Standard ISO 8879 — Standard Generalized Markup Language ## NAME sgmls - a validating SGML parser An SGML System Conforming to\ International Standard ISO 8879 —\ Standard Generalized Markup Language ## SYNOPSIS **sgmls** \[ **-deglprsuv** \] \[ **-c***file* \] \[ **-i***name* \] \[ *filename...* \] ## DESCRIPTION *Sgmls* parses and validates the SGML document entity in *filename...* and prints on the standard output a simple ASCII representation of its Element Structure Information Set. (This is the information set which a structure-controlled conforming SGML application should act upon.) Note that the document entity may be spread amongst several files; for example, the SGML declaration, document type declaration and document instance set could each be in a separate file. If no filenames are specified, then *sgmls* will read the document entity from the standard input. A filename of **-** can also be used to refer to the standard input. The following options are available: - **-c***file* Write a report of capacity usage to *file*. The report is in the format of a RACT result. RACT is the Reference Application for Capacity Testing defined in the Proposed American National Standard *Conformance Testing for Standard Generalized Markup Language (SGL) Systems* (X3.190-199X), Draft July 1991. - **-d** Warn about duplicate entity declarations. - **-e** Describe open entities in error messages. Error messages always include the position of the most recently opened external entity. - **-g** Show the GIs of open elements in error messages. - **-i***name* Pretend that - **\** 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 - **\** and will use **%***name***;** 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. - **-l** Output **L** commands giving the current line number and filename. - **-p** Parse only the prolog. *Sgmls* will exit after parsing the document type declaration. Implies **-s**. - **-r** Warn about defaulted references. - **-s** Suppress output. Error messages will still be printed. - **-u** Warn about undefined elements: elements used in the DTD but not defined. Also warn about undefined short reference maps. - **-v** Print the version number. ### Entity Manager An external entity resides in one or more files. The entity manager component of *sgmls* maps a sequence of files into an entity in three sequential stages: - 1\. each carriage return character is turned into a non-SGML character; - 2\. each newline character is turned into a record end character, and at the same time a record start character is inserted at the beginning of each line; - 3\. the files are concatenated. A system identifier is interpreted as a list of filenames separated by colons. A filename of **-** can be used to refer to the standard input. If no system identifier is supplied, then the entity manager will attempt to generate a filename using the public identifier (if there is one) and other information available to it. Notation identifiers are not subject to this treatment. This process is controlled by the environment variable **SGML\_PATH**; this contains a colon-separated list of filename templates. A filename template is a filename that may contain substitution fields; a substitution field is a **%** character followed by a single letter that indicates the value of the substitution. If **SGML\_PATH** uses the **%S** field (the value of which is the system identifier), then the entity manager will also use **SGML\_PATH** to generate a filename when a system identifier that does not contain any colons is supplied. The value of a substitution can either be a string or it can be *null*. The entity manager transforms the list of filename templates into a list of filenames by substituting for each substitution field and discarding any template that contained a substitution field whose value was null. It then uses the first resulting filename that exists and is readable. Substitution values are transformed before being used for substitution: firstly, any names that were subject to upper case substitution are folded to lower case; secondly, space characters are mapped to underscores and slashes are mapped to percents. The value of the **%S** field is not transformed. The values of substitution fields are as follows: - **%%** A single **%**. - **%D** The entity's data content notation. This substitution will succeed only for external data entities. - **%N** The entity, notation or document type name. - **%P** The public identifier if there was a public identifier, otherwise null. - **%S** The system identifier if there was a system identifier otherwise null. - **%X** (This is provided mainly for compatibility with ARCSGML.) A three-letter string chosen as follows: | | | | | | --- | --- | --- | --- | | | | With public identifier | | | | | | | No public | Device | Device | | | identifier | independent | dependent | | Data or subdocument entity | **nsd** | **pns** | **vns** | | General SGML text entity | **gml** | **pge** | **vge** | | Parameter entity | **spe** | **ppe** | **vpe** | | Document type definition | **dtd** | **pdt** | **vdt** | | Link process definition | **lpd** | **plp** | **vlp** | The device dependent version is selected if the public text class allows a public text display version but no public text display version was specified. - **%Y** The type of thing for which the filename is being generated: | | | | --- | --- | | SGML subdocument entity | **sgml** | | Data entity | **data** | | General text entity | **text** | | Parameter entity | **parm** | | Document type definition | **dtd** | | Link process definition | **lpd** | The value of the following substitution fields will be null unless a valid formal public identifier was supplied. - **%A** Null if the text identifier in the formal public identifier contains an unavailable text indicator, otherwise the empty string. - **%C** The public text class, mapped to lower case. - **%E** The public text designating sequence (escape sequence) if the public text class is **CHARSET**, otherwise null. - **%I** The empty string if the owner identifier in the formal public identifier is an ISO owner identifier, otherwise null. - **%L** The public text language, mapped to lower case, unless the public text class is **CHARSET**, in which case null. - **%O** The owner identifier (with the **+//** or **-//** prefix stripped.) - **%R** The empty string if the owner identifier in the formal public identifier is a registered owner identifier, otherwise null. - **%T** The public text description. - **%U** The empty string if the owner identifier in the formal public identifier is an unregistered owner identifier, otherwise null. - **%V** The public text display version. This substitution will be null if the public text class does not allow a display version or if no version was specified. If an empty version was specified, a value of **default** will be used.\ ### System declaration The system declaration for *sgmls* is as follows: | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | SYSTEM "ISO 8879:1986" | | CHARSET | | BASESET | "ISO 646-1983//CHARSET | | | International Reference Version (IRV)//ESC 2/5 4/0" | | DESCSET | 0 128 0 | | CAPACITY | PUBLIC | "ISO 8879:1986//CAPACITY Reference//EN" | | FEATURES | | MINIMIZE | DATATAG | NO | OMITTAG | YES | RANK | NO | SHORTTAG | YES | | LINK | SIMPLE | NO | IMPLICIT | NO | EXPLICIT | NO | | OTHER | CONCUR | NO | SUBDOC | YES 1 | FORMAL | YES | | SCOPE | DOCUMENT | | SYNTAX | PUBLIC | "ISO 8879:1986//SYNTAX Reference//EN" | | SYNTAX | PUBLIC | "ISO 8879:1986//SYNTAX Core//EN" | | VALIDATE | | | GENERAL | YES | MODEL | YES | EXCLUDE | YES | CAPACITY | YES | | | NONSGML | YES | SGML | YES | FORMAL | YES | | SDIF | | | PACK | NO | UNPACK | NO | The memory usage of *sgmls* is not a function of the capacity points used by a document; however, *sgmls* can handle capacities significantly greater than the reference capacity set. In some environments, higher values may be supported for the SUBDOC parameter. Documents that do not use optional features are also supported. For example, if **FORMAL NO** is specified in the SGML declaration, public identifiers will not be required to be valid formal public identifiers. Certain parts of the concrete syntax may be changed: The shunned character numbers can be changed. Eight bit characters can be assigned to LCNMSTRT, UCNMSTRT, LCNMCHAR and UCNMCHAR. Declaring this requires that the syntax reference character set be declared like this: | | | | --- | --- | | BASESET | "ISO Registration Number 100//CHARSET | | | ECMA-94 Right Part of Latin Alphabet Nr. 1//ESC 2/13 4/1" | | DESCSET | 0 256 0 | Uppercase substitution can be performed or not performed both for entity names and for other names. Either short reference delimiters assigned by the reference delimiter set or no short reference delimiters are supported. The reserved names can be changed. The quantity set can be increased within certain limits subject to there being sufficient memory available. The upper limit on NAMELEN is 239. The upper limits on ATTCNT, ATTSPLEN, BSEQLEN, ENTLVL, LITLEN, PILEN, TAGLEN, and TAGLVL are more than thirty times greater than the reference limits. The upper limit on GRPCNT, GRPGTCNT, and GRPLVL is 253. NORMSEP cannot be changed. DTAGLEN are DTEMPLEN irrelevant since *sgmls* does not support the DATATAG feature. ### SGML declaration The SGML declaration may be omitted, the following declaration will be implied: | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | \ | with the exception that characters 128 through 254 will be assigned to DATACHAR. When exporting documents that use characters in this range, an accurate description of the upper half of the document character set should be added to this declaration. For ISO Latin-1, an appropriate description would be:\ | | | | --- | --- | | BASESET | "ISO Registration Number 100//CHARSET | | | ECMA-94 Right Part of Latin Alphabet Nr. 1//ESC 2/13 4/1" | | DESCSET | 128 32 UNUSED | | | 160 95 32 | | | 255 1 UNUSED | ### Output format The output is a series of lines. Lines can be arbitrarily long. Each line consists of an initial command character and one or more arguments. Arguments are separated by a single space, but when a command takes a fixed number of arguments the last argument can contain spaces. There is no space between the command character and the first argument. Arguments can contain the following escape sequences. - **\\\\** A **\\.** - **\\n** A record end character. - **\\\|** Internal SDATA entities are bracketed by these. - **\\***nnn* The character whose code is *nnn* octal. A record start character will be represented by **\\012**. Most applications will need to ignore **\\012** and translate **\\n** into newline. The possible command characters and arguments are as follows: - **(***gi* The start of an element whose generic identifier is *gi*. Any attributes for this element will have been specified with **A** commands. - **)***gi* The end an element whose generic identifier is *gi*. - **-***data* Data. - **&***name* A reference to an external data entity *name*; *name* will have been defined using an **E** command. - **?***pi* A processing instruction with data *pi*. - **A***name val* The next element to start has an attribute *name* with value *val* which takes one of the following forms: - **IMPLIED** The value of the attribute is implied. - **CDATA** *data* The attribute is character data. This is used for attributes whose declared value is **CDATA**. - **NOTATION** *nname* The attribute is a notation name; *nname* will have been defined using a **N** command. This is used for attributes whose declared value is **NOTATION**. - **ENTITY** *name...* The attribute is a list of general entity names. Each entity name will have been defined using an **I**, **E** or **S** command. This is used for attributes whose declared value is **ENTITY** or **ENTITIES**. - **TOKEN** *token...* The attribute is a list of tokens. This is used for attributes whose declared value is anything else. - **D***ename name val* This is the same as the **A** command, except that it specifies a data attribute for an external entity named *ename*. Any **D** commands will come after the **E** command that defines the entity to which they apply, but before any **&** or **A** commands that reference the entity. - **N***nname* *nname.* Define a notation This command will be preceded by a **p** command if the notation was declared with a public identifier, and by a **s** command if the notation was declared with a system identifier. A notation will only be defined if it is to be referenced in an **E** command or in an **A** command for an attribute with a declared value of **NOTATION**. - **E***ename typ nname* Define an external data entity named *ename* with type *typ* (**CDATA**, **NDATA** or **SDATA**) and notation *not.* This command will be preceded by one or more **f** commands giving the filenames generated by the entity manager from the system and public identifiers, by a **p** command if a public identifier was declared for the entity, and by a **s** command if a system identifier was declared for the entity. *not* will have been defined using a **N** command. Data attributes may be specified for the entity using **D** commands. An external data entity will only be defined if it is to be referenced in a **&** command or in an **A** command for an attribute whose declared value is **ENTITY** or **ENTITIES**. - **I***ename typ text* Define an internal data entity named *ename* with type *typ* (**CDATA** or **SDATA**) and entity text *text*. An internal data entity will only be defined if it is referenced in an **A** command for an attribute whose declared value is **ENTITY** or **ENTITIES**. - **S***ename* Define a subdocument entity named *ename*. This command will be preceded by one or more **f** commands giving the filenames generated by the entity manager from the system and public identifiers, by a **p** command if a public identifier was declared for the entity, and by a **s** command if a system identifier was declared for the entity. A subdocument entity will only be defined if it is referenced in a **{** command or in an **A** command for an attribute whose declared value is **ENTITY** or **ENTITIES**. - **s***sysid* This command applies to the next **E**, **S** or **N** command and specifies the associated system identifier. - **p***pubid* This command applies to the next **E**, **S** or **N** command and specifies the associated public identifier. - **f***filename* This command applies to the next **E** or **S** command and specifies an associated filename. There will be more than one **f** command for a single **E** or **S** command if the system identifier used a colon. - **{***ename* The start of the SGML subdocument entity *ename*; *ename* will have been defined using a **S** command. - **}***ename* The end of the SGML subdocument entity *ename*. - **L***lineno file* - **L***lineno* Set the current line number and filename. The *filename* argument will be omitted if only the line number has changed. This will be output only if the **-l** option has been given. - **#***text* An APPINFO parameter of *text* was specified in the SGML declaration. This is not strictly part of the ESIS, but a structure-controlled application is permitted to act on it. No **#** command will be output if **APPINFO NONE** was specified. A **#** command will occur at most once, and may be preceded only by a single **L** command. - **C** This command indicates that the document was a conforming SGML document. If this command is output, it will be the last command. An SGML document is not conforming if it references a subdocument entity that is not conforming. ## BUGS Some non-SGML characters in literals are counted as two characters for the purposes of quantity and capacity calculations. ## SEE ALSO The SGML Handbook, Charles F. Goldfarb\ ISO 8879 (Standard Generalized Markup Language), International Organization for Standardization ## ORIGIN ARCSGML was written by Charles F. Goldfarb. *Sgmls* was derived from ARCSGML by James Clark (jjc@jclark.com), to whom bugs should be reported.