'\" te .\" Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved. .TH sgml 5 "7 Jan 1997" "SunOS 5.11" "Standards, Environments, and Macros" .SH NAME sgml, solbook \- Standard Generalized Markup Language .SH DESCRIPTION .sp .LP Standard Generalized Markup Language (\fBSGML\fR) is the ISO standard 8879:1986 that describes a syntax for marking up documents with tags that describe the purpose of the text rather than the appearance on the page. This form of markup facilitates document interchange between different platforms and applications. \fBSGML\fR allows the management of information as data objects rather than text on a page. .sp .LP In an \fBSGML\fR document the main structural components are called \fBelements\fR. The organization and structure of a document and the meaning of elements are described in the Document Type Definition ( \fBDTD\fR ). Elements are the \fItags\fR that identify the content. Element names may be descriptive of the content for ease of use. For example \fB\fR for paragraphs. Elements can have \fBattributes\fR which are used to modify or refine the properties or characteristics of the element. Within the \fBDTD\fR a valid context for each element is defined and a framework is provided for the types of elements that constitute a compliant document. .sp .LP Another component of the \fBDTD\fR is \fBentities\fR. Entities are a collection of characters that can be referenced as a unit. Entities are similar to constants in a programming language such as C. They can be defined and referenced. An entity can represent one character or symbol which does not appear on a standard keyboard, a word or group of words, or an entire separate sgml marked-up file. Entities allow reuse of standard text. .sp .LP There is no single standard \fBDTD\fR , but the de facto standard for the computer industry is the DocBook \fBDTD\fR , developed and maintained by the Davenport Group. Within Sun, the SolBook \fBDTD\fR , which is a proper subset of DocBook \fBDTD\fR , is used when writing reference manual pages. The SolBook \fBDTD\fR contains a number of tags that are designed for the unique needs of the reference pages. .SH SOLBOOK ELEMENTS .sp .LP Elements are defined with a hierarchical structure that gives a structure to the document. The following is a description of some of the elements from the SolBook \fBDTD\fR which are used for reference pages. .SS "DOCTYPE" .sp .LP The first line in an \fBSGML\fR file that identifies the location of the DTD that is used to define the document. The \fB\fR\&. All of the text and other tags must be contained within this tag. .SS "RefMeta" .sp .LP The next tag in a reference page is \fB\fR, which is a container for several other tags. They are: .sp .ne 2 .mk .na \fB \fR .ad .RS 20n .rt This is the title of the reference page. It is equivalent to the name of the reference page's file name, without the section number extension. .RE .sp .ne 2 .mk .na \fB \fR .ad .RS 20n .rt This is the section number that the reference page resides in. The contents may be a text entity reference. .RE .sp .ne 2 .mk .na \fB \fR .ad .RS 20n .rt There are one or more \fB\fR tags which contain \fImeta\fR information. Meta information is information about the reference page. The \fB\fR tag has the \fBclass\fR attribute. There are four classes that are routinely used. .sp .ne 2 .mk .na \fBdate \fR .ad .RS 14n .rt This is the date that the file was last modified. By consensus this date is changed only when the technical information on the page changes and not simply for an editorial change. .RE .sp .ne 2 .mk .na \fBsectdesc \fR .ad .RS 14n .rt This is the section title of the reference page; for example \fBUser Commands\fR. The value of this attribute may be a text entity reference. .RE .sp .ne 2 .mk .na \fBsoftware \fR .ad .RS 14n .rt This is the name of the software product that the topic discussed on the reference page belongs to. For example \fBUNIX\fR commands are part of the SunOS x.x release. The value of this attribute may be a text entity reference. .RE .sp .ne 2 .mk .na \fBarch \fR .ad .RS 14n .rt This is the architectural platform limitation of the subject discussed on the reference page. If there are no limitations the value used is \fBgeneric\fR. Other values are \fBsparc \fRand\fB x86\fR. .RE .sp .ne 2 .mk .na \fBcopyright \fR .ad .RS 14n .rt This attribute contains the Sun Microsystems copyright. Any other copyrights that may pertain to the individual reference page file should be entered as separate \fB\fR entries. The value of this attribute may be a text entity reference. .RE .RE .SS "RefNameDiv" .sp .LP This tag contains the equivalent information to the \fB\&.TH\fR macro line in an \fBnroff\fR(1) reference page. \fB\fR contains three tags. These tags contain the text that is before and after the `-' (dash) on the \fBNAME\fR line. .sp .ne 2 .mk .na \fB \fR .ad .RS 20n .rt These are the names of the topics that are discussed in the file. There may be more than one \fB\fR for a page. The first \fB\fR must match the name of the file and the \fB\fR\&. If there are more than one \fB\fR tags, each is separated by a `,' (comma). The comma is generated by the publisher of sgml files, so it should not be typed. This is referred to as \fIauto-generated\fR text. .RE .sp .ne 2 .mk .na \fB \fR .ad .RS 20n .rt The text after the dash on the \fBNAME\fR line is contained in this tag. This is a short summary of what the object or objects described on the reference page do or are used for. The dash is also auto-generated and should not be typed in. .RE .sp .ne 2 .mk .na \fB \fR .ad .RS 20n .rt In some cases the \fB\fR is a general topic descriptor of a group of related objects that are discussed on the same page. In this case the first tag after the \fB\fR is a \fB\fR\&. The \fB\fR tags follow. Only one \fB\fR is allowed, and it should match the \fB\fR\&. .RE .SS "RefSynopsisDiv" .sp .LP The \fBSYNOPSIS\fR line of the reference page is contained by this tag. There is a \fB\fR that usually contains an entity reference. The text is the word \fBSYNOPSIS.\fR There are several tags within \fB<refsynopsisdiv>\fR that are designed specifically for the type of synopsis that is used in the different reference page sections. The three types are: .sp .ne 2 .mk .na \fB<cmdsynopsis> \fR .ad .RS 19n .rt Used for commands and utilities pages. .RE .sp .ne 2 .mk .na \fB<funcsynopsis> \fR .ad .RS 19n .rt Used for programming interface pages. .RE .sp .ne 2 .mk .na \fB<synopsis> \fR .ad .RS 19n .rt Used for pages that do not fall into the other two categories. .RE .SS "RefSect1" .sp .LP This tag is equivalent to the \fB\&.SH\fR nroff macro. It contains a \fB<title>\fR element that is the title of the reference page section. Section names are the standard names such as \fBDESCRIPTION,\fR \fBOPTIONS,\fR \fBPARAMETERS,\fR \fBSEE\fR \fBALSO,\fR and others. The contents of the \fB<title>\fR may be a text entity reference. .SS "RefSect2" .sp .LP This tag is equivalent to the \fB\&.SS\fR nroff macro. It contains a \fB<title>\fR element that contains the text of the sub-section heading. \fB<refsect2>\fR tags may also be used within a \fB<refsynopsisdiv>\fR as a sub-section heading for the \fBSYNOPSIS\fR section. .SH BLOCK ELEMENTS .sp .LP There are a number of block elements that are used for grouping text. This is a list of some of these elements. .sp .ne 2 .mk .na \fB<para> \fR .ad .RS 22n .rt This tag is used to contain a paragraph of text. .RE .sp .ne 2 .mk .na \fB<variablelist> \fR .ad .RS 22n .rt This tag is used to create two column lists. For example descriptions for command options, where the first column lists the option and the second column describes the option. .RE .sp .ne 2 .mk .na \fB<orderedlist> \fR .ad .RS 22n .rt An list of items in a specific order. .RE .sp .ne 2 .mk .na \fB<itemizedlist> \fR .ad .RS 22n .rt A list of items that are marked with a character such as a bullet or a dash. .RE .sp .ne 2 .mk .na \fB<literallayout> \fR .ad .RS 22n .rt Formatted program output as produced by a program or command. This tag is a container for lines set off from the main text in which line breaks, tabs, and leading white space are significant. .RE .sp .ne 2 .mk .na \fB<programlisting> \fR .ad .RS 22n .rt A segment of program code. Line breaks and leading white space are significant. .RE .sp .ne 2 .mk .na \fB<table> \fR .ad .RS 22n .rt This tag contains the layout and content for tabular formatting of information. \fB<table>\fR has a required \fB<title>\fR\&. .RE .sp .ne 2 .mk .na \fB<informaltable> \fR .ad .RS 22n .rt This tag is the same as the \fB<table>\fR tag except the \fB<title>\fR is not required. .RE .sp .ne 2 .mk .na \fB<example> \fR .ad .RS 22n .rt This tag contains examples of source code or usage of commands. It contains a required \fB<title>\fR\&. .RE .sp .ne 2 .mk .na \fB<informalexample> \fR .ad .RS 22n .rt This tag is the same as the \fB<example>\fR tag except the \fB<title>\fR is not required. .RE .SH INLINE ELEMENTS .sp .LP The inline elements are used for tagging text. .sp .ne 2 .mk .na \fB<command> \fR .ad .RS 21n .rt An executable program or the entry a user makes to execute a command. .RE .sp .ne 2 .mk .na \fB<function> \fR .ad .RS 21n .rt A subroutine in a program or external library. .RE .sp .ne 2 .mk .na \fB<literal> \fR .ad .RS 21n .rt Contains any literal string. .RE .sp .ne 2 .mk .na \fB<parameter> \fR .ad .RS 21n .rt An argument passed to a computer program by a function or routine. .RE .sp .ne 2 .mk .na \fB<inlineequation> \fR .ad .RS 21n .rt An untitled mathematical equation occurring in-line. .RE .sp .ne 2 .mk .na \fB<link> \fR .ad .RS 21n .rt A hypertext link to text within a book, in the case of the reference manual it is used to cross reference to another reference page. .RE .sp .ne 2 .mk .na \fB<olink> \fR .ad .RS 21n .rt A hypertext link used to create cross references to books other than the reference manual. .RE .sp .ne 2 .mk .na \fB<xref> \fR .ad .RS 21n .rt A cross reference to another part of the same reference page. .RE .SH SEE ALSO .sp .LP \fBman\fR(1), \fBnroff\fR(1), \fBman\fR(5)