Manual Pages for UNIX Operating System command usage for man sgml

Standards, Environments, and Macros                       sgml(5)



NAME
     sgml, solbook - Standard Generalized Markup Language

DESCRIPTION
     Standard Generalized Markup Language (SGML) is the ISO stan-
     dard  8879:1986 that describes a syntax for marking up docu-
     ments with tags that describe the purpose of the text rather
     than the appearance on the page. This form of markup facili-
     tates 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  elements.  The organization and structure of a docu-
     ment and the meaning of elements are described in the  Docu-
     ment  Type  Definition  ( DTD ). Elements are the  tags that
     identify the content. Element names may  be  descriptive  of
     the  content  for ease of use. For example   for para-
     graphs. 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 ele-
     ments that constitute 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  stan-
     dard 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  Sol-
     Book   DTD  ,  which is a proper subset 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  structure  to  the  document.  The  following is a
     description of some of the elements from  the  SolBook   DTD
     which are used for reference pages.

  DOCTYPE




SunOS 5.11           Last change: 7 Jan 1997                    1






Standards, Environments, and Macros                       sgml(5)



     The first line in an  SGML file that identifies the location
     of  the  DTD that is used to define the document. The 
     TYPE 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
     . All of the text and other tags must be contained
     within this tag.

  RefMeta
     The next tag in a reference page is  , which  is  a
     container for several other tags. They are:

          This is the title of the reference page.
                         It  is  equivalent  to  the  name of the
                         reference page's file name, without  the
                         section number extension.


              This is  the  section  number  that  the
                         reference page resides in.  The contents
                         may be a text entity reference.


            There are  one  or  more   
                         tags  which  contain  meta  information.
                         Meta information  is  information  about
                         the  reference  page. The  
                         tag has the  class attribute. There  are
                         four classes that are routinely used.

                         date          This is the date that  the
                                       file was last modified. By
                                       consensus  this  date   is
                                       changed   only   when  the
                                       technical  information  on
                                       the  page  changes and not
                                       simply  for  an  editorial
                                       change.


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






SunOS 5.11           Last change: 7 Jan 1997                    2






Standards, Environments, and Macros                       sgml(5)



                         software      This is the  name  of  the
                                       software  product 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 limitation of the
                                       subject discussed  on  the
                                       reference  page.  If there
                                       are  no  limitations   the
                                       value   used  is  generic.
                                       Other values are sparc and
                                       x86.


                         copyright     This  attribute   contains
                                       the Sun Microsystems copy-
                                       right.  Any  other   copy-
                                       rights that may pertain to
                                       the  individual  reference
                                       page    file   should   be
                                       entered as separate                                         miscinfo>   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.  con-
     tains three tags. These tags contain the text that is before
     and after the `-' (dash) on the NAME line.

                These are the names of the  topics  that
                         are  discussed in the file. There may be
                         more than one   for a page. The
                         first    must match the name of
                         the file  and  the  .  If
                         there  are more than one  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.



SunOS 5.11           Last change: 7 Jan 1997                    3






Standards, Environments, and Macros                       sgml(5)



             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.


          In some cases the   is  a
                         general  topic  descriptor of a group of
                         related objects that  are  discussed  on
                         the  same  page.  In this case the first
                         tag after the   is  a                           discriptor>.  The  tags follow.
                         Only one  is allowed, and
                         it should match the .


  RefSynopsisDiv
     The SYNOPSIS line of the reference page is contained by this
     tag.  There  is  a