debian/cdesktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial import of the CDE 2.1.30 sources from the Open Group.

Browse Source
This commit is contained in:
Peter Howkins
2012-03-10 18:21:40 +00:00
commit 83b6996daa
18978 changed files with 3945623 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
cde/doc/C/guides/infoAPg/BEntity.sgm Normal file
View File

@@ -0,0 +1,22 @@
<!-- $XConsortium: BEntity.sgm /main/2 1996/09/22 13:11:07 vobadm $ -->
<!ENTITY infoapg.fig.1 SYSTEM "./infoAPg/graphics/infostr.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.2 SYSTEM "./infoAPg/graphics/docsrc.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.3 SYSTEM "./infoAPg/graphics/multss.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.4 SYSTEM "./infoAPg/graphics/bkcase.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.5 SYSTEM "./infoAPg/graphics/blddir.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.6 SYSTEM "./infoAPg/graphics/newlib.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.7 SYSTEM "./infoAPg/graphics/addbkcas.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.8 SYSTEM "./infoAPg/graphics/repbkcas.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.9 SYSTEM "./infoAPg/graphics/tlkitmod.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.10 SYSTEM "./infoAPg/graphics/docuhier.cgm" NDATA CGM-BINARY>

3
cde/doc/C/guides/infoAPg/Title.tmpl Normal file
View File

@@ -0,0 +1,3 @@
/* $XConsortium: Title.tmpl /main/1 1996/09/22 13:54:15 rws $ */
/* TOC title, only what's between quotes should be modified. */
title = "Information System Author's and Programmer's Guide"

99
cde/doc/C/guides/infoAPg/adbook.sgm Normal file
View File

@@ -0,0 +1,99 @@
<!-- $XConsortium: adbook.sgm /main/2 1996/09/22 15:09:44 rws $ -->
<!DOCTYPE DOCBOOK PUBLIC "-//HaL and O'Reilly//DTD DocBook V2.2.1//EN" [
<!ENTITY CDEcopyright "<GlossTerm Role=nogloss>Common Desktop Environment 1.x Internal Release</GlossTerm>
&copy; Copyright 1996 Digital Equipment Corp.
&copy; Copyright 1996 Fujitsu Limited
&copy; Copyright 1996 Hewlett-Packard Company
&copy; Copyright 1996 Hitachi, Ltd.
&copy; Copyright 1996 International Business Machines Corp.
&copy; Copyright 1996 Novell, Inc.
&copy; Copyright 1996 Sun Microsystems, Inc.">
<!ENTITY headerFix "&empty;">
<!ENTITY AbstractBullet "&bullet;">
<!ENTITY empty "">
<!ENTITY newline SDATA "[newlin]">
<!ENTITY emdash "&mdash;">
<!ENTITY bullet "&bull;">
<!ENTITY dquote "&rdquor;">
<!ENTITY sigspace "&nbsp;">
<!ENTITY vellipsis "&vellip;">
<!ENTITY tm "&trade;">
<!ENTITY a.m. "AM">
<!ENTITY cents "&cent;">
<!ENTITY date SDATA "[date]">
<!ENTITY div "&divide;">
<!ENTITY ellipsis "&hellip;">
<!ENTITY endash "&ndash;">
<!ENTITY geq "&ge;">
<!ENTITY leq "&le;">
<!ENTITY minutes "&prime;">
<!ENTITY neq "&ne;">
<!ENTITY p.m. "PM">
<!ENTITY pellipsis "....">
<!ENTITY pm "&plusmn;">
<!ENTITY seconds "&Prime;">
<!ENTITY squote "&rsquor;">
<!ENTITY sterling "&pound;">
<!ENTITY time SDATA "[time]">
<!ENTITY vblank SDATA "[vblank]">
<!ENTITY ProductName "CDE Desktop">
<!ENTITY infoapg.fig.1 SYSTEM "./graphics/infostr.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.2 SYSTEM "./graphics/docsrc.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.3 SYSTEM "./graphics/multss.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.4 SYSTEM "./graphics/bkcase.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.5 SYSTEM "./graphics/blddir.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.6 SYSTEM "./graphics/newlib.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.7 SYSTEM "./graphics/addbkcas.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.8 SYSTEM "./graphics/repbkcas.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.9 SYSTEM "./graphics/tlkitmod.cgm" NDATA CGM-BINARY>
<!ENTITY infoapg.fig.10 SYSTEM "./graphics/docuhier.cgm" NDATA CGM-BINARY>
<!ENTITY % local.notations "| XPM | XBM | XWD">
<!NOTATION xpm SYSTEM "XPM">
<!NOTATION xbm SYSTEM "XBM">
<!NOTATION xwd SYSTEM "XWD">
<!ENTITY preface SYSTEM "./preface.sgm">
<!ENTITY overview SYSTEM "./ch01.sgm">
<!ENTITY struct SYSTEM "./ch02.sgm">
<!ENTITY prebuild SYSTEM "./ch03.sgm">
<!ENTITY build SYSTEM "./ch04.sgm">
<!ENTITY admin SYSTEM "./ch05.sgm">
<!ENTITY trouble SYSTEM "./ch06.sgm">
<!ENTITY undss SYSTEM "./ch07.sgm">
<!ENTITY createss SYSTEM "./ch08.sgm">
<!ENTITY archform SYSTEM "./ch09.sgm">
<!ENTITY useform SYSTEM "./ch10.sgm">
<!ENTITY tocform SYSTEM "./ch11.sgm">
<!ENTITY glossary SYSTEM "./glossary.sgm">
]>
<docbook>
<book>
&preface;
&overview;
&struct;
&prebuild;
&build;
&admin;
&trouble;
&undss;
&createss;
&archform;
&useform;
&tocform;
&glossary;
</book>
</docbook>

77
cde/doc/C/guides/infoAPg/book.sgm Normal file
View File

@@ -0,0 +1,77 @@
<!-- $XConsortium: book.sgm /main/2 1996/09/22 13:18:45 vobadm $ -->
<!DOCTYPE Book PUBLIC "-//HaL and O'Reilly//DTD DocBook//EN" [
<!ENTITY % ISOpublishing PUBLIC "ISO 8879-1986//ENTITIES Publishing//EN">
%ISOpublishing;
<!ENTITY % ISOnumeric PUBLIC "ISO 8879-1986//ENTITIES Numeric and Special Graphic//EN">
%ISOnumeric;
<!ENTITY % ISOdiacritical PUBLIC "ISO 8879-1986//ENTITIES Diacritical Marks//EN">
%ISOdiacritical;
<!ENTITY % ISOgeneraltech PUBLIC "ISO 8879-1986//ENTITIES General Technical//EN">
%ISOgeneraltech;
<!ENTITY % ISOalatin1 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN">
%ISOalatin1;
<!ENTITY % ISOalatin2 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 2//EN">
%ISOalatin2;
<!ENTITY % ISOgreek PUBLIC "ISO 8879-1986//ENTITIES Greek Symbols//EN">
%ISOgreek;
<!ENTITY % ISOboxandline PUBLIC "ISO 8879-1986//ENTITIES Box and Line Drawing//EN">
%ISOboxandline;
<!ENTITY % BEntities SYSTEM "./infoAPg/BEntity.sgm">
%BEntities;
<!ENTITY % local.notations "| XPM | XBM | XWD">
<!NOTATION XPM SYSTEM "XPM">
<!NOTATION XBM SYSTEM "XBM">
<!NOTATION XWD SYSTEM "XWD">
<!ENTITY preface SYSTEM "./infoAPg/preface.sgm">
<!ENTITY overview SYSTEM "./infoAPg/ch01.sgm">
<!ENTITY struct SYSTEM "./infoAPg/ch02.sgm">
<!ENTITY prebuild SYSTEM "./infoAPg/ch03.sgm">
<!ENTITY build SYSTEM "./infoAPg/ch04.sgm">
<!ENTITY admin SYSTEM "./infoAPg/ch05.sgm">
<!ENTITY trouble SYSTEM "./infoAPg/ch06.sgm">
<!ENTITY undss SYSTEM "./infoAPg/ch07.sgm">
<!ENTITY createss SYSTEM "./infoAPg/ch08.sgm">
<!ENTITY archform SYSTEM "./infoAPg/ch09.sgm">
<!ENTITY useform SYSTEM "./infoAPg/ch10.sgm">
<!ENTITY tocform SYSTEM "./infoAPg/ch11.sgm">
<!ENTITY glossary SYSTEM "./infoAPg/glossary.sgm">
]>
<!-- ____________________________________________________________________________ -->
<Book>
<Title>Common Desktop Environment:
Information System Author's and Programmer's Guide</Title>
&preface;
&overview;
&struct;
&prebuild;
&build;
&admin;
&trouble;
&undss;
&createss;
&archform;
&useform;
&tocform;
&glossary;
</Book>

223
cde/doc/C/guides/infoAPg/ch01.sgm Normal file
View File

@@ -0,0 +1,223 @@
<!-- $XConsortium: ch01.sgm /main/4 1996/10/11 09:23:23 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.1">
<Title id="n0Crl2IBiWmBt8oL">About the Build Process and Tools</Title>
<IndexTerm><Primary>information libraries</Primary>
<Secondary>building</Secondary><Tertiary>process overview</Tertiary></IndexTerm>
<Para>
This section offers a brief overview of the build process you
perform to create an on-line information library. It also discusses
the software tools available in the Information Manager
for performing the build.
</Para>
<Para>
To build an on-line information library with the
Information Manager,
you must supply a set of SGML-conforming document(s) for the
books you will be building, including the appropriate document
type definitions (DTDs), book source documents, a table of
contents (TOC) for each book, the style sheet(s) that control the
on-line and printed format of the books, and a bookcase
specification that organizes the source documents.
</Para>
<Para>
The DTDs associated with your books must use the
Information Manager Architectural Forms. For information on applying these
architectural forms to your DTDs, see
<Link Linkend="nWGeMZBc9og24aK">Using Architectural
Forms</Link>.
</Para>
<Sect1>
<Title id="n4Crl2IBiWmBt8oL">Process Overview</Title>
<IndexTerm><Primary>software tools</Primary><Secondary>process overview</Secondary></IndexTerm>
<Para>
The general process for producing and administering
Information Manager browser files from SGML source is covered in these
sections:
</Para>
<ItemizedList>
<ListItem>
<Para>
<Link Linkend="sidr7JBU3pBt8oL">Preparing to Build</Link>. This section includes:
</Para>
<ItemizedList>
<ListItem>
<Para>A discussion of the files you need to successfully
validate and build a book that is browsable with the Information Manager
including:
</Para>
<ItemizedList>
<ListItem>
<Para>the SGML documents that make up a
book
</Para>
</ListItem>
<ListItem>
<Para>
a hypertext TOC for each book
</Para>
</ListItem>
<ListItem>
<Para>style sheet(s)
</Para>
</ListItem>
<ListItem>
<Para>a bookcase specification
</Para>
</ListItem>
</ItemizedList>
</ListItem>
<ListItem>
<Para>a procedure for creating a valid hypertext TOC
</Para>
</ListItem>
<ListItem>
<Para>
a description of how the Information Manager uses style
sheets and how you specify style sheets in your bookcase specification
</Para>
</ListItem>
<ListItem>
<Para>
a procedure for creating a bookcase specification
</Para>
</ListItem>
<ListItem>
<Para>
an example bookcase specification
</Para>
</ListItem>
</ItemizedList>
</ListItem>
<ListItem>
<Para>
<Link Linkend="fi1SgFBr-1698oL">Building Information Libraries</Link>.
This section explains how to:
</Para>
<ItemizedList>
<ListItem>
<Para>
<Link Linkend="KyEB2dBpuI9X3cS">validate</Link> your SGML documents
</Para>
</ListItem>
<ListItem>
<Para>
<Link Linkend="xXk7ubBtGL9X3cS">build</Link> a new information library
</Para>
</ListItem>
<ListItem>
<Para>
<Link Linkend="n7Ktl2IBUXmBt8oL">add</Link> a bookcase to an existing library
</Para>
</ListItem>
<ListItem>
<Para>
<Link Linkend="pOUExiBLxJ9X3cS">replace</Link> a bookcase in an existing library
</Para>
</ListItem>
<ListItem>
<Para>
<Link Linkend="WmNvZbBE6K9X3cS">update</Link> style sheets in built bookcases
</Para>
</ListItem>
</ItemizedList>
</ListItem>
<ListItem>
<Para>
<Link Linkend="B7XKbKBcgmg24aK">Administering Bookcases</Link>.
This section describes how to copy, remove, list, rename, or rearrange
bookcases in an information library.</Para>
</ListItem>
</ItemizedList>
</Sect1>
<Sect1>
<Title id="n3Crl2IBiWmBt8oL">Tools Overview</Title>
<IndexTerm><Primary>information libraries</Primary>
<Secondary>building</Secondary><Tertiary>tools overview</Tertiary></IndexTerm>
<IndexTerm><Primary>software tools</Primary><Secondary>overview</Secondary></IndexTerm>
<Para>
To build a library using the Information Manager, you:
</Para>
<ItemizedList>
<ListItem>
<Para>
Create a hypertext table of contents for each book based
on the <filename>dtinfoTOC.dtd(5)</filename>.
</Para>
<Para>See
<Link Linkend="n8aJ92dBIsI9X3cS">Creating a Table of Contents</Link>.
</Para>
</ListItem>
<ListItem>
<Para>
Supply or create valid Information Manager style sheet(s), based on the
<filename>dtinfoStyle.dtd(5)</filename> for the SGML documents that will be built.
</Para>
<Para>See
<Link Linkend="tgmdnkb6vm9x3cs">Understanding Information Manager Style Sheets</Link>.</Para>
</ListItem>
<ListItem>
<Para>
Create a bookcase specification based on the <filename>dtinfoBook.dtd(5)</filename>.
</Para>
<Para>
See
<Link Linkend="TcQg4bBSxI9X3cS">Creating a Bookcase Specification</Link>.
</Para>
</ListItem>
<ListItem>
<Para>
Build browser-readable information libraries using the
<Command>dtinfogen build</Command> command.
</Para>
<Para>
See
<Link Linkend="fi1SgFBr-1698oL">Building Information Libraries</Link>.
</Para>
</ListItem>
</ItemizedList>
<Para>
On Information Manager libraries that are already built, you can:
</Para>
<ItemizedList>
<ListItem>
<Para>
Replace existing style sheets or style sheet information
in the document database, without rebuilding the
database, using the <Command>dtinfogen update</Command> command.
</Para>
<Para>
See
<Link Linkend="WmNvZbBE6K9X3cS">Updating Style Sheets in Built Bookcases</Link>.
</Para>
</ListItem>
<ListItem>
<Para>
Add or replace a bookcase in the library using the
<Command>dtinfogen build</Command> command.
</Para>
<Para>
See
<Link Linkend="n7Ktl2IBUXmBt8oL">Adding a Bookcase to an Existing Library</Link> and
<Link Linkend="pOUExiBLxJ9X3cS">Replacing a Bookcase in an Existing Library</Link>.
</Para>
</ListItem>
<ListItem>
<Para>
Copy, remove, rename, list, or rearrange bookcases in a
library using the <Command>dtinfogen admin</Command> command.
</Para>
<Para>See
<Link Linkend="B7XKbKBcgmg24aK">Administering Bookcases</Link>.
</Para>
</ListItem>
</ItemizedList>
</Sect1>
</Chapter>

242
cde/doc/C/guides/infoAPg/ch02.sgm Normal file
View File

@@ -0,0 +1,242 @@
<!-- $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>

1126
cde/doc/C/guides/infoAPg/ch03.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

777
cde/doc/C/guides/infoAPg/ch04.sgm Normal file
View File

@@ -0,0 +1,777 @@
<!-- $XConsortium: ch04.sgm /main/4 1996/10/11 09:23:48 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.4">
<title id="fi1SgFBr-1698oL">Building Information Libraries</title>
<indexterm><primary>information libraries</primary>
<secondary>building</secondary></indexterm>
<para>
This chapter discusses how to use <command>dtinfogen</command>
subcommands to validate and
build your SGML documents into an Information Manager-browsable
library and how to update style sheet information in a bookcase.
</para>
<para>
You use the <command>dtinfogen validate</command> command to
validate your SGML book documents and your bookcase specification.
Validation is useful during preparation for the build.
<indexterm><primary>Information Manager</primary>
<secondary>commands</secondary>
<tertiary>dtinfogen validate</tertiary></indexterm>
</para>
<para>
You use the <command>dtinfogen build</command> command,
which also performs SGML validation, to build a new information library,
add a bookcase to an existing information library, and update an
existing library.
<indexterm><primary>Information Manager</primary>
<secondary>commands</secondary>
<tertiary>dtinfogen build</tertiary></indexterm>
</para>
<para>
Once you have built an information library, you can use
the <command>dtinfogen update</command> command to update the
style sheet information associated with the library.
These procedures are covered in:
<indexterm><primary>Information Manager</primary>
<secondary>commands</secondary>
<tertiary>dtinfogen update</tertiary></indexterm>
</para>
<itemizedlist>
<listitem>
<para>
<link linkend="KyEB2dBpuI9X3cS">Validating Your SGML Documents</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="ki1SgFBr-1698oL">Building, Adding, and Replacing Bookcases
in a Library</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="WmNvZbBE6K9X3cS">Updating Style Sheets in Built Bookcases
</link>
</para>
</listitem>
</itemizedlist>
<para>
See the <command>dtinfogen(1)</command> man page for command
syntax and additional examples of these commands.
</para>
<sect1>
<title id="WxGm7JBlsoBt8oL">Before You Build a New Library</title>
<indexterm><primary>information libraries</primary>
<secondary>building</secondary><tertiary>prerequisites</tertiary></indexterm>
<para>
Before you build a new Information Manager information library you need to:
</para>
<itemizedlist>
<listitem>
<para>
Specify the method to be used to map external entity references
to your system files. You can either:
</para>
<itemizedlist>
<listitem>
<para>
Set the appropriate environment variables for handling external
entity references, or
</para>
</listitem>
<listitem>
<para>
Specify the appropriate catalog file using the <option>-m</option>
option with the <command>dtinfogen build</command> command.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Check to make sure that you have all of the required
SGML-conforming documents, including DTD(s), hypertext TOCs,
and style sheet(s) for every book in the bookcase.
You can validate your SGML documents using the
<command>dtinfogen validate</command> command
as described in <link linkend="ByGm7JBlsoBt8oL">
Running dtinfogen validate</link>.
</para>
</listitem>
<listitem>
<para>
Understand the options that <command>dtinfogen build</command> provides,
as described in <link linkend="ki1SgFBr-1698oL">Building,
Adding, and Replacing Bookcases in a Library</link>.
</para>
</listitem>
</itemizedlist>
</sect1>
<!--((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<title id="n9yEB2dBpuI9X3cS">Setting Environment Variables</title>
<indexterm><primary>environment variables</primary></indexterm>
<para>
Depending on whether you are using the
<citetitle>SGML Open Technical Resolution 9401:1994</citetitle>
recommendation for resolving external entity references,
you need to set one or both of the following environment variables,
or use the <option>-m</option> option with the
<command>dtinfogen</command> command:</para>
<variablelist>
<varlistentry>
<term><systemitem class="environvar">SGML_CATALOG_FILES</systemitem></term>
<listitem>
<para>
Set this environment variable if you follow the
<citetitle>SGML Open Technical Resolution 9401:1994</citetitle>
recommendation related to external entity management.
The value of this environment variable specifies the
location of the file <filename>catalog</filename> or
<filename>CATALOG</filename> (you can use either upper-case
or lower-case letters) that lists SGML entity declarations and
file mapping identifiers.
</para>
<para>
If you don't set this environment variable,
you can use the <option>-m</option> option with the
appropriate <command>dtinfogen</command> command to map public
identifiers and entity names to system files.
See the <filename>catalog(5)</filename> man page for more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><systemitem class="environvar">SGML_PATH</systemitem></term>
<listitem>
<para>
Set this environment variable to map external entity references
to system files.</para>
<para>See the <command>dtinfogen(5)</command> man page
for more information.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>For related information, see:
</para>
<itemizedlist>
<listitem>
<para>
<citetitle>SGML Open Technical Resolution 9401:1994</citetitle>
</para>
</listitem>
</itemizedlist>
</sect1>
<!--((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<title id="KyEB2dBpuI9X3cS">Validating Your SGML Documents</title>
<indexterm><primary>SGML documents</primary>
<secondary>validating</secondary></indexterm>
<para>
Before building an information library, you should validate your
SGML documents to ensure that they conform to the appropriate DTD.
</para>
<para>You can use the <command>dtinfogen validate</command>
<indexterm><primary>Information Manager</primary>
<secondary>commands</secondary>
<tertiary>dtinfogen validate</tertiary></indexterm>
command to perform SGML validation on bookcase specifications,
on individual documents, or any other SGML conforming document.
During the validation process <command>dtinfogen validate</command>:
</para>
<itemizedlist>
<listitem>
<para>
Checks the input document's DTD to verify that it conforms to SGML.
</para>
</listitem>
<listitem>
<para>Verifies that the SGML markup in the input document is
consistent with the markup language defined in the document's DTD.
</para>
</listitem>
</itemizedlist>
<para>
If any documents are found to be invalid, error messages are
issued by the <command>dtinfogen validate</command> program.
All errors in files used to build an information library must
be corrected before the data can be built.
</para>
<sect2>
<title id="ByGm7JBlsoBt8oL">Running dtinfogen validate</title>
<indexterm><primary>information libraries</primary>
<secondary>document validation</secondary></indexterm>
<para>
The basic command line for the following example, which performs
validation on a single-bookcase information library, is:
</para>
<programlisting>
<userinput>dtinfogen validate ch03.sgm ch04.sgm ch05.sgm</userinput>
</programlisting>
<para>where</para>
<para>
<filename>ch03.sgm ch04.sgm ch05.sgm</filename>
</para>
<para>
specifies the SGML documents that are to be validated.
The <command>dtinfogen validate</command> command can be run
against any valid SGML conforming document.
</para>
<para>
Error messages are returned if a document is invalid.
Here is an example of the type of errors returned against an
example file <filename>ch05.sgm</filename>,
which contains missing or invalid entity declarations.
</para>
<programlisting>
%: <userinput>dtinfogen validate</userinput>
nsgmls:ch05.sgm:12:1:E: cannot open "hal.gml" (No such file or directory)
nsgmls:ch05.sgm:20:1:E: general entity "tab" not defined and no default entity
..............................
..............................
..............................
dtinfogen: command failed: nsgmls -sg /usr/dt/infolib/C/SGML/dtinfo.decl ch05.sgm
ch05.sgm
</programlisting>
</sect2>
</sect1>
<!--((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<title id="ki1SgFBr-1698oL">Building, Adding, and Replacing Bookcases in a Library</title>
<indexterm><primary>information libraries</primary>
<secondary>building</secondary>
<tertiary>with dtinfogen build</tertiary>
</indexterm>
<para>
This section describes how you use the
<command>dtinfogen build</command> command to build a bookcase
into a new information library, add a bookcase to an existing
information library, and update the information database in an
existing library.
<indexterm><primary>Information Manager</primary>
<secondary>commands</secondary><tertiary>dtinfogen build</tertiary>
</indexterm>
</para>
<sect2>
<title id="jI.RgFBe.1698oL">Build Considerations</title>
<indexterm><primary>information libraries</primary>
<secondary>build considerations</secondary></indexterm>
<para>
You can build information libraries of all sizes,
containing any number of books and bookcases.
You can have (but are not limited to) information libraries containing:
</para>
<itemizedlist>
<listitem>
<para>A single bookcase consisting of one or more books
</para>
</listitem>
<listitem>
<para>
Multiple bookcases, each consisting of one or more books.
</para>
</listitem>
</itemizedlist>
<para>
When designing an information library, you should give thought
to its presentation in the Information Manager and to its reception
by readers, many of whom may not be experienced users of on-line
documentation.
</para>
<para>
Information structure and information search capability
are among the most important factors in the design of an
on-line information library. Readers must be able to easily
discern the structure of a book or set of books in a bookcase.
In addition, they must be able to find the information they want quickly,
through the use of clear hypertext links and through efficient search
mechanisms.
</para>
<sect3>
<title id="SKUExiBLxJ9X3cS">Library Configuration</title>
<para>The Information Manager has very powerful search capabilities.
However, the configuration of your on-line information library affects
the efficiency of the search process.
</para>
<para>
In general, the fewer bookcases you have in an information library,
and the fewer books contained in each bookcase,
the faster the build process will proceed. This type of information
library structure can also be quickly and easily updated.
</para>
<para>
Unfortunately, as the number of bookcases grows,
this type of library structure becomes inefficient in terms
of the browser's ability to search its contents for information.
</para>
<para>
On the other hand, an information library that contains a
smaller number of bookcases, each of which contains a relatively
large number of books, will take much longer to build and to
subsequently update. But search times for this type of library
structure will be significantly shorter.
</para>
</sect3>
<sect3>
<title id="aKUExiBLxJ9X3cS">Build Space</title>
<para>
Before you build an information library, you must ensure that
sufficient space is available in the appropriate locations for
the build process to succeed.</para>
<para>Upon build completion, an information library takes up
about the same amount of space as the source from which it was built.
However, during the build process itself, up to three times
as much additional space will be required for temporary file storage.
This additional space must be allocated as temporary build space,
which is automatically removed upon completion of the build.
The default location for temporary build space is
<filename>/usr/tmp</filename>.
</para>
<para>
If you find that the disk space available in
<filename>/usr/tmp</filename> is less than three times the size of the
original document source, you should use the <option>-T</option> option
with the <command>dtinfogen build</command> command to specify a
different location for the temporary build files, or set the <systemitem
class="environvar">TMPDIR</systemitem> environment variable.
</para>
<caution>
<para>
The current version of the Information Manager has no concurrent-use
locking mechanisms to prevent users from attempting to simultaneously
build or modify the same information library. Take precautions to ensure
that no other <command>dtinfogen</command> or Information Manager
processes are accessing the information library when you run the
<command>dtinfogen build</command> command. Concurrent use of the
<command>dtinfogen</command> commands may cause an Information Manager
failure.
</para>
</caution>
</sect3>
</sect2>
</sect1>
<!--((((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<title id="n4Ofh7JBpooBt8oL">Information Library Organization</title>
<para>
When you build an information library, your browser-readable
files are organized in the structure depicted in the figure
<link linkend="n9Ofh7JBpooBt8oL">Build Directory Structure</link>.
</para>
<figure>
<title id="n9Ofh7JBpooBt8oL">Build Directory Structure</title>
<graphic id="gr58" entityref="infoapg.fig.5"></graphic>
</figure>
<sect2>
<title id="zOfh7JBpooBt8oL">Build Directory Structure</title>
<indexterm><primary>Information Manager build directories</primary>
<secondary>directory structure</secondary></indexterm>
<para>
The build directory structure shows:
</para>
<variablelist>
<varlistentry>
<term><replaceable>BC</replaceable><filename>.dbd</filename></term>
<listitem>
<para>
This file is the document database for the bookcase
<replaceable>BC</replaceable>. It contains all compiled text,
graphics, and table data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>BC</replaceable><filename>.dbi</filename></term>
<listitem>
<para>
This file contains the index data for bookcase
<replaceable>BC</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>BC</replaceable><filename>.sch</filename></term>
<listitem>
<para>
This file describes the structure of the database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>dtsearch</filename> directory</term>
<listitem>
<para>
This directory contains all the files related to the full-text search engine.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>bookcase.map</filename></term>
<listitem>
<para>
This file organizes the bookcases within the library.
You use the <command>dtinfogen admin</command> command to modify this file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>LIB</replaceable><filename>.oli</filename></term>
<listitem>
<para>
The string used for <replaceable>LIB</replaceable> gives the library its file name.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<!--(((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<title id="xXk7ubBtGL9X3cS">Building a New Library</title>
<para>
Here is an example of the basic <command>dtinfogen build</command>
command line for building a new information library:
</para>
<programlisting>
dtinfogen build <option>-T</option> <replaceable>/k1/local/daver/</replaceable> <option>-l</option> <replaceable>InfoLib1 DCE.bc INFOMGR.bc PROG.bc</replaceable>
</programlisting>
<para>
where
</para>
<variablelist>
<varlistentry>
<term><option>-T</option> <replaceable>/k1/local/daver</replaceable></term>
<listitem>
<para>
Specifies the directory in which temporary files generated
during the build process will be placed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option> <replaceable>InfoLib1</replaceable></term>
<listitem>
<para>
Specifies the name of the directory containing the information library.
After the build, <filename>InfoLib1</filename>
will contain the three bookcases specified in the command line
arguments that follow.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>DCE.bc INFOMGR.bc PROG.bc</replaceable></term>
<listitem>
<para>
Specify the file names of your bookcase specification files.
Each bookcase specification contains the names of one or
more books to be built. You can include as many bookcase
specification file names on the command line as you wish.
</para>
</listitem>
</varlistentry>
</variablelist>
<para><command>dtinfogen build</command> converts the documents
specified in each of the bookcase specifications into browser-readable
format and places them in the newly created information
library directory <filename>InfoLib1</filename>.
</para>
<para>
Assuming the names of the three bookcases
(as specified by each bookcase's BOOKCASENAME element) are
<systemitem>DCE</systemitem>, <systemitem>INFOMGR</systemitem>,
and <systemitem>PROG</systemitem>, respectively,
the <filename>InfoLib1</filename> directory now contains the
bookcase directories <filename>DCE</filename>, <filename>INFOMGR</filename>,
and <filename>PROG</filename>. Each bookcase, in turn, contains
the document databases (books) specified by its BOOK element(s).
</para>
<para>
The figure <link linkend="wKUExiBLxJ9X3cS">Creating a New Library</link>
depicts the newly built <filename>InfoLib1</filename> library.
</para>
<figure>
<title id="wKUExiBLxJ9X3cS">Creating a New Library</title>
<graphic id="gr59" entityref="infoapg.fig.6"></graphic>
</figure>
</sect1>
<!--((((((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<title id="n7Ktl2IBUXmBt8oL">Adding a Bookcase to an Existing Library</title>
<indexterm><primary>bookcases</primary>
<secondary>adding</secondary>
<tertiary>with dtinfogen build</tertiary></indexterm>
<para>
In addition to creating a new Information Manager information
library, you can also use <command>dtinfogen build</command> to add
a bookcase that has not yet been built to an existing information library.
In the example below, assume the argument
<option>-l</option>&nbsp;<replaceable>InfoLib1</replaceable>
is the name of an existing information library rather than the name
of a new information library.
</para>
<programlisting>
dtinfogen build <option>-l</option> <replaceable>InfoLib1 ORA.bc</replaceable></programlisting>
<para>
where
</para>
<variablelist>
<varlistentry>
<term><option>-l</option> <replaceable>InfoLib1</replaceable></term>
<listitem>
<para>
is the name of the directory that contains the existing information library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>ORA.bc</replaceable></term>
<listitem>
<para>
is the file name of the bookcase specification file whose contents
you are adding to the <filename>InfoLib1</filename> information library.
You can include as many bookcase specification names on the command line
as you wish.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<command>dtinfogen build</command>
converts the book documents in the bookcase specification file
<filename>ORA.bc</filename> into browser-readable format and adds
them to the existing information library directory
<filename>InfoLib1</filename>.</para>
<para>Assuming the name of the added bookcase (as specified
by its BOOKCASENAME element) is <systemitem>ORA</systemitem>,
the <filename>InfoLib1</filename> directory now contains the bookcase
directories <systemitem>DCE</systemitem>,
<systemitem>INFOMGR</systemitem>, <systemitem>PROG</systemitem>,
and <systemitem>ORA</systemitem>.
</para>
<para>
The figure <link linkend="bMUExiBLxJ9X3cS">Adding a Bookcase to an Existing
Library</link> depicts the revised <filename>InfoLib1</filename>
library.
</para>
<note>
<para>
Added bookcases are appended to the existing list of bookcases
in the Information Manager Book List. The <command>dtinfogen admin</command>
command can be used to rearrange the list after it is built.
See the <command>dtinfogen(1)</command> man page.</para>
</note>
<figure>
<title id="bMUExiBLxJ9X3cS">Adding a Bookcase to an Existing Library</title>
<graphic id="gr60" entityref="infoapg.fig.7"></graphic>
</figure>
</sect1>
<!--))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect1>
<title id="pOUExiBLxJ9X3cS">Replacing a Bookcase in an Existing Library</title>
<indexterm><primary>bookcases</primary>
<secondary>replacing</secondary><tertiary>with dtinfogen build</tertiary>
</indexterm>
<para>
In addition to creating information libraries and adding bookcases
to existing libraries, you can also replace specified bookcases
in a library with the <command>dtinfogen build</command> command.
In the example below, the <command>dtinfogen build</command> process
is used to rebuild the bookcases <systemitem>INFOMGR</systemitem> and
<systemitem>PROG</systemitem> and to overwrite the existing bookcases
of the same name in the <filename>InfoLib1</filename> information library.
</para>
<programlisting>
dtinfogen build <option>-l</option> <replaceable>InfoLib1 INFOMGR.bc PROG.bc</replaceable></programlisting>
<para>
where
</para>
<variablelist>
<varlistentry>
<term><option>-l</option> <replaceable>InfoLib1</replaceable></term>
<listitem>
<para>
is the name of the directory that contains the existing information library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>INFOMGR.bc PROG.bc</replaceable></term>
<listitem>
<para>
are the file names of the bookcase specification files whose
contents you are rebuilding in order to update the information
library <filename>InfoLib1</filename>. You can include as
many bookcase specification file names on the command line as you wish.
</para>
</listitem>
</varlistentry>
</variablelist>
<para><command>dtinfogen build</command> rebuilds the books in the
bookcase specification files <filename>INFOMGR.bc</filename> and
<filename>PROG.bc</filename> and places them in the existing
information library directory <filename>InfoLib1</filename>.
</para>
<para>
The newly built bookcases, whose bookcase names are
<systemitem>INFOMGR</systemitem> and <systemitem>PROG</systemitem>
(as specified in the their respective BOOKCASENAME elements),
overwrite the existing bookcases that have the same names.
</para>
<para>
The figure <link linkend="n1PUExiBLxJ9X3cS">Replacing
Bookcases in an Existing Library</link> depicts the revised
<filename>InfoLib1</filename> library.
</para>
<figure>
<title id="n1PUExiBLxJ9X3cS">Replacing Bookcases in an Existing Library</title>
<graphic id="gr61" entityref="infoapg.fig.8"></graphic>
</figure>
</sect1>
<!--((((((((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<title id="WmNvZbBE6K9X3cS">Updating Style Sheets in Built Bookcases</title>
<indexterm><primary>style sheet</primary>
<secondary>updating</secondary></indexterm>
<indexterm><primary>Information Manager</primary>
<secondary>commands</secondary><tertiary>dtinfogen update</tertiary></indexterm>
<para>
In Information Manager, you can change the formatting instructions
for existing bookcases without rebuilding those databases.
This capability gives you great flexibility in the way you handle
books whose formatting characteristics must change to meet differing
audience or industry requirements.
</para>
<para>
You use the <command>dtinfogen update</command> command to reformat
the books in existing information libraries by updating the style
sheet information that controls their formatting.
</para>
<para>
With <command>dtinfogen update</command> you can revise a style sheet
and quickly see the results of your changes, or you can replace one
style sheet with another and quickly reformat associated documents.</para>
<para>When you run <command>dtinfogen update</command>, only the
documents or document sections affected by the style sheet changes
are reformatted.
</para>
<para>
Before you run <command>dtinfogen update</command> to reformat documents
in an information library:
</para>
<itemizedlist>
<listitem>
<para>
Ensure that any changes you have made to the style sheet are valid.
The <command>dtinfogen update</command> command validates the style
sheet file during the update process.
</para>
</listitem>
<listitem>
<para>
Set the appropriate environment variables for handling
external entity references or specify the appropriate catalog file
using the <option>-m</option> option when you run
<command>dtinfogen update</command>.</para>
</listitem>
</itemizedlist>
<caution>
<para>Do not run the Information Manager or execute an
<command>dtinfogen admin</command> process while updating a style sheet.
</para>
</caution>
<sect2>
<title id="CDdVddBydG9X3cS">Running dtinfogen update</title>
<para>
The basic command line for the following example,
which reformats the documents and/or document sections
that use the specified style sheet, is:
</para>
<programlisting>
dtinfogen update <option>-l</option> <replaceable>InfoLib1</replaceable> <option>-b</option> <replaceable>INFOMGR style1.sty</replaceable></programlisting>
<para>
where
</para>
<variablelist>
<varlistentry>
<term><option>-l</option> <replaceable>InfoLib1</replaceable></term>
<listitem>
<para>
Is the name of the directory that contains the existing information library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option> <replaceable>INFOMGR</replaceable></term>
<listitem>
<para>
Is the name of the bookcase (as specified in the its BOOKCASENAME element)
that includes the sections that will be reformatted by the
specified style sheet.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>style1.sty</replaceable></term>
<listitem>
<para>
Is the file name of the style sheet that will be applied
during the <command>dtinfogen update</command> process.
The style sheet you use must conform to
<filename>StyleSheet.dtd</filename> as discussed
in <link linkend="tgmdnkb6vm9x3cs">Understanding
Information Manager Style Sheets</link>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
After running <command>dtinfogen update</command> process you can
open the information library using the Information Manager Book List
window to see the effect of your changes.
</para>
<para>
For related information, see:
</para>
<itemizedlist>
<listitem>
<para>the <command>dtinfogen(1)</command> man page</para>
</listitem>
<listitem>
<para><link linkend="TcQg4bBSxI9X3cS">Creating a Bookcase Specification</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="j3fa6XBbiK9X3cS">Using Style Sheets</link></para>
</listitem>
<listitem>
<para>
<link linkend="tgmdnkb6vm9x3cs">Understanding Information Manager
Style Sheets</link></para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>

579
cde/doc/C/guides/infoAPg/ch05.sgm Normal file
View File

@@ -0,0 +1,579 @@
<!-- $XConsortium: ch05.sgm /main/4 1996/10/11 09:23:56 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.5">
<Title id="B7XKbKBcgmg24aK">Administering Bookcases</title>
<IndexTerm><Primary>information libraries</Primary>
<Secondary>bookcase administration</Secondary></IndexTerm>
<Para>
After building bookcases into an information library, you can
perform several administrative functions on the bookcases that
make up the library without having to rebuild them. Specifically,
you can:
</Para>
<ItemizedList>
<ListItem>
<Para><Link Linkend="K7XKbKBcgmg24aK">Copy bookcases from another library</Link></Para>
</ListItem>
<ListItem>
<Para><Link Linkend="B8XKbKBcgmg24aK">Remove bookcases from a library</Link></Para>
</ListItem>
<ListItem>
<Para><Link Linkend="M8XKbKBcgmg24aK">List the bookcases in a library</Link></Para>
</ListItem>
<ListItem>
<Para><Link Linkend="n0cWdbKB-zmg24aK">Rename bookcases in a library</Link></Para>
</ListItem>
<ListItem>
<Para><Link Linkend="vbWdbKB-zmg24aK">Rearrange bookcases in a library</Link></Para>
</ListItem>
</ItemizedList>
<Para>
See also
<Link Linkend="n7Ktl2IBUXmBt8oL">Adding a Bookcase to an Existing Library</Link>.
</Para>
<!--(((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<Title id="n01cq1dBePI9X3cS">Running dtinfogen admin</Title>
<IndexTerm><Primary>Information Manager Toolkit</Primary><Secondary>commands</Secondary>
<Tertiary>dtinfogen admin</Tertiary></IndexTerm>
<Para>
<command>dtinfogen admin</command>
is an interactive program that displays a menu
from which you select the administrative operation you want to
perform. To run the <Command>dtinfogen admin</Command> command,
on the command line type:
</Para>
<ProgramListing>
<UserInput>dtinfogen admin</UserInput>
</ProgramListing>
<Para>
When you press enter, the following menu appears.</Para>
<LiteralLayout>
1) Copy a bookcase from another library
2) Remove a bookcase
3) List bookcases in a library
4) Rename a bookcase
5) Rearrange bookcases in a library
6) Exit
Please enter your choice [1-6]
</LiteralLayout>
</sect1>
<!--((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<Title id="K7XKbKBcgmg24aK">Copying Bookcases from Another Library</Title>
<IndexTerm><Primary>information libraries</Primary><Secondary>copying bookcases between</Secondary></IndexTerm>
<IndexTerm><Primary>bookcases</Primary><Secondary>copying from another library</Secondary></IndexTerm>
<Para>
When you copy a bookcase from another library,
<command>dtinfogen admin</command>
validates the bookcase you are copying against the bookcases in
the destination library. This ensures that no section IDs are
duplicated within the library, and that the database versions are
compatible with each other.
</Para>
<Para>
If the bookcase you want to copy already exists in the destination
library, <Command>dtinfogen admin</Command> asks whether you wish to replace the
bookcase.
</Para>
<Para>
To copy a bookcase from another library:
</Para>
<OrderedList>
<ListItem>
<Para>At a command line, enter <UserInput>dtinfogen admin</UserInput>.
</Para>
<Para>
The following menu appears:
</Para>
<LiteralLayout>
1) Copy a bookcase from another library
2) Remove a bookcase
3) List bookcases in a library
4) Rename a bookcase
5) Rearrange bookcases in a library
6) Exit
Please enter your choice [1-6]
</LiteralLayout>
</ListItem>
<ListItem>
<Para>On the command line, enter <UserInput>1</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays:
</Para>
<LiteralLayout>
Enter the path for the library from which you want to copy a bookcase.
This can be a relative or absolute path.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
Enter the path to the information library from which you
want to copy a bookcase. For example: <UserInput>/lit/wolfe</UserInput>
</Para>
<Para>
<command>dtinfogen admin</command> displays the bookcases available in the
library you specified. For example:
</Para>
<LiteralLayout>
The bookcases available in /lit/wolfe are:
1) Life [Life Works]
2) Essays [Essays from Life]
3) Poems [Collections of Poems]
Enter the number associated with the bookcase you want to copy.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
At the prompt, enter the number corresponding to the
bookcase you want to copy. <command>dtinfogen admin</command> displays:
</Para>
<LiteralLayout>
You specified <Replaceable>[Life]</Replaceable>. Do you really want to copy this bookcase?
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
To copy the bookcase you specified, enter
<UserInput>Y</UserInput> (you can use
an uppercase or lowercase character).
</Para>
</ListItem>
<ListItem>
<Para>
Enter the path to the information library to which you
want to copy the bookcase. For example:
<UserInput>/lit/destiny</UserInput>
</Para>
<Para>
<command>dtinfogen admin</command> displays the bookcases available in the
library you specified:
</Para>
<LiteralLayout>
The bookcases available in /lit/destiny are:
1) Child [School Days]
2) Reports [Reports from School]
Bookcases appear in the browser Book List in the order listed here.
Enter the number corresponding to the position you want bookcase to occupy [1-2].
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
Enter the number corresponding to the position you want
the bookcase to occupy.
</Para>
<Para>
If another bookcase already occupies the position you
choose, the bookcase you are copying takes its place, and
the original bookcase moves down one place in the list.
</Para>
<Para>
<command>dtinfogen admin</command> displays the new order of the bookcases in
the library. For example:
</Para>
<LiteralLayout>
You specified this order for the bookcases:
1) Child [School Days]
2) Reports [Reports from School]
3) Life [Life Works]
Is this correct? [ynq]
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
To copy the bookcase into this position, enter
<UserInput>Y</UserInput>. <command>dtinfogen admin</command> saves the addition to the library and returns
to the main menu.
</Para>
</ListItem>
</OrderedList>
</sect1>
<!--))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect1>
<Title id="B8XKbKBcgmg24aK">Removing Bookcases from a Library</Title>
<IndexTerm><Primary>information libraries</Primary><Secondary>removing bookcases from</Secondary></IndexTerm>
<IndexTerm><Primary>bookcases</Primary><Secondary>removing from a library</Secondary></IndexTerm>
<Para>
The procedure for removing a bookcase with <command>dtinfogen
admin</command> is similar to the procedure for copying a bookcase into
a library. When you remove a bookcase from a library, its database is
deleted from the information library.
</Para>
<Para>
When you specify the library to work with, <Command>dtinfogen
admin</Command> lists the bookcases found in that library. You simply
specify the bookcase to remove. If the information you supply is valid,
<Command>dtinfogen admin</Command> prompts you for confirmation before
removing the bookcase you specified.
</Para>
<Para>
To remove a bookcase from a library:
</Para>
<OrderedList>
<ListItem>
<Para>
At a command line, enter <UserInput>dtinfogen admin</UserInput>.
</Para>
<Para>
The following menu appears.
</Para>
<LiteralLayout>
1) Copy a bookcase from another library
2) Remove a bookcase
3) List bookcases in a library
4) Rename a bookcase
5) Rearrange bookcases in a library
6) Exit
Please enter your choice [1-6]
</LiteralLayout>
</ListItem>
<ListItem>
<Para>To remove a bookcase, enter <UserInput>2</UserInput>.
</Para>
<Para>
<Command>dtinfogen admin</Command> displays:
</Para>
<LiteralLayout>
Enter the path for the library from which you want to remove a bookcase.
This can be a relative or absolute path.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
Enter the path to the information library from which you
want to remove the bookcase. For example: <UserInput>/lit/wolfe</UserInput>.
</Para>
<Para>
<Command>dtinfogen admin</Command> displays the bookcases available in the
library you specified:
</Para>
<LiteralLayout>
The bookcases available in /lit/wolfe are:
1) Life [Life Works]
2) Essays [Essays from Life]
3) Poems [Collections of Poems]
Enter the number corresponding to the bookcase to remove.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
At the prompt, enter the number corresponding to the
bookcase you want to remove.
<Command>dtinfogen admin</Command> displays:
</Para>
<LiteralLayout>
You specified <Replaceable>[Essays]</Replaceable>. Do you really want to remove this bookcase?
</LiteralLayout>
</ListItem>
<ListItem>
<Para>To remove the bookcase you specified, enter <UserInput>Y</UserInput>.
<Command>dtinfogen admin</Command> removes the bookcase and returns to the
main menu.
</Para>
</ListItem>
</OrderedList>
</sect1>
<!--((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect1>
<Title id="M8XKbKBcgmg24aK">Listing the Bookcases in a Library</Title>
<IndexTerm><Primary>information libraries</Primary><Secondary>listing bookcases in</Secondary></IndexTerm>
<IndexTerm><Primary>bookcases</Primary><Secondary>listing for a library</Secondary></IndexTerm>
<Para>
In trying to identify the library to work with, you may want to
list the bookcases in a library.
</Para>
<Para>
To list bookcases in a library:
</Para>
<OrderedList>
<ListItem>
<Para>At a command line, enter
<UserInput>dtinfogen admin</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays:</Para>
<LiteralLayout>
1) Copy a bookcase from another library
2) Remove a bookcase
3) List bookcases in a library
4) Rename a bookcase
5) Rearrange bookcases in a library
6) Exit
Please enter your choice [1-6]
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
To list a bookcase, enter <UserInput>3</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays:</Para>
<LiteralLayout>
Enter the path for the library for which you want to list bookcases.
This can be a relative or absolute path.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
Enter the path to the information library for which you
want to list bookcases. For example: <UserInput>/lit/wolfe</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays the bookcases available in the
library you specified. For example:
</Para>
<LiteralLayout>
The bookcases available in /lit/wolfe are:
1) Life [Life Works]
2) Essays [Essays from Life]
3) Poems [Collections of Poems]
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
After listing the bookcases in the information library, <command>dtinfogen admin</command>
returns you to the main menu.
</Para>
</ListItem>
</OrderedList>
</sect1>
<!--)))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect1>
<Title id="n0cWdbKB-zmg24aK">Renaming Bookcases in a Library</Title>
<IndexTerm><Primary>information libraries</Primary><Secondary>renaming bookcases in</Secondary></IndexTerm>
<IndexTerm><Primary>bookcases</Primary><Secondary>renaming in a library</Secondary></IndexTerm>
<Para>
You can change the bookcase names that the browser displays in
the Information Manager Book List. To rename a bookcase:
</Para>
<OrderedList>
<ListItem>
<Para>
At a command line, enter <UserInput>dtinfogen admin</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays:
</Para>
<LiteralLayout>
1) Copy a bookcase from another library
2) Remove a bookcase
3) List bookcases in a library
4) Rename a bookcase
5) Rearrange bookcases in a library
6) Exit
Please enter your choice [1-6]
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
To rename a bookcase, enter <UserInput>4</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays:
</Para>
<LiteralLayout>
Enter the path for the library containing the bookcase you want to rename.
This can be a relative or absolute path.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
Enter the path to the information library you want to
rename. For example: <UserInput>/lit/wolfe</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays the bookcases available in the
library you specified:
</Para>
<LiteralLayout>
The bookcases available in /lit/wolfe are:
1) Life [Life Works]
2) Essays [Essays from Life]
3) Poems [Collections of Poems]
Enter the number corresponding to the bookcase you want to rename.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
At the prompt, enter the number corresponding to the
bookcase you want to rename. <command>dtinfogen admin</command> displays:
</Para>
<LiteralLayout>
You specified <Replaceable>[Poems]</Replaceable>. Do you really want to rename the bookcase?
</LiteralLayout>
</ListItem>
<ListItem>
<Para>To rename the bookcase you specified, enter <UserInput>Y</UserInput>.
<command>dtinfogen admin</command> asks you to enter the new title for the
bookcase:
</Para>
<LiteralLayout>
Enter the new title for <Replaceable>[Poems]</Replaceable>.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
Enter the new title for the bookcase.
<command>dtinfogen admin</command> displays the new title:
</Para>
<LiteralLayout>You entered <Replaceable>[Old Poems]</Replaceable>. Is this title correct?
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
To accept the new title, enter <UserInput>Y</UserInput>.
<command>dtinfogen admin</command> saves the
new title and returns to the main menu.
</Para>
</ListItem>
</OrderedList>
</sect1>
<!--)))))))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect1>
<Title id="vbWdbKB-zmg24aK">Rearranging Bookcases in a Library</Title>
<IndexTerm><Primary>information libraries</Primary><Secondary>rearranging bookcases in</Secondary></IndexTerm>
<IndexTerm><Primary>bookcases</Primary><Secondary>rearranging in a library</Secondary></IndexTerm>
<Para>
After you have built a library, you may find that you want to
display the bookcases in a different order in the Information Manager Book List.
Or, you may have added a bookcase using
<Command>dtinfogen build</Command>, and
want to move it to a different position. You can use
<Command>dtinfogen admin</Command> to
change the order of bookcases in a library.
</Para>
<Para>
To rearrange bookcases within a library:
</Para>
<OrderedList>
<ListItem>
<Para>
At a command line, enter <UserInput>dtinfogen admin</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays:
</Para>
<LiteralLayout>
1) Copy a bookcase from another library
2) Remove a bookcase
3) List bookcases in a library
4) Rename a bookcase
5) Rearrange bookcases in a library
6) Exit
Please enter your choice [1-6]
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
To rearrange bookcases within a library, enter <UserInput>5</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays:
</Para>
<LiteralLayout>
Enter the path for the library you want to rearrange.
This can be a relative or absolute path.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
Enter the path to the information library you want to
rearrange. For example: <UserInput>/lit/wolfe</UserInput>.
</Para>
<Para>
<command>dtinfogen admin</command> displays the bookcases available in the
library you specified:
</Para>
<LiteralLayout>
The bookcases available in /lit/wolfe are:
1) Life [Life Works]
2) Essays [Essays from Life]
3) Poems [Collections of Poems]
Enter the number corresponding to the bookcase you want to move.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
At the prompt, enter the number corresponding to the
bookcase you want to move. <command>dtinfogen admin</command> displays:
</Para>
<LiteralLayout>
You specified <Replaceable>[Poems]</Replaceable>. Do you really want to move this bookcase?
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
To move the bookcase you specified to a different position
in the library, enter <UserInput>Y</UserInput>.
<command>dtinfogen admin</command> displays the current
order of the library without the bookcase you selected to
move. For example:
</Para>
<LiteralLayout>
The order of the bookcase without [Poems] is:
1) Life [Life Works]
2) Essays [Essays from Life]
Bookcases appear in the browser Book List in the order listed here.
Enter the number corresponding to the position you want bookcase to occupy.
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
Enter the number corresponding to the position you want
the bookcase to occupy.
</Para>
<Para>
If another bookcase already occupies the position you
choose, the bookcase you are moving takes its place, and
the original bookcase moves one place down in the list.
</Para>
<Para>
<Command>dtinfogen admin</Command> displays the new order of the bookcases in
the library. For example:
</Para>
<LiteralLayout>
You specified this order for the bookcases:
1) Poems [Collections of Poems]
2) Life [Life Works]
3) Essays [Essays from Life]
Is this correct? [ynq]
</LiteralLayout>
</ListItem>
<ListItem>
<Para>
To accept the rearranged order, enter <UserInput>Y</UserInput>.
<Command>dtinfogen admin</Command> saves
the new order and returns to the main menu.
</Para>
</ListItem>
</OrderedList>
</sect1>
</Chapter>

510
cde/doc/C/guides/infoAPg/ch06.sgm Normal file
View File

@@ -0,0 +1,510 @@
<!-- $XConsortium: ch06.sgm /main/4 1996/10/11 09:24:03 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.6">
<Title id="n0W3SgFBd02698oL">Troubleshooting</Title>
<IndexTerm><Primary>troubleshooting</Primary></IndexTerm>
<Para>
This section describes problems that may occur with the
Information Manager tools as a result of:
</Para>
<ItemizedList>
<ListItem>
<Para>
Build Errors&mdash; these errors can occur during the
<Command>dtinfogen build</Command>,
<Command>dtinfogen tocgen</Command>, and
<Command>dtinfogen update</Command> processes.
</Para>
</ListItem>
<ListItem>
<Para>
Style Sheet Errors&mdash; these errors can occur during the
<Command>dtinfogen build</Command> or the
<Command>dtinfogen update</Command> processes.
</Para>
</ListItem>
<ListItem>
<Para>
Library Administration Errors&mdash; these errors occur
during the <Command>dtinfogen admin</Command> process.
</Para>
</ListItem>
</ItemizedList>
<Para>
For more information, see <filename>dtinfogen(1)</filename>.
</Para>
<!--))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect1>
<Title id="DW3SgFBd02698oL">Build Errors</Title>
<Para>
The following error messages are generally associated with the
build process and are generated by either the
<Command>dtinfogen build</Command>,
<Command>dtinfogen tocgen</Command>, or
<Command>dtinfogen update</Command> programs.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>(ERROR) An undeclared style sheet name NAME was
found in the bookcase specification.
</computeroutput>
</literallayout>
<para>
means that style sheet <Replaceable>NAME</Replaceable> is specified in the bookcase
specification but has not been declared anywhere.
</Para>
<Para>
You must include the style sheet explicitly. One way of
including a style sheet is through the use of an entity
reference.
</Para>
<para>The following error message:</para>
<literallayout>
<computeroutput>(ERROR) An illegal ToC was found.
</computeroutput>
</literallayout>
<para>means that
the Information Manager found more than one TOC within the same
book.
</Para>
<Para>
Only one TOC is allowed for each book.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>(ERROR) Memory exhausted.
</computeroutput>
</literallayout>
<para>
means that insufficient memory was available to complete the build.
</Para>
<Para>
You must increase the memory available for the build
process. See
<Link Linkend="jI.RgFBe.1698oL">Build Considerations</Link> for more information
about allocating memory for the build process.
</Para>
<para>
The following error message:</para>
<literallayout>
<computeroutput>(ERROR) ToC validation failed.
</computeroutput>
</literallayout>
<para>
means that TOC validation failed.
</Para>
<Para>
Check the log of the build for details on where to find the error.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) IDREF = <Replaceable>LINK</Replaceable>
" of ToC file = <Replaceable>FILE</Replaceable>
" at line = <Replaceable>LINE</Replaceable>
" is pointing to an unavailable section.
</computeroutput>
</literallayout>
<para>
means that a hypertext link <Replaceable>LINK</Replaceable> at line
<Replaceable>LINE</Replaceable> in the TOC file
<Replaceable>FILE</Replaceable>
does not have a destination section.
</Para>
<Para>
Supply a unique ID for the destination section.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Section ID = <Replaceable>ID</Replaceable>
" of file = <Replaceable>FILE</Replaceable>
" at line = <Replaceable>LINE</Replaceable>
" does not have a corresponding link with
" the value = <Replaceable>ID</Replaceable>
" from the
" TOC file = <Replaceable>TOCFILE</Replaceable>.
</computeroutput>
</literallayout>
<para>
means that no link exists from the TOC file <Replaceable>TOCFILE</Replaceable>
to the section <Replaceable>ID</Replaceable> for
<Replaceable>FILE</Replaceable>.
</Para>
<Para>
Check the TOC file <Replaceable>TOCFILE</Replaceable>
and add a link with the value
<Replaceable>ID</Replaceable> to the TOC.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Duplicate ID = <Replaceable>ID</Replaceable>
" found in file = <Replaceable>FILENAME1</Replaceable>
" at line = <Replaceable>LINE1</Replaceable>
" is in conflict with
" ID = <Replaceable>ID</Replaceable>
" found in file = <Replaceable>FILE2</Replaceable>
" at line = <Replaceable>LINE2</Replaceable>.
</computeroutput>
</literallayout>
<para>
means that the Information Manager found the duplicate ID value
<Replaceable>ID</Replaceable> in both
<Replaceable>FILE1</Replaceable> and <Replaceable>FILE2</Replaceable>.
</Para>
<Para>
Each ID value must be unique. Change the appropriate
ID value to make it unique. Be sure to update the TOC
file with the new value.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Duplicate section ID = <Replaceable>ID</Replaceable>
" found in the file = <Replaceable>FILE1</Replaceable>
" at line = <Replaceable>LINE1</Replaceable>
" is in conflict with section ID = <Replaceable>ID</Replaceable>
" in file = <Replaceable>FILE2</Replaceable>
" at line= <Replaceable>LINE2</Replaceable>.
</computeroutput>
</literallayout>
<para>
means that the Information Manager found the duplicate section ID value
<Replaceable>ID</Replaceable> in both
<Replaceable>FILE1</Replaceable> and <Replaceable>FILE2</Replaceable>.
</Para>
<Para>
Each section ID value must be unique. Change the
appropriate section ID value to make it unique. Be sure
to update the TOC file with the new value.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Tab ID = <Replaceable>TabId</Replaceable>
" of book = <Replaceable>bookName</Replaceable>
" specified in file = <Replaceable>FILE1</Replaceable>
" at line = <Replaceable>LINE</Replaceable>
" is not pointing to any
" section ID found in the book.
</computeroutput>
</literallayout>
<para>
means that the tab ID value <Replaceable>TabId</Replaceable> listed in
<Replaceable>bookName</Replaceable> was not
found in the files that comprise <Replaceable>bookName</Replaceable>.
</Para>
<Para>
All tabs must point to a valid section in the book. Make
sure the tab ID is pointing to a valid section.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Style sheet validation failed.
</computeroutput>
</literallayout>
<para>
means that a syntax error was found in the style sheet.
</Para>
<Para>Correct the syntax error in the style sheet.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) An ID could not be found for the graphical
object.
</computeroutput>
</literallayout>
<para>
means that the graphical object did not have an ID.
Supply a non-empty ID value for the graphical object.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Terms file does not exist.
</computeroutput>
</literallayout>
<para>
means that there is insufficient disk space
to contain a temporary file for searchable terms information.
</Para>
<Para>
Verify that you have enough disk space to perform the build.
</Para>
</sect1>
<!--))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect1>
<Title id="n7eNaekBIaXwA0YK">Style Sheet Errors</Title>
<Para>
The following error messages are associated with style sheets.
For information about creating and using style sheets, see
<Link Linkend="tgmdnkb6vm9x3cs">Understanding Information Manager Style Sheets</link>
and <Link Linkend="btcmaab0ang24ak">Creating a Style Sheet</link>.
</para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Autonumber: missing ID attribute.
</computeroutput>
</literallayout>
<para>
means that the ID attribute for autonumbering could not be found.
Specify the ID attribute for autonumbering.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Autonumber: missing Type attribute.
</computeroutput>
</literallayout>
<para>
means that the Type attribute for autonumbering could not be found.
Specify the Type attribute for autonumbering.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Autonumber: missing Initial attribute.
</computeroutput>
</literallayout>
<para>
means that the Initial attribute for autonumbering could not be found.
Specify the Initial attribute for autonumbering.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Autonumber: missing Delta attribute.
</computeroutput>
</literallayout>
<para>
means that the Delta attribute for autonumbering could not be found.
Specify the Delta attribute for autonumbering.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Autonumber: missing Reset attribute.
</computeroutput>
</literallayout>
<para>
means that the Reset attribute for autonumbering could not be found.
Specify the Reset attribute for autonumbering.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Autonumber: missing Counter attribute.
</computeroutput>
</literallayout>
<para>
means that the Counter for autonumbering could not be found.
Specify the Counter attribute for autonumbering.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) No name given for the style sheet.
</computeroutput>
</literallayout>
<para>
means that the style sheet name was missing.
Specify the style sheet name.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Syntax error in <Replaceable>EXPR</Replaceable>.
</computeroutput>
</literallayout>
<para>
means that a syntax error was found in the expression
<Replaceable>EXPR</Replaceable>
specified for an Information Manager architectural form.
</Para>
<Para>
Search for the expression
<Replaceable>EXPR</Replaceable> in the DTD and correct
the syntax for the Information Manager architectural form.
</Para>
</sect1>
<!--))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect1>
<Title id="L4E7gLBYimg24aK">Library Administration Messages</Title>
<Para>
The following error messages are associated with the
<Command>dtinfogen admin</Command> command.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) <Replaceable>InfoLibPath</Replaceable> is not a valid information library.
</computeroutput>
</literallayout>
<para>
means that the <Replaceable>InfoLibPath</Replaceable> you specified may
be an invalid path, or the information library itself may be invalid.
Enter the correct path name, or check to see if there is a file named
<Filename>*.oli</Filename> under the
<Replaceable>InfoLibPath</Replaceable> you chose.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) No copying is performed because of errors found in validation.
</computeroutput>
</literallayout>
<para>
means that
<Command>dtinfogen admin</Command>
found a problem in the validation phase
and did not copy the bookcase into the destination
library. The problem may be version mismatch or
duplicate IDs.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Data version mismatch
" <Replaceable>checkBase</Replaceable> version = #
" <Replaceable>installBase</Replaceable> version = #
</computeroutput>
</literallayout>
<para>
means that
<Command>dtinfogen admin</command>
found a database version mismatch in the
bookcase you are copying (<Replaceable>checkbase</Replaceable>) and the bookcase
that exists in the information library (installed base).
Rebuild the bookcases with the same version of the build
tools.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Duplicate ID value [<Replaceable>ID</Replaceable>] found in <Replaceable>BookCaseName</Replaceable>
</computeroutput>
</literallayout>
<para>
means that
<Command>dtinfogen admin</Command>
found <Replaceable>ID</Replaceable> in the bookcase you are copying and in
<Replaceable>BookCaseName</Replaceable>, the bookcase into which you are
copying. All IDs must be unique. Change the ID value of
one of the sections in the SGML document and rebuild
the bookcases.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) The position you chose is not valid. Please
specify a valid position for the bookcase.
</computeroutput>
</literallayout>
<para>
means that the position you specified for a particular bookcase is out
of range. Please specify a valid position for the bookcase.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) Unable to remove <Replaceable>BookCaseName</Replaceable> from
<Replaceable>InfoLibPath</Replaceable>
</computeroutput>
</literallayout>
<para>
means that
<Command>dtinfogen admin</Command> was unable to remove bookcase
<Replaceable>BookCaseName</Replaceable> from the information library
<Replaceable>InfoLibPath</Replaceable>. Verify that you have the correct
permissions for changing this bookcase. It may be that this bookcase
does not exist in the information library, or the bookcase
path is not valid.
</Para>
<para>
The following error message:
</para>
<literallayout>
<computeroutput>
(ERROR) You have chosen an invalid number. Please specify a number 1-6.
</computeroutput>
</literallayout>
<para>
means that
you have chosen a number that is out of range.
</Para>
</sect1>
</Chapter>

648
cde/doc/C/guides/infoAPg/ch07.sgm Normal file
View File

@@ -0,0 +1,648 @@
<!-- $XConsortium: ch07.sgm /main/4 1996/10/11 09:24:11 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.7">
<title id="tgmdnkb6vm9x3cs">Understanding Information Manager Style Sheets</title>
<IndexTerm><Primary>style sheets</Primary><Secondary>understanding</Secondary></IndexTerm>
<para>
Style sheets control the appearance of your documents in the Information
Manager browser by defining the on-line and print formatting
characteristics of every element in your DTD. Information Manager style
sheets must conform to the stylesheet document type definition,
<filename>dtinfoStyle.dtd</filename>.
</para>
<para>
Style sheets are specified as part of the bookcase specification
document. To build an information library with the Information Manager,
you must reference a default style sheet at the bookcase level. For more
information see <filename>dtinfoBook.dtd(5)</filename>,
<link linkend="n0Crl2IBiWmBt8oL">About the Build Process and Tools</link>,
and <link linkend="j3fa6XBbiK9X3cS">Using Style Sheets</link>.
</para>
<para>
For specific information about creating style sheets see:
</para>
<itemizedlist>
<listitem>
<para>
<link linkend="whpipbbc3h9x3cs">Style Sheet Structure</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="btcmaab0ang24ak">Creating a Style Sheet</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="suwh3wbmhwy94ak">Style Features</link>
</para>
</listitem>
</itemizedlist>
<!-- ))))))))))))))))))))))))))))))))))))))))))))) -->
<sect1>
<title id="whpipbbc3h9x3cs">Style Sheet Structure</title>
<IndexTerm><Primary>style sheet structure</Primary></IndexTerm>
<para>
A style sheet consists of <systemitem>AutoNumber</systemitem>
declarations, followed by <systemitem>Path</systemitem> statements
and style specifications.
</para>
<para>
You can specify style sheets at the bookcase, book, and section
levels. If, at a level subordinate to the bookcase level, you do
not specify a style sheet, the style for that level is inherited
from a containing element. If no style sheet is specified in a containing
element, the text appears in the Information Manager Reading Window
in 14 point Helvetica, the default as specified in the global
Xresources file. The default font for print is 12 point Helvetica.
</para>
<note>
<para>
For more information on inheritance, see
<link linkend="pgqaykbbgsg24ak">Understanding Inheritance</link>.
</para>
</note>
<para>
Each style sheet must have a unique name within the scope of a Bookcase
document. The Information Manager uses the style sheet name as a
reference within a bookcase and within each of its books and sections.
</para>
<para>
Creating a style sheet is essentially a matter of selecting
elements, via a <link linkend="jipipbbc3h9x3cs"><systemitem>Path</systemitem></link>
statement, by name, context, and attribute(s), and then assigning
typographic properties to the <systemitem>Path</systemitem>.
</para>
<itemizedlist>
<listitem>
<para>
You can use the <systemitem>Select</systemitem>
feature within a path to select elements by attribute value, by
absolute position, or by relative position.
</para>
</listitem>
<listitem>
<para>
You use <systemitem>Path</systemitem>
statements in the style sheet to identify the elements you wish to
format using <systemitem>Online</systemitem> and/or
<systemitem>Print</systemitem> (hard copy) feature
specifications.
</para>
</listitem>
<listitem>
<para>
The <systemitem>Online</systemitem>
and <systemitem>Print</systemitem> feature sets
match in function, description, and specification except for these
<link linkend="cwccmncd70hp2ol">print-specific features</link>:
</para>
<itemizedlist>
<listitem>
<para>
<link linkend="n4kpipbbc3h9x3cs">Medium</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="r74dmncp70hp2ol">PageBreak</link>
</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
Here is a partial example of style sheet syntax specifying
the formatting characteristics of a Chapter
element, which in some documentation is the largest element that
uses the <systemitem>DTINFO.Section</systemitem>
architectural form. Specifying the largest <systemitem>DTINFO.Section</systemitem>
as the first <systemitem>Path</systemitem> in your style sheet is
sometimes useful for setting up default rendering characteristics.
</para>
<literallayout>
&lt;Path>
Chapter&lt;/Path>
&lt;online>
&lt;wrap word>
&lt;margin left=20 right=20>
&lt;font fallback=sans weight=medium slant=roman size=14>
&lt;family name=helvetica charset="iso8859-1">
&lt;/font>
&lt;/online>
</literallayout>
<!--((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect2>
<title id="jipipbbc3h9x3cs">Specifying the Path</title>
<IndexTerm><Primary>specifying the path</Primary></IndexTerm>
<para>
A path statement specifies the hierarchical path from the
outermost containing element to an element that will be affected
by some feature you specify in the style sheet. To identify a particular
element in a given hierarchy, you simply specify the minimum unique
path to that element.
</para>
<para>
A path is always resolved by the first path specification
that matches the element or element class in context. You can use
wildcard characters as well as special element
<systemitem>Select</systemitem> statements to identify
specific elements for formatting. <systemitem>Select</systemitem>
statements are described in <link linkend="n6jmj9jbj6ng24ak">Using
Select Statements</link>.
</para>
<para>
In the following figure, the Chapter
element contains a Title followed by two Paragraph
elements and a Section element. The Section
element, in turn, contains a Title and two Paragraph elements.
</para>
<Figure>
<Title id="n1mievocfe0hp2ol">Simple Document Hierarchy</Title>
<GRAPHIC id="gr71" entityref="infoapg.fig.10"></graphic>
</Figure>
<para>
Based on the preceding figure, the complete path for
the Section element is:
</para>
<programlisting>
&lt;Path> Chapter Section &lt;/Path>
</programlisting>
<note>
<para>
Because the hierarchy in the diagram contains only one Section element,
the element name alone is sufficient to identify the Section element.
</para>
</note>
<para>
To identify Paragraph elements contained in Section
elements, the path is:
</para>
<programlisting>
&lt;Path>Chapter Section Paragraph &lt;/Path>
</programlisting>
<para>
Two wildcards are available for specifying paths in a style sheet:
</para>
<itemizedlist>
<listitem>
<para>
The question mark ( <literal>?</literal> )
specifies that any single element can intervene.
</para>
</listitem>
<listitem>
<para>The asterisk ( <literal>*</literal> )
wildcard specifies zero or any number of intervening elements.
</para>
</listitem>
</itemizedlist>
<para>
Based on the figure above, the following two statements specify
the same element:
</para>
<programlisting>
&lt;Path> Chapter Section Title &lt;/Path>
</programlisting>
<programlisting>
&lt;Path> Chapter ? Title &lt;/Path>
</programlisting>
<para>
However, unlike the two PATH statements above, the following PATH statement
selects more than the Title statement contained in Section.
</para>
<programlisting>
&lt;Path> Chapter * Title &lt;/Path>
</programlisting>
</sect2>
</sect1>
<!--)))))))))))))))))))))))))))))))))))))))))-->
<sect1>
<title id="n6jmj9jbj6ng24ak">Using Select Statements</title>
<IndexTerm><Primary>select statements</Primary></IndexTerm>
<para>
<systemitem>Select</systemitem> statements
enable you to apply a different style to the same element in different
contexts. For example, by using a <systemitem>Select</systemitem>
statement, you can apply a different set of formatting characteristics
to a paragraph element depending on whether it follows a particular
type of head, is subordinated within a list, or is part of a warning.
This is possible because <systemitem>Select</systemitem>
statements enable you to match specific instances of the element
either by the element's attribute value or by its position.
</para>
<para>
Each element in a <systemitem>Path</systemitem> can have its own
<systemitem>Select</systemitem> statement. <systemitem>Select</systemitem> statements
use simple comparison operators: equal to (==), not equal to (!=), and boolean operators,
"and" (&#38;&#38;) and "or" (||).
</para>
<!--))))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect2>
<title id="lkb3nlchsaznuzs">Identifying Elements by Attribute</title>
<para>
You can identify elements by using element attribute values.
For example, if a Paragraph element
has the following start-tag:
</para>
<programlisting>
&lt;PARAGRAPH label="UNIque">
</programlisting>
<para>
then the path to that Paragraph element can be specified as:
</para>
<programlisting>
&lt;PATH>Paragraph &lt;Select>@label == "UNIque"&lt;/Select>
&lt;/PATH>
</programlisting>
<para>
Any element attribute can be used in this way by prepending
the "@" character to the attribute name. Similarly, the same
Paragraph element could be specifically
excluded with the following statement:
</para>
<programlisting>
&lt;PATH>Paragraph &lt;Select>@label != "UNIque"&lt;/Select>
&lt;/PATH>
</programlisting>
</sect2>
<!--(((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect2>
<title id="azp3nlcmsaznuzs">Identifying Elements by Position</title>
<para>
You can identify elements by position using models based on
the relative or absolute position of an element in the element hierarchy.
The two approaches, with their identifying keywords, are:
</para>
<itemizedlist>
<listitem>
<para>
The absolute position of elements
in the parse tree, using the <systemitem>"Position"</systemitem>
keyword.
</para>
</listitem>
<listitem>
<para>The relative position of elements among like siblings,
using the <systemitem>"Sibling"</systemitem> keyword.
</para>
</listitem>
</itemizedlist>
<para>
These two models can be used together in any
<systemitem>Path</systemitem> statement. Both require
numbers as values, but you can also use a special value,
<systemitem>"#LAST"</systemitem>, to specify the last element
in a list of elements. The example DTD Fragment and Document Instance
Fragments below illustrates two possible absolute and relative position
element selection models. The sample <systemitem>Path</systemitem>
statements that follow use the two models to illustrate how you
can use these selection mechanisms to select specific element items.
</para>
<example>
<title id="itzl.ocz40hp2ol">DTD Fragment and Document Instance Fragments</title>
<literallayout>
&lt;!ELEMENT List - - (Title?,Item+)>
&lt;!ATTLIST List Type (Bulleted|Numbered) "Bulleted">
&lt;!ELEMENT Title - - #PCDATA >
&lt;!ELEMENT Item - - #PCDATA >
INSTANCE A: INSTANCE B:
&lt;List Type="Numbered"> &lt;List Type="Numbered">
&lt;Item>Fee&lt;/item> &lt;Title>Fee Fie Foe Fum&lt;/item>
&lt;Item>Fie&lt;/item> &lt;Item>Fee&lt;/item>
&lt;Item>Foe&lt;/item> &lt;Item>Fie&lt;/item>
&lt;Item>Fum&lt;/item> &lt;Item>Foe&lt;/item>
&lt;/List> &lt;Item>Fum&lt;/item>
&lt;/List>
</literallayout>
</example>
<!--((((((((((((((((((((((((((((((((((((((((((((((((((-->
<sect3>
<title id="n7ch3nlcwsaznuzs">Absolute Position Model</title>
<para>
You can select an element based on its absolute position in
the parse tree by using the <systemitem>"Position"</systemitem>
keyword in <systemitem>SELECT</systemitem> statements.
</para>
<para>
In the example DTD Fragment and Document Instance Fragments
shown above, the content model allows an optional Title element,
but in Instance A, the optional Title element is not used.
The following path identifies the first Item
element in Instance A:
</para>
<programlisting>
&lt;PATH> List &lt;Select>@Type == "Numbered"&lt;/Select> Item &lt;Select>position == 1 &lt;/Select>
&lt;/PATH>
</programlisting>
<para>
If the preceding path were used for Instance B, the Information Manager
would not find the first Item element because its absolute position in
the parse tree is second, after its peer Title.
</para>
<para>
The following path selects the remaining Item elements in Instance A:
</para>
<programlisting>
&lt;PATH> List &lt;Select>@Type == "Numbered"&lt;/Select> Item &lt;Select>position != 1 &lt;/Select>
&lt;/PATH>
</programlisting>
<para>
If the preceding path were used in Instance B, all of the
Item elements would match.
</para>
</sect3>
<!-- (((((((((((((((((((((((((((((((((((((((((((( -->
<sect3>
<title id="jrj3nlcbsaznuzs">Relative Position Model</title>
<para>
You can select elements based on their position, relative
to like siblings, in the parse tree by using the
<systemitem>"Sibling"</systemitem> keyword in
<systemitem>Select</systemitem> statements. This model
provides a direct method for selecting the first and last elements
in a group of like elements.
</para>
<para>
You can identify the first Item
element in either Instance A or Instance B with the following statement:
</para>
<programlisting>
&lt;PATH> List &lt;Select>@Type == "Numbered"&lt;/Select> Item &lt;Select> sibling == 1 &lt;/Select>
&lt;/PATH>
</programlisting>
<para>
The following path identifies the last Item element in both Instances:
</para>
<programlisting>
&lt;PATH> List &lt;Select>@Type == "Numbered"&lt;/Select> Item &lt;Select> sibling == "#LAST" &lt;/Select>
&lt;/PATH>
</programlisting>
</sect3>
</sect2>
<!--))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect2>
<title id="n62r3nlcgsaznuzs">Grouping Select Expressions</title>
<para>
You can group <systemitem>Select</systemitem>
expressions to identify the elements that are neither first nor
last by using the following comparison operators:
</para>
<itemizedlist>
<listitem>
<para>
&#38;&#38; -- The "and" operator.
All expressions must be true.
</para>
</listitem>
<listitem>
<para>|| -- The "or" operator. Any expression can be true.
</para>
</listitem>
</itemizedlist>
<para>
Although no grouping operator is provided, the natural left-to-right
logic effects similar results. The following path shows a compound
<systemitem>Select</systemitem> statement for
Instance B:
</para>
<programlisting>
&lt;PATH> List &lt;Select>@Type == "Numbered"&lt;/Select> Item &lt;Select>sibling != 1 &#38;&#38; position != "#LAST" &lt;/Select>
&lt;/PATH>
</programlisting>
<para>
As described above, the content of a <systemitem>Select</systemitem>
statement can specify either position or attribute value. And, more
than one <systemitem>Select</systemitem> can occur
in a <systemitem>Path</systemitem> statement (one
per element name). Here are some additional guidelines regarding
the use of <systemitem>Select</systemitem> statements.
</para>
<variablelist>
<varlistentry>
<term>position == <replaceable>n</replaceable></term>
<listitem>
<para>
Selects the element if its relative position in
a string of elements is equal to <replaceable>n</replaceable>. For
example <userinput>position == 3</userinput> selects
the element if its position is equal to 3. A space must precede
and follow the <userinput>==</userinput>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>position != <replaceable>n</replaceable></term>
<listitem>
<para>
Selects the element if its relative position in
a string of elements is <emphasis>not</emphasis> equal to <replaceable>n</replaceable>.
For example <userinput>position != 3</userinput>
selects the element if its position is <emphasis>not</emphasis>
equal to 3. A space must precede and follow the <userinput>!=</userinput>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@<replaceable>attribute</replaceable> == <replaceable>"string"</replaceable></term>
<listitem>
<para>Selects the element if its <replaceable>attribute</replaceable>
is equal to <replaceable>string</replaceable>. For example,
<userinput>@label == "chapter"</userinput> specifies
an element that has a label attribute with the value "chapter".
A space must precede and follow the <userinput>==</userinput>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@<replaceable>attribute</replaceable> != "<replaceable>string</replaceable>"</term>
<listitem>
<para>Selects the element if its <replaceable>attribute</replaceable>
is <emphasis>not</emphasis> equal to <replaceable>string</replaceable>.
For example, <userinput>@label != "chapter"</userinput>
specifies an element that has a label attribute that does <emphasis>not</emphasis>
have the value "chapter". A space must precede and follow the <userinput>!=</userinput>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
This example specifies a title element that has a label attribute
with the value "chapter":
</para>
<programlisting>
&lt;Path> * title &lt;Select>@label == "chapter"&lt;/Select>
&lt;/Path>
</programlisting>
<note>
<para>
The Information Manager does not support selection on a wildcard. For example:
<userinput>&lt;Path> * &lt;Select>@label == "Chapter" &lt;/Select>&lt;/Path></userinput> is not supported.
</para>
</note>
</sect2>
<!--)))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect2>
<title id="zqw3nlcmsaznuzs">Element Hierarchies and DTINFO.Section</title>
<para>
For style sheets, the element hierarchy defined by the source
DTD is not necessarily the only element hierarchy that requires
formatting. Each element to which the <systemitem>DTINFO.Section</systemitem>
Architectural Form is applied constitutes the root of a separate
element hierarchy you must address. Thus, the element paths in the
figure <link linkend="n1mievocfe0hp2ol">Simple Document Hierarchy</link>
are true if <systemitem>DTINFO.Section</systemitem>
is applied only to the Chapter element.
</para>
<para>
However, if <systemitem>DTINFO.Section</systemitem>
were applied to both Chapter and Section, then the
minimum unique path for the Paragraph
elements contained in Section
elements would be:
</para>
<programlisting>
&lt;Path> Section Paragraph
&lt;/Path>
</programlisting>
<para>
Likewise, for Paragraph elements contained in Chapter
elements, the path would be:
</para>
<programlisting>
&lt;Path> Chapter Paragraph
&lt;/Path>
</programlisting>
</sect2>
</sect1>
<!--)))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<sect1>
<title id="pgqaykbbgsg24ak">Understanding Inheritance</title>
<para>
Some style sheet features are inherited from a containing
parent element. As the short example style sheet below illustrates,
child elements will display the inheritable formatting characteristics
of the parent until the style sheet specifies different formatting
characteristics for either the parent or the child. If the style
features for the parent are changed, then all of its child elements
inherit the same changes.
</para>
<para>
The example style sheet shows <systemitem>Path</systemitem>
statements for the elements SECT1, SECT1 TITLE, and PARA. Note that
<systemitem>Font</systemitem>, <systemitem>Family</systemitem>,
and <systemitem>Margin</systemitem> are set in the SECT1
element and are inherited by the other elements (SECT1 TITLE and
PARA) that are contained by SECT1. In the second <systemitem>Path</systemitem>
statement, the font size and weight values are reset to 18-point
medium for all SECT1 TITLE elements. These new values are not inherited
by the PARA element because PARA is a child of SECT1, not of SECT1
TITLE.
</para>
<example>
<title id="vpgq.occ50hp2ol">Example Short Style Sheet</title>
<literallayout>
&lt;STYLESHEET Name=General>
&lt;path>
SECT1 &lt;/path>
&lt;Online>
&lt;Font Fallback=sans Weight=medium Slant=roman Size=14>
&lt;Family Name=helvetica Charset=iso8859-1>
&lt;Margin Left=20 Right=20 Top=30 Bottom=30>
&lt;/Online>
&lt;path> SECT1 TITLE &lt;/path>
&lt;Online>
&lt;Font Weight=bold Size=18>
&lt;/Online>
&lt;path>
PARA &lt;/path>
&lt;Online>
&lt;Linebreak both>
&lt;Layout ASpace=6 BSpace=6>
&lt;/Online>
&lt;/STYLESHEET>
</literallayout></example>
<para>
The inherited style features are:
</para>
<itemizedlist>
<listitem>
<para><link linkend="rrn5xmc0gwwa0yk">Font</link></para>
</listitem>
<listitem>
<para><link linkend="ujpipbbc3h9x3cs">HighLight</link></para>
</listitem>
<listitem>
<para><link linkend="djpipbbc3h9x3cs">Ignore</link></para>
</listitem>
<listitem>
<para><link linkend="jjpipbbc3h9x3cs">Layout</link></para>
</listitem>
<listitem>
<para><link linkend="xjpipbbc3h9x3cs">Margin</link></para>
</listitem>
<listitem>
<para><link linkend="n4kpipbbc3h9x3cs">Medium</link></para>
</listitem>
</itemizedlist>
<para>
The style features that are not inherited are:
</para>
<itemizedlist>
<listitem>
<para><link linkend="dq2emncz70hp2ol">Border</link></para>
</listitem>
<listitem>
<para><link linkend="yrddmncb70hp2ol">Cell</link></para>
</listitem>
<listitem>
<para><link linkend="qjpipbbc3h9x3cs">ColFormat</link></para>
</listitem>
<listitem>
<para><link linkend="n0jpipbbc3h9x3cs">LineBreak</link>
</para>
</listitem>
<listitem>
<para><link linkend="r74dmncp70hp2ol">PageBreak</link></para>
</listitem>
<listitem>
<para><link linkend="n4llcmnc770hp2ol">Position</link></para>
</listitem>
<listitem>
<para><link linkend="n9kpipbbc3h9x3cs">Prefix and Suffix</link></para>
</listitem>
<listitem>
<para><link linkend="w9jdmnch70hp2ol">Row</link></para>
</listitem>
<listitem>
<para><link linkend="n0sodmncn70hp2ol">Table</link></para>
</listitem>
<listitem>
<para>TGroup</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>

1915
cde/doc/C/guides/infoAPg/ch08.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

106
cde/doc/C/guides/infoAPg/ch09.sgm Normal file
View File

@@ -0,0 +1,106 @@
<!-- $XConsortium: ch09.sgm /main/4 1996/10/11 09:24:29 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.9">
<Title id="vSMTMZBRyng24aK">Understanding Architectural Forms</Title>
<IndexTerm><Primary>architectural forms</Primary>
<Secondary>understanding</Secondary></IndexTerm>
<Para>
You use the
Information Manager to build a bookcase, a collection of
books in an information library, from a set of SGML documents.
For some of these documents, such as style sheets, the SGML
document type is defined by SGML DTDs distributed with the
Information Manager. For others, such as the content of your books, you
may use any document type definition (DTD).
</Para>
<Para>
Many SGML applications face the problem of understanding the
semantics that should be attached to elements in any arbitrary
DTD. To handle this, the Information Manager provides architectural forms.
</Para>
<Para>
An architectural form is a name given to a class containing
elements that are to be processed uniformly by some application.
Architectural forms define base classes. The specific SGML
element defined in a specific DTD is then treated as a subclass.
To implement architectural forms, you annotate your DTD with
standard SGML attributes corresponding to
Information Manager architectural
forms. In most cases, the architectural forms are defined using
the <SystemItem>FIXED</SystemItem> keyword,
setting a specific attribute value for all
instances of the element in all documents.
</Para>
<!--)))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<Sect1>
<Title id="kZLOUiBgsK9X3cS">Simple Example of an Architectural Form</Title>
<Para>
You must modify your existing DTDs so the
Information Manager can
manage the information correctly. For example, the
Information Manager
uses &ldquo;titles&rdquo; to determine the content displayed in various fields
of the Information Manager Reading windows. Of course, in any specific DTD, the choices
of a Generic Identifier for a title object are limitless. It could be
called <SystemItem>head</SystemItem>, <SystemItem>h1</SystemItem>,
<SystemItem>title</SystemItem>,
<SystemItem>ti</SystemItem>, and so on. To allow the application to
identify these title objects, we apply the attribute
<SystemItem>DTINFO.Title</SystemItem> to our
DTD. So, for example, if our specific element is named
<SystemItem>head</SystemItem>:
</Para>
<ProgramListing>
&lt;!ELEMENT HEAD - - (PCDATA) >
&lt;!ATTLIST HEAD
DTINFO.Title NAME #FIXED "#CONTENT">
</ProgramListing>
<Para>
As the application is processing a document, every instance of
the element
<SystemItem>HEAD</SystemItem> will have associated with it an attribute named
<SystemItem>DTINFO.Title</SystemItem>. The application can recognize this and process the
content of the element as it would any title.
</Para>
<Note>
<Para>
Applying architectural forms does not affect
the validity of your SGML instances. For
more information on applying architectural
forms to your DTD, see
<Link Linkend="nWGeMZBc9og24aK">Modifying your
Existing DTD</Link>.</Para>
</Note>
</Sect1>
<!--))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
<Sect1>
<Title id="zZLOUiBgsK9X3cS">How Architectural Forms Fit in the Toolkit Model</Title>
<Para>
The figure
<Link Linkend="dPkT9aB7Wng24aK">Toolkit Model</Link> illustrates how different pieces of
information interact during the build process. The shaded area
in the figure represents the part of the build involving
architectural forms.
</Para>
<Figure>
<Title id="dPkT9aB7Wng24aK">Toolkit Model</Title>
<GRAPHIC id="gr53" entityref="infoapg.fig.9"></graphic>
</Figure>
<Para>
For information on developing a bookcase document under the
DTD provided by the Information Manager, see
<Link Linkend="TcQg4bBSxI9X3cS">Creating a Bookcase
Document</Link>. For details on creating
a style sheet document which conforms to the
<Filename>dtinfoStyle.dtd</Filename>, see
<Link Linkend="btcmaab0ang24ak">Creating a Style Sheet</Link>.
</Para>
</Sect1>
</Chapter>

1019
cde/doc/C/guides/infoAPg/ch10.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

127
cde/doc/C/guides/infoAPg/ch11.sgm Normal file
View File

@@ -0,0 +1,127 @@
<!-- $XConsortium: ch11.sgm /main/4 1996/10/11 09:24:44 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.11">
<Title id="S3CTVcBfQJ9X3cS">Table of Contents Architectural Forms</Title>
<IndexTerm><Primary>architectural forms</Primary>
<Secondary>table of contents</Secondary></IndexTerm>
<Para>
If you already have a table of contents document instance in
SGML format, you do not have to create a new table of contents.
Instead, you can apply
Information Manager architectural forms to the
elements in your existing table of contents DTD so
Information Manager knows
how to treat the table of contents information.
</Para>
<Note>
<Para>
For information on creating an SGML table of
contents that conforms to the
Information Manager <Filename>dtinfoTOC.dtd</Filename>,
see <Link Linkend="n8aJ92dBIsI9X3cS">Creating a Table of Contents</Link>.
</Para>
</Note>
<Para>
You can add these attributes to your existing table of contents
DTD:
</Para>
<VariableList>
<VarListEntry>
<Term><SystemItem>DTINFO.TOC</SystemItem></Term>
<ListItem>
<Para>Apply
<SystemItem>DTINFO.TOC</SystemItem> to elements that designate tables of
contents.
</Para>
<Para>
Entity name: <SystemItem>DTINFO.TOC</SystemItem>
</Para>
<Para>
Attribute template:
<SystemItem>DTINFO.TOC CDATA #FIXED</SystemItem>
</Para>
<Para>
Related Forms:
<SystemItem>DTINFO.Scope</SystemItem>,
<SystemItem>DTINFO.Value</SystemItem>,
<SystemItem>DTINFO.ID</SystemItem>.
</Para>
<Para>
Example:
</Para>
<LiteralLayout>
&lt;!ELEMENT TOC - - ( Title, TitleAbbrev?, TOCfront*,
(TOCpart+ | TOCchap+), TOCback* ) &gt;
&lt;!ATTLIST TOC
Id ID #REQUIRED
%DTINFO.TOC; &ldquo;&num;CONTENT&rdquo;
%DTINFO.ID; &ldquo;attr( Id )&rdquo;--&gt;
&gt;
</LiteralLayout>
<Comment><SystemItem>DTINFO.TOCEntry</SystemItem></Comment>
<Para>
Apply <SystemItem>DTINFO.TOCEntry</SystemItem> to elements that indicate an entry in
a book&rsquo;s table of contents.</Para>
<Para>
Entity name: <SystemItem>DTINFO.TOCEntry</SystemItem>
</Para>
<Para>
Attribute template:
<SystemItem>DTINFO.TOCEntry CDATA #FIXED</SystemItem>
</Para>
<Para>Related Forms:
<SystemItem>DTINFO.Scope</SystemItem>,
<SystemItem>DTINFO.Value</SystemItem>,
<SystemItem>DTINFO.ID</SystemItem>.
</Para>
<Para>
Example:
</Para>
<LiteralLayout>
&lt;!ELEMENT TOCpart - - ( TOCentry+, TOCchap* ) &gt;
&lt;!ATTLIST TOCpart
Id ID #IMPLIED
%DTINFO.ID; &ldquo;attr( Id )&rdquo;
%DTINFO.TOCEntry; #CONTENT&rdquo;
&gt;
</LiteralLayout>
<Comment><SystemItem>DTINFO.TOCLevel</SystemItem></Comment>
<PARA>
Apply
<SystemItem>DTINFO.TOCLevel</SystemItem> to elements that indicate an entry
in a book&rsquo;s table of contents.</PARA>
<PARA>Entity name:
<SystemItem>DTINFO.TOCLevel</SystemItem></PARA>
<PARA>Attribute template:
<SystemItem>DTINFO.TOCLevel CDATA &num;FIXED
</SystemItem></PARA>
<PARA>Related Forms:
<SystemItem>DTINFO.Scope</SystemItem>,
<SystemItem>DTINFO.Value</SystemItem>,
<SystemItem>DTINFO.ID</SystemItem>.</PARA>
<PARA>Example:
</PARA>
<LITERALLAYOUT>
&lt;!ELEMENT TOCpart - - ( TOCentry+, TOCchap* ) &gt;
&lt;!ATTLIST TOCpart
Id ID #IMPLIED
%DTINFO.ID; &ldquo;attr( Id )&rdquo;
%DTINFO.TOCLevel;
&gt;
</LiteralLayout>
</ListItem>
</VarListEntry>
</VariableList>
</Chapter>

201
cde/doc/C/guides/infoAPg/glossary.sgm Normal file
View File

@@ -0,0 +1,201 @@
<!-- $XConsortium: glossary.sgm /main/2 1996/09/22 15:10:34 rws $ -->
<!-- (c) Copyright 1996 Digital Equipment Corporation. -->
<!-- (c) Copyright 1996 Hewlett-Packard Company. -->
<!-- (c) Copyright 1996 International Business Machines Corp. -->
<!-- (c) Copyright 1996 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1996 Novell, Inc. -->
<!-- (c) Copyright 1996 FUJITSU LIMITED. -->
<!-- (c) Copyright 1996 Hitachi. -->
<Glossary Id="sz6BJNB1DI9X3cS">
<Title>Glossary</Title>
<Glossentry>
<GlossTerm>architectural form</GlossTerm>
<glossdef>
<para>
A template for a class of SGML elements or set of
attributes.
</para>
</glossdef>
</Glossentry>
<GlossEntry>
<GlossTerm>attribute</GlossTerm>
<glossdef>
<para>
The named value associated with a specific occurrence of
an element.
</para>
</glossdef>
</GlossEntry>
<Glossentry>
<GlossTerm>book</GlossTerm>
<glossdef>
<para>
In the Information Manager, an electronic book. A collection of sections
arranged according to a hypertext table of contents (TOC).
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>bookcase</GlossTerm>
<glossdef>
<para>
A group of electronic books on related topics. A logical set
of information (perhaps several related books) that are
accompanied by a single full-text index. A bookcase and
style sheets represents the minimum collection of
information that can be built into an
Information Library information
library.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>Bookcase DTD</GlossTerm>
<glossdef>
<para>
The document type definition defining the structure of
the specification files used to build books for the
Information Manager.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>bookcase specification</GlossTerm>
<glossdef>
<para>
An SGML document that contains or specifies the book
files, style sheets, and other SGML entities necessary to
build an Information Manager information library.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>Book List</GlossTerm>
<glossdef>
<para>
The list of bookcases and books available from the
Information Manager.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>Browser</GlossTerm>
<glossdef>
<para>
The Information Manager on-line system that allows
you to view and manage on-line information.
</para>
</glossdef>
</Glossentry>
<GlossEntry>
<GlossTerm>document instance</GlossTerm>
<glossdef>
<para>
The SGML source for your document, including the
document content and the SGML markup.
</para>
</glossdef>
</GlossEntry>
<Glossentry>
<GlossTerm>DTD</GlossTerm>
<glossdef>
<para>
Acroynm for document type definition. The formal
constructs that establish the markup for a document.
The DTD also includes informal guidelines and
conventions for applying SGML to a document type.
</para>
</glossdef>
</Glossentry>
<GlossEntry>
<GlossTerm>dtinfogen</GlossTerm>
<glossdef>
<para>
The on-line document compilation and display system.
</para>
</glossdef>
</GlossEntry>
<GlossEntry>
<GlossTerm>GUI</GlossTerm>
<glossdef>
<para>
Acronym for Graphical User Interface. An application&rsquo;s
look and feel.
</para>
</glossdef>
</GlossEntry>
<Glossentry>
<GlossTerm>information library</GlossTerm>
<glossdef>
<para>
The entire set of on-line bookcases available in the
Information Manager library.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>Information Manager</GlossTerm>
<glossdef>
<para>
The overall document input, creation, mark-up and display
system.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>modified DTD</GlossTerm>
<glossdef>
<para>
The DTD for the document source, with
architectural forms applied.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>reading window</GlossTerm>
<glossdef>
<para>
The Information Manager window that shows the text, tables
and graphics of a book.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>section</GlossTerm>
<glossdef>
<para>A single unit of documentation that is displayed within a
Reading window. On average, a section is a
screen or two in length and does not typically span more
than seven screens.
</para>
</glossdef>
</Glossentry>
<Glossentry><GlossTerm>SGML</GlossTerm>
<glossdef>
<para>Acronym for Standard Generalized Markup Language
(ISO 8879). SGML is the Information Manager document input and
storage format.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>style sheet</GlossTerm>
<glossdef>
<para>
A file that defines the document rendering
characteristics for on-line viewing and for printing.
</para>
</glossdef>
</Glossentry>
<Glossentry>
<GlossTerm>TOC</GlossTerm>
<glossdef>
<para>
Acronym for hypertext table of contents that organizes
sections of Information Manager on-line book titles.
</para>
</glossdef>
</Glossentry>
</Glossary>

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/addbkcas.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/bkcase.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/blddir.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/docsrc.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/docuhier.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/infostr.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/multss.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/newlib.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/repbkcas.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/CDR/tlkitmod.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/addbkcas.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/bkcase.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/blddir.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/docsrc.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/docuhier.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/infostr.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/multss.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/newlib.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/repbkcas.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/infoAPg/graphics/tlkitmod.cgm Normal file
View File

Binary file not shown.

228
cde/doc/C/guides/infoAPg/preface.sgm Normal file
View File

@@ -0,0 +1,228 @@
<!-- $XConsortium: preface.sgm /main/4 1996/10/03 10:50:52 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. -->
<preface id="InfoAPG.Pref">
<title>Preface</title>
<Para>
The <CiteTitle>Information System Author's and Programmer's Guide</CiteTitle>
does the following:
</para>
<itemizedlist>
<listitem>
<para>
Provides information on building SGML-conforming document files into
a form you can view with the Information Manager.
</para>
</listitem>
<listitem>
<para>
Describes how to create and use style sheets.
</para>
</listitem>
<listitem>
<para>
Describes architectural forms, and explains how to apply them to a DTD so users can
build SGML documents into a form viewable with the Information Manager.
</para>
</listitem>
</itemizedlist>
<Note>
<Para>
To use the Information Manager successfully, your
SGML source must use the generalized
markup specified by the Standard Generalized Markup Language [SGML (ISO-8879)].
</Para>
</Note>
<sect1 id="InfoAPG.Pref.div.1">
<Title>Who Should Use This Book</Title>
<Para>
This guide is intended for technical writers, administrators, and publishers who
are responsible for creating, validating, and building SGML
documents into on-line information libraries viewable in the
CDE Information Manager. Readers should have an
understanding of SGML and the ability to edit an SGML DTD.</Para>
</Sect1>
<sect1 id="InfoAPG.Pref.div.2">
<title>How This Book Is Organized</title>
<para>Explanations of the contents of this book follow:</para>
<ItemizedList>
<listitem>
<para>
Chapter 1, &ldquo;About the Build Process and Tools,&rdquo;
provides an overview of the
Information Manager build process
along with a brief description of the documents and
commands associated with that process.
</para>
</listitem>
<listitem>
<para>
Chapter 2, &ldquo;SGML and Information Manager Document Structure&rdquo;
provides a brief overview of SGML concepts and of the
Information Manager on-line information structure.
</para>
</listitem>
<listitem>
<para>
Chapter 3, &ldquo;Preparing to Build&rdquo;
describes the SGML components you need in order to
build an information library.
</para>
</listitem>
<listitem>
<para>
Chapter 4, &ldquo;Building Information Libraries&rdquo;
covers the process of building and updating an
information library using the <command>dtinfogen</command> commands.
</para>
</listitem>
<listitem>
<para>
Chapter 5, &ldquo;Administering Bookcases&rdquo;
describes how you can modify an existing information
library by copying, removing, rearranging, renaming,
and listing the bookcases in a library.
</para>
</listitem>
<listitem>
<para>
Chapter 6, &ldquo;Troubleshooting&rdquo;
gives troubleshooting advice and discusses build errors, style sheet errors,
and library administration messages.
</para>
</listitem>
<listitem>
<para>
Chapter 7, &ldquo;Understanding Style Sheets&rdquo;
describes the DtInfo Style Sheet model and provides general guidelines
for developing style sheet structure, setting up element path specifications,
and using the Select feature. It also describes element inheritance.
</para>
</listitem>
<listitem>
<para>
Chapter 8, &ldquo;Creating a Style Sheet&rdquo; describes
the available style sheet features
and defines their attributes and values. Provides instructions for
creating a style sheet. Includes examples illustrating
how the features might be used in a style sheet.
</para>
</listitem>
<listitem>
<para>
Chapter 9, &ldquo;Understanding Architectural Forms&rdquo;
describes Information Manager architectural forms and shows how they
fit in the model for the Information Manager build process and tools.
</para>
</listitem>
<listitem>
<para>
Chapter 10, &ldquo;Using Architectural Forms&rdquo;
describes Information Manager
architectural forms and how to apply them in your DTD(s).
</para>
</listitem>
<listitem>
<para>
Chapter 11, &ldquo;Table of Contents Architectural Forms&rdquo; describes
how to apply architectural forms to the elements in your table of contents
DTD so the Information Manager knows how to treat the table of contents
information.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="Q3yRgFBsz1698oL">
<title>Related Documentation</title>
<Para>For additional information about SGML, see:</Para>
<ItemizedList>
<ListItem>
<Para>ISO 8879:
<CiteTitle Pubwork=Book>1986 Information Processing - Text and Office
Systems - Standard Generalized Markup Language
(SGML)</CiteTitle> Geneva, 15 October 1986.
</Para>
</ListItem>
<ListItem>
<Para>
<CiteTitle Pubwork=Book>The SGML Handbook</CiteTitle>, C.F. Goldfarb, Clarendon Press,
Oxford University Press, 1990.
</Para>
</ListItem>
<ListItem>
<Para>
<CiteTitle Pubwork=Book>Practical SGML, Second Edition</CiteTitle>, Eric van Herwijnen,
Kluwer Academic Publishers, 1994.
</Para>
</ListItem>
<ListItem>
<Para>
SGML Open Home Page, http://www.sgmlopen.org/sgml/docs/index.html
</Para>
</ListItem>
</ItemizedList>
</Sect1>
<sect1 id="InfoAPG.Pref.div.4">
<title>What DocBook SGML Markup Means</title>
<para>This book is written in the Structured Generalized Markup
Language (SGML) using the DocBook Document Type Definition (DTD).
The following table describes the DocBook markup used for
various semantic elements.
</para>
<table id="InfoAPG.Pref.tbl.1" frame="Topbot">
<title>DocBook SGML Markup</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colwidth="1.65in">
<colspec colwidth="2.63in">
<colspec colwidth="2.92in">
<thead>
<row>
<entry align="left" valign="bottom"><para><literal>Markup Appearance
</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>
Semantic Element(s)</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>
Example</literal></para></entry></row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><para><command>AaBbCc123</command></para></entry>
<entry align="left" valign="top"><para>The names of commands.</para></entry>
<entry align="left" valign="top"><para>Use the <command>ls</command> command to list files.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><literal>AaBbCc123</literal></para></entry>
<entry align="left" valign="top"><para>The names of command options.</para></entry>
<entry align="left" valign="top"><para>Use <command>ls</command> <literal>&minus;a</literal>
to list all files.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">AaBbCc123</symbol></para></entry>
<entry align="left" valign="top"><para>Command-line placeholder:
replace with a real name or value.</para></entry>
<entry align="left" valign="top"><para>To delete a file, type <command>rm
</command> <symbol role="Variable">filename</symbol>.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>AaBbCc123</filename></para></entry>
<entry align="left" valign="top"><para>The names of files and
directories.</para></entry>
<entry align="left" valign="top"><para>Edit your <filename>.login</filename>
file.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><emphasis>AaBbCc123</emphasis></para></entry>
<entry align="left" valign="top"><para>Book titles, new words or terms, or
words to be emphasized.</para></entry>
<entry align="left" valign="top"><para>Read Chapter 6 in <emphasis>User's
Guide</emphasis>.
These are called <emphasis>class</emphasis> options.
You <emphasis>must</emphasis> be root to do this.</para></entry>
</row></tbody></tgroup></table>
</sect1>
</preface>