1127 lines
37 KiB
Plaintext
1127 lines
37 KiB
Plaintext
<!-- $XConsortium: ch03.sgm /main/4 1996/10/11 09:23:39 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.3">
|
|
<title id="sidr7JBU3pBt8oL">Preparing to Build</title>
|
|
<indexterm><primary>book source</primary><secondary>preparing</secondary>
|
|
</indexterm>
|
|
<para>
|
|
Tools in the Information System Toolkit process a number of
|
|
different SGML files to build documents that are displayable in the
|
|
Information Manager. This section discusses the files required to
|
|
build documents with the Information Manager.
|
|
<indexterm><primary>information libraries</primary><secondary>building
|
|
</secondary><tertiary>required files</tertiary></indexterm>
|
|
</para>
|
|
<sect1>
|
|
<title id="n1Pih7JBbpoBt8oL">Required Files</title>
|
|
<indexterm><primary>build requirements</primary>
|
|
<secondary>required files</secondary></indexterm>
|
|
<para>
|
|
To build an Information Manager browsable book, you must supply the following:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="jbQg4bBSxI9X3cS">Book Source Document(s)
|
|
</link> — These SGML-conforming documents contain the text of the book
|
|
and its SGML markup.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="n3NGoZbBosJ9X3cS">Table of Contents File
|
|
</link> — Each Information Manager book requires a hypertext TOC that
|
|
conforms to <filename>dtinfoTOC.dtd(5)</filename>.
|
|
You can create the hypertext TOC with the
|
|
<command>dtinfogen tocgen</command> command.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="j3fa6XBbiK9X3cS">Style Sheets</link> —
|
|
Style sheets govern the formatting of your books.
|
|
In Information Manager, you can specify style sheet
|
|
information for both
|
|
the on-line and printed output of your books.
|
|
Style sheets must conform to <filename>dtinfoStyle.dtd(5)</filename>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="r58-aZBwFK9X3cS">Bookcase Specification</link>
|
|
— The bookcase specification, which conforms to
|
|
<filename>dtinfoBook.dtd(5)</filename>, contains or makes reference
|
|
to all of the SGML entities
|
|
required by the Information Manager during the build process.
|
|
A bookcase specification can be used to build a single book or
|
|
a complete Information Manager information library that
|
|
contains many books.
|
|
</para>
|
|
<para>
|
|
<link linkend="TcQg4bBSxI9X3cS">Creating a Bookcase Specification</link>
|
|
describes how you can create this document.
|
|
An example is shown in <link linkend="XcQg4bBSxI9X3cS">Example Bookcase
|
|
Specification</link>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
<!--)))))))))))))))))))))))))))))))))))))))))))))))))-->
|
|
<sect1>
|
|
<title id="jbQg4bBSxI9X3cS">Book Source</title>
|
|
<indexterm><primary>book source</primary></indexterm>
|
|
<indexterm><primary>required files</primary>
|
|
<secondary>book source</secondary></indexterm>
|
|
<para>
|
|
At least one conforming SGML document is required for each book
|
|
in your bookcase. A single SGML document may constitute a
|
|
complete book or it may be only one of several documents
|
|
that make up a complete book.
|
|
</para>
|
|
<para>
|
|
The SGML book source, whether it is one document or several,
|
|
includes the text (content) of the book and its SGML markup.
|
|
Through the use of entity references, the document source may
|
|
also make reference to external text and non-text entities
|
|
that reside in separate files or external system units.
|
|
</para>
|
|
<para>
|
|
Entity references cause the specified entities to be embedded
|
|
at the reference point in the SGML document.
|
|
</para>
|
|
<para>
|
|
A document type definition (DTD) must be associated with the
|
|
SGML document source. The DTD defines the structural
|
|
relationships of elements such as titles, paragraphs, lists, tables,
|
|
graphics, and so forth.
|
|
</para>
|
|
<para>
|
|
In most cases the DTD resides outside of the SGML document and
|
|
is referenced by it, typically in a DOCTYPE declaration at the top of
|
|
each SGML-conforming document. See the example
|
|
<link linkend="mhgjriBo9H9X3cS">DOCTYPE Declaration</link> below.
|
|
</para>
|
|
<para>
|
|
The figure <link linkend="kADiOlB78H9X3cS">SGML Document Source</link>
|
|
illustrates the relationship between documents, including hypertext
|
|
TOCs, and external entities, that can be used to produce an
|
|
Information Manager book.
|
|
</para>
|
|
<figure>
|
|
<title id="kADiOlB78H9X3cS">SGML Document Source</title>
|
|
<graphic id="gr55" entityref="infoapg.fig.2"></graphic>
|
|
</figure>
|
|
<para>
|
|
An SGML declaration is required by the SGML parser. It specifies the
|
|
character set and SGML delimiters that are valid for the document
|
|
instance. <filename>dtinfo.decl(5)</filename> is the SGML declaration
|
|
used by the Information Manager.
|
|
<indexterm><primary>declaration</primary><secondary>SGML</secondary></indexterm>
|
|
<indexterm><primary>SGML declaration</primary></indexterm>
|
|
</para>
|
|
<para>
|
|
The Information Manager declaration <filename>dtinfo.decl(5)</filename>
|
|
cannot be substituted or overridden. Therefore, your DTD's element
|
|
declarations must contain the omitted tag minimization parameter
|
|
(for example: <computeroutput>“-o” or “--”
|
|
</computeroutput>) because the Information Manager SGML declaration has
|
|
OMITTAG set to YES. For more information,
|
|
see <citetitle pubwork="Book">Element Declaration</citetitle>,
|
|
in <citetitle pubwork="Book">International Standards Organization (ISO) 8879
|
|
</citetitle>.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The Information Manager's SGML declaration
|
|
<filename>dtinfo.decl</filename> is supplied with the Information
|
|
Manager and is referenced automatically when you invoke the
|
|
<command>dtinfogen build</command>, <command>dtinfogen
|
|
validate</command>, or <command>dtinfogen update</command> commands.
|
|
</para>
|
|
</note>
|
|
<figure>
|
|
<title id="mhgjriBo9H9X3cS">Example DOCTYPE Declaration</title>
|
|
<programlisting>
|
|
<!DOCTYPE Chapter PUBLIC
|
|
“-//HaL and O'Reilly//DTD DocBook//EN”
|
|
[
|
|
<!ENTITY % ISOlist PUBLIC
|
|
“-//Common Desktop Environment//ENTITIES ISO Catalog//EN”>
|
|
%ISOlist;
|
|
%ISOlat1;
|
|
%ISOnum;
|
|
%ISOpub;
|
|
%ISOtech;
|
|
<!ENTITY % halpubs SYSTEM “hal.gml” >
|
|
%halpubs;
|
|
]>
|
|
<CHAPTER ID=”CH-1015-3-1” LABEL=”3”><TITLE>Working in the
|
|
X Environment</TITLE>
|
|
<TITLEABBREV>Working in the X Environment</TITLEABBREV>
|
|
<HIGHLIGHTS>
|
|
<PARA>This chapter shows you how to begin working
|
|
productively in the X environment. It describes how to:
|
|
</PARA>
|
|
…
|
|
</programlisting>
|
|
</figure>
|
|
<note>
|
|
<para>
|
|
See <link linkend="Q3yRgFBsz1698oL">Related Documentation</link>
|
|
for a listing of books that describe how to create
|
|
SGML-conforming documents.
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
|
|
<!--)))))))))))))))))))))))))))))))))))))))))))))))-->
|
|
|
|
<sect1>
|
|
<title id="n3NGoZbBosJ9X3cS">Table of Contents</title>
|
|
<indexterm><primary>table of contents</primary></indexterm>
|
|
<para>
|
|
Each book you build as part of an Information Manager
|
|
information library is required to have a hypertext table of
|
|
contents (TOC). Hypertext links connect the list of section
|
|
titles in the TOC with the actual on-line sections to which
|
|
those titles refer.
|
|
<indexterm><primary>required files</primary>
|
|
<secondary>table of contents</secondary></indexterm>
|
|
</para>
|
|
<para>
|
|
The TOC is displayed in the Information Manager as the initial
|
|
entry point to a book. It establishes the default linear path of
|
|
the book — the path that a reader would take if he or she
|
|
were reading a hard copy version of the book. When a reader selects
|
|
(clicks on) a section title in the TOC, the browser traverses
|
|
the link and displays the on-line section in a reading window.
|
|
</para>
|
|
<para>
|
|
In the Information Manager, the TOC is also a powerful hypertext
|
|
navigation tool with important features that help to orient the
|
|
reader spatially within the on-line document. For example,
|
|
using information supplied by the TOC, the Information Manager
|
|
graphical map is able to display the relative locations of sections
|
|
in the book. And, using the TOC, the Information Manager's Book List
|
|
window's collapsible book list provides hierarchical information
|
|
about the book's structure.
|
|
</para>
|
|
<para>In order to set up the hypertext links required in the
|
|
TOC, the Information Manager must be able to identify sections
|
|
in your document source. This is done through the application
|
|
of the Information Manager architectural forms to your book's DTD.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Before you can create a TOC for your book, you must apply
|
|
Information Manager architectural forms to identify every element
|
|
in your DTD that is to be referenced as a section in the TOC.
|
|
This enables Information Manager's table of contents generator
|
|
to extract the section's title and its unique section ID value.
|
|
(See <link linkend="S3CTVcBfQJ9X3cS">Table of Contents Architectural Forms
|
|
</link>.)
|
|
</para>
|
|
</note>
|
|
|
|
<!--)))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
|
|
|
|
<sect2>
|
|
<title id="n8aJ92dBIsI9X3cS">Creating a Table of Contents</title>
|
|
<indexterm><primary>table of contents</primary>
|
|
<secondary>creating</secondary></indexterm>
|
|
<para>
|
|
You use the <command>dtinfogen tocgen</command> command to create the
|
|
TOCs for each of your books.
|
|
</para>
|
|
|
|
<sect3>
|
|
<title id="Sb4E8eBmqJ9X3cS">Running dtinfogen tocgen</title>
|
|
<para>Here's an example of using <command>dtinfogen tocgen</command>
|
|
to generate a table of contents.
|
|
Before running <command>dtinfogen tocgen</command>,
|
|
ensure that the book’s source files:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Contain a DTD or include a reference to a DTD to which the
|
|
Information Manager architectural forms have been applied.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Contain valid SGML markup based on the DTD.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The basic <command>dtinfogen tocgen</command> command line
|
|
for this example is:</para>
|
|
<programlisting>
|
|
dtinfogen tocgen -T <replaceable>/usr/pers</replaceable> -f <replaceable>TOC.file</replaceable> -id <replaceable>asg.toc</replaceable> -title <replaceable>“Acoustic Sound Generators”</replaceable> <replaceable>pref.sgm</replaceable> <replaceable>ch01.sgm</replaceable> <replaceable>ch02.sgm</replaceable> <replaceable>ch03.sgm</replaceable> <replaceable>appx.sgm</replaceable>
|
|
</programlisting>
|
|
<para>
|
|
where
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-T</option> <replaceable>/usr/pers</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the directory in which temporary files are
|
|
placed during the build process. The default is to use the
|
|
environment variable <systemitem class="environvar">TMPDIR</systemitem>.
|
|
If variable <systemitem class="environvar">TMPDIR</systemitem> is not set,
|
|
<filename>/usr/tmp</filename> is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>-f</option> <replaceable>TOC.file</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the name of the file to which the output of
|
|
the <command>dtinfogen tocgen</command> process is sent.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>-id</option> <replaceable>asg.toc</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the TOC identifier in the newly created TOC file.
|
|
The alphanumeric string value of <option>-id</option>,
|
|
in this case <replaceable>asg.toc</replaceable>, associates the
|
|
table of contents file with the specific set of book source files
|
|
for which the TOC was generated. You must use a value that is
|
|
unique across bookcases in each library.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><option>-title</option>
|
|
<replaceable>“Acoustic Sound Generators”</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the TOC title. The value of <option>-title</option>,
|
|
in this case, <replaceable>“Acoustic Sound Generators”</replaceable>,
|
|
becomes the title of the newly created TOC file.
|
|
</para>
|
|
<para>
|
|
The TOC title identifies the table of contents of the book
|
|
with which it is associated. This name appears as the title of
|
|
the TOC node when viewed in the Information Manager reading window.
|
|
</para>
|
|
<para>
|
|
If you don't use the <option>-title</option> flag to supply a name,
|
|
you may open the TOC file after it is generated and replace the
|
|
default string <computeroutput>$Title = “Table of Contents”
|
|
</computeroutput> with the appropriate title.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><replaceable>pref.sgm</replaceable> <replaceable>ch01.sgm</replaceable>
|
|
<replaceable>ch02.sgm</replaceable> <replaceable>ch03.sgm</replaceable>
|
|
<replaceable>appx.sgm</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the names of the document entities from which the
|
|
table of contents section title listing will be generated.
|
|
</para>
|
|
<para>The document entities should be entered on the command
|
|
line in the order in which their contents should appear in
|
|
the on-line book.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
The <command>dtinfogen tocgen</command> program validates your
|
|
document entities against their DTDs, verifying that the
|
|
Information Manager architectural forms have been applied.
|
|
</para>
|
|
<para>
|
|
After successful validation, <command>dtinfogen tocgen</command>
|
|
then extracts the list of section titles and section identifiers
|
|
from the book source files and generates the TOC file.
|
|
</para>
|
|
<para>
|
|
If you later add or remove sections in any of the book source files,
|
|
you must regenerate the TOC.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!--(((((((((((((((((((((((((((((((((((((((((((((-->
|
|
|
|
<sect1>
|
|
<title id="j3fa6XBbiK9X3cS">Using Style Sheets</title>
|
|
<indexterm><primary>required files</primary>
|
|
<secondary>style sheet</secondary></indexterm><indexterm>
|
|
<primary>style sheet</primary><secondary>using</secondary></indexterm>
|
|
<para>
|
|
Style sheets control the formatted appearance of your books
|
|
in Information Manager. You can use a single style sheet to
|
|
specify both the on-line display characteristics of your books
|
|
in the Information Manager as well as the printed output
|
|
characteristics of your books when printed from the
|
|
Information Manager.
|
|
</para>
|
|
<para>
|
|
You can also use a single style sheet to describe how
|
|
to format multiple documents within a bookcase, or you can
|
|
use multiple style sheets to process different document types
|
|
within the same bookcase.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The figure <link linkend="JmNvZbBE6K9X3cS">How Multiple Style Sheets
|
|
are Used</link> illustrates how books and sections within books
|
|
can use different style sheets.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="n2PY0rbBgJJ9X3cS">Specifying Style Sheets at Different
|
|
Levels</link> explains how style sheets can be specified at
|
|
the bookcase level, at the book level, and at the section level.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="bPY0rbBgJJ9X3cS">Example Bookcase Using Multiple
|
|
Style Sheets</link> shows an example bookcase specification
|
|
that uses four style sheets to provide formatting information
|
|
for three books.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Once you have built an information database, you can use
|
|
the <command>dtinfogen update</command>
|
|
<indexterm><primary>Information Manager</primary>
|
|
<secondary>commands</secondary>
|
|
<tertiary>dtinfogen update</tertiary></indexterm>
|
|
command to reformat the sections using new style sheet information.
|
|
See <link linkend="WmNvZbBE6K9X3cS">Updating Style Sheets in Built
|
|
Bookcases</link>.
|
|
</para>
|
|
<para>For information about creating style sheets,
|
|
see <link linkend="BtCmaaB0ang24aK">Creating a Style Sheet</link>.
|
|
</para>
|
|
<figure>
|
|
<title id="JmNvZbBE6K9X3cS">How Multiple Style Sheets are Used</title>
|
|
<graphic id="gr56" entityref="infoapg.fig.3"></graphic>
|
|
</figure>
|
|
<para>
|
|
As shown in the illustration, the default style sheet
|
|
<replaceable>Style01</replaceable> will be used to format
|
|
all books in a bookcase unless a different style sheet is
|
|
specified at the book level, or at the section level.
|
|
When a style sheet other than the default style sheet is specified,
|
|
it is valid only for formatting the specified book or the section
|
|
for which it was defined. Processing then continues with the
|
|
default style sheet unless a different style sheet is again specified.
|
|
</para>
|
|
|
|
<!--))))))))))))))))))))))))))))))))))))))))))))))))-->
|
|
|
|
<sect2>
|
|
<title id="n5mNvZbBE6K9X3cS">Defining Style Sheets</title>
|
|
<indexterm><primary>style sheet</primary>
|
|
<secondary>defining</secondary></indexterm>
|
|
<para>
|
|
You must define a default style sheet for every
|
|
bookcase in your Information Manager library
|
|
(see <link linkend="TcQg4bBSxI9X3cS">Creating a
|
|
Bookcase Specification</link>.)
|
|
</para>
|
|
<sect3>
|
|
<title id="n2PY0rbBgJJ9X3cS">Specifying Style Sheets at Different Levels</title>
|
|
<para>
|
|
Each style sheet must have a unique name, specified at the top
|
|
of the style sheet document itself. All of the style sheets
|
|
used in a bookcase can be defined using entity declarations
|
|
at the top of the bookcase specification. Here is an example
|
|
of entity declarations for a set of style sheets:
|
|
</para>
|
|
<programlisting>
|
|
[
|
|
<!-- Style sheets -->
|
|
<!ENTITY Style01 SYSTEM “InfoMgrRN/style01.sty” >
|
|
<!ENTITY Style02 SYSTEM “Perl/perl.sty” >
|
|
<!ENTITY PrefSty SYSTEM “Preface/pref.sty” >
|
|
<!ENTITY IDXSty SYSTEM “Index/IDX.sty” >
|
|
...............
|
|
...............
|
|
...............
|
|
]
|
|
</programlisting>
|
|
<para>
|
|
The declared style sheets are referenced from within the
|
|
bookcase specification using entity references.
|
|
<link linkend="bPY0rbBgJJ9X3cS">Example Bookcase Using Multiple
|
|
Style Sheets</link> illustrates a complete bookcase specification
|
|
with all entity declarations and style sheet entity references.
|
|
</para>
|
|
<sect4>
|
|
<title id="SmNvZbBE6K9X3cS">Specifying a Style Sheet at the Bookcase
|
|
Level</title>
|
|
<indexterm><primary>style sheet</primary>
|
|
<secondary>bookcase level</secondary></indexterm>
|
|
<para>
|
|
The default style sheet is specified at the bookcase level.
|
|
Entity references are made to any other style sheets that are
|
|
defined for the bookcase.
|
|
</para>
|
|
<para>The BOOKCASE element start tag begins the listing of
|
|
the bookcase's contents, including the style sheets that
|
|
will be used and the SGML document entities that will be processed.
|
|
</para>
|
|
<para>
|
|
The initial bookcase statement
|
|
<computeroutput><BOOKCASE StyleSheet=style01></computeroutput>
|
|
names <replaceable>style01</replaceable> as the default style sheet.
|
|
After the BOOKCASENAME and BOOKCASEDESC elements are specified,
|
|
entity references are made to all style sheet entities that will
|
|
be used to format the bookcase's contents. For example:
|
|
</para>
|
|
<programlisting>
|
|
<BOOKCASE StyleSheet=Style01>
|
|
<BOOKCASENAME>INFOMGR</>
|
|
<BOOKCASEDESC>Info Manager Release Notes</>
|
|
|
|
<!-- Include the style sheets. -->
|
|
|
|
&Style01;
|
|
&Style02;
|
|
&PrefSty;
|
|
&IDXSty;
|
|
</programlisting>
|
|
|
|
<para>
|
|
The ampersand and semicolon in each of the entity references:
|
|
<computeroutput>&Style01;</computeroutput>,
|
|
<computeroutput>&Style02;</computeroutput>,
|
|
<computeroutput>&PrefSty;</computeroutput>, and
|
|
<computeroutput>&IDXSty;</computeroutput>are the open and close
|
|
delimiters for entity references.
|
|
</para>
|
|
</sect4>
|
|
<sect4>
|
|
<title id="TmNvZbBE6K9X3cS">Specifying a Style Sheet at the Book Level</title>
|
|
<indexterm><primary>style sheet</primary>
|
|
<secondary>book level</secondary></indexterm>
|
|
<para>
|
|
The default style sheet specified by the BOOKCASE element
|
|
is used for each book in a bookcase unless a different style
|
|
sheet is specified at the book level or at the section level.
|
|
</para>
|
|
<para>
|
|
The BOOK element start tag begins the listing of the book's
|
|
contents, and refers to the style sheet that will be used
|
|
(if it is different than the default style sheet). For example:
|
|
</para>
|
|
<programlisting>
|
|
</BOOK>
|
|
|
|
<!-- Perl Manual -->
|
|
<BOOK StyleSheet=Style02>
|
|
</programlisting>
|
|
<para>
|
|
This statement specifies that <computeroutput>Style02</computeroutput>
|
|
will be used to format the <citetitle>Perl Manual</citetitle> SGML source.
|
|
</para>
|
|
<para>
|
|
After the book's source files are processed, the next
|
|
BOOK element start tag resets the style sheet to the default
|
|
style sheet value specified by the initial BOOKCASE element start tag,
|
|
unless another style sheet is specified.
|
|
</para>
|
|
</sect4>
|
|
<sect4>
|
|
<title id="VmNvZbBE6K9X3cS">Specifying a Style Sheet at the
|
|
Section Level</title>
|
|
<indexterm><primary>style sheet</primary>
|
|
<secondary>section level</secondary></indexterm>
|
|
<para>
|
|
Section-level style sheets are not specified inside the book
|
|
element listing of the bookcase file. Instead, they are specified
|
|
in a book's document type definition (DTD) using Information Manager
|
|
architectural forms. The Information Manager architectural forms
|
|
identify specific section-level elements in a book to which
|
|
the formatting characteristics of a specified style sheet
|
|
will apply.
|
|
</para>
|
|
<para>
|
|
For related information, see:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="BtCmaaB0ang24aK">Creating a Style Sheet</link>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="vSMTMZBRyng24aK">Understanding Architectural Forms</link>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect4>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<!--)))))))))))))))))))))))))))))))))))))))))))))))))-->
|
|
|
|
<sect2>
|
|
<title id="bPY0rbBgJJ9X3cS">Example Bookcase Using Multiple Style Sheets</title>
|
|
|
|
<para>
|
|
This is an example of a bookcase specification that defines
|
|
three books and uses four style sheets. The style sheet entities
|
|
<computeroutput>&PrefSty;</computeroutput> and
|
|
<computeroutput>&IDXSty;</computeroutput> are referenced
|
|
in the book DTD(s).
|
|
</para>
|
|
<programlisting>
|
|
<!DOCTYPE Bookcase PUBLIC
|
|
“-//Common Desktop Environment//DTD DtInfo Bookcase Description//EN”
|
|
[
|
|
<!-- Style sheets -->
|
|
<!ENTITY style01 SYSTEM “InfoMgrRN/style01.sty” >
|
|
<!ENTITY style02 SYSTEM “Perl/perl.sty” >
|
|
<!ENTITY PrefSty SYSTEM “Preface/pref.sty” >
|
|
<!ENTITY IDXSty SYSTEM “Index/IDX.sty” >
|
|
<!ENTITY TOCSTY SYSTEM “TOC/TOC.sty” >
|
|
|
|
<!-- Book documents declared as SUBDOC -->
|
|
<!ENTITY tocfile SYSTEM “Small/small.toc” SUBDOC >
|
|
<!ENTITY ch03 SYSTEM “Small/ch03.sgm” SUBDOC >
|
|
<!ENTITY xlsc SYSTEM “Small/xlsc.sgm” SUBDOC >
|
|
<!ENTITY rnotes.TOC SYSTEM “InfoMgrRN/rnotes.TOC” SUBDOC >
|
|
<!ENTITY rnotes.N SYSTEM “InfoMgrRN/rnotes.N” SUBDOC >
|
|
<!ENTITY perl.TOC SYSTEM “Perl/perl.TOC” SUBDOC >
|
|
<!ENTITY copytrade.N SYSTEM “Perl/copytrade.N” SUBDOC >
|
|
<!ENTITY about.N SYSTEM “Perl/02about.N” SUBDOC >
|
|
<!ENTITY intro.N SYSTEM “Perl/1intro.N” SUBDOC >
|
|
<!ENTITY start.N SYSTEM “Perl/2start.N” SUBDOC >
|
|
<!ENTITY datatypes.N SYSTEM “Perl/3datatypes.N” SUBDOC >
|
|
<!ENTITY form.N SYSTEM “Perl/4form.N” SUBDOC >
|
|
<!ENTITY commands.N SYSTEM “Perl/5commands.N” SUBDOC >
|
|
<!ENTITY perl.NDX SYSTEM “Perl/perl.NDX” SUBDOC >
|
|
<!ENTITY comments.N SYSTEM “Perl/comments.N” SUBDOC >
|
|
|
|
|
|
]>
|
|
<BOOKCASE StyleSheet=style01>
|
|
<BOOKCASENAME>Information Manager</>
|
|
<BOOKCASEDESC>Information Manager Release Notes</>
|
|
|
|
<!-- Include the four style sheets. -->
|
|
|
|
&style01;
|
|
&style02;
|
|
&PrefSty;
|
|
&IDXSty;
|
|
|
|
<!-- *****BOOK 1 - Small example book***** -->
|
|
<BOOK>
|
|
<TITLE>DocBook DTD Examples</>
|
|
<SHORTTITLE>SGML Examples</>
|
|
|
|
<TAB TabLoc=”RE-1015-XLSCLIENTS-1”>Manpage</>
|
|
|
|
<TOCFILE>&tocfile;</TOCFILE>
|
|
<FILE>&ch03;</FILE>
|
|
<FILE>&xlsc;</FILE>
|
|
</BOOK>
|
|
|
|
<!-- *****BOOK 2 - Information Manager Release Notes***** -->
|
|
<BOOK>
|
|
<TITLE>Information Manager Release Notes</>
|
|
<SHORTTITLE>Info Manager Notes</>
|
|
|
|
<TAB TabLoc=”7M6zf5B0CM9X3cS”>Contents</>
|
|
<TAB TabLoc=”wP3zf5B-BM9X3cS”>Features</>
|
|
<TAB TabLoc=”yP3zf5B-BM9X3cS”>To Do</>
|
|
<TAB TabLoc=”mJ6G0CB1LG9I8gW”>Link Demos</>
|
|
<TAB TabLoc=”0K6zf5B-BM9X3cS”>Figures</>
|
|
|
|
<TOCFILE>&rnotes.TOC;</>
|
|
<FILE>&rnotes.N;</>
|
|
</BOOK>
|
|
|
|
<!-- *****BOOK 3 - Perl Manual***** -->
|
|
<BOOK StyleSheet=style02>
|
|
<TITLE>Perl Manual</>
|
|
|
|
<TAB TabLoc=”Xmhyf5Bu6M9X3cS”>Contents</>
|
|
<TAB TabLoc=”3tpQGzASEYy94aK”>About This Book</>
|
|
<TAB TabLoc=”Oo9fP6B59WwA0YK”>Index</>
|
|
<TAB TabLoc=”DNph.0BBMXwA0YK”>Comments</>
|
|
|
|
<TOCFILE>&perl.TOC;</>
|
|
<FILE>&copytrade.N;</>
|
|
<FILE>&about.N;</>
|
|
<FILE>&intro.N;</>
|
|
<FILE>&start.N;</>
|
|
<FILE>&datatypes.N;</>
|
|
<FILE>&form.N;</>
|
|
<FILE>&commands.N;</>
|
|
<FILE>&perl.NDX;</>
|
|
<FILE>&comments.N;</>
|
|
</BOOK>
|
|
|
|
</BOOKCASE></programlisting>
|
|
<note>
|
|
<para>This example bookcase specification conforms to the
|
|
<filename>dtinfoBook.dtd</filename> distributed with the Information Manager.
|
|
</para>
|
|
</note>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!--)))))))))))))))))))))))))))))))))))))))))))))))))))-->
|
|
|
|
<sect1>
|
|
<title id="r58-aZBwFK9X3cS">Bookcase Specification</title>
|
|
<indexterm><primary>bookcase specification</primary></indexterm>
|
|
<indexterm><primary>required files</primary>
|
|
<secondary>bookcase specification</secondary></indexterm>
|
|
<para>
|
|
To build a bookcase into an information library, you use a bookcase
|
|
specification to tell the Information Manager tools what to build.
|
|
</para>
|
|
<para>
|
|
In its simplest form, the bookcase specification
|
|
contains the bookcase name and bookcase description,
|
|
the style sheets that describe the formatting of each book,
|
|
and the SUBDOC entity references for the SGML documents
|
|
comprising the books.
|
|
</para>
|
|
<para>
|
|
You must use SGML SUBDOC entity declarations
|
|
<indexterm><primary>SGML</primary>
|
|
<secondary>SUBDOC entity declarations</secondary></indexterm>
|
|
to include the book documents in the bookcase specification.
|
|
The structure of the bookcase specification is defined in
|
|
<filename>dtinfoBook.dtd</filename>.
|
|
</para>
|
|
<para>
|
|
A general procedure for producing a bookcase specification
|
|
is provided in the section <link linkend="TcQg4bBSxI9X3cS">
|
|
Creating a Bookcase Specification</link>.
|
|
</para>
|
|
<para>
|
|
The information you need to supply in the bookcase specification includes:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Bookcase name</term>
|
|
<listitem>
|
|
<para>
|
|
This name is used by the Information Manager and by the
|
|
internal search engine. It must be no longer than eight
|
|
alphanumeric characters and it must be unique within the bookcase.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Bookcase description</term>
|
|
<listitem>
|
|
<para>
|
|
This is a description or synopsis of the book(s) comprising the bookcase.
|
|
Typical examples might be: <citetitle>UNIX Administration Guides</citetitle>,
|
|
or <citetitle>Scientific Papers on Acoustic Sound Generation</citetitle>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>One or more style sheets</term>
|
|
<listitem>
|
|
<para>
|
|
Style sheets contain the collection of formatting instructions
|
|
that define how an SGML document should be formatted both on-line
|
|
and in print. You must identify one style sheet as the default style
|
|
sheet for all books in the bookcase specification.
|
|
</para>
|
|
<para>
|
|
You can include style sheets in the bookcase specification
|
|
or you can reference them via an entity declaration at the top
|
|
of the bookcase specification.
|
|
See <link linkend="XcQg4bBSxI9X3cS">Example Bookcase Specification</link>.
|
|
</para>
|
|
<para>
|
|
To understand how the Information Manager handles multiple style sheets
|
|
in a single bookcase specification, see <link linkend="j3fa6XBbiK9X3cS">
|
|
Using Style Sheets</link>.
|
|
</para>
|
|
<para>
|
|
For information about creating style sheets,
|
|
see <link linkend="BtCmaaB0ang24aK">Creating a Style Sheet</link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>One or more books</term>
|
|
<listitem>
|
|
<para>
|
|
The information you need to supply for each book in the
|
|
bookcase specification includes:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Book title</term>
|
|
<listitem>
|
|
<para>The full title of each book in the bookcase.
|
|
The length of a book title is technically unlimited.
|
|
Optimally however, titles should be no longer than 50 characters in length.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Book short title</term>
|
|
<listitem>
|
|
<para>
|
|
An optional abbreviated title for each book.
|
|
The short title is used by the Information Manager's search engine.
|
|
Technically, the length of the short title is unlimited,
|
|
but optimally it should be no more than 20 characters in length.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Tab information</term>
|
|
<listitem>
|
|
<para>
|
|
Tabs are displayed in an Information Manager reading window.
|
|
They resemble binder tabs and enable readers to move quickly
|
|
to different sections in an on-line book.
|
|
</para>
|
|
<para>
|
|
The tab information you supply in the bookcase specification
|
|
includes the names and unique identifiers of sections in a book
|
|
that will be available through the browser interface.
|
|
</para>
|
|
<para>
|
|
Tabs are optional and one or more of them may be specified
|
|
for each book in the bookcase. The length of the text of each
|
|
tab and the number of tabs in a given book is technically unlimited.
|
|
However, on-line readability will be improved by using
|
|
relatively concise tab names such as <literal>Contents</literal>,
|
|
<literal>Preface</literal>, <literal>Index</literal>, and so forth,
|
|
and limiting the number of tabs to be displayed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Table of contents (TOC)</term>
|
|
<listitem>
|
|
<para>
|
|
Each book defined in the bookcase specification must have a
|
|
hypertext TOC that conforms to the Information Manager
|
|
<filename>dtinfoTOC.dtd</filename>.
|
|
</para>
|
|
<para>
|
|
You can use the <command>dtinfogen tocgen</command> command
|
|
to produce an Information Manager table of contents.
|
|
See <link linkend="n8aJ92dBIsI9X3cS">Creating a Table of Contents</link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Book source documents</term>
|
|
<listitem>
|
|
<para>
|
|
These are the SGML-conforming document entities that make up each book.
|
|
</para>
|
|
<para>
|
|
Because these documents may conform to different DTDs,
|
|
you must use SGML SUBDOC entities to pull in the source
|
|
information during the build process.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
The figure <link linkend="xJDiOlB78H9X3cS">Bookcase Specification</link>
|
|
illustrates the relationship of the bookcase specification and other
|
|
documents used to build an information library.
|
|
</para>
|
|
<figure>
|
|
<title id="xJDiOlB78H9X3cS">Bookcase Specification</title>
|
|
<graphic id="gr57" entityref="infoapg.fig.4"></graphic>
|
|
</figure>
|
|
<sect2>
|
|
<title id="TcQg4bBSxI9X3cS">Creating a Bookcase Specification</title>
|
|
<indexterm><primary>bookcase specification</primary>
|
|
<secondary>creating</secondary></indexterm>
|
|
<para>
|
|
To create a bookcase specification:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Using a text editor such as <command>vi</command>, <command>emacs</command>,
|
|
or an appropriately configured SGML editor, open a new file in
|
|
your book's build area. If you prefer, you can copy the
|
|
<link linkend="XcQg4bBSxI9X3cS">Example Bookcase Specification</link>
|
|
below or any example bookcase specification included in this
|
|
documentation and modify it for your purposes.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
At the top of the file, specify the bookcase DTD. For example:
|
|
</para>
|
|
<programlisting>
|
|
<!DOCTYPE Bookcase PUBLIC
|
|
“-//Common Desktop Environment//DTD DtInfo Bookcase Description//EN”
|
|
[
|
|
</programlisting>
|
|
<para>
|
|
The open brace ( [ ) at the end of the DOCTYPE declaration indicates
|
|
that a set of entity declarations will follow.
|
|
See the <filename>dtinfoBook.dtd(5)</filename> man page.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Using an entity declaration, specify the style sheet to use.
|
|
You can define multiple style sheets using entity declarations.
|
|
</para>
|
|
|
|
<programlisting>
|
|
<!-- Style sheets -->
|
|
<!ENTITY style01 SYSTEM “style01.sty” >
|
|
</programlisting>
|
|
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Using the SGML SUBDOC entity feature, specify the documents
|
|
that will comprise the book, including the TOC.
|
|
</para>
|
|
|
|
<programlisting>
|
|
<!-- Book files declared as SUBDOC -->
|
|
<!ENTITY tocfile SYSTEM “small.toc” SUBDOC >
|
|
<!ENTITY ch03 SYSTEM “ch03.sgm” SUBDOC >
|
|
<!ENTITY xlsc SYSTEM “xlsc.sgm” SUBDOC >
|
|
</programlisting>
|
|
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
After specifying all of the entities you will be using,
|
|
close the entity declaration with a closing brace ( ] )
|
|
and a closing declaration delimiter ( > ).
|
|
</para>
|
|
<programlisting>]></programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Enter the SGML start tag <BOOKCASE> and specify the default
|
|
style sheet to use for the bookcase.
|
|
</para>
|
|
<programlisting>
|
|
<BOOKCASE StyleSheet=sty1>
|
|
</programlisting>
|
|
<para>
|
|
In this example, the BOOKCASE element's attribute
|
|
<replaceable>StyleSheet</replaceable> is assigned the value
|
|
<systemitem>sty1</systemitem>, which is the name of the STYLESHEET
|
|
element in the style sheet file <filename>style01.sty</filename>.
|
|
</para>
|
|
<para>
|
|
If multiple style sheets are declared in the entity subset
|
|
declaration, you can specify any one of them as the default
|
|
style sheet for the bookcase.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Enter the BOOKCASENAME and BOOKCASEDESC elements and their
|
|
contents—in this case <replaceable>SMALL</replaceable> and
|
|
<replaceable>Demonstration small bookcase</replaceable>, respectively.
|
|
</para>
|
|
<para>
|
|
BOOKCASENAME can be no longer than eight alphanumeric characters,
|
|
and must not contain periods.
|
|
</para>
|
|
<para>
|
|
Next, using an entity reference, specify the style sheet to be
|
|
included—in this case <computeroutput>style01</computeroutput>.
|
|
</para>
|
|
<programlisting>
|
|
<BOOKCASENAME>SMALL</>
|
|
<BOOKCASEDESC>Demonstration small bookcase</>
|
|
&style01;
|
|
</programlisting>
|
|
<para>
|
|
After referencing all style sheets for the bookcase, begin
|
|
specifying the book(s) that make up the bookcase.
|
|
</para>
|
|
<note>
|
|
<para>Different style sheets can be assigned to different bookcases,
|
|
and even to different books within a bookcase using an identifier
|
|
reference. See <link linkend="j3fa6XBbiK9X3cS">Using Style Sheets</link>.
|
|
For information about creating style sheets, see
|
|
<link linkend="BtCmaaB0ang24aK">Creating a Style Sheet</link>.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Specify the book to build by entering the BOOK element's start tag,
|
|
and the TITLE and SHORTTITLE elements and their contents.
|
|
</para>
|
|
<programlisting>
|
|
<BOOK>
|
|
<TITLE>DocBook DTD Examples</>
|
|
<SHORTTITLE>SGML Examples</>
|
|
</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If you are setting up binder tabs in your book, supply the
|
|
tab information.
|
|
</para>
|
|
<para>
|
|
For each tab, you must specify the TAB element's start tag—
|
|
which requires the TabLoc attribute and its value—and the text
|
|
(in this case “Manpage”) that will appear in the tab when
|
|
it is displayed in the browser.
|
|
</para>
|
|
|
|
<programlisting>
|
|
<TAB TabLoc=“RE-1015-XLSCLIENTS-1”>Manpage</>
|
|
</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Use the <TOCFILE> tag to contain the table of contents
|
|
document referenced via the SUBDOC entity declaration at the top
|
|
of the bookcase specification.
|
|
</para>
|
|
<programlisting>
|
|
<TOCFILE>&tocfile;</TOCFILE>
|
|
</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Use <FILE> tags to contain the book documents referenced
|
|
via SUBDOC entity declarations at the top of the bookcase specification.
|
|
</para>
|
|
<programlisting>
|
|
<FILE>&ch03;</FILE>
|
|
<FILE>&xlsc;</FILE>
|
|
</programlisting>
|
|
<para>
|
|
You can also list multiple book documents in a single set of <FILE>
|
|
tags. For example:
|
|
</para>
|
|
<programlisting>
|
|
<FILE>&ch03; &xlsc;</FILE>
|
|
</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
After all documents are referenced for this book,
|
|
close this book using the </BOOK> end tag.
|
|
</para>
|
|
<programlisting>
|
|
</BOOK>
|
|
</programlisting>
|
|
<para>
|
|
Repeat steps 8 thorough 11 for each additional book that is to be
|
|
included in the bookcase.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
After all books are specified, close the bookcase specification
|
|
using the </BOOKCASE> end tag.
|
|
</para>
|
|
<programlisting>
|
|
</BOOKCASE>
|
|
</programlisting>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>
|
|
The complete bookcase example is shown in
|
|
<link linkend="XcQg4bBSxI9X3cS">Example Bookcase Specification</link>.
|
|
</para>
|
|
|
|
<!--)))))))))))))))))))))))))))))))))))))-->
|
|
|
|
<sect3>
|
|
<title id="XcQg4bBSxI9X3cS">Example Bookcase Specification</title>
|
|
<indexterm><primary>bookcase specification</primary>
|
|
<secondary>example</secondary></indexterm>
|
|
<para>
|
|
This is an example of a small bookcase specification.
|
|
It defines one bookcase containing a single book and uses a
|
|
single style sheet.
|
|
</para>
|
|
<para>
|
|
Although the style sheet in the example below is referenced
|
|
via an entity reference, the complete text of the style sheet
|
|
<computeroutput>STYLE01</computeroutput> could be included
|
|
in the bookcase specification.
|
|
</para>
|
|
<programlisting>
|
|
<!DOCTYPE Bookcase PUBLIC
|
|
“-//Common Desktop Environment//DTD DtInfo Bookcase Description//EN”
|
|
[
|
|
<!-- Style sheets -->
|
|
<!ENTITY style01 SYSTEM “style01.sty” >
|
|
|
|
<!-- Book files declared as SUBDOC -->
|
|
<!ENTITY tocfile SYSTEM “small.toc” SUBDOC >
|
|
<!ENTITY ch03 SYSTEM “ch03.sgm” SUBDOC >
|
|
<!ENTITY xlsc SYSTEM “xlsc.sgm” SUBDOC >
|
|
]>
|
|
<BOOKCASE StyleSheet=sty1>
|
|
<BOOKCASENAME>SMALL</>
|
|
<BOOKCASEDESC>Demonstration small bookcase</>
|
|
&style01;
|
|
|
|
<BOOK>
|
|
<TITLE>DocBook DTD Examples</>
|
|
<SHORTTITLE>SGML Examples</>
|
|
|
|
<!-- Tab information -->
|
|
<TAB TabLoc=”RE-1015-XLSCLIENTS-1”>Manpage</>
|
|
|
|
<TOCFILE>&tocfile;</TOCFILE>
|
|
|
|
<FILE>&ch03;</FILE>
|
|
<FILE>&xlsc;</FILE>
|
|
|
|
</BOOK>
|
|
|
|
</BOOKCASE>
|
|
</programlisting>
|
|
<note>
|
|
<para>
|
|
This example bookcase specification conforms to the
|
|
<filename>dtinfoBook.dtd</filename> distributed with the Information Manager.
|
|
</para>
|
|
</note>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|