Guide to the DocBook DTD DTD release 2.1</> <subtitle>Documentation version 1.3 for release 2.1, 7 May 1994 </subtitle> <authorgroup> <corpauthor>HaL Computer Systems International, Ltd.</> <corpauthor>O'Reilly & Associates, Inc.</> </authorgroup> <copyright> <year>1992</year> <year>1993</year> <year>1994</year> <holder>HaL Computer Systems International, Ltd.</> <holder>O'Reilly & Associates, Inc.</holder> </copyright> </bookbiblio> <legalnotice> <para>Permission to use, copy, modify and distribute the DocBook DTD and its accompanying documentation for any purpose and without fee is hereby granted, provided that this copyright notice appears in all copies. HaL Computer Systems and O'Reilly & Associates make no representation about the suitability of the DTD for any purpose. It is provided “as is” without expressed or implied warranty. </para> </legalnotice> <legalnotice> <para>Please direct all questions, bug reports, or suggestions for changes to davenport@ora.com or by mail to either: Terry Allen, O'Reilly & Associates, Inc., 103A Morris Street, Sebastopol, California, 95472; or Conleth O'Connell, HaL Computer Systems, 3006–A Longhorn Blvd., Austin, Texas, 78758. </para> </legalnotice> </bookinfo> <preface><title>Acknowledgements</> <para>The DocBook DTD is a joint effort of Hal Computer Systems International, Ltd., and O'Reilly & Associates, Inc. Conleth O'Connell and Terry Allen are the current design team for the DTD; Con deserves special mention as chief architect. Through several revisions, a lot of other people at both companies contributed their insight and encouragement, particularly Steve Williams and David Bass of HaL Computer Systems, and Dale Dougherty of O'Reilly & Associates. Special mention for help with this revision goes to Eve Maler of Digital Equipment Corporation (synopses and good general advice) and Bryan Caporlette of Passage Systems (CALS table model). </para> <sect1><title>How to Get the DocBook DTD Online 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. Development of the DocBook DTD 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. A Structural View of the DTD 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. Sets, Books, and Their Parts 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 Preface, Chapter, Appendix, Bibliography, Glossary, and Index 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 Table of Contents 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. Lists of Titles (LoT) 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. BookInfo and DocInfo 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. References 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 Sections (Heads) 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. Block-Oriented Elements 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 Highlights and Epigraph 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 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. Lists 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 Procedures 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 MsgSet 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 Tables 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 Figures and Equations 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. Examples 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. LiteralLayouts, ProgramListings, Screens, and ScreenShots 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 BlockQuotes 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. Sidebars 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. Footnotes 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 and Other Blocks 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. Elements Indicating Nonlinear Relationships 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 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 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. Links and Anchors 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. Cross References (XRefs) 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 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.) Using 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. Articles 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. Reference Entries 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. RefEntry Basics 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 RefEntry Variations 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. RefMeta 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 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 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 Synopses 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. RefHeads 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. Miscellaneous 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. The Elements Alphabetized 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 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. Other 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.) cptrphrase.gp 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-line” vs. “In flow” 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. CALS Tables 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. List of Elements 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 Part of Index. It contains a PrimaryIE, which may be accompanied by SecondaryIE, TertiaryIE, SeeIE, and SeeAlsoIE. It has common attributes. IndexTerm A character string to be indexed, occurring in the text flow but not in the text itself. (And remember, IndexTerm appears in the text, not in the Index!) Primary, Secondary, and Tertiary index items are nested within this tag, as are See and SeeAlso items. It has common, SpanEnd, PageNum, and Significance attributes. The SpanEnd attribute may not be used if IndexTerm has content; it should be used only to mark the end of a span of text that begins earlier at an IndexTerm that does have content. The value of SpanEnd must be the ID of that earlier IndexTerm. 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). InformalEquation An untitled mathematical equation displayed on a line by itself, rather than in-line. It contains a Graphic, and has common attributes. InformalTable An array of text that has no Title. Otherwise, it is just like Table except that it lacks the ShortEntry and ToCEntry attributes. See Table. InlineEquation An untitled mathematical equation occurring in-line or as the content of an Equation. It contains a Graphic, and has common attributes. InlineGraphic Encloses graphical data or points via an attribute to an external file containing such data, and is to be rendered in-line. InlineGraphic 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, under “Notations.” If it is desired to point to an external file, a filename may be supplied as the value of the Fileref attribute, or an external entity name may be supplied as the value of the Entityref attribute. Interface Any part of a graphical user interface. It may contain members of cptrphrase.gp, and has common, Class, and MoreInfo attributes. Class may have the value Button, Icon, Menu, or MenuItem (no default). For the MoreInfo attribute see Application. InterfaceDefinition A specification for a graphical user interface. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. InvPartNumber An inventory part number. It contains plain text. ISBN International Standard Book Number of a document. It contains plain text. ISSN International Standard Serial Number of a journal. It contains plain text. IssueNum The number of an issue of a journal. It contains plain text. ItemizedList A list in which each item is marked with a bullet, dash, or other dingbat (or no mark at all). It consists of one or more ListItems. A ListItem in an ItemizedList contains paragraphs and other block-oriented elements, which may in turn contain other lists; an ItemizedList may be nested within other lists, too. It has common attributes and a Mark attribute. Your application might supply the mark to be used for an ItemizedList, but you can use this attribute to indicate the mark you desire to be used; there is no fixed list of these. Usage Note: You might want to use one of the ISO text entities that designates an appropriate dingbat. JobTitle Part of Affiliation. It contains plain text. JournalInfo Information about the journal in which an Article appears, in that Article's ArtHeader. It contains, in order, a required Title, optional TitleAbbrev, Subtitle, ISSN, VolumeNum, IssueNum, PageNums, PubDate, Publisher, and Copyright. KeyCap The text printed on a physical key on a computer keyboard, not necessarily the same thing as a KeyCode. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. Keycode The computer's numeric designation of a key on a computer keyboard. Keycode contains plain text and has common attributes. Keysym A key symbol name, which is not necessarily the same thing as a Keycap. For example, the Keysym for the H key (Keycap H) might be h. It contains plain text, and has common attributes. LegalNotice An acknowledgement of trademarks, etc. It may have a Title, followed by paragraphs, and BlockQuotes in any order. Lineage Part of an author's name, such as “Jr.” It contains plain text. LineAnnotation A writer's or editor's comment on a line of program code within an Example, ProgramListing, or Screen. LineAnnotations are a document author's comments on the code, not the comments written into the code itself by the code's author. Link A hypertext link. At present, all the link types represented in the DTD are provisional. Link is less provisional than the others, however. In HyTime parlance, Link is a clink. It may contain in-line elements and has Endterm, Linkend, and Type attributes. The required Linkend attribute specifies the target of the link, and the optional Endterm attribute specifies text that is to be fetched from elsewhere in the document to appear in the Link. You can also supply this text directly as the content of the Link, in which case the Endterm attribute is to be ignored (new and tentative rule for this version, comments invited). ListItem A wrapper for the elements of items in an ItemizedList or OrderedList; it also occurs within VarListEntry in VariableList. It may contain just about anything except Sects and book components. It has common attributes and an Override attribute, which may have any of the values of ItemizedList's Mark attribute; use Override to override the mark set at the ItemizedList level, when you desire to create ItemizedLists with varying marks. Literal Any literal string, used in-line, that is part of data in a computer. This may be as precise as the value of an argument, but Literal may also be used as a catch-all element. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. LiteralLayout The wrapper for lines set off from the main text that are not tagged as Screens, Examples, or ProgramListing, in which line breaks and leading white space are to be regarded as significant. It contains in-line elements, and has common and Width attributes, for specifying a number representing the maximum width of the contents. LoT The generic tag for such things as a List of Figures or List of Tables. An LoT may occur within a Chapter, or Appendix, or may be a book component on its own. It contains, in order, an optional DocInfo, Title, and TitleAbbrev, followed by one or more LoTentries. It has common and Label attributes; in this case the values of Label may be Equation, Examples, Figures, or Tables, with no default. LoTentry An element of LoT. It contains the text of the thing to be listed, including, if desired, in-line elements. It has common and PageNum attributes. Macro Dropped. See SystemItem. ManVolNum Specific to UNIX man pages, it designates the section of a complete set of reference pages that a reference page belongs to. It appears within RefMeta, contains plain text, and has common attributes. Markup A string of formatting markup in text, which it is desired to represent literally. See also SGMLTag. It contains plain text and has common attributes. Mask Values in a specified structure that should be read when updating resource values. Mask contains plain text and has common attributes. MediaLabel The physical medium on or in which some information is contained. MediaLabel may contain plain text, and has common, Class, and MoreInfo attributes. Class may have the value Cartridge, CDRom, Disk, or Tape (no default). For the MoreInfo attribute see Application. Member Part of a SimpleList. It contains in-line elements and has common attributes. Menu Dropped. See Interface. MenuItem Dropped. See Interface. ModeSpec Contains application-specific information necessary for the completion of an OLink; see OLink. Msg 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. It has common and Label attributes. MsgAud Describes the audience to which a Msg is relevant. It contains plain text only, and has common attributes. MsgEntry A wrapper for an entry in a MsgSet. A MsgEntry must contain one or more Msgs, followed by an optional MsgInfo, then any number of MsgExplans. MsgEntry has common attributes. MsgExplan 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. It has common attributes. MsgInfo Information about the Msg containing it. It may have any number of MsgLevels, MsgOrigs, and MsgAuds, in any order, and has common attributes. MsgLevel The level of importance or severity of a Msg. It contains only plain text, and has common attributes. MsgMain The main error message of a Msg. MsgMain begins with an optional Title and contains MsgText, which is the text of the message. It has common attributes. MsgOrig The origin of a Msg. It contains only plain text and has common attributes. MsgRel An optional subpart of a Msg, containing 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. It has common attributes. MsgSet A list of error messages produced by a system, with various additional information. MsgSet contains one or more MsgEntries, and has common attributes. Usage Note: The entire Msg* construction is new and complicated; it may be simplified in the future. MsgSub An optional subpart of a Msg, which might contain messages that appear in various contexts. It contains a an optional Title followed by MsgText. MsgSub has common attributes. MsgText Contents of the parts of Msg. It may contain block-oriented elements, and has common attributes. Note A message to the user, set off from the text. See Caution. OLink A link that may perform some operation to find its target. In contrast to Link, OLink has no Linkend attribute, but rather a TargetDocEnt, the value of which is the name of a text or data entity already defined by the user. The LinkMode attribute points by ID to a ModeSpec; for convenience, ModeSpecs located in the BookInfo. ModeSpec contains instructions (probably application-specific) for operating on the entity named by TargetDocEnt, e.g., the TargetDocEnt is another Book, and the ModeSpec specifies that all the second-level headings should be searched for a phrase. The LocalInfo attribute may be used to hold such a phrase, which may be thought of as a replacement for some variable in ModeSpec. Finally, OLink has a Type attribute, also. Option An option for a computer program command. It may have members of cptrphrase.gp, and has common attributes. Optional For use in Synopsis, as in a RefEntry, where optional parameters conventionally are shown in square brackets. Optional should replace those brackets. It may contain elements from cptrphrase.gp, and has common attributes. OrderedList A numbered or lettered list, consisting of ListItems. A ListItem in an OrderedList contains paragraphs and other block-oriented elements, which may in turn contain other lists; an OrderedList may be nested within other lists, too. OrderedList has common attributes, along with a Numeration attribute, which may have the value Arabic, Upperalpha, Loweralpha, Upperroman, or Lowerroman. If no value is supplied, the processing expectation should be that Arabic numbering (1, 2, 3, . . .) is to be used. It has an InheritNum attribute, for which the value Inherit specifies for a nested list that the numbering of ListItems should include the number of the item within which they are nested (2a, 2b, etc., rather than a, b, etc.); the default value is Ignore. It has a Continuation attribute, with values Continues or Restarts (the default), which may be used to indicate whether the numbering of a list begins afresh (default) or continues that of the immediately preceding list (Continues). You need supply the Continuation attribute only if your list continues the numbering of the preceding list. OrgName An organization that is not a corporation (cf. CorpName) It contains plain text. OrgDiv Part of an organization. It contains plain text. OSname Dropped. See SystemItem. OtherCredit Supplements Author and Editor; you could use it to credit a contributor, a contributing editor, or some deserving production person. Contents are as for Author. It has common attributes. OtherName An alternative to Firstname and Surname, for use in Author, Editor, or OtherCredit. It contains plain text. PageNums The numbers of the pages contained in a Book, for use in its BookBiblio. It contains plain text (e.g., ix, 292). Para A paragraph. A Para may not have a Title: to attach a Title to a Para use FormalPara. Para may contain any in-line element and almost any block-oriented element. Abstract, AuthorBlurb, Caution, Important, Note, and Warning are excluded, as are Sects and higher-level elements. Para has common attributes. Paragraphs See Para. ParamDef Part of a FuncSynopsis, providing data type information and the name of the Parameter this information applies to. A ParamDef may contain any combination of plain text, Replaceable, Data, or Parameter, in any order. It has common attributes. See FuncDef, FuncSynopsis. It has common attributes. Parameter Part of an instruction to a computer. It may contain members of cptrphrase.gp, and has common, Class, and MoreInfo attributes. Class may have the value Command, Function, or Option (no default). For the MoreInfo attribute see Application. Part A section of a Book containing book components. Part contains an optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro, followed by one or more book components. It has common and Label attributes. PartIntro Introduction to the contents of a Part; may also appear in Reference. It has optional Title and TitleAbbrev, and then may contain anything that can appear in a Chapter. PartIntro has common and Label attributes. Phone Part of Address. It contains plain text. POB Part of Address. It contains plain text. Postcode Part of Address. It contains plain text. Preface Any introductory matter in a Book. Preface may occur more than once in Book, before any Chapter, Part, or Reference: for example, you might have two Prefaces, one titled “Preface” and the other “Introduction.” Preface may begin with a DocInfo, followed by a required Title, optional TitleAbbrev, and anything found in the body of a Chapter. Preface has common attributes. Primary A word or phrase occurring in the text that is to appear in the index under as a primary entry. It must be nested within IndexTerm tags. Primary may contain in-line elements. It has SortAs and common attributes. SortAs can be used to provide an alternate string for alphabetizing the index: if Primary has the content “14” one might give Primary the attribute Sortas=“fourteen”. PrimaryIE A primary entry in an Index, not in the text. It may contain only plain text. It has common attributes and a Linkends attribute, which has the value of some list of element IDs. PrintHistory The printing history of a Book. It contains paragraphs. Procedure A list 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. Procedure has common attributes. ProductName Formal name for any product. It contains in-line elements, and has common and Class attributes. The Class attribute may have the values Service, Trade (the default), Registered, Copyright, or Logo. Thus a trademark is a Productname with the default Class attribute value. ProductNumber A number assigned to a product. It contains plain text. ProgramListing A listing of a program. Line breaks and leading white space are significant in a ProgramListing, which may contain in-line elements, including LineAnnotations. (LineAnnotations are a document author's comments on the code, not the comments written into the code itself by the code's author.) ProgramListing has common and Width attributes, the latter for specifying a number representing the maximum width of the contents. Prompt Dropped. See SystemItem. Property A defined set of data associated with a window. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. ProtocolRequest Message sent from a program to a server. It may contain members of cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. PubDate The date of publication of a document. It contains plain text. Publisher The publisher of a document. It contains a PublisherName and any number of Addresses. PublisherName The name of a publisher of a document. It contains plain text. PubsNumber A number assigned to a publication, other than an ISBN or ISSN or InvPartNumber. It contains plain text and has common attributes. Quote An in-line quotation. For block quotes use BlockQuote. Quote may contain members of cptrphrase.gp, and has common attributes. RefClass An element of RefNameDiv, in which the applicability or scope of the topic of a RefEntry may be indicated. It may contain plain text or Application. RefDescriptor A substitute for RefName to be used when a RefEntry covers more than one topic and none of the topic names is to be used as the sort name. It contains plain text and has common attributes. RefEntry A reference page. It contains, in order, an optional DocInfo and optional RefMeta; any number of Comments and members of links.gp, in any order; a required RefNameDiv, an optional RefSynopsisDiv, and one or more RefSect1s. It has common attributes. Reference A collection of RefEntries, formin a book component. Reference has an optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro, and one or more RefEntries. It has common and Label attributes. RefEntryTitle Primary name given to a reference page for sorting and indexing. It may be the same as the first of the RefNames, or it may be the same as the RefDescriptor. It may contain in-line elements, and has common attributes. RefFileName Dropped. It is now called RefEntryTitle. RefMeta The first major division of a reference page, in which metainformation about the reference page is supplied. RefMeta contains, in order, a required RefEntryTitle, an optional ManVolNum, and any number of RefMiscInfos. It has common attributes. RefMiscInfo Marks information in RefMeta that may be supplied by vendors, such as copyright, release date, revision date, print status, operating system, hardware architecture, or a descriptive phrase for use in a print header. It contains plain text, and has common and Class attributes. The Class attribute can be used to distinguish categories of RefMiscInfos. RefName The subject or subjects of a reference page. It appears within RefNameDiv. It may contain plain text and in-line elements, and has common attributes. RefNameDiv The second major division of a reference page. It contains, in order, an optional RefDescriptor, one or more RefNames, a required RefPurpose, and an optional RefClass, followed by any number of Comments and links, in any order. It has common attributes. RefPurpose A short phrase describing the subject of the reference page. It may contain in-line elements and has common attributes. RefSect1 Equivalent to a Sect1 in the DocBook DTD. It contains a Title, followed by any of the allowable contents of a Sect, except that only two levels of subsection are allowed, RefSect2 and RefSect3. It has common attributes. RefSect2 Equivalent to a Sect2 in the DocBook DTD, and may occur within RefSect1 or RefSynopsisDiv. It may contain any of the allowable contents of a Sect, except that only RefSect3 is allowed as a further subsections. It has common attributes. RefSect3 Subdivision of RefSect2. No further subdivisions allowed; contents otherwise as for RefSect2. It has common attributes. RefSynopsisDiv The third major division of a reference page, in which the syntax of the subject of the reference page is indicated. It contains, in order, an optional Title and TitleAbbrev, followed by either one or more synopses (Synopsis, CmdSynopsis, or FuncSynopsis) succeeded by any number of RefSect2s, or simply one or more RefSect2s. It has common attributes. ReleaseInfo Information about a particular version of a document. It contains plain text. Replaceable Part of a synopsis or command line, indicating that its contents may be replaced. It may contain basic in-line elements (not cptrphrase.gp) and has common and Class attributes. Class may have the value Command, Function, Option, or Parameter (no default). Resource Dropped. See SystemItem. ReturnValue A value returned by a function. It contains plain text and has common attributes. RevHistory A section of BookInfo or DocInfo recording revisions to the document. It consists of any number of Revisions, and has common attributes. Revision An entry in RevHistory, describing some revision made to the text. It contains, in order, a required RevNumber, required Date, one or more sets of AuthorInitials, and a required RevRemark. RevNumber The number of a Revision. It contains plain text. RevRemark An element of Revision, describing the Revision. It contains plain text. Row A row in a TBody, THead, or TFoot. It contains one or more Entries or EntryTbls, in any order. It has common, Rowsep, and VAlign attributes. Rowsep determines Row separators. If its content is Yes, display the internal vertical row ruling below each Row; if No, do not display it. It is ignored for the last Row of the TGroup, THead, or TFoot, where the frame value applies. There is no default. The value is inherited from TGroupStyle, if used. Valign governs the vertical positioning of text within a Row. Allowed values are Top, Middle, and Bottom (no default). Screen Intended to represent what the user sees or might see on a computer screen. It consists of in-line elements, in which line breaks and leading white space are considered significant. It has common attributes and a Width attribute for specifying a number representing the maximum width of the contents. ScreenInfo Part of ScreenShot (see ScreenShot). A ScreenInfo indicates how the Graphic with which it is paired was created, as a guide for future revisions. It may contain only plain text, and has common attributes. ScreenShot Like Screen, intended to represent what the user sees or might see on a computer screen. It consists of an optional ScreenInfo and a required Graphic. It has common attributes and a Width attribute for specifying a number representing the maximum width of the contents. Secondary A word or phrase in the text that is to appear in the index beneath a Primary entry. It must be nested within IndexTerm tags and must follow a Primary element. It may contain in-line elements, and has SortAs and common attributes. See Primary. SecondaryIE Part of IndexEntry, like PrimaryIE (see PrimaryIE). Sect1 A top-level section of a book component, including the Title of that section. Sect2–5 nest in order within Sect1. Anything may occur within a Sect1 except a DocInfo, Preface, Chapter, Appendix, or another Sect1, including a Glossary, Bibliography, RefEntry, ToC, Index, or LoT. A Sect must have a Title, which is the text of the heading itself, and may have a TitleAbbrev; it must include some content, whether paragraphs or other block-oriented elements, including a Sect2. Sect1–5 have common, Label, and Renderas attributes. The Renderas attribute may have the value Sect1 through Sect5, and may be used to specify that the Sect (particularly its heading) is to be presented in the format defined for a Sect of some other level. Sect2 A section beginning with a second-level heading; must be nested within a Sect1. Allowable and required contents for Sect2, and its attributes, are like those for Sect1. Sect3 See Sect1, Sect2. Sect4 See Sect1, Sect2. Sect5 See Sect1, Sect2. Sect5 may not contain Sects of any level, and no further subdivisions are supplied in the DocBook DTD. See Part of IndexTerm, indicating, for a word or phrase in the text, the index entry to which the reader is to be directed when he consults the stub index entry for another element within the IndexTerm. See must be nested within IndexTerm tags and must follow a Primary or Secondary element. It may contain in-line elements, and has common attributes. SeeAlso Like See, but indicates the index entries to which the reader is also to be directed when he consults a full index entry. SeeAlso must be nested within IndexTerm tags and must follow a Primary or Secondary element. It may contain in-line elements, and has common attributes. SeeAlsoIE A “see also” entry in an Index, not in the text, occurring unnested within IndexEntry at the PrimaryIE or SecondaryIE level. It may contain plain text only. It has common attributes and a Linkends attribute, which has the value of some list of IndexEntry IDs. SeeIE A “see” entry in an Index, not in the text, occurring unnested within IndexEntry at the PrimaryIE or SecondaryIE level. It may contain plain text only. It has common attributes and a Linkend attribute, which has the value of some IndexEntry ID. Seg A component of a SegmentedList. Segs are the only content of a SegmentedList's SegListItems. Seg may contain in-line elements. It has common attributes. SegListItem A list item in a SegmentedList. It consists of two or more Segs, and has common attributes. SegmentedList A list of sets of units. It may be used to represent sets of information often presented as simple tables. SegmentedList may have a Title and TitleAbbrev, followed by any number of SegTitles, and one or more SegListItems. It has common attributes. SegTitle A title that pertains to one Seg in each SegListItem: the first SegTitle to the first Seg, the second SegTitle to the second Seg, and so on. It may contain in-line elements. SegTitles are grouped at the beginning of a SegmentedList, before the SegListItems. It has common attributes. Series Dropped. SeriesInfo Part of BookInfo or BiblioEntry, containing information about the publication series of which the book is a part. SeriesInfo contains, in order, a required Title, optional TitleAbbrev and Subtitle; any number of AuthorGroups, optional ISBN, VolumeNum, and IssueNum; a required SeriesVolNums, any number of PubDates and Publishers, and finally an optional Copyright. It has common attributes. SeriesVolNums The numbers of all the volumes in a Series, for use in SeriesInfo. It contains plain text (e.g., 1-5). Set Two or more Books. Set may have, in order, a Title, TitleAbbrev, SetInfo, and ToC, followed by the Books, followed by an optional SetIndex. Note that a SetIndex may appear in a Book, too. Set has common attributes. SetIndex Index to a Set. It may occur within a Set or one of the Books in a Set. 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. SetInfo Metainformation for a Set, in which it may appear. It may contain, in any order, any number of: Author, AuthorInitials, Copyright, CorpAuthor, CorpName, Date, Editor, Edition, InvPartNumber, ISBN, LegalNotice, OrgName, OtherCredit, PrintHistory, ProductName, ProductNumber, Publisher, PubsNumber, ReleaseInfo, RevHistory, Title, Subtitle, and VolumeNum. SetInfo has common attributes and a Contents attribute. Contents is partly a stub for future development; at the moment its values should be the IDs of the ToC, Books, and SetIndex that comprise the Set, in the order of their appearance. SGMLTag An element tag in SGML. This element contains plain text, and should not include delimiting angle brackets, ampersands, percent signs, or semicolons: those should be supplied by the renderer if appropriate. It has common and Class attributes. Class may be Attribute, Element, GenEntity, or ParamEntity; there is no default. ShortAffil Brief version of of Affiliation, in which it may appear. It contains plain text. Sidebar Segment of a book component that is isolated from the narrative flow of the main text, typically boxed and floating. Sidebar may have a Title and a TitleAbbrev, followed by paragraphs, lists, and other block-oriented elements. No Sects allowed. Sidebar has common attributes. SimPara A paragraph that is only a text block, without included block-oriented elements. It may contain InlineGraphic, InlineEquation, and synopses. SimPara has common attributes. SimpleList Intended for long lists of single words or short phrases. It consists of one or more Members, and has common, Columns, and Type attributes. The value of the Type attribute may be Inline, Horiz, or Vert (the default), indicating that the list should be formatted as part of a regular paragraph, as an array reading L to R then top to bottom, or as an array reading top to bottom then L to R. The Columns attribute value must be a number, the number of columns the array should contain. Further details on rendering may be found in the comment in the DTD, but these details may required some revision in the future. SpanSpec Formatting information for a spanned column in a TGroup (part of Table). SpanSpec is an empty element, bearing common, Align, Char, Charoff, Colsep, Nameend (required), Namest (required), Rowsep, and Spanname, (required) attributes. SpanSpec identifies a horizontal span of columns and associated attributes that can subsequently be referenced by its SpanName to provide attributes repeatedly used in the Entries or EntryTbls in the Rows of the TGroup that is nested within the THead, TFoot, or TBody in which the SpanSpec occurs. The reason Colname is used rather than Colnum in identifying SpanSpec is that the names are independent of revisions that may change the number of inserted/deleted columns, as long as Namest remains to the left of (has a smaller colnum than) Nameend. SpanSpecs set on THead or TFoot override those on the containing TGroup and apply to just the THead or TFoot. SpanSpecs from the containing TGroup apply to TBody. 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). The default is Center. 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. The default is inherited from the ColSpec of the column named by Namest. 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 ColSpec of the column named by Namest. 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. (In CALS, Yes is expressed as 1 and No as 0.) The default is inherited from the ColSpec of the column named by Namest. Nameend is the name of the rightmost column of the span. Names are identified in the Colspec of the current TGroup. Namest or Name Start, is the name of the leftmost column of the span. Names are identified in the Colspec of the current TGroup. 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 the ColSpec of the column named by Namest. Spanname is the name of the horizontal span. State Part of Address. It contains plain text. Step Part of a Procedure. After its optional Title, Step must consist either of block-oriented elements such as paragraphs followed optionally by a SubSteps element, or simply a SubSteps element. SubSteps then contains one or more Steps—it is a wrapper. Step has common attributes and a Performance attribute, which indicates whether the step must be performed: the values are Optional and Required (the default). Street Part of Address. It contains plain text. StructField A field in a Structure. It contains plain text and has common attributes. StructName The name of a Structure. It contains plain text and has common attributes. SubSteps A wrapper for Steps within Steps. See Procedure, Step. Note that SubSteps, like Step, has a Performance attribute, the values of which may be Optional or Required (the default). Subscript A subscript. It may contain basic in-line elements and Replaceable, and has common attributes. Subtitle Subtitle of a document. It contains plain text. Superscript A superscript. It may contain basic in-line elements and Replaceable, and has common attributes. Surname (Western-style) family name of an author. It contains plain text. SWapplic Dropped. See Application. Symbol A name that is replaced by a value before processing. It contains plain text and has common attributes. Synopsis The syntax of a command or function. It appears within RefSynopsisDiv, and may occur elsewhere in a document, too. Synopsis has an optional title, followed by one or more in-line elements and Graphics; within it, line breaks and white space are significant. It has common attributes. CmdSynopsis and FuncSynopsis are alternates to Synopsis, but they may not contain Graphics and within them line breaks and white space are not significant. Synopsis should be displayed as a block-oriented element, not in-line. SynopFragment Part of CmdSynopsis. It contains one or more Args or Groups, in any order, and has the attributes ID (the only required attribute), Lang, Remap, Role, and XRefLabel. SynopFragmentRef Part of a CmdSynopsis. It contains RCDATA (characters, in which entity references and character references are recognized in parsing) rather than elements. It has common and Linkend (required) attributes. Linkend should point to SynopFragment. SystemItem Any system-related item. It may contain members of cptrphrase.gp, and has common, Class, and MoreInfo attributes. Class may have the value Constant, EnvironVar, Macro, OSname, Prompt, Resource, or SystemName (no default). For the MoreInfo attribute see Application. SystemName Dropped. See SystemItem. Table An array of text. The Table models available in version 1.2.2 have been dropped in favor of a CALS-compliant Table model. The present Table element has a required Title, an optional TitleAbbrev, and either one or more Graphics or one or more TGroups. Tables may not contain either Tables or InformalTables. Table has common, Colsep, Frame, Label, Orient, Pgwide, Rowsep, Shortentry, Tabstyle, and Tocentry attributes. elements that may be contained within TGroup are specified as having omissible end tags, except for EntryTbl. Who said the military isn't thoughtful? 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 value of Frame applies. There is no default; the value may be inherited from Tabstyle in the FOSI. Frame describes the positioning of framing rules around the Table. The allowed values are Sides (left and right), Top (below title), Bottom (after last Row, possibly the last Row of TFoot), Topbot (both top and bottom), All (all of the aforementioned), and None. There is no default. The value may be inherited from Tabstyle in the FOSI. Label is just the same as DocBook's Label attribute: a reference string, such as a number, to be prefixed to the Title. Orient determines the orientation of the Table. The allowed values are Port (the orientation of the rest of the text of the Book, that is, upright) and Land (90 degrees counterclockwise from the orientation of the rest of the text of the Book). If you assume that the page is taller than it is wide, tables that take up a whole page and are wider than they are tall should be given the Land value. There is no default, the value may be inherited from the FOSI. Pgwide constrains the table to or liberates it from the boundaries of its column. If the value is Yes, the table runs across the entire page; if No, the table “runs across just the (galley) width of the current column of the page, regardless of the value of Orient. If the value is No, it has no meaning for the case when Orient is set to Land. The value may be inherited from Tabstyle in the FOSI, if available. 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. There is no default. The value may be inherited from TabStyle. Shortentry determines whether value of ShortEntry is be used in the an Index or ToC or LoT. If the value is No, the TitleAbbrev is not used; if Yes, the ShortEntry is used. Usage Note: Be aware that this mechanism duplicates the DocBook element TitleAbbrev. It would be better, for any given work, to choose one mechanism or the other, rather than mix them. Tabstyle is the name of a table style defined in the FOSI. There is no default. Tocentry determines whether the Table's Title should be included in an LoT. The value may be Yes (include) or No (exclude). The default is Yes (include). should be ignored if the optional Title is omitted; that would be the case if you were using Table, instead of InformalTable, for a Table that has no Title; presumably only a reference string could then appear in an LoT. Term The hanging term attached to a ListItem within a VarListEntry in a VariableList; visually, a VariableList is a set of Terms with attached items such as paragraphs. Each ListItem may be associated with a set of Terms. Term may contain in-line elements or synopses. It has common attributes. Tertiary A word or phrase that is to appear in the index under a Secondary entry. It must be nested within IndexTerm tags and must follow a Secondary element. It may contain in-line elements, and has SortAs and common attributes. See Primary. TertiaryIE Part of IndexEntry, like PrimaryIE see PrimaryIE). TBody Wrapper for the Rows of a Table or InformalTable. It contains simply one or more Rows, and has common and VAlign attributes. VAlign governs the vertical positioning of text within a Row. Allowed values are Top (the default), Middle, and Bottom. TFoot TFoot is a optional part of TGroup (part of Table), identifying the footer information in a Table, which is displayed after the TBody and also at the bottom of any TBody Rows before a page break. TFoot must have one or more Rows. It has common and VAlign attributes, the latter with the allowed values of Top (the default), Middle (approximately centered vertically), and Bottom. TGroup The part of a Table that is contains an array along with its formatting information. In order, a TGroup has any number of ColSpecs, any number of SpanSpecs, an optional THead, and optional TFoot, and a required TBody. Each TGroup effectively identifies a new portion of a Table. If a new ColSpec is provided, it replaces a previous one. If both ColSpec and SpanSpec are new, that SpanSpec should refer to columns in the most recent ColSpec. If only a new SpanSpec is provided, it should refer to columns defined by the most immediately prior ColSpecs in a TGroup of the Table. On the other hand, a new ColSpec to either a THead or TFoot replaces all prior column definitions. TGroup has common, Align, Char, Charoff, Cols, Colsep, Rowsep, 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). The default is Left, unless overridden by TGroupStyle. 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 is aligned to the left (the original doc incorrectly specifies “right”) of that character. The default is “”, unless inherited from TGroupStyle. 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 50 unless overridden by TGroupStyle. Cols is the number of columns in the table (required). 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 value of Frame applies. There is no default. The value is inherited from TGroupStyle, if used. 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. There is no default. The value is inherited from TGroupStyle, if used. TGroupStyle is a unique table group style defined in a FOSI (no default). THead THead is a optional part of TGroup (part of Table). THead may have any number of ColSpecs, followed by one or more required Rows. It has common and VAlign attributes, the latter with the allowed values of Top, Middle, and Bottom (the default). THead identifies the heading information in a Table, which is displayed at the top of the Table and again at the top of any continuation after a page break between Rows in TBody. Tip A suggestion to the user, set off from the text. See Caution. Title The text of a heading or the title of a block-oriented element. Title may contain in-line elements, and has common and PageNum attributes. TitleAbbrev An optional, abbreviated version of any Title. You may want to use this element when a title is so long that it might be truncated in some part of an online display, such as a title bar. TitleAbbrev may contain in-line elements and has common attributes. ToC A Table of Contents, which may be a book component on its own or may occur within other book components. It may have a DocInfo, Title, and TitleAbbrev. Formerly, ToC contained only ToCentry1s, but in this revision it has been subdivided to follow the divisions of a book: following the 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, 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 is the actual entry, which was formerly ToCEntry), then contains any number of ToCChaps. 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. ToC has common attributes. ToCBack Entry for back matter in a ToC. See ToC. It has common, Linkend, Pagenum, and Label attributes. The Label attribute may take the value of Bib, Gloss, or Index, depending on the identity of the piece of front matter concerned. ToCChap See ToC. ToCFront Entry for introductory matter in a ToC. See ToC. It has common, Linkend, Pagenum, and Label attributes. The Label attribute may take the value of Equations, Examples, Figures, Preface, or Tables, depending on the identity of the piece of front matter concerned. ToCLevel1 The top-level tag for entries in a ToC. See ToC. ToCLevel2–5 may be nested within it, in order. All have common attributes and Linkend and PageNum attributes. PageNum is for indicating the page numbers on which the Table of Contents entries appear in a printed book. Linkend, should you choose to use it, should have the value of the ID of the relevant book part. ToCLevel1–5 may contain in-line elements. ToCPart See ToC. Token A unit of information in the context of lexical analysis. It contains plain text and has common attributes. Trademark A trademark. It may contain members of cptrphrase.gp, and has common and Class attributes. Class may have the values Service, Trade, Registered, or Copyright; the default is Trade. Type Indicates the classification of a value. It contains plain text and has common attributes. ULink A link containing a URL. A URL is a Uniform Resource Locator, as used with the World Wide Web. Very generally, a URL is a string specifying, according to a defined protocol, a method, a path to a target, and possibly some additional information. The URL should be given as the value of the URL attribute; there is also a Type attribute. While ULink is powerful, it is experimental and may be dropped in future revisions. Users should not expect it to be supported by SGML browsers. UserInput Data entered by the user. It may contain elements from cptrphrase.gp, and has common and MoreInfo attributes. For the MoreInfo attribute see Application. VarArgs An empty element, part of FuncSynopsis, indicating that the Function in question has a variable number of arguments. The string “(...)” should be output. VariableList An optionally titled list of VarListEntries, which are composed of sets of one or more Terms with associated ListItems; ListItems contain paragraphs and other block-oriented elements in any order. Inclusions are as for OrderedList (see OrderedList). VariableList has common attributes. VarListEntry A component of VariableList (see VariableList). It has common attributes. VarParam Dropped. Void An empty element, part of FuncSynopsis, that indicates that the Function in question takes no arguments. The string “(void)” should be output. See VarArgs. It has common attributes. VolumeNum The number of a Book in relation to Set, or of a journal, when Book is used to represent a journal by containing Articles. It contains plain text and has common attributes. Warning An admonition set off from the text. See Caution. WordAsWord A word (or letter or number) used not to represent the thing or idea it usually represents, but merely as the word itself. For example, “The term WORDASWORDGothic/WORDASWORD means different things to art historians and typographers,” or for a single character, “the letter WORDASWORDX/WORDASWORD”. It contains plain text and has common attributes. XRef Cross reference link to another part of the document. It has Linkend and Endterm attributes, just like Link, but like Anchor, it may have no 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 Link. Year Year of publication, for use in Copyright. It contains plain text.