You can find the DocBook DTD and its documentation online in the Davenport archive (/pub/davenport/docbook) at ftp.ora.com (140.186.65.25). This sample session shows how to retrieve the DTD and its documentation: %ftp ftp.ora.com Connected to ruby.ora.com. 220 ruby FTP server (Version 6.12 Thu Apr 23 21:09:30 EDT 1993) ready. Name (ftp.ora.com:dale): anonymous 331 Guest login ok, send e-mail address as password. Password: ← type e-mail address ftp>cd pub/davenport/docbook The DocBook DTD and related ASCII files are in a file named docbook.N.shar, where N is the current revision number: ftp>get docbook.2.1.shar Most of these files also exist separately and may be ftp'd individually. The get command will put this ASCII shar file on your system. You must later unpack it on your system: sh docbook.2.1.shar Back to your ftp session. The DocBook documentation is in a compressed PostScript file: ftp>binary ftp>get docbook.ps.Z This puts the binary file docbook.ps.Z on your system. You must uncompress it before sending it to a PostScript printer or viewer. The DocBook DTD defines structural SGML markup for computer documentation and technical books. It is supported by the Davenport Group, which is a group of software documentation producers that was established to promote the interchange and delivery of computer documentation using SGML and other relevant standards. Our primary goal in developing this DTD was to filter existing software documentation into SGML. It describes the structures we and other producers and consumers of software documentation have encountered in processing large bodies of such material. While it was initiated as an interchange format, the DTD is now coming into use as a production DTD. Accordingly, in this revision, specific processing expectations have been developed for some elements, and some print conventions are modelled more directly than before. We expect that this DTD will evolve as it is applied to more documents, as more SGML tools come into use, and as users gain more experience in working with it. We are interested in your use of the DocBook DTD and welcome comment (see title page for addresses). We are committed to reviewing revisions made by various groups and evaluating them for inclusion in the next release. Groups using the DocBook DTD for material other than software documentation may need to extend it for their domain of applications. Likewise, anyone may wish to construct a subset of this DTD, or a local version that constrains authors more tightly. Before making changes you should read the section near the top of the DTD itself regarding local modifications. The DTD uses the model of books to represent the content of documentation. The primary metainformation about a collection of documents is located at the Book level. A collection of Books can be a Set, but no larger structures are provided. A Book is composed of book components, such as Prefaces and Chapters and Appendices, some of which may be organized in Parts. Below these book components are additional levels of sectioning, marked as Sect1 through Sect5. A section is further organized by block-oriented elements such as Paras (paragraphs). Other block-oriented elements, such as lists, are more complex, requiring other elements within them. For example, a Listitem (an item in a list) may contain more than one paragraph, and lists may be nested within Listitems. In addition to its hierarchical organization, the information may be marked up with elements that indicate nonlinear relationships, including IndexTerms, XRefs (cross references), and Links. This DTD also provides many general and specific in-line elements, some of which are peculiar to computer documentation. The following sections show examples of how to combine the syntactic elements defined in the DocBook DTD. Following these examples is a reference section with brief definitions of all the elements. SGML element names are not case-sensitive. We capitalize them for readability. In the examples that follow, some punctuation and math characters are represented by text entities (for example, &amp;), which are defined by external reference in the DTD. A few elements appear in various contexts; for example, Title is used for the contents of headings at all levels. The typography of the examples is designed for legibility; line breaks and leading white space are not significant. In some elements the dreaded SGML mixed content is allowed, but should be benign. The following warning should no longer be needed: For best results start the text of an element immediately after the start tag, without a space or line break. Some attributes are not mentioned in the following description. For full details on attributes, see the alphabetical list of elements. Here's a diagram of a fairly vanilla Book: Book BookInfo ToC LoT Preface Chapter Chapter Chapter Chapter Reference Appendix Appendix Glossary Bibliography Index Books may have Chapters and Appendices grouped in Parts: Book BookInfo Preface Part PartIntro Chapter Chapter Part PartIntro Chapter Chapter Chapter Part PartIntro Chapter Chapter A reference manual might be arranged like this: Book BookInfo ToC LoT Preface Reference Reference Reference Reference Appendix Appendix Appendix Appendix Index A Set of Books may have a SetInfo and must contain two or more Books: Set SetInfo Book Book Book In a change from the previous revision, the all-purpose DocBook wrapper has been retired. Now, in order to parse your document, you must specify its highest-level element at its head, in the document type declaration: !DOCTYPE chapter SYSTEM "/anyold/path/docbook.dtd" or construct a shell file that contains a document type declaration, and refers to your document as an entity. In this case, your document should have no document type declaration itself. In this example a short Book is represented, with its later parts commented out: <!DOCTYPE book SYSTEM "/anyold/path/docbook.dtd" [ !ENTITY bookinfo SYSTEM "/some/path/bookinfo.sgm" !ENTITY pref SYSTEM "/some/path/pref.sgm" !ENTITY c1 SYSTEM "/some/path/ch01.sgm" !ENTITY c2 SYSTEM "/some/path/ch07.sgm" !ENTITY appa SYSTEM "/some/path/appa.sgm" !ENTITY appb SYSTEM "/some/path/appb.sgm" !ENTITY glossary SYSTEM "/some/path/glossary.sgm" ]> BOOK &bookinfo; &pref; &c1; !-- &c2; -- !-- &appa; -- !-- &appb; -- !-- &glossary; -- /BOOK A Book may begin with a Title and TitleAbbrev (abbreviated title), followed in order by an optional BookInfo, an optional ToC (Table of Contents), any number of LoTs (List of Titles), any number of Prefaces, main contents, and back matter. The main contents are required, and must be one or more Parts; one or more Chapters followed by any number of References; one or more Articles; or one or more References. All back matter is optional, but must appear in order: any number of Appendices, a Glossary, a Bibliography, and any number of Indexes and SetIndexes, followed by any number of LoTs, followed by an optional ToC. Book has FPI and Label attributes; you can supply an SGML Formal Public Indentifier (FPI) as the value of the former and the number of a Book, when it is part of a Set, in the latter. The Label attribute, which is provided for book parts, too, allows you to “take a snapshot” of a document collection, or to use one particular state of it for reference. The Mark attribute on OrderedList and the BeginPage element provide further means to do this. You might want to use these elements to ensure that an on-line presentation of your document collection can be matched to a print version by standard reference methods (citing chapter number, number of an item in a list, page number). Part contains an optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro, followed by one or more book components. You can use book components individually. For example, here is a Chapter standing on its own: Chapter Title TitleAbbrev Para Para BOOK CHAPTER ID="CH-061-ch05-1" TITLEAn Introduction to the X Window System /TITLE TITLEABBREVIntro to X /TITLEABBREV PARAAnd so on. . . . /PARA /CHAPTER /BOOK A Chapter or Appendix may have a DocInfo, followed by a required Title and some text at least a Sect, a paragraph, a list, or a RefEntry. It may also have a TitleAbbrev. The DocInfo may contain information relevant to that book part alone; information general to the collection(s) of which it is part should be placed in the collection(s)'s BookInfo(s). A Preface, Glossary, or Bibliography must have a Title, so you can use the Preface element for a foreword or acknowledgements section and call a Glossary or Bibliography something else, such as “Key Words,” or “Sources.” Bibliography, Glossary, and Index are also allowed to have more specialized contents: BiblioEntry for Bibliography, GlossEntry for Glossary, and IndexEntry for Index. These specialized book parts may be divided into BiblioDivs, GlossDivs, or IndexDivs, respectively. (An IndexEntry is part of an Index, whereas an IndexTerm is part of the text of a document, marking the term to be indexed.) Additionally, an IndexDiv may have a SegmentedList, to accommodate permuted indices. A Glossary may end with a Bibliography. IndexEntries and IndexTerms are discussed later. BiblioEntries may begin and end with BiblioMisc, between which there must be an ArtHeader, BookBiblio, or SeriesInfo. This makes it possible to use the same content model for metainformation and bibliographic reference. (In the future there should perhaps be some way to link from a BiblioEntry to a BookBiblio somewhere on one's local system.) GlossaryEntries are simply pairs of GlossaryTerms and GlossaryDefs, both of which may contain in-line elements. Bibliography, Glossary, Reference, and Index may be book components on their own or may occur at the beginning or end of a Preface, Chapter, Appendix, or Sect. A RefEntry (the element for a man page) cannot be a book component, but can appear in the same places within Preface, Chapter, Appendix, or Sect as can a Bibliography, Glossary, or Index. You could construct a Chapter this way: Chapter Title Para Sect1 Title Para Para Para Glossary Bibliography Sect1 Title RefEntry RefEntry RefEntry RefEntry Index A ToC, or table of contents, may be a book component on its own or may occur within other book components. It may have a DocInfo, Title, and TitleAbbrev. In this revision, ToC has been subdivided to follow the divisions of a book: following an optional Title and TitleAbbrev, a ToC may have any number of ToCFronts, which are the entries for the front matter. Following the ToCFronts, if any, a ToC must have either one or more ToCParts (entries for Parts) or ToCChaps (entries for Chapters and Appendices), and may have any number of ToCBacks (entries for back matter). A ToCPart may begin with in-line elements (in all cases, this part is the actual table of contents entry, which was formerly ToCEntry), then contains any number of ToCChaps. Like other ToC subelements, it has a PageNum attribute, which may have the value of a physical page number. A ToCChap may begin with in-line elements, then may have any number of ToCLevel1s, which are entries for Sect1s. ToCLevel1s may begin with in-line elements, then may have any number of ToCLevel2s, and so on down to ToCLevel5, which may have only in-line elements. Thus if you have a Table of Contents that shows section headings, the second-level entries are nested within the first-level entries, and so on. Alternately, a Link may be included as all or part of the contents of a ToC subelement, both pointing to a section by its ID and containing (as text) the page number on which the section begins. For example: TOC ID="CH-061-toc-1" TITLETable of Contents /TITLE TOCCHAP LINKEND="S1-061-ch01-1"Chapter One: Nuts and Bolts /TOCCHAP TOCCHAPChapter Two: Screws and Nails TOCLEVEL1Screws /TOCLEVEL1 TOCLEVEL1Nails /TOCLEVEL1 /TOCCHAP /TOC Notice that you can make a ToC into a small model of a Book, a facility that could be used to provide context to an application that may be called upon to process an arbitrary piece of a Book without access to the other pieces. This facility is duplicated in BookInfo's Contents attribute, and the ToC must be considered along with any LoTs and the BookInfo to provide fuller context. An LoT is like a ToC except that it is used for lists of tables, figures, and so on. An LoT contains LoTEntries, which may contain Links, just like ToC subelements. LoTEntries also have a PageNum attribute, but have no subelements. A BookInfo contains metainformation about the collection of documents of which it is a part. BookInfo must contain a BookBiblio (a wrapper, new in this revision, for any information that might appear in a bibliographic reference), followed by any number of LegalNotices, followed by any number of ModeSpecs (which are link processing information sets, pointed to by the LinkMode attribute of OLink, and collected here for common reference). BookInfo has a Contents attribute, the values of which are the IDs of the ToC, LoTs, Prefaces, Parts, Chapters, Appendixes, References, Glossary, Bibliography, and Indexes comprising the Book, in the order of their appearance. BookBiblio contains all the information about a book that may be relevant to a bibliographical citation, so that it may also be used or referred to by BiblioEntry. In fact, all the information typically found on a title page's recto and verso are included in BookBiblio, except the LegalNotices, although only Title and AuthorGroup are required. BookBiblio may contain, in order: the required Title (the title of the Book), optional TitleAbbrev, Subtitle, and Edition, followed by one or more required AuthorGroups; then, optionally, either an ISBN followed by an optional VolumeNum (the number of the volume in a Set) or (in case you are using Book for a journal composed of Articles) an ISSN followed by optional VolumeNum, optional IssueNum, and an optional PageNums (the numbers of the pages contained in a given issue or volume). After these elements there may occur, again optionally and in order, the labelling information InvPartNumber, ProductNumber, ProductName, PubsNumber, and ReleaseInfo. Then there may be any number of Pubdates followed by any number of Publishers, followed by an optional Copyright, then an optional SeriesInfo (information about a series the Book is published as part of). Following that there may be any number of Abstracts, any number of ConfGroups (wrappers for information about a conference from which the Book results), any number of ContractNums mixed with any number of ContractSponsors, and an optional PrintHistory followed by an optional RevHistory. An individual book component may have a DocInfo, in which information pertinent only to that component may appear. DocInfo may contain, in order: a required Title, optional TitleAbbrev and Subtitle, followed by one or more AuthorGroups, any number of Abstracts, an optional RevHistory, and any number of LegalNotices. A Reference is a collection of RefEntries. Before its RefEntries, it has an optional DocInfo, a required Title, an optional TitleAbbrev, and an optional PartIntro. It may be a book component or may occur within a Part. For example: Reference Title PartIntro RefEntry RefEntry RefEntry RefEntry RefEntry A Preface, Chapter, or Appendix may contain up to five levels of hierarchical sections called Sect1, Sect2, and so on. In a RefEntry, these are RefSect1 through RefSect3 (no further subheads). Headings must be nested properly: a Sect3 is not allowed directly under a Sect1 without a Sect2 in between. Sects1--4 that contain lower-level Sects may be empty of other content. However, a Bridgehead (a heading not contained in a wrapper that associates it with the text following, and independent of the Sect hierarchy) may be inserted between block-oriented elements anywhere, with its RenderAs attribute set to an appropriate value. In this revision, the Docbook DTD no longer allows you to put paragraphs, lists, and other block-oriented elements between Sects. A section includes a Title (the text of the heading itself) and all material following, up to the end of the document or the next section at the same or higher level. Consequently, anything may occur in a section except another book component (DocInfo, Glossary, and so on) or another section of the same level; deeper sections must be nested properly. SECT1 ID="S1-061-ch05-1" TITLERunning the Program /TITLE PARAIf you have the sample programs and a workstation that runs X, you can try out this program by compiling FILENAME>basic/basicwin.c</FILENAME. /PARA /SECT1 Sections have a Number attribute, in case you wish to hard-code section numbering for reference. Most book components can contain the following block-oriented elements, some of them in formal and informal dress. Informal elements such as InformalTable are simply untitled equivalents of their formal sisters (Table), and are not to be listed in a LoT (such as a List of Tables). Highlights (list of main points) an Epigraph Paragraphs Lists Procedures MsgSets (error messages) Admonitions (Warnings, Tips, and so on) Tables and InformalTables Figures and Equations Examples LiteralLayouts, ProgramListings, Screens, and ScreenShots Graphics BlockQuotes Sidebars Footnotes Admonitions and other blocks An Epigraph (a section of poetry or prose, usually specially formatted) may occur between a book component's Title and other content. Highlights (a section of major points appearing in the book component) typically appears below either the Title (or below any Epigraph), or may be extracted and presented before book component proper begins. Paragraphs are the lowest level of ordinary text that you need to tag except for in-line elements. The DocBook DTD offers three kinds of paragraphs. Para may contain block-oriented elements (for example, Footnotes, lists, and Figures), while SimPara excludes them. FormalPara requires a Title, while Para and SimPara may not have Titles. FormalPara, Para, and SimPara are allowed in exactly the same contexts. No provision is made, in the case of SimPara, for indicating indentation; in the case of FormalPara and Para it is not needed. In some cases, such as admonitions and Footnotes, paragraph tags are required within the outer tags, to allow multiple paragraphs. Thus a paragraph may be nested within a paragraph if a wrapper intervenes. WARNING PARANever use software from sources you would not trust with your firstborn. /PARA PARAIf in doubt about a program, don't use it at all. /PARA /WARNING Lists contain ListItems, which typically contain paragraphs; ListItems, too, may contain more than one paragraph. (See List examples below.) Aside from straight text and, in the case of SimPara, block-oriented elements, paragraphs may contain any of the in-line elements discussed in the “In-line Components” section. There are five kinds of lists: ItemizedList (bulletted, dashed, and so on) OrderedList (numbered or lettered) VariableList (composed of paragraphs or sets of paragraphs with associated Terms) SegmentedList (a series of entries composed of equal numbers of segments, with optional titles pertaining to all the first segments, all the second segments, and so on) SimpleList (composed of terms that may be arranged in columns or in-line) Lists may be nested within ListItems (an ItemizedList inside a ListItem of an OrderedList, for example), and ListItems may include paragraphs and other block-oriented elements. ItemizedLists use the Mark attribute to determine the character that precedes each ListItem. You may leave this to an application to decide, or supply a text string (there is no default and there are no generally agreed upon strings) to specify the mark that should appear before each ListItem. You might use such strings as Bullet, Dash, Box, or Check, or a text entity instead (such as bull). The Mark value can be overridden at the ListItem level by the value of the ListItem's Mark attribute, if it is supplied. Here's an ItemizedList: ITEMIZEDLIST MARK="DASH" LISTITEM PARAThis function should connect the client to an X server with\break FUNCTION>XOpenDisplay</FUNCTION, and exit gracefully if the connection could not be made. /PARA /LISTITEM LISTITEM PARAGet information about the physical screen, and use it to calculate the desired size of the window. /PARA PARAA second paragraph occurring within the same dashed ListItem would be marked up as this paragraph is. /PARA /LISTITEM /ITEMIZEDLIST Normally an ItemizedList nested within a list of the same type is given a different mark or alphanumeric style (as in an outline). The DocBook DTD does not define any default sequence of marks. You must either indicate them by using the appropriate attributes or instruct your SGML application that, for example, the sequence of marks for an ItemizedList that contains another ItemizedList is bullets, then dashes. OrderedLists may use the Numeration attribute to determine how the list is numbered. This attribute has a delimited set of values: Arabic (1, 2, 3), Upperalpha (A, B, C), Loweralpha (a, b, c), Upperroman (I, II, III), or Lowerroman (i, ii, iii). If extensions are needed, for example in the case of Japanese or Arabic documents, the values LocalAlpha and LocalNumber might be used, though these are not now supported. The default is Arabic. If your numbered list begins with 1, you do not need to supply a Numeration value. OrderedList also has the Continuation attribute, to indicate whether the numbering of a list begins afresh or continues the numbering of the immediately preceding list. Finally, OrderedList has an InheritNum attribute, the values of which are Inherit and Ignore. Ignore is the default; i.e., numbering starts over (1, 2, 3 instead of 3.1, 3.2, 3.3). Set InheritNum to Inherit if you want nested lists to pick up the numbering of the ListItem within which they are nested (an OrderedList nested under the third ListItem of another OrderedList is numbered 3.1, 3.2, 3.3, instead of 1, 2, 3). ORDEREDLIST LISTITEM PARA>The window is mapped with <FUNCTION>XMapWindow</FUNCTION or related routines. /PARA /LISTITEM LISTITEM PARAAll its ancestors must be mapped. This condition is always satisfied for the children of the root window, the top-level windows of each application. /PARA /LISTITEM LISTITEM PARAThe window must not be obscured by visible sibling windows or their ancestors this depends on the stacking order. When first mapped, a window appears on top of its siblings, which will be on top of all windows if its parent is the root window. /PARA /LISTITEM /ORDEREDLIST A VariableList may have a Title and TitleAbbrev, and must have VarListEntries, each of which contains a set of one or more Terms followed by a ListItem. Terms may contain in-line elements. Schematically a VariableList looks like this: VariableList VarListEntry Term Term ListItem Para Para VarListEntry Term ListItem Para VarListEntry Term ListItem Para In actual markup: VARIABLELIST VARLISTENTRY TERMWindow /TERM LISTITEM PARAA unique integer identifier (ID) that is returned by XCreateWindow or XCreateSimpleWindow and is thereafter used by the program to refer to the created window resource. /PARA /LISTITEM /VARLISTENTRY VARLISTENTRY TERMDisplay /TERM LISTITEM PARAA large structure that contains information about the server and its screens. It is filled only after this program connects to a server by calling XOpenDisplay. /PARA PARAA small structure containing information about the server and its screens would be more economical, but we mention it only to generate another paragraph. /PARA /LISTITEM /VARLISTENTRY /VARIABLELIST A SegmentedList is composed of labelled sets of information, and may be used to represent information that is often presented in simple tables. A SegmentedList may have a Title and TitleAbbrev, followed by any number of SegTitles and two or more SegListItems. SegListItems are composed of two or more Segs, which may contain in-line elements. You might render a SegmentedList in tabular form, or use some other typographic arrangment, such as: SEGMENTEDLIST SEGTITLEMuseum /SEGTITLE SEGTITLECity /SEGTITLE SEGTITLECollections /SEGTITLE SEGLISTITEM SEGAsian Art Museum /SEG SEGSan Francisco /SEG SEGEast Asian, Indian, and Islamic /SEG /SEGLISTITEM SEGLISTITEM SEGBritish Museum /SEG SEGLondon /SEG SEG><EMPHASIS>all areas</EMPHASIS /SEG /SEGLISTITEM SEGLISTITEM SEGLouvre /SEG SEGParis /SEG SEGmostly paintings /SEG /SEGLISTITEM /SEGMENTEDLIST This SegmentedList might appear in print as follows: Museum: Asian Art Museum City: San Francisco Collections: East Asian, Indian, and Islamic Museum: British Museum City: London Collections: all areas Museum: Louvre City: Paris Collections: mostly paintings A SimpleList is intended for long lists of single words or short phrases. It consists of one or more Members, and has Columns and Type attributes. The value of Type may be Vert (the default), Horiz, or Inline. Inline indicates that the list should be formatted as a regular part of a paragraph, with commas and “and” inserted, such as: a, b, c, d, e, f, g, h, i, j, k, and l. Vert and Horiz indicate that the Members should be displayed in the number of columns specified by the Columns attribute (the default is 1). If the value of Type is Vert, the Members should be ordered from top to bottom of each column: a d g j b e h k c f i l If Horiz, the Members should be ordered left to right, one row at a time: a b c d e f g h i j k l A Procedure is a quasilist of operations to be performed. Procedure may have a Title and TitleAbbrev, followed by block-oriented elements, such as paragraphs, followed by one or more Steps. A Step may have a SubSteps wrapper for Steps nested within it, and this nesting may continue indefinitely (contrast the methods of nesting lists and Sects). This construction is intended to maximize the reusability of subsections of Procedures. Note that “SubSteps” is an element name, not the plural of SubStep (there is no element named SubStep). After an optional Title, a Step must consist either of block-oriented elements such as paragraphs followed optionally by a SubSteps element, or simply a SubSteps element. A SubSteps then contains one or more Steps it is a wrapper. PROCEDURE TITLE>Waking Up</TITLE PARAThis is what you must do to awaken. /PARA STEP PARABring yourself to a hypnopompic state, either from an ongoing dream or by use of your internal clock. You may feel unable to move, but you will no longer be dreaming. /PARA PARANow you are ready for real-world readjustment. /PARA SUBSTEPS STEP PARARoll over. /PARA /STEP STEP PARASquint out of one eye. /PARA /STEP /SUBSTEPS /STEP STEP PARAYawn and rise from your bed. /PARA /STEP /PROCEDURE A MsgSet is a quasilist of messages produced by a system, with various additional information. These are typically error messages, but they could conceivably be congratulatory or soothing messages to the user. Please note that the entire Msg* construction is new and complicated; it may be simplified in the future. MsgSet contains one or more MsgEntries, which are merely wrappers, each containing one or more Msgs, followed by an optional MsgInfo, then any number of MsgExplans. Msg is the part of a MsgEntry that contains the error message and its subparts, along with explanatory text. A Msg has a required MsgMain, followed by any number of MsgSubs and MsgRels, in any order. MsgMain is the main error message of a Msg. MsgMain begins with an optional Title, followed by MsgText, the real content of the message (containing may be block-oriented elements). MsgSub contains messages that appear in various contexts. It, too, contains a an optional Title followed by MsgText. MsgRel contains a message that is related to the main message (MsgMain) but which appears in a different place. For example, MsgMain might be a message that appears on a network client, and MsgRel a related message that appears at the server console in response to the same condition or event. MsgRel begins with an optional Title and contains MsgText. That finishes the Msg part of MsgEntry; there remain MsgInfo and MsgExplan. MsgInfo holds information about the Msg containing it. It may have any number of MsgLevels, MsgOrigs, and MsgAuds, in any order. MsgLevel describes, in plain text, the level of importance or severity of a Msg. MsgOrig describes, in plain text, the origin of a Msg. MsgAud describes, again in plain text, the audience to which a Msg is relevant. MsgExplan is a holder for any kind of explanatory material relating to the Msg. MsgExplan begins with an optional Title (typically something such as “Explanation:” or “Action:”) and may contain block-oriented elements. MSGENTRY MSG MSGMAIN MSGTEXT PARAAuto removal: Token-ring lobe /PARA /MSGTEXT /MSGMAIN MSGSUB TITLEFailure /TITLE MSGTEXT PARALocal token-ring adapter /PARA PARALocal access unit /PARA PARALocal lobe cables /PARA /MSGTEXT /MSGSUB MSGREL TITLENetWare message: /TITLE MSGTEXT PARA>TOKEN-NW-237-Adapter <REPLACEABLE>number</REPLACEABLE> -board <REPLACEABLE>number</REPLACEABLE : The adapter is beaconing. /PARA PARA>Ring status = <REPLACEABLE>code</REPLACEABLE . /PARA /MSGTEXT /MSGREL /MSG MSGINFO MSGORIGNetView for NetWare /MSGORIG MSGLEVELInformative /MSGLEVEL /MSGINFO MSGEXPLAN TITLEExplanation: /TITLE PARAAdapter left the ring as part of the beacon automatic recovery process. /PARA /MSGEXPLAN MSGEXPLAN TITLEAction: /TITLE PARAAsk the LAN administrator to review the link data. /PARA /MSGEXPLAN /MSGENTRY A Table is an ordered array of text, usually with a title and headings. This information may be represented in SGML, but it may also be convenient to provide it in another form. The DocBook DTD allows you to mark up a table in SGML and also provide a graphic representation of it in an external file by using the Graphic element. Aside from Graphic, DocBook's Table formerly offered a choice of a simple model or a version of the canontbl.dtd, copyright SoftQuad, Inc. (used by kind permission of Yuri Rubinsky, SoftQuad). However, as no general solution to table markup seems to have been developed, and the CALS MIL-28001 DTD is more widely supported by existing tools, DocBook now permits only Graphic or a CALS-compliant model. If it is any consolation, the canontbl.dtd uses much of the same structure as CALS, easing migration from one model to the other. A Table has a required Title, a TitleAbbrev, and one or more Graphics (which may be pointers to external files that contain the Table formatted in a different way) or one or more TGroups, which are slabs of CALS table. For details on the contents of Table see the alphabetical list of elements; Tables may not be nested within Tables, but a Table may contain an EntryTbl, which achieves the same effect. InformalTable is Table's untitled sister. For Graphic, see Figure, below. TABLE TITLESample Decimal-Aligned Table /TITLE TGROUP ALIGN="CHAROFF="50"CHAR="." COLS="3" TBODY ROW ENTRY>345.021</ENTRY ENTRY>211.02</ENTRY ENTRY>221.3</ENTRY /ROW ROW ENTRY>blue</ENTRY ENTRY>red</ENTRY ENTRY>yellow</ENTRY /ROW /TBODY /TGROUP /TABLE A Figure must have a Title, may have a TitleAbbrev, and may contain one or more of the following: BlockQuote, InformalEquation, Graphic, InformalTable, Link, LiteralLayout, OLink, ProgramListing, Screen, Synopses, and ULink. A Graphic may contain graphical data or point to exterior files that contain such data. It has an ID attribute and a Format attribute that indicates how the data is formatted. Format may have the value CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS, EQN, FAX, FAXTILE, GIF, IGES, PIC, PS, TBL, TEX, TIFF. There is no default. Graphic may point to an external file via its Fileref or Entityref attributes. The value of Fileref should be a filename; the value of Entityref should be that of an external data entity. These attributes may conflict, so an order of precedence is specified: if data is given as the content of Graphic, neither Entityref nor Fileref should be given but a Format value should be supplied. If no data is given as the content of Graphic, only one of Entityref Fileref should be given; if both are present, Entityref pre\"empts Fileref. If either of those attributes is used, Format should not be. If Graphic occurs within or between paragraphs, it is to be displayed as a block (that is, Graphic is an informal figure); if a graphical image is to be presented in-line, it must be marked as an InlineGraphic, which is otherwise just like Graphic. Figure has common, Label, and Float attributes; Float indicates whether the Figure is to be rendered where convenient (yes) or at the place it occurs in the text (no, the default). FIGURE ID="FG-061-ch05-2" FLOAT="YES" TITLEThe xdmlogwin Display /TITLE GRAPHIC ENTITYREF="gr061ch05t2" /FIGURE Equations are solely graphical in this revision. An Equation may have a Title and TitleAbbrev, and then contains one or more InformalEquations or Graphics, in any order. InformalEquation is an untitled equation to be displayed as a block, like InformalTable, and may contain one or more Graphics; it has common attributes. InlineEquation is just the same as InformalEquation, but is to be display in-line. Example is defined very loosely, so that a program listing can be accompanied by other block-oriented elements. An Example must have a Title, may have a TitleAbbrev, and then contains any combination of paragraphs, lists, and other block-oriented elements. The DocBook DTD provides three elements for material set off from the main text, in which white space and line breaks are to be considered significant: LiteralLayout, ProgramListing, and Screen. All of these elements may contain in-line elements only, not block-oriented elements. They all have a Width attribute, which is some number indicating to an application how wide the widest line is, and a fixed Format attribute, with the value “linespecific.” LiteralLayout is the simplest of the linespecific elements. It consists only of the set-off lines: PARAFor information about the U.N. and intergalactic space, ask LITERALLAYOUT Butros Butros Ghali Secretary General United Nations /LITERALLAYOUT about the Security Council's jurisdiction over the Moon. /PARA A ProgramListing is just like a LiteralLayout, but should be reserved for listings of programs, which may require a different style of presentation. ProgramListings may have LineAnnotations, which are a document author's comments on the code, not the comments written into the code itself by the code's author. A Screen is a representation of all or part of a screen display, which may be textual or graphical. A Screen contains text and in-line elements, in the manner of a LiteralLayout. A Screen has no Title; if you want a Screen to have a Title, enclose it in a Figure or Example. Here's a Screen with text content: SCREEN ID="SC-1015-12-24" SYSTEMITEM CLASS="PROMPT"%//SYSTEMITEM> <USERINPUT>make install</USERINPUT install -c -m 0644 rgb.txt /usr/lib/X11 install -c -m 0644 rgb.dir /usr/lib/X11 install -c -m 0644 rgb.pag /usr/lib/X11 install -c -s showrgb /usr/lib/X11 install in ./rgb done /SCREEN If you want to represent a Screen's contents graphically, use the ScreenShot element. A ScreenShot has a Width attribute and contains an optional ScreenInfo and a required Graphic. The ScreenInfo is a comment about how the image in the Graphic was created (so you can recreate it if need be), and is not meant to be displayed or printed; it contains plain text. Here's a ScreenShot: SCREENSHOT SCREENINFO Press the F1 key and type “catfile” while holding down the Alt, Page Down, and F12 keys. /SCREENINFO GRAPHIC FORMAT="GIF"FILEREF="figs/05.07.gif" /GRAPHIC /SCREENSHOT BlockQuote is intended for a quotation set off from the main text, rather than occurring in-line (for an in-line quote, use Quote). In a BlockQuote white space is not significant: the lines wrap. A BlockQuote contains paragraphs and other block-oriented elements, not plain text. A Sidebar is a segment of text isolated from the narrative flow of the main text, typically boxed and allowed to float in the page layout. Magazines and newspapers contain many sidebars. A Sidebar may have a Title and a TitleAbbrev, and must have text in the form of paragraphs, lists, Figures, or other block-oriented elements; no Sects or other Sidebars are allowed. Within a paragraph or other element, the location of the footnote mark should be indicated with FootnoteRef, which points to the corresponding Footnote with its Linkend attribute, the value of which is the ID of the associated Footnote. FootnoteRef may contain plain text, which is the mark to be displayed, or it may be empty, in which case its Mark attribute provides another way of indicating the contents of the mark, such as an asterisk (*), a number (84), or a dingbat specified by a name that is to be interpreted by the application (dagger). Footnote may occur directly following the FootnoteRef, or at some other location within the document. It may contain paragraph, BlockQuote, InformalEquation, InformalTable, Graphic, Synopses, LiteralLayout, ProgramListing, Screen, and any kind of list. It has ID, Label, Lang, Remap, Role, and XRefLabel attributes; the ID attribute is required, as a FootnoteRef must point to it. Admonitions are special sections of text that call attention to some matter of importance. Admonitions are one of the following elements: Caution, Important, Warning, Tip, and Note. They may have Titles, paragraphs, and other block-oriented elements, but no Sects or other admonitions. Abstract (a document summary) and AuthorBlurb (author information) may have Titles and paragraphs. IndexTerms, Links, Anchors, and XRefs all indicate nonlinear relationships within the text unlike the hierarchical nesting of Sects and the linear flow of paragraphs within Sects. IndexTerms are words or phrases to be indexed. The DocBook DTD provides for three levels of indexing, as well as for “see” and “see also” indexing. IndexTerms may occur almost anywhere, but their contents may not do double duty as part of the text (troff style, not Tex style). The contents of IndexTerm do not appear in the text itself. An IndexTerm must contain a Primary, and may contain a See and one or more SeeAlsos, as well as a Secondary; within Secondary there may be a See and one or more SeeAlsos, as well as a Tertiary. IndexTerm has common, SpanEnd, PageNum, and Significance attributes. The SpanEnd attribute is for use in an IndexTerm ending a span of text to be indexed; that IndexTerm must be empty (have no content or end tag) and must have as the value of SpanEnd the ID of the IndexTerm that begins the span, earlier in the text. The PageNum attribute may be used to indicate the page on which the indexed term is found in print. Significance may have the value Preferred, indicating that the entry is the most pertinent of the series, or Normal (the default). PARAThis paragraph deals with two subjects that should be listed in the index: how to rotate your terminal and how to adjust its height. /PARA INDEXTERM PRIMARYrotating your terminal /PRIMARY /INDEXTERM INDEXTERM PRIMARYterminal /PRIMARY SECONDARYrotation of /SECONDARY /PRIMARY /INDEXTERM INDEXTERM PRIMARYterminal /PRIMARY SECONDARYadjustment of /SECONDARY SEEALSOtroubleshooting /SEEALSO /PRIMARY /INDEXTERM IndexEntries, which occur in the Index, might be constructed by extracting and processing the IndexTerms. IndexEntries themselves are put together just like IndexTerms, with the corresponding elements PrimaryIE, SecondaryIE, TertiaryIE, SeeIE, and SeeAlsoIE. A link is a pointer to another section in the document, or to another document. The link elements in this revision are still somewhat provisional, and are under active review. The most conventional of them is Link, which may include in-line elements as text and has a required Linkend attribute, which is the ID of the element it is linked to. It also has a Type attribute, so you can assign a role to a Link. And Link has an Endterm attribute, the value of which may be the ID of an element whose content is to appear as the text of the Link. For example, Link might give the label of a hot spot explicitly: To go there, LINK LINKEND="H1-061-ch05-1" click here /LINK or a Link might point to a section and display its title: Click to go to LINK LINKEND="S1-061-ch05-1"ENDTERM="T1-061-ch05-1" /LINK where the content of the element that bears the ID T1-061-ch05-1 (perhaps the title of Chapter Five) is displayed as the hot spot. (This is effectively an unclean form of CONREF.) Please note that the common attribute XRefLabel provides another mechanism for displaying text associated with a Link's target. Link uses the SGML mechanism of IDREF in pointing to an element by its ID. An SGML application may report an IDREF error when the ID does not occur in the document set being processed. This may be harmless. Anchor is an in-line element that marks a location as a target for a Link (any element bearing an ID may be a target, of course). Anchor has ID, PageNum, Remap, Role, and XRefLabel attributes, but only the ID is required. It is an empty element: at minimum, only the start tag is supplied, with an ID: There is an Anchor <ANCHOR ID=" 061-ch05-AN-7"> in this sentence. Two other links are provided in this revision, OLink (a link that performs some operation on its target) and ULink (a link that uses a Universal Resource Locator). Both of these are experimental and may be dropped in the future; for details, see the alphabetical list. In particular, ULink stores all link information in a format that SGML does not process, and you cannot expect SGML browsers to work on ULinks. USE EITHER AT YOUR OWN RISK. An XRef is a cross reference to another part of a document. It has Linkend and Endterm attributes, just like Link, but like Anchor, it may not have content. XRef must have a Linkend, but the Endterm is optional. If it is used, the content of the element it points to is displayed as the text of the cross reference; if it is absent, the XRefLabel of the cross-referenced object is displayed. See XREF LINKEND="ch05-s1"ENDTERM="ch05-t1", for more information. The example above references the section that has the ID "ch05-s1"and supplies the text of its Title, which has the ID "ch05-t1", in the manner of: “See Terminal Emulation and the xterm Terminal Type for more information.” To include in the cross reference text generated text that may be associated with the target, e.g., “Figure 5-1.”, use the same mechanism you employ to generate that text in the first place (your application's defaults or style sheet). In-line elements are used to label specific terms or usage. In-line elements may appear anywhere in a block-oriented element, but may not span two block-oriented elements. In documentation these elements are typically indicated by font changes. All of the elements defined in the DTD in the parameter entities that comprise inlinechar.gp may appear in-line. (See the Reference section for brief definitions of in-line elements.) Trying to determine the most specific in-line element that can be applied to the specialized terms in your document can be time-consuming and frustrating. Instead, you may wish to tag these terms using only the most general in-line elements. We have found it useful, in converting files from troff to SGML, to translate the font changes that mark off these terms in print into five DocBook tags: Emphasis, Literal, Parameter, UserInput, and Interface (which correspond well to our conventional use of italic, typewriter font, italic typewriter, bold typewriter, and sans serif; you may wish to choose other values). Some such tags (Application, Database, Interface, MediaLabel, Parameter, Replaceable, SystemItem, Trademark, and SGMLtag) now have a Class attribute with delimited values for each element. This mechanism provides a two-step approach toward specifying the meanings of in-line terms. For example, an Interface may be further specified as Button, Icon, Menu, or MenuItem through its Class attribute. You can thus indicate the general meaning of the term or be more precise, as you like. New in this revision is an Article element. A Book may consist of Articles, in which case it represents an issue of a journal (and you should provide its ISSN, not ISBN, in the BookInfo) or a collective work, such as an anthology. An Article has, in order, a required ArtHeader, main contents as for Chapter, then any number of Indexes, Glossaries, Bibliographies, Appendixes and Acknos, in any order. Article has common and ParentBook attributes, the latter pointing to the ID of the enclosing Book. For the details of ArtHeader, see the alphabetical list of elements. A man page or reference page is a distinct form of reference information. We have modelled our RefEntry element on man pages. In this DTD, a RefEntry may occur within a Chapter or Appendix, or a collection of RefEntries may be made into a book component called Reference. A RefEntry contains, in order: one DocInfo (optional); one RefMeta (optional); one or more Comments, links, FootnoteRefs, or XRefs (optional); one RefNameDiv (required); one RefSynopsisDiv (optional); one or more RefSect1s (required). Schematically, with additional elements particular to RefEntries: RefEntry DocInfo RefMeta RefEntryTitle ManVolNum RefMiscInfo RefNameDiv RefName RefPurpose RefSynopsisDiv Synopsis RefSect1 RefSect2 RefSect2 RefSect1 RefSect1 Reference entries have conventional divisions, but no single definitive conventional format. The arrangement of information in the initial divisions of a reference entry may be rather complicated. RefEntry accomodates several alternate structures for this information. For example, a typical reference entry has only a single subject (here, RefName), which is named in a division that is usually called “Name” (here, RefNameDiv), and is followed by an em dash and a short descriptive phrase (here, RefPurpose). A reference entry for mwm, the Motif window manager, might have this text in its Name division: "mwm   the Motif window manager" This is simple to tag: “mwm” is a RefName and the descriptive phrase is a RefPurpose (the em dash should not be represented in the SGML document). Other reference entries may provide a purpose statement on more than one subject (command, function, file format, and so on). For example, in a reference entry for grep there may be several subjects described by the same purpose statement: "grep, egrep, fgrep   search a file for a string or regular expression" Here all the terms in the series are RefNames, and should be tagged individually. Still other reference entries may provide a group name for a series of subjects that is not itself one of the subjects discussed. For example, in an AT&T reference entries called “string,” the name of the reference entry is given in this manner: "string: strcasecmp, strncasecmp\enspace  \enspace string operators" In this series, “string,” is not a function name like the terms that follow the colon following “string.” In a RefEntry the word “string” is tagged as a RefDescriptor, which is an optional rather than a required element of RefNameDiv. Many of the higher-level elements of RefEntry may occur only within RefEntries, not within Chapters or other book components. These are: RefMeta, RefEntryTitle, ManVolNum, RefMiscInfo, RefNameDiv, RefDescriptor, RefName, RefPurpose, RefSynopsisDiv, and RefSect1--3. The RefMeta contains, in order, a RefEntryTitle, an optional ManVolNum, and any number of RefMiscInfos. All this is metainformation, some of which may occur in the heading of a reference entry. None of it is from the body of a reference entry. RefEntryTitle is the primary name by which the reference entry is sorted and indexed. ManVolNum is the alphanumerical designation often supplied in parentheses after the RefEntryTitle, as in “string(3C).” It refers to the historical arrangement of reference entries in sections. Other pieces of information may follow the ManVolNum, each captured with the tag RefMiscInfo, so that you may have a series of RefMiscInfos (as many as eight have been reported in legacy documents). For example, O'Reilly's reference entry for XmuReshapeWidget includes the heading “Xmu Shape Extension Utilities,” which should be tagged as a RefMiscInfo. Other examples of RefMiscInfo contents are copyright, date, draft status, hardware architecture, and a descriptive phrase for use in a print header. Of these RefMeta elements, only RefEntryTitle may contain in-line elements; the others may contain only plain text. Do not be confused by the fact that RefEntryTitle may contain the same contents as RefName in the RefNameDiv. For the mwm reference entry, “mwm” is the content of both RefEntryTitle and RefName. This may not always be the case, as in the “string” example above: in that instance, “string” is the content of RefEntryTitle, but it is not a RefName. Remember, the RefMeta does not contain the contents of the Name division of a reference entry, only metainformation. REFMETA REFENTRYTITLEldsysdump /REFENTRYTITLE MANVOLNUMldsysdump(1) /MANVOLNUM REFMISCINFO CLASS="Sysad"System Administration Commands /REFMISCINFO REFMISCINFO CLASS="Copyright"Copyright 1985 /REFMISCINFO /REFMETA RefNameDiv is the top division of a reference entry, the one usually labelled “Name.” The RefNameDiv contains, in order, an optional RefDescriptor (for reference entries such as the “string” example), one or more RefNames, a required RefPurpose, followed by any number of RefClasses. Comments, FootnoteRefs, links, or XRefs may also appear at the end of RefNameDiv. In RefClass you indicate the applicability or scope of the topic of a RefEntry (such as “LocalBlocking”). RefName may contain further nested elements from the parameter entity computerterms.gp, such as Command or Function. RefPurpose may contain any in-line elements. The examples of RefNameDiv cited above are tagged like this: REFNAMEDIV ID="061-RP72" REFNAMEmwm /REFNAME REFPURPOSE the Motif window manager /REFPURPOSE /REFNAMEDIV REFNAMEDIV ID="061-RP73" REFNAME grep /REFNAME REFNAME egrep /REFNAME REFNAME fgrep /REFNAME REFPURPOSE search a file for a string or regular expression /REFPURPOSE /REFNAMEDIV REFNAMEDIV ID="061-RP74" REFDESCRIPTOR string /REFDESCRIPTOR REFNAME strcat /REFNAME REFNAME strdup /REFNAME REFNAME strncat /REFNAME REFNAME strcmp /REFNAME REFNAME strncmp /REFNAME REFPURPOSE string operators /REFPURPOSE /REFNAMEDIV RefSynopsisDiv is intended for the second division of reference entries, usually titled Synopsis or Syntax. But there are reference entries without Synopsis or Syntax divisions, so RefSynopsisDiv is an optional part of RefEntry. The content of this division is often simply a single line giving the syntax for the subject of the reference entry, or something less constrained, in some cases including subheadings. Thus the content of RefSynopsisDiv may be one or more synopses (Synopsis, CmdSynopsis, or FuncSynopsis, containing a single line or a set of lines), or one or more synopses followed by any number of RefSect2s, or one or more RefSect2s. Here is a valid RefSynopsisDiv: REFSYNOPSISDIV ID="RS-061-66" SYNOPSIS COMMAND>ls</COMMAND OPTIONAL><PARAMETER>options</PARAMETER></OPTIONAL REPLACEABLE CLASS="PARAMETER"><FILENAME directory\_name/FILENAME /REPLACEABLE /SYNOPSIS /REFSYNOPSISDIV In this revision, DocBook has incorporated two new synopsis types, CmdSynopsis and FuncSynopsis, both kindly donated by Eve Maler. For explanations of these elements, please see the alphabetical list of elements. The rest of a reference entry consists of one or more divisions, which are to be tagged as RefSect1s, which may have RefSect2s, which may have RefSect3s. These are just like Sect1--3, with the same required and allowable contents. Some elements are not part of the illustrations or body of text in a printed work. Such elements may appear in a printed work but are not part of the text. Others are provided in case they should be needed for some aspect of on-screen display or book production (TitleAbbrevs). Still others are metainformation, such as comments. TitleAbbrev may be provided where a long Title might be inappropriately truncated in some on-line display such as a title bar, or for use in a printed header or footer. RevHistory, an element of DocInfo, records the authorship of changes to a book. It consists of one or more Revisions, each of which must contain a RevNumber, a Date, one or more AuthorInitials, and a RevRemark. A Comment, containing in-line elements and plain text, is something not meant to be displayed or printed, such as a message to a production editor. Beware! Comment is not an SGML comment, it is an element. Just tagging text as a Comment will not ensure that it is hidden; you must arrange that in your application. And in line-specific elements you may find that the line breaks in your comment are rendered by your application. Emphasized entries indicate block-oriented elements. “Dropped” elements appeared in version 1.2.2 but do not appear in the current version; many have been shifted to attribute values in cptrphrase.gp. Common attributes now include ID, Lang (language), Remap (to store the former GI of an element in a document filtered to Docbook), Role (to type Docbook elements when need be), and XRefLabel (text to be displayed as the label of cross references to a block-oriented element). ID is an identifier, which must be a string that is unique at least within the document and which must begin with a letter. Lang should be a language code drawn from ISO 639 (perhaps extended with a country code drawn from ISO 3166, as en_US). Use it when you need to signal your application to change hyphenation and other display characteristics. Remap is a device for preserving a previous tag name when fitting a document to the DocBook DTD. Think of CHAPTER Remap=“Fascicle” as saying, “I'm a Chapter now, but in a previous life I was a Fascicle.” Role allows you to clone DocBook elements without creating new ones: if you have lists of vegetables and lists of fruit (perhaps displayed differently), give them Role=vegetables and Role=fruit attributes. Certain other attributes occur regularly. PageNum is the number of the page on which a given element begins or occurs in a printed book. Label holds some text associated with its element that is to be output when the document is rendered. XRefLabel holds some text that is to be used when a cross reference (XRef) is made to its element. Type is used with links, as it is clear that different types of links may be required; it duplicates the function of Role. The Class attribute has been introduced in an attempt to control the number of computer-specific in-line elements. The elements that bear the Class attribute, such as Interface, have general meanings that can be made more specific by providing a value for Class from the delimited list for that element. For example, for the Interface element one may specify Menu, or Button; for the MediaLabel element one may specify CDRom or Tape. Each element has its own list of permissible values for Class, and no default is set, so you can ignore this attribute if you wish. Some attributes are defined with the keyword %yesorno;, which resolves to NUMBER. To supply the required number, which must be either 1 or 0, you can use the parameter entities %yes; (1); or %no; (0). An attributes that has the keyword IMPLIED bears no processing expections if it is absent or its value is null. Application designers might wish to supply plausible defaults, but none is specified here. However, it would be plausible to imply that the language of a DocBook instance is U.S. English unless specified otherwise. (This matter may be clarified when character set specification is added to the DTD; for now, the character set must be inferred from the Lang attribute value, if present.) This parameter entity has been introduced to provide some structure for in-line elements related to computers. Its contents are: plain text, Anchor, BeginPage, all the index terms, Comment, Subscript, Superscript, all the kinds of links, Action, Application, ClassName, Command, ComputerOutput, Database, ErrorName, ErrorType, EventStructure, EventType, Filename, Function, Hardware, Interface, InterfaceDefinition, KeyCap, KeyCode, KeySym, LineAnnotation, Literal, Mask, MediaLabel, MsgText, Option, Optional, Parameter, Property, ProtocolRequest, Replaceable, ReturnValue, StructField, StructName, Symbol, SystemDialog, SystemItem, Token, Type, and UserInput. Many of these elements now have attributes with delimited value lists; some former in-line elements now appear as values for those attributes. In this document, “in-line” means ”occuring within a line of text, like a character or character string, not causing a line break.” This term is sometimes used to refer to objects such as an illustration around which something like a paragraph is wrapped; here that circumstance will be called “in flow.” There is no provision yet for indicating that an object is in flow, but one could make creative use of the Role attribute to do so. A related point: formal objects have titles; informal objects do not. That an object is informal does not mean that it is in-line: these are two different characteristics. In this revision, the former Table models have been replaced by one derived from MIL-M-28001B, dated 26 July 1993 (supersedes MIL-M-28001A of 20 July 1990.) The documentation of Table and its subelements, below, has been taken from that document, with some editing and attempts at clarification. Abstract A document summary. Abstract contains an optional Title followed by paragraphs, and has common attributes. Abbrev An abbreviation, especially one followed by a period. It contains plain text and has common attributes. Ackno Acknowledgements in an Article. It contains plain text. Acronym A pronounceable contraction of initials, usually printed in all caps or small caps. It contains plain text and has common attributes. Action A function invoked in response to a user event. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. Address A real-world address. It contains any number, in any order, of: Street, POB, Postcode, City, State, Country, Phone, Fax, and Email. Affiliation Author's institutional affiliation. It contains, in order, an optional ShortAffil, any number of JobTitles, optional OrgName, any number of Orgdivs, and any number of Addresses. Anchor Marks a target for a Link. Anchor may appear almost anywhere, and has no content. Anchor has ID, Pagenum, Remap, Role, and XRefLabel attributes; the ID is required. Appendix May occur only after Chapters or References, in a Book. Appendix begins with an optional DocInfo, followed by a required Title, optional TitleAbbrev, and anything found in the body of a Chapter. It has common and Label attributes. Application The name of a software program. It may contain members of cptrphrase.gp, and has common, Class, and MoreInfo attributes. Class may be Hardware or Software (no default). MoreInfo may have the value RefEntry, indicating that a RefEntry exists containing additional information about this term. The default value for MoreInfo is None. Arg Argument in a CmdSynopsis. Arg may contain any number of Args, Groups, Options, SynopFragmentRefs, Replaceables, in any order, mixed with plain text. Arg is defined in the DTD as having common attributes and the attributes defined by the parameter entities argchcatt and repatt. argchcatt or “argument choice attribute” resolves to the attribute Choice, with allowed values Opt (the Arg is optional; the default), Req (it is required), and Plain (neither optional nor required). repatt or “repetition attribute” resolves to the attribute Rep, with allowed values Repeat (the Arg may be repeated; the default) and Norepeat (the Arg does not repeat). ArtHeader Metainformation for an Article. ArtHeader has, in order, a required Title, optional TitleAbbrev, optional Subtitle, one or more AuthorGroups, optional BookBiblio, a required ArtPageNums, any number of Abstracts, any number of ConfGroups, and finally any number ContractNums and ContractSponsors, in any order. ArtHeader has common attributes. Article An article in a journal. Book may be used to hold Articles. An Article has, in order, a required ArtHeader, main contents as for Chapter, then any number of Indexes, Glossaries, Bibliographies, Appendixes and Acknos, in any order. Article has common and ParentBook attributes, the latter pointing to the ID of the enclosing Book. ArtPageNums Page numbers of an Article as published. It contains plain text (e.g., 23-147). Author Author of a document, occuring in AuthorGroup. It consists of one or more of the following, in any order: Honorific, Firstname, Surname, Lineage, OtherName, Affiliation, and AuthorBlurb. It has common attributes. AuthorBlurb Short description of author. AuthorBlurb contains an optional Title followed by paragraphs, and has common attributes. AuthorGroup Wrapper for Author information. It contains one or more CorpAuthors, Collabs, and Authors, in any order. AuthorInitials Indicates the author of a Revision or Comment. It contains plain text and has common attributes. BeginPage Marks a page break in a print version of a work that may be displayed online. It is without content, but has ID, PageNum, Remap, Role, and XRefLabel attributes. The ID is required. The value of PageNum, which is not required, should be the folio (page number) of the page beginning at that point. Usage Note: Once you give a PageNum to a BeginPage, subsequent BeginPages should be assumed to indicate that value incremented by one per BeginPage. You can indicate a change or reset in page numbering by providing a PageNum value for a later BeginPage. BiblioDiv A section of a Bibliography. It may have, in order, an optional Title, optional TitleAbbrev, any number of block-oriented elements, followed by one or more BiblioEntries. It has common attributes. BiblioEntry An entry in a Bibliography. It may begin and end with BiblioMiscs, between which must be an ArtHeader, BookBiblio, or SeriesInfo. That is, the main content of a BiblioEntry may be identical to a section of metainformation. BiblioEntry has common attributes. Bibliography A bibliography. It may be a book component on its own, or may appear within a Preface, Chapter, or Appendix, or at the end of a Glossary. It may have a DocInfo, a Title and a TitleAbbrev, then optional block-oriented elements, and then one or more BiblioEntries or one or more BiblioDivs. It has common attributes. BiblioMisc Untyped information required in a BiblioEntry or BookInfo, in addition to the elements required there. It contains plain text and has common attributes. BlockQuote A quotation set off from the main text, rather than occurring in-line. It may have a Title, followed by block-oriented elements. It has common attributes. Book A collection of book components. The Book content model has been drawn more tightly since version 1.2.2, but is loose enough to accomodate English, French, and Japanese books. A Book may have a Title and TitleAbbrev, followed in order by an optional BookInfo, an optional ToC, any number of LoTs, any number of Prefaces, main contents, and back matter. The main contents are required, and must be one or more Parts; one or more Chapters followed by any number of References; one or more Articles; or one or more References. All back matter is optional, but must appear in order: any number of Appendices, a Glossary, a Bibliography, and any number of Indexes and SetIndexes, followed by any number of LoTs followed by an optional ToC. Book has common, FPI, and Label attributes. The FPI attribute is intended to hold an SGML Formal Public Identifier for the Book; the Label attribute can be used to supply the number of a Book, or you can use the content of the VolumeNum element in BookInfo. in constructing Formal Public Identifiers you use your ISBN publisher's prefix. In the ISBN 1–565692–043–0, for example, the publisher's prefix is 565692. BookAcronym Dropped. BookBiblio All the information about a book that may be relevant to a bibliographical citation; occurs in BookInfo and may be used in BiblioEntry. Only Title and AuthorGroup are required. BookBiblio may contain, in order: the required Title, optional TitleAbbrev, Subtitle, and Edition, followed one or more required AuthorGroups; then, optionally, either an ISBN followed by an optional VolumeNum or an ISSN followed by optional VolumeNum, optional IssueNum, and an optional PageNums. After these elements there may occur, again optionally and in order, InvPartNumber, ProductNumber, ProductName, PubsNumber, and ReleaseInfo; then there may be any number of Pubdates followed by any number of Publishers, followed by optional Copyright, then optional SeriesInfo; then any number of Abstracts, any number of ConfGroups, any number of ContractNums mixed with any number of ContractSponsors, and an optional PrintHistory followed by an optional RevHistory. BookBiblio has common attributes. is the numbers of the pages contained in a given issue or volume BookInfo Metainformation for a Book, in which it may appear. BookInfo must contain a BookBiblio, followed by any number of LegalNotices, followed by any number of ModeSpecs (which are pointed to by the LinkMode attribute of OLink, and are collected here for convenience). BookInfo has common attributes and a Contents attribute, the values of which are the IDs of the ToC, LoTs, Prefaces, Parts, Chapters, Appendixes, References, Glossary, Bibliography, and indexes comprising the Book, in the order of their appearance. BookTitle Dropped. BridgeHead A free-floating heading not tied to the Sect hierarchy. It may contain in-line elements and has common and Renderas attributes. Use the Renderas attribute to indicate the format in which the BridgeHead should appear (Sect1, Sect2, Sect3, Sect4, Sect5, or Other, the default). Button Dropped. See Interface. Caution An admonition set off from the text; Tip, Warning, Important, and Note all share its model. Its contents may include paragraphs, lists, and so forth, but not another admonition. Caution and its sisters have common attributes. Chapter A part of a Book. Chapter contain anything except higher-level elements such as Part, Book, and Set, or peers such as Appendix and Preface. A Chapter may begin with a DocInfo, followed by a required Title, optional TitleAbbrev, and body. The body may be either paragraphs and block-oriented elements or Sects containing them. At the beginning and end of the body of a Chapter, or the beginning and end of any Sect, there may be any number of ToCs, LoTs, Indexes, Glossaries, and Bibliographies, not that such an organization is recommended for ordinary use. Chapter has common and Label attributes. Character An element of a writing system. Characters may belong to Charsets, and in some contexts fonts represent characters. (See Glyph, Font.) It contains plain text and has common attributes. Charset A conventionally defined set of characters, (not a font). It contains plain text and has common attributes. Citation Any in-line bibliographic reference to another published work that uses a reference string, such as an abbreviation in a Bibliography. Compare CiteTitle. Citation contains plain text and has common attributes. CiteBook Dropped. See CiteTitle. CiteChap Dropped. See CiteTitle. CiteSect Dropped. See CiteTitle. CiteTitle A citation for some published work. Compare Citation. It may contain members of cptrphrase.gp, and has common and Pubwork attributes. The value of Pubwork should indicate the type of work cited; it may be Article, Book, Chapter, RefEntry, or Section (no default). CiteRefEntry A citation of a reference entry. It must have a RefEntryTitle, followed by an optional ManVolNum. It has common attributes. City Part of Address. It contains plain text. Classname The name of the class to which a program component belongs. It contains plain text and has common attributes. CmdSynopsis Synopsis for a Command. A CmdSynopsis contains any number of Args and Groups, in any order, followed by a single required Command, another set of any number of Args and Groups, in any order, and ending with any number of optional SynopFragments. CmdSynopsis has common, Label, and Sepchar attributes. Label has no default; Sepchar has the default “ ”. The following is courtesy Eve Maler (see also the entries for the subelements elsewhere in this list: An argument at the command level (Arg) is a parameter passed to a command to specify or modify the command's behavior; it often consists of a variable value (Replaceable) such as a filename field, or an option (Option) and its own nested argument (Arg). If the contents of an argument are not marked up further, they are assumed to be something the user must type as shown (probably an option, but this is implicit). The Choice attribute on the two argument elements indicates whether the argument must be present (“Req”, the default), whether it is optional (“Opt”), or whether no indication of presence is given (“Plain”, the default). A group (Group) as a peer or child of an argument is a collection of arguments, options, or other constructs that must appear in some relation to each other. For example, three options that are exclusive of each other and are optional would be in a group with a choice of “Opt” (the default). The “Optmult” choice allows zero or more of the children of the group to be supplied, and the “Reqmult” choice requires one or more of the children of the group to be supplied. An option (Option) is a literal string or name of a parameter-keyword controlling the behavior of the command; a variable value (Replaceable) is a mnemonic name for a value that the user must supply, such as an input file name. The Option and Replaceable elements are available in text as well as in synopses. Stacks of options (for example, “-aefstuv”) should be put into a single Option element for simplicity. Depressingly complex constructs may appear anywhere within a synopsis. A SynopFragment reference (SynopFragmentRef) is a special kind of variable value assigned in place of this construct, which is then broken out into its own synopsis subset (SynopFragment) for clarity. A SynopFragment must have an ID, and any SynopFragmentRefs supplied must point to some SynopFragment. Plain text within a CmdSynopsis is allowed only inside Cmd, Arg, Option, Replaceable, and SynopFragmentRef. The top-level separator character attribute value (“ ” by default) should be used to separate arguments and groups from their repeat indicators (“. . .”) and to separate Commands and their arguments and groups at the top level. The CmdSynopsis structure does not meet the needs of DCL and other VMS-related command languages that have command parameters such as /[NO]WRITE, positional versus nonpositional parameters, and so on. Probably additional low-level elements would have to be added to the mix and the top-level structure enhanced slightly to account for these. However, CmdSynopsis appears to meet most UNIX-related needs. Processing expectations: The “Opt” settings on arguments and groups (and probably “Optmult” as well for now) should produce square brackets. The “Req” settings (and probably “Reqmult” as well for now) should produce curly braces. The children of Group (if there is more than one child) should be either separated by vertical bars or formatted as a stacked list. Spacing at the Command and Group levels is controlled by formatter defaults and/or the sepchar setting. Example command synopsis in typical UNIX(tm) format: rm [-f] [-r] [-i] [-] {filename|dirname} . . . | | | | | | | | | | optional args | | | repeat indicator | (contain options)| | | | | | second child of group command name | | | first child of group | required repeatable group SGML source for this example: CMDSYNOPSIS COMMANDrm/COMMAND ARG Choice="opt"-f/ARG (OPTION not required for arg contents ARG Choice="opt"-r/ARG unless doing extra-special processing) ARG Choice="opt"-i/ARG ARG Choice="opt"-/ARG (various synopsis formats GROUP Choice="req" Rep="repeat" can be generated) REPLACEABLEfilename/REPLACEABLE REPLACEABLEdirname/REPLACEABLE /GROUP /CMDSYNOPSIS Collab A collaborative group of authors. It contains a required CollabName followed by any number of Affiliations. CollabName Name of a collaborative group of authors. It contains plain text. ColSpec Column specifier, that is, formatting information for a column in a Table, part of TGroup, THead, or TGroup. ColSpec is an empty element, bearing common and Align, Char, Charoff, Colname, Colnum, Colsep, Colwidth, and Rowsep attributes. The default values come from the TGroup, THead, or TFoot that starts the current enclosing group. Each ColSpec is for a single column, so it properly has a column number, Colnum, implicitly in order starting from 1, and an optional Colname by which it is known when used in any SpanSpec or in Entry. A ColSpec set on THead or TFoot should be complete for all columns. It overrides those on the containing TGroup and applies to just the THead or TFoot. If there is no ColSpec used within THead or TFoot, then the ColSpec of the containing TGroup (or the prior TGroup) is used. ColSpecs from the containing TGroup apply to TBody. For TGroupStyle, see TGroup. Align controls the horizontal position of text within the column. The value of Align may be Left (quad flush left), Center (centered), Right (quad flush right), Justify (both quad left and right), or Char (align to the left of Char, positioned by Charoff). There is no default. Char contributes to Align. If the value of Align is “char”, the value of Char should be a character on the first occurrance of which the entry is to be aligned. If that character does not occur in the entry, the entry is aligned to the left of the position determined by Charoff. (Think of using the decimal point to align decimal numbers: Char=“. ”and Charoff says how far over in the column the decimals should be; if no decimal occurs, the number is an integer and is aligned to the left of the decimals.) No value implies there is no character to align on. The default is implied, from the enclosing TGroup. (That is, you normally declare that an entire TGroup shall be decimal-aligned, but if you need to align a specific column differently, you can do it by specifying another Char at the ColSpec level.) Charoff contributes with Char to Align. Charoff is the proportion of the current column width, expressed in percentage, to be allowed before the left edge of the first occurrence of the character given as the value of Char. The default is inherited from the enclosing TGroup. That is, if columns in a TGroup are to be decimal-aligned, and the decimal point is to fall three-quarters of the way across each cell (most of your numbers are of the form 123.4), you could set Charoff to 75 in TGroup; that value would be inherited by ColSpec, where you could modify it for a specific column (for example, by setting it to 50 for a column of numbers of the form 12.34). Colname gives the name of the column, which is used to specify the position in a row, or the start or end of a horizontal span of columns (SpanSpec). There is no default. Colnum gives the number of the column, counting from 1 at left of the table. There is no default. Colsep determines column separators. If its value is Yes, display the internal column rulings to the right of each item; if No, do not display it. It is ignored for the last column, where the Frame setting applies. There is no default. The value is inherited from TGroupStyle if used. Colwidth is either a proportional measure of the form number*, such as “5*” for 5 times the proportion, or “*” (=“1*”); or a fixed measure, such as 2pt for 2 points, 3pc for 3 picas; or a mixed measure, such as 2*+3pt. Coefficients are positive numbers with up to two decimal places. There is no default. If no value is given, the value should be obtained from the FOSI, or, if there is no FOSI value, the value 1 should be used. (Perhaps this means that you can vary the width of columns by stating their relative proportions, or you can give fixed widths. If you use a decimal number less than one, express it in the form 0.2, not .2.) Rowsep determines row separators. If its content is Yes, display the internal vertical row ruling below each item; if No, do not display it. It is ignored for the last row of the table, where the value of Frame applies to the entire Table. There is no default. The value is inherited from TGroupStyle, if used. Command An executable program, or the entry a user makes to execute a command. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. Comment A remark made within the document file that is intended for use during interim stages of production. A Comment should not be displayed to the reader of the finished, published work. It may appear almost anywhere, and may contain almost anything below the Section level. Note that, unlike an SGML comment, unless you take steps to suppress it, the Comment element will be output by an SGML parser or application. You may wish to do this to display Comments along with text during the editorial process. ComputerOutput Data presented to the user by a computer. It may contain elements from cptrphrase.gp, and has common and MoreInfo attributes For the MoreInfo attribute see Application. ConfGroup A wrapper for information about a conference. It contains any number of ConfDates, ConfTitles, ConfNums, Addresses, and ConfSponsors, in any order. ConfNum The number of a conference. It contains plain text. ConfSponsor Sponsor of a conference in connection with which a document was written. It contains plain text. ConfDates Dates of a conference in connection with which a document was written. It contains plain text (e.g., 21-24 May 1927). ConfTitle Title of a conference in connection with which a document was written. It contains plain text. Constant Dropped. See SystemItem. ContractNum Number of a contract under which a document was written. It contains plain text. ContractSponsor Sponsor of a contract under which a document was written. It contains plain text. Copyright Copyright information about a document. It consists of one or more Years followed by any number of Holders. CorpAuthor Corporate author of a book, for use in BookInfo or BiblioEntry. It contains plain text and has common attributes. CorpName Name of a corporation. It contains plain text. Country Part of Address. It contains plain text. Data Optional component of FuncParam and ParamDef. It wraps plain text, Replaceable, more Data, Emphasis, and may contain links and indexing information. It has common attributes. Date Date of publication or revision. It contains plain text. (No provision has been made for representing eras; you could include this information along with the date data.) Database An organized set of data. It may contain members of cptrphrase.gp, and has common, Class, and MoreInfo attributes. Class may have the value Name, Table, Field, Key1, Key2, or Record (no default). For the MoreInfo attribute see Application. DbField Dropped. See Database. DbName Dropped. See Database. DbRecord Dropped. See Database. DbTable Dropped. See Database. DocBook Dropped. Use the book component's name (e.g., Chapter) as the Doctype, or construct a shell Book in which you can insert individual book components as entities. DocInfo Metainformation for a book component, in which it may appear. Only Title and AuthorGroup are required. DocInfo may contain, in order: the required Title, optional TitleAbbrev and Subtitle, followed by one or more AuthorGroups, any number of Abstracts, an optional RevHistory, and any number of LegalNotices. DocInfo has common attributes. Edition The edition of a document. It contains plain text. Editor The editor of a document. Contents are the same as for Author. Email Part of Address. It contains plain text. Emphasis Provided for use where you would traditionally use italics or bold type to emphasize a word or phrase. It contains plain text and has common attributes. Entry A euphemism for a cell in a table—you'd rather be in an Entry than in a Cell, wouldn't you? An Entry occurs in a Row, and must have either some assortment of paragraphs, admonitions, lists, and Graphics, or in-line elements. Entry has common and Align, Char, Charoff, Colname, Colsep, Morerows, Nameend, Namest, Rotate, Rowsep, Spanname, and VAlign attributes. Attribute values may be inherited from enclosing elements that share the same attribute. “An Entry not specified by a SpanSpec gets its defaults from its starting column.” Align controls the horizontal position of text within the column. The value of Align may be Left (quad flush left), Center (centered), Right (quad flush right), Justify (both quad left and right), or Char (align on leftmost of Char, positioned by Charoff). There is no default; the value may be inherited from ColSpec or SpanSpec. Char contributes to Align. If the value of Align is “char”, the value of Char should be a character on the first occurrance of which the entry is to be aligned. If that character does not occur in the entry, the entry is aligned to the left (the original doc incorrectly specifies “right”) of the position determined by Charoff. The default is inherited; no value implies there is no character to align on. Charoff contributes with Char to Align. Charoff is the proportion of the current column width, expressed in percentage, to be allowed before the left edge of the first occurrence of the character given as the value of Char, if any. The default is inherited from ColSpec or SpanSpec. Colname gives the name of the column, which is used to specify the position in a row, or the start or end of a horizontal span of columns (SpanSpec). There is no default; omit if SpanName is present. The implied value is either the first column of the Row, or, if already in a Row, the next column after the end of the prior Entry or EntryTbl. Colsep determines column separators. If its value is Yes, display the internal column rulings to the right of each Entry; if No, do not display it. It is ignored for the last column, where the Frame setting applies. (In CALS, Yes is expressed as 1 and No as 0.) There is no default; if no value is given the value is inherited from ColSpec or SpanSpec. Morerows is the number of additional rows in a vertical straddle. The default is 0. Nameend is the name of the rightmost column of a span. Names are identified in the ColSpec of the current TGroup. There is no default. Namest or Name Start, is the name of the leftmost column of a span. Names are identified in the ColSpec of the current TGroup. Rotate governs rotations, which are not additive to those specified in the FOSI. Values may be Yes or No (1 or 0). No specifies no rotation; Yes specifies 90 degrees rotation counterclockwise to table orientation. No other values are supported! Rowsep determines row separators. If its content is Yes, display the internal vertical row ruling below each item; if No, do not display it. It is ignored for the last row of the table, where the frame value applies. There is no default. The value is inherited from Row, if used there. Spanname is the name of a horizontal span. No default. VAlign governs the vertical positioning of text within an Entry. Allowed values are Top, Middle, and Bottom (no default). EntryTbl A form of subtable. It may occur in Row, along with Entry. Several EntryTbls of differing formats may occur in the same Row of a TBody, but EntryTbl may not contain itself. Aside from that restriction, EntryTbl contains one or more sets of these elements, in order: any number of ColSpecs, any number of SpanSpecs, an optional THead, and a required TBody. There is no implication of alignment of subrows in different EntryTbls. Default attribute values come instead from those of like-named attributes on enclosing elements: Table, TGroup, ColSpec, SpanSpec, THead, TFoot, TBody, or Row. EntryTbl has common, Align, Char, Charoff, ColName, Cols, Colsep, Nameend, Namest, Rowsep, Spanname, and TGroupStyle attributes. Align controls the horizontal position of text within the column. The value of Align may be Left (quad flush left), Center (centered), Right (quad flush right), Justify (both quad left and right), or Char (align to the left of Char, positioned by Charoff). There is no default; the value may be inherited from ColSpec or SpanSpec. Char contributes to Align. If the value of Align is “char”, the value of Char should be a character on the first occurrance of which the entry is to be aligned. If that character does not occur in the entry, the entry is aligned to the left (the original doc incorrectly specifies “right”) of the position determined by Charoff. There is no default. Charoff contributes with Char to Align. Charoff is the proportion of the current column width, expressed in percentage, to be allowed before the left edge of the first occurrence of the character given as the value of Char, if any. The default is inherited from the enclosing TGroup. Colname gives the name of the leftmost column of EntryTbl. There is no default. Cols is the number of columns in the EntryTbl. There is no default. Colsep determines column separators. If its value is Yes, display the internal column rulings to the right of the EntryTbl, except if the EntryTbl falls in the the last column, where the siderule (sic) setting applies; if No, do not display it. There is no default. The value is inherited from the enclosing TGroup. Nameend is the name of the rightmost column of a span. Names are identified in the ColSpec of the current TGroup. There is no default. Namest or Name Start, is the name of the leftmost column of a span. Names are identified in the ColSpec of the current TGroup. There is no default. Rowsep determines row separators. If its content is Yes, display the internal vertical row ruling below the EntryTbl; if No, do not display it. It is ignored for the last row of the table, where the frame value applies. There is no default. The value is inherited from the enclosing TGroup. Spanname is the name of a horizontal span. TGroupStyle is the name of a table group style defined in the FOSI. There is no default. Epigraph A brief section of poetry or prose at the start of a chapter. It contains paragraphs and has common attributes. Equation A titled mathematical equation displayed on a line by itself, rather than in-line. It has an optional Title and TitleAbbrev, followed by either an InformalEquation or a Graphic (see Graphic). Equation has common and Label attributes. ErrorName An error message reported by a computer. It contains plain text and has common attributes. ErrorType A classification of an error message reported by a computer. It contains plain text and has common attributes. EventStructure The code that defines an Event. It contains plain text and has common attributes. EventType A classification of an event. It contains plain text and has common attributes. Example Intended for sections of program source code that are provided as examples in the text. It contains a required Title and an optional TitleAbbrev, followed by one or more block-oriented elements in any combination. It has common and Label attributes. A simple Example might contain a Title and a ProgramListing. ExternalLink Dropped. Fax Part of Address. It contains plain text. Figure An illustration. It must have a Title, and may have a TitleAbbrev, followed by one or more of BlockQuote, InformalEquation, Graphic, InformalTable, Link, LiteralLayout, OLink, ProgramListing, Screen, Synopsis, and ULink, in any order. Figure has common, Label, and Float attributes; Float indicates whether the Figure is supposed to be rendered where convenient (yes) or at the place it occurs in the text (no, the default). To reference an external file containing graphical content use the Graphic element within Figure. Filename The name of a file, including pathname if this information is present. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. FirstName (Western-style) given name of Author, Editor, or OtherCredit. It contains plain text. FirstTerm First occurrence of a word in a given context. It contains plain text and has common attributes. Font A collection of Glyphs (see Glyph). It contains plain text and has common attributes. Footnote The contents of a footnote, when the note occurs outside the block-oriented element in which the FootnoteRef occurs. (Compare InlineNote.) The point in the text where the mark for a specific footnote goes is indicated by FootnoteRef. Footnote may contain Para, SimPara, BlockQuote, InformalEquation, InformalTable, Graphic, Synopsis, LiteralLayout, ProgramListing, Screen, and any kind of list. It has ID, Label, Lang, Remap, Role, and XRefLabel attributes; the ID attribute is required, as a FootnoteRef must point to it. FootnoteRef Identifies the location for a footnote mark. It may contain plain text, which is the mark to be displayed, or it may be empty, in which case the Mark attribute provides another way of indicating the contents of the mark (such as an asterisk, *, a number, 84, or a dingbat specified by a name that is to be interpreted by the application). FootnoteRef has ID, Linkend, and Mark attributes. The Linkend attribute, which is required, has as its value the ID of the associated Footnote, and the Mark. ForeignPhrase Any word or words from a language other than that of the document which you want to mark off in some way. In English, inter alia and c'est la vie are ForeignPhrases. It contains plain text and has common attributes. FormalPara A paragraph with a Title. FormalPara contains a required Title followed by a required Para, and has common attributes. FuncDef Part of a FuncSynopsis. Like Paramdef, it provides data type information and the name of the Function (or Parameter, in the case of ParamDef) this information applies to. A FuncDef may contain any combination of plain text, Replaceable, Data, or Function, in any order. It has common attributes. Separating this information from the rest of the synopsis avoids messing with data type information that appears before or after the item it applies to, such as array information (“[]”). It also avoids the issue of placing the pointer (“*”) indicator (next to the rest of the left-hand data type or next to the Parameter or Function name?). Any spaces that surround the Parameter or Function must be inserted by the writer. FuncParams Optional component of ParamDef. It supplies “inner parameters” for Paramters that are pointers to Functions. FuncParams contains elements from ctprphrase.gp and has common attributes. FuncSynopsis (contributed Eve Maler, along with remarks on its subelements.) A C synopsis that shows a prototype or definition indicating a function's name. A FuncSynopsis also indicates the data type of its return value, and the positions, purposes, and data types of its parameters. A FuncSynopsis begins with an optional FuncSynopsisInfo, which contains additional information about the synopsis that follows; line breaks and leading white space are significant within a FuncSynopsisInfo. This is followed by one or more blocks defining a function (you might use more than one for connecting related sets of functions). Each of these blocks consists of a required FuncDef, followed by a Void, a VarArgs, or one or more ParamDefs. Void, Varargs, and and ParamDef are mutually exclusive. Usage Note: You should supply no specific information on the arguments before the ellipsis that VarArgs should output when rendered, but if it is necessary to represent the ellipsis in the source it may ben enclosed within a final ParamDef. FuncSynopsis has common and Label attributes. The processing application is expected to provide all parentheses, semicolons, and the like. The exceptions are any spaces surrounding function and parameter names, any parentheses or commas or spacing inside lists of data types of parameters that are pointers to functions, and the parentheses around those parameter names themselves. These exceptions are a bit confusing in the unusual case (pointers to functions), but they greatly simplify tagging and still allow either K&R style or ANSI C style to be produced (assuming writers have cooperated in supplying enough information for ANSI). FuncSynopsisInfo Information supplementing the FuncDefs of a FuncSynopsis. It contains elements of ctprphrase.gp, and within it line breaks and leading white space are significant. See FuncSynopsis. It has common attributes. Function A subroutine in a program or external library. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. FunctionParam Dropped. See Parameter. Glossary A glossary of terms. Glossary may occur within a Chapter, Appendix, or Preface, or may be a book component in its own right. It contains in order an optional DocInfo, optional Title, and optional TitleAbbrev, followed by any number of block-oriented elements, followed by one or more GlossEntries or one or more GlossDivs. It has common attributes. GlossDef The definition attached to a GlossTerm in a GlossEntry. It may contain Comments, GlossSeeAlsos, paragraphs, and other block-oriented elements, in any order; it has common and Subject attributes. The Subject attribute may hold a list of subject areas (e.g., DCE RPC General) as keywords. GlossDiv A division of a Glossary. It may have a Title and TitleAbbrev, followed by block-oriented elements, followed by one or more GlossEntries. It has common attributes. GlossEntry An entry in a Glossary. It contains, in order, a required GlossTerm, an optional Acronym, an optional Abbrev, and any number of GlossSees and GlossDefs, in any order. It has common attributes. GlossSee A cross-reference from one GlossEntry to another. It may contain plain text or no content, and has common and OtherTerm attributes. OtherTerm is a reference to the GlossTerm within the cross-referenced GlossEntry; that GlossTerm should be displayed at the point of the GlossSee. GlossSeeAlso A cross-reference from one GlossDef to another GlossEntry. It may contain plain text or no content, and has common and OtherTerm attributes. OtherTerm is a reference to the GlossTerm within the cross-referenced GlossEntry; that GlossTerm should be displayed at the point of the GlossSee. GlossTerm A term in the text of a Chapter (for example) that is glossed in a Glossary; also used for those terms in GlossEntries, in the Glossary itself. As you may not want to tag all occurrences of these words outside of Glossaries, you might consider GlossTerm, when used outside of Glossaries, to be similar to FirstTerm, except that GlossTerm may contain other in-line elements. GlossTerm contains in-line elements and has common attributes. Glyph A mark, a component of a font. A character or ligature might be made up of one, two, or more Glyphs. Cf. Character. It contains plain text and has common attributes. Graphic Encloses graphical data or points via an attribute to an external file containing such data, and is to be rendered as an object, not in-line. It has Format, Fileref, Entityref, and ID attributes. The format attribute may have the value of any of the formats defined at the head of the DTD, including CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS, EQN, FAX, FAXTILE, GIF, IGES, PIC, PS, TBL, TEX, TIFF. The value of Fileref should be a filename, qualified by a pathname if desired; the value of Entityref should be that of an external data entity. If data is given as the content of Graphic, both Entityref and Fileref, if present at all, should be ignored, but a Format value should be supplied. if no data is given as the content of Graphic and a value for Entityref is given, Fileref, if present, should be ignored but no Format value should be supplied. Finally, if there is no content for Graphic and Entityref is absent or null, Fileref must be given the appropriate value, and again no Format value should be supplied. Group A group of constituent parts of a CmdSynopsis. A Group consists of one or more Args, Groups, SynopFragmentrefs, and Replaceables, in any order. See CmdSynopsis. Group has common, grpchcatt, and repatt attributes. argchcatt or “argument choice attribute” resolves to the attribute Choice, with allowed values Opt (the Arg is optional; the default), Req (it is required), and Plain (neither optional nor required). repatt or “repetition attribute” resolves to the attribute Rep, with allowed values Norepeat (the Arg may be repeated; the default) and Repeat (the Arg does not repeat). grpchcatt or “group choice attribute” is a parameter entity that resolves to the the Choice attribute for the element Group. The allowed values are Opt (the Arg is optional; the default), Req (it is required), Plain (neither optional nor required), OptMult (optional and repeatable), and ReqMult (required multiple times). Hardware A physical part of a computer system. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. Highlights A list of main points discussed in a book component such as a Chapter. It may contain paragraphs, lists, and admonitions, and has common attributes. Holder Part of Copyright; the holder of the copyright of the document. It contains plain text. Honorific A person's title, to be used as part of Author, Editor, or OtherCredit. It contains plain text. HWapplic Dropped. See Application. Icon Dropped. See Interface. Important An admonition set off from the text. See Caution. Index An index to a Chapter, Appendix, Preface, or Book. It contains an optional DocInfo, Title, and TitleAbbrev, followed by any number of block-oriented elements, and then one or more IndexEntries or one or more IndexDivs. It has common attributes. IndexAs Dropped. IndexDiv A division of an Index. It may have a Title and TitleAbbrev, some optional introductory matter (block-oriented elements, Anchors, Comments), and must then contain one or more IndexEntries or a SegmentedList (use a SegmentedList for a permuted index). It has common attributes. IndexEntry