CDE/cde/doc/C/guides/infoAPg/ch02.sgm

<!-- $XConsortium: ch02.sgm /main/4 1996/10/11 09:23:31 cdedoc $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Chapter id="infoapg.div.2">
<Title id="GCgdOlB-xG9X3cS">SGML and Information Manager Document Structure</Title>
<IndexTerm><Primary>document structure</Primary></IndexTerm>
<Para>
This chapter introduces, briefly and at a very high-level, some
SGML concepts and terminology as they relate to the
Information Manager&rsquo;s on-line documentation model.
It also discusses how the Information Manager organizes SGML information for
on-line presentation. It includes these topics:
</Para>
<ItemizedList>
<ListItem>
<Para>
<Link Linkend="OCgdOlB-xG9X3cS">How SGML Structures Information</Link>
</Para>
</ListItem>
<ListItem>
<Para>
<Link Linkend="GI.RgFBe.1698oL">How the Information Manager Organizes On-line Information</Link>
</Para>
</ListItem>
</ItemizedList>
<Para>
Go directly to
<Link Linkend="sidr7JBU3pBt8oL">Preparing to Build</Link>
if you are interested in learning about the build process.
</Para>
<Sect1>
<Title id="OCgdOlB-xG9X3cS">How SGML Structures Information</Title>
<Para>
Standard Generalized Markup Language (SGML) is an
international standard for defining the structure of information
in a document. It does this by identifying the elements of a
document and then describing the relationships of these elements
to each other using a formal markup language.
</Para>
<Para>
Elements are the logical building blocks of an SGML document
such as its chapters, paragraphs, tables, graphics, and so forth.
As described in the SGML standard (<CiteTitle>ISO 8879</CiteTitle>):
&ldquo;A document is a logical construct that contains a document element, the top
node of a tree of elements that make up the document&rsquo;s content.&rdquo;
</Para>
<Para>
This hierarchy of logical elements is itself made up of a collection
of physical entities, which can include files, parts of files,
graphics, and other data. These physical entities are pulled
together during the build process into the logical structure
defined by the document type definition (DTD) for a given
document.
</Para>
<Para>
The DTD is described briefly below.
</Para>
<Sect2>
<Title id="aCgdOlB-xG9X3cS">Document Type Definition</Title>
<Para>
The rules that govern the types of elements that can be contained
in a given document and their order and frequency are defined in
a special SGML document called a Document Type Definition (DTD).
</Para>
<Para>
The DTD contains the markup rules that pertain to a class of
documents, including the list of allowable elements that can be
used in documents of a given type.
</Para>
<Para>
For example, the DTD may stipulate that a document must
consist of at least one chapter, a summary abstract, and an index.
</Para>
<Para>
It may further define the relationships and the content of these
elements, stating, for example, that chapters must start with a
chapter title followed by one or more paragraphs, each of which
can contain numbered lists, bulleted lists, tables, graphics, and
so forth.
</Para>
<Para>
Through this process of defining the elements that comprise a
given document type and the attributes that an element can
have, the DTD dictates the structure of the document.
</Para>
<Para>For more information about the SGML standard, see
<Link Linkend="Q3yRgFBsz1698oL">Related Documentation</Link>.
</Para>
</Sect2>
</Sect1>
<Sect1>
<Title id="GI.RgFBe.1698oL">How Information Manager Organizes On-line Information</Title>
<Para>
When you view on-line information through the
Information Manager Book List window,
you are looking at a collection of one or more
<FirstTerm>bookcases</FirstTerm> of books
about related topics. This collection is referred to as an
<FirstTerm>information library</FirstTerm>. Each bookcase contains one or more
<FirstTerm>books</FirstTerm>.
</Para>
<Para>
This section describes the structure of on-line information in the
Information Manager. The figure
<Link Linkend="pIfh7JBpooBt8oL">On-line Information Structure</Link> depicts
the Information Manager&rsquo;s library structure.
</Para>
<Sect2>
<Title id="UIfh7JBpooBt8oL">On-line Information Structure</Title>
<IndexTerm><Primary>on-line information</Primary><Secondary>structure of</Secondary></IndexTerm>
<Para>
An Information Manager information library (infolib) is created from
SGML-conforming documents by a set of software tools called the
Information System Toolkit. The SGML documents contain all of the text,
tables, graphics, and other related elements that make up the books in
each of the bookcases. The Information Manager tools take the SGML input
and organize it internally into a hypertext-linked database that makes
retrieval of specific pieces of information in the library very
efficient.
<IndexTerm><Primary>SGML document</Primary></IndexTerm>
</Para>
<Para>
Each book in an Information Manager information library contains a hypertext
table of contents (TOC) and one or more sections. The hypertext
TOC<IndexTerm><Primary>table of contents</Primary></IndexTerm> is the entry point
into an on-line book in the Information Manager.
The TOC describes the structure of the document and acts as an
interactive electronic map to help you navigate through the
document to find specific information contained in the section(s).
To &ldquo;move&rdquo; to a section within the on-line document body, you
simply select the desired section title in the TOC.
</Para>
<Para>
Sections are
the smallest units of information in an Information Manager on-line book. They
consist primarily of text but can also include graphics and tables.
</Para>
<Para>
Information Manager &ldquo;connects&rdquo; book sections to the TOC through the use of
hypertext links<IndexTerm><Primary>hypertext links</Primary></IndexTerm>.
Each entry in the TOC contains a unique
hypertext reference, whose value maps to a section in the on-line
document.
</Para>
<Para>
These TOC hypertext links provide many of the advanced
document navigation features found in the Information Manager,
including the collapsible book list, the graphical location map,
and the printing hierarchy.
</Para>
</Sect2>
<Sect2>
<Title id="fIfh7JBpooBt8oL">On-line Information Hierarchy</Title>
<IndexTerm><Primary>information libraries</Primary><Secondary>information hierarchy</Secondary></IndexTerm>
<Para>
The on-line information hierarchy, as structured in the Information Manager,
consists of:
</Para>
<VariableList>
<VarListEntry>
<Term>Information library</Term>
<ListItem>
<Para>
A collection of bookcases.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Bookcase</Term>
<ListItem>
<Para>
A collection of style sheets and books. The bookcase also
contains a full-text search index constructed by the
Toolkit.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Book</Term>
<ListItem>
<Para>
One or more sections organized under a hypertext TOC.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Section</Term>
<ListItem>
<Para>
The smallest unit of information in a book. Each section
is referenced in the TOC and is viewable in one reading
window of the browser.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
<Figure>
<Title id="pIfh7JBpooBt8oL">On-line Information Structure</Title>
<GRAPHIC id="gr54" entityref="infoapg.fig.1"></graphic>
</Figure>
<Para>
In order for the tools in the Information System Toolkit to structure
your documents correctly, you must apply Information Manager
architectural forms to your documents&rsquo; DTDs. Applying Information
Manager architectural forms to your DTD does not invalidate your
existing document instances.
</Para>
<Para>
The DTDs that are shipped with Information Manager&mdash;
<filename>dtinfoBook.dtd</filename>, <filename>dtinfoTOC.dtd</filename>, <filename>dtinfoStyle.dtd</filename>, and
<filename>docbook.dtd</filename>&mdash; already contain these
architectural forms.
</Para>
<Para>
See <Link linkend="infoapg.div.10">Using Architectural Forms</LINK> for
instructions on applying the Information Manager architectural forms to
your documents&rsquo; DTDs.
</Para>
<para>
For related information, see:
</para>
<ItemizedList>
<ListItem>
<Para>
<Link Linkend="n1Pih7JBbpoBt8oL">Required Files</Link>
</Para>
</ListItem>
<ListItem>
<Para>
<Link Linkend="jI.RgFBe.1698oL">Build Considerations</Link>
</Para>
</ListItem>
</ItemizedList>
</sect2>
</Sect1>
</Chapter>