unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

sgml(5)               Standards, Environments, and Macros              sgml(5)



NAME
       sgml, solbook - Standard Generalized Markup Language

DESCRIPTION
       Standard  Generalized  Markup  Language  (SGML)  is  the  ISO  standard
       8879:1986 that describes a syntax for marking up  documents  with  tags
       that describe the purpose of the text rather than the appearance on the
       page. This form of  markup  facilitates  document  interchange  between
       different  platforms  and  applications.  SGML allows the management of
       information as data objects rather than text on a page.

       In an  SGML document the main structural  components  are  called  ele-
       ments.  The organization and structure of a document and the meaning of
       elements are described in the Document Type Definition (  DTD  ).  Ele-
       ments  are  the   tags  that identify the content. Element names may be
       descriptive of the content for ease of use.  For  example   <&lt;para>&gt;  for
       paragraphs.  Elements  can have  attributes which are used to modify or
       refine the properties or characteristics of
        the element. Within the  DTD a  valid  context  for  each  element  is
       defined and a framework is provided for the types of elements that con-
       stitute a compliant document.

       Another component of the  DTD is entities. Entities are a collection of
       characters  that  can  be referenced as a unit. Entities are similar to
       constants in a programming language such as C. They can be defined  and
       referenced. An entity can  represent one character or symbol which does
       not appear on a standard keyboard, a word or  group  of  words,  or  an
       entire  separate  sgml marked-up file. Entities allow reuse of standard
       text.

       There is no single standard  DTD , but the de facto  standard  for  the
       computer industry is the DocBook  DTD , developed and maintained by the
       Davenport Group. Within Sun, the SolBook  DTD , which is a proper  sub-
       set  of DocBook  DTD , is used when writing reference manual pages. The
       SolBook  DTD contains a number of tags that are designed for the unique
       needs of the reference pages.

SolBook Elements
       Elements  are defined with a hierarchical structure that gives a struc-
       ture to the document. The following is a description  of  some  of  the
       elements from the SolBook  DTD which are used for reference pages.

   DOCTYPE
       The first line in an  SGML file that identifies the location of the DTD
       that is used to define the document. The <&lt;!DOCTYPE string is what the
        SGML -aware  man(1) command uses to identify that a file is  formatted
       in  SGML rather than  nroff(1).

   RefEntry
       The  top  layer  element that contains a reference page is  <&lt;refentry>&gt;.
       All of the text and other tags must be contained within this tag.

   RefMeta
       The next tag in a reference page is  <&lt;refmeta>&gt;, which  is  a  container
       for several other tags. They are:

       <&lt;refentrytitle>&gt; This  is the title of the reference page. It is equiva-
                       lent to the name of the  reference  page's  file  name,
                       without the section number extension.



       <&lt;manvolnum>&gt;     This  is  the  section  number  that the reference page
                       resides in.  The contents may be a text  entity  refer-
                       ence.



       <&lt;refmiscinfo>&gt;   There are one or more  <&lt;refmiscinfo>&gt; tags which contain
                       meta information. Meta information is information about
                       the  reference  page.  The   <&lt;refmiscinfo>&gt;  tag has the
                       class attribute. There are four classes that  are  rou-
                       tinely used.

                       date            This is the date that the file was last
                                       modified. By  consensus  this  date  is
                                       changed  only when the technical infor-
                                       mation on the page changes and not sim-
                                       ply for an editorial change.




                       sectdesc        This is the section title of the refer-
                                       ence page; for example  User  Commands.
                                       The  value  of  this attribute may be a
                                       text entity reference.



                       software        This is the name of the software  prod-
                                       uct  that  the  topic  discussed on the
                                       reference page belongs to. For  example
                                       UNIX commands are part of the SunOS x.x
                                       release. The value  of  this  attribute
                                       may be a text entity reference.



                       arch            This is the architectural platform lim-
                                       itation of the subject discussed on the
                                       reference page. If there are no limita-
                                       tions the value used is generic.  Other
                                       values are sparc and x86.



                       copyright       This   attribute   contains   the   Sun
                                       Microsystems copyright. Any other copy-
                                       rights that may pertain to the individ-
                                       ual  reference  page  file  should   be
                                       entered   as   separate   <&lt;refmiscinfo>&gt;
                                       entries. The value  of  this  attribute
                                       may be a text entity reference.




   RefNameDiv
       This  tag contains the equivalent information to the  .TH macro line in
       an nroff(1) reference page. <&lt;refnamediv>&gt;  contains  three  tags.  These
       tags  contain  the  text that is before and after the `-' (dash) on the
       NAME line.

       <&lt;refname>&gt;       These are the names of the topics that are discussed in
                       the  file.  There may be more than one  <&lt;refname>&gt; for a
                       page. The first <&lt;refname>&gt; must match the  name  of  the
                       file  and  the  <&lt;refentrytitle>&gt;. If there are more than
                       one <&lt;refname>&gt; tags, each is separated by a `,' (comma).
                       The  comma is generated by the publisher of sgml files,
                       so it should not be typed. This is referred to as auto-
                       generated text.



       <&lt;refpurpose>&gt;    The  text  after the dash on the NAME line is contained
                       in this tag. This is a short summary of what the object
                       or  objects  described  on the reference page do or are
                       used for. The dash is also  auto-generated  and  should
                       not be typed in.



       <&lt;refdiscriptor>&gt; In  some  cases  the <&lt;refentrytitle>&gt; is a general topic
                       descriptor of a group of related objects that are  dis-
                       cussed  on  the  same  page. In this case the first tag
                       after the <&lt;refnamediv>&gt; is a <&lt;refdiscriptor>&gt;. The  <&lt;ref-
                       name>&gt; tags follow. Only one <&lt;refdiscriptor>&gt; is allowed,
                       and it should match the <&lt;refentrytitle>&gt;.



   RefSynopsisDiv
       The SYNOPSIS line of the reference page is contained by this tag. There
       is a <&lt;title>&gt; that usually contains an entity reference. The text is the
       word SYNOPSIS. There are several tags within <&lt;refsynopsisdiv>&gt; that  are
       designed specifically for the type of synopsis that is used in the dif-
       ferent reference page sections. The three types are:

       <&lt;cmdsynopsis>&gt;   Used for commands and utilities pages.



       <&lt;funcsynopsis>&gt;  Used for programming interface pages.



       <&lt;synopsis>&gt;      Used for pages that do not fall into the other two cat-
                       egories.



   RefSect1
       This  tag  is equivalent to the  .SH nroff macro. It contains a <&lt;title>&gt;
       element that is the title of the reference page section. Section  names
       are  the  standard  names such as DESCRIPTION, OPTIONS, PARAMETERS, SEE
       ALSO, and others. The contents of the <&lt;title>&gt; may be a text entity ref-
       erence.

   RefSect2
       This  tag  is equivalent to the .SS nroff macro. It contains a  <&lt;title>&gt;
       element that contains the text of the sub-section  heading.  <&lt;refsect2>&gt;
       tags  may also be used within a <&lt;refsynopsisdiv>&gt; as a sub-section head-
       ing for the  SYNOPSIS section.

Block Elements
       There are a number of block elements that are used for  grouping  text.
       This is a list of some of these elements.

       <&lt;para>&gt;                  This  tag  is  used  to  contain a paragraph of
                               text.



       <&lt;variablelist>&gt;          This tag is used to create  two  column  lists.
                               For  example  descriptions for command options,
                               where the first column lists the option and the
                               second column describes the option.



       <&lt;orderedlist>&gt;           An list of items in a specific order.



       <&lt;itemizedlist>&gt;          A  list of items that are marked with a charac-
                               ter such as a bullet or a dash.



       <&lt;literallayout>&gt;         Formatted program output as produced by a  pro-
                               gram  or  command.  This tag is a container for
                               lines set off from the main text in which  line
                               breaks,  tabs, and leading white space are sig-
                               nificant.



       <&lt;programlisting>&gt;        A segment of  program  code.  Line  breaks  and
                               leading white space are significant.



       <&lt;table>&gt;                 This  tag  contains  the layout and content for
                               tabular formatting of information.  <&lt;table>&gt; has
                               a required  <&lt;title>&gt;.



       <&lt;informaltable>&gt;         This tag is the same as the  <&lt;table>&gt; tag except
                               the  <&lt;title>&gt; is not required.



       <&lt;example>&gt;               This tag contains examples of  source  code  or
                               usage  of  commands.   It  contains  a required
                               <&lt;title>&gt;.



       <&lt;informalexample>&gt;       This tag is the  same  as  the   <&lt;example>&gt;  tag
                               except the  <&lt;title>&gt; is not required.



Inline Elements
       The inline elements are used for tagging text.

       <&lt;command>&gt;               An executable program or the entry a user makes
                               to execute a command.



       <&lt;function>&gt;              A subroutine in a program or external library.



       <&lt;literal>&gt;               Contains any literal string.



       <&lt;parameter>&gt;             An argument passed to a computer program  by  a
                               function or routine.



       <&lt;inlineequation>&gt;        An untitled mathematical equation occurring in-
                               line.



       <&lt;link>&gt;                  A hypertext link to text within a book, in  the
                               case  of  the  reference  manual  it is used to
                               cross reference to another reference page.



       <&lt;olink>&gt;                 A hypertext link used to  create  cross  refer-
                               ences to books other than the reference manual.



       <&lt;xref>&gt;                  A  cross  reference to another part of the same
                               reference page.



SEE ALSO
       man(1), nroff(1), man(5)



SunOS 5.10                        7 Jan 1997                           sgml(5)