ch04.sgm 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777
  1. <!-- $XConsortium: ch04.sgm /main/4 1996/10/11 09:23:48 cdedoc $ -->
  2. <!-- (c) Copyright 1995 Digital Equipment Corporation. -->
  3. <!-- (c) Copyright 1995 Hewlett-Packard Company. -->
  4. <!-- (c) Copyright 1995 International Business Machines Corp. -->
  5. <!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
  6. <!-- (c) Copyright 1995 Novell, Inc. -->
  7. <!-- (c) Copyright 1995 FUJITSU LIMITED. -->
  8. <!-- (c) Copyright 1995 Hitachi. -->
  9. <chapter id="infoapg.div.4">
  10. <title id="fi1SgFBr-1698oL">Building Information Libraries</title>
  11. <indexterm><primary>information libraries</primary>
  12. <secondary>building</secondary></indexterm>
  13. <para>
  14. This chapter discusses how to use <command>dtinfogen</command>
  15. subcommands to validate and
  16. build your SGML documents into an Information Manager-browsable
  17. library and how to update style sheet information in a bookcase.
  18. </para>
  19. <para>
  20. You use the <command>dtinfogen validate</command> command to
  21. validate your SGML book documents and your bookcase specification.
  22. Validation is useful during preparation for the build.
  23. <indexterm><primary>Information Manager</primary>
  24. <secondary>commands</secondary>
  25. <tertiary>dtinfogen validate</tertiary></indexterm>
  26. </para>
  27. <para>
  28. You use the <command>dtinfogen build</command> command,
  29. which also performs SGML validation, to build a new information library,
  30. add a bookcase to an existing information library, and update an
  31. existing library.
  32. <indexterm><primary>Information Manager</primary>
  33. <secondary>commands</secondary>
  34. <tertiary>dtinfogen build</tertiary></indexterm>
  35. </para>
  36. <para>
  37. Once you have built an information library, you can use
  38. the <command>dtinfogen update</command> command to update the
  39. style sheet information associated with the library.
  40. These procedures are covered in:
  41. <indexterm><primary>Information Manager</primary>
  42. <secondary>commands</secondary>
  43. <tertiary>dtinfogen update</tertiary></indexterm>
  44. </para>
  45. <itemizedlist>
  46. <listitem>
  47. <para>
  48. <link linkend="KyEB2dBpuI9X3cS">Validating Your SGML Documents</link>
  49. </para>
  50. </listitem>
  51. <listitem>
  52. <para>
  53. <link linkend="ki1SgFBr-1698oL">Building, Adding, and Replacing Bookcases
  54. in a Library</link>
  55. </para>
  56. </listitem>
  57. <listitem>
  58. <para>
  59. <link linkend="WmNvZbBE6K9X3cS">Updating Style Sheets in Built Bookcases
  60. </link>
  61. </para>
  62. </listitem>
  63. </itemizedlist>
  64. <para>
  65. See the <command>dtinfogen(1)</command> man page for command
  66. syntax and additional examples of these commands.
  67. </para>
  68. <sect1>
  69. <title id="WxGm7JBlsoBt8oL">Before You Build a New Library</title>
  70. <indexterm><primary>information libraries</primary>
  71. <secondary>building</secondary><tertiary>prerequisites</tertiary></indexterm>
  72. <para>
  73. Before you build a new Information Manager information library you need to:
  74. </para>
  75. <itemizedlist>
  76. <listitem>
  77. <para>
  78. Specify the method to be used to map external entity references
  79. to your system files. You can either:
  80. </para>
  81. <itemizedlist>
  82. <listitem>
  83. <para>
  84. Set the appropriate environment variables for handling external
  85. entity references, or
  86. </para>
  87. </listitem>
  88. <listitem>
  89. <para>
  90. Specify the appropriate catalog file using the <option>-m</option>
  91. option with the <command>dtinfogen build</command> command.
  92. </para>
  93. </listitem>
  94. </itemizedlist>
  95. </listitem>
  96. <listitem>
  97. <para>
  98. Check to make sure that you have all of the required
  99. SGML-conforming documents, including DTD(s), hypertext TOCs,
  100. and style sheet(s) for every book in the bookcase.
  101. You can validate your SGML documents using the
  102. <command>dtinfogen validate</command> command
  103. as described in <link linkend="ByGm7JBlsoBt8oL">
  104. Running dtinfogen validate</link>.
  105. </para>
  106. </listitem>
  107. <listitem>
  108. <para>
  109. Understand the options that <command>dtinfogen build</command> provides,
  110. as described in <link linkend="ki1SgFBr-1698oL">Building,
  111. Adding, and Replacing Bookcases in a Library</link>.
  112. </para>
  113. </listitem>
  114. </itemizedlist>
  115. </sect1>
  116. <!--((((((((((((((((((((((((((((((((((((((((((((((((((-->
  117. <sect1>
  118. <title id="n9yEB2dBpuI9X3cS">Setting Environment Variables</title>
  119. <indexterm><primary>environment variables</primary></indexterm>
  120. <para>
  121. Depending on whether you are using the
  122. <citetitle>SGML Open Technical Resolution 9401:1994</citetitle>
  123. recommendation for resolving external entity references,
  124. you need to set one or both of the following environment variables,
  125. or use the <option>-m</option> option with the
  126. <command>dtinfogen</command> command:</para>
  127. <variablelist>
  128. <varlistentry>
  129. <term><systemitem class="environvar">SGML_CATALOG_FILES</systemitem></term>
  130. <listitem>
  131. <para>
  132. Set this environment variable if you follow the
  133. <citetitle>SGML Open Technical Resolution 9401:1994</citetitle>
  134. recommendation related to external entity management.
  135. The value of this environment variable specifies the
  136. location of the file <filename>catalog</filename> or
  137. <filename>CATALOG</filename> (you can use either upper-case
  138. or lower-case letters) that lists SGML entity declarations and
  139. file mapping identifiers.
  140. </para>
  141. <para>
  142. If you don't set this environment variable,
  143. you can use the <option>-m</option> option with the
  144. appropriate <command>dtinfogen</command> command to map public
  145. identifiers and entity names to system files.
  146. See the <filename>catalog(5)</filename> man page for more information.
  147. </para>
  148. </listitem>
  149. </varlistentry>
  150. <varlistentry>
  151. <term><systemitem class="environvar">SGML_PATH</systemitem></term>
  152. <listitem>
  153. <para>
  154. Set this environment variable to map external entity references
  155. to system files.</para>
  156. <para>See the <command>dtinfogen(5)</command> man page
  157. for more information.
  158. </para>
  159. </listitem>
  160. </varlistentry>
  161. </variablelist>
  162. <para>For related information, see:
  163. </para>
  164. <itemizedlist>
  165. <listitem>
  166. <para>
  167. <citetitle>SGML Open Technical Resolution 9401:1994</citetitle>
  168. </para>
  169. </listitem>
  170. </itemizedlist>
  171. </sect1>
  172. <!--((((((((((((((((((((((((((((((((((((((((((-->
  173. <sect1>
  174. <title id="KyEB2dBpuI9X3cS">Validating Your SGML Documents</title>
  175. <indexterm><primary>SGML documents</primary>
  176. <secondary>validating</secondary></indexterm>
  177. <para>
  178. Before building an information library, you should validate your
  179. SGML documents to ensure that they conform to the appropriate DTD.
  180. </para>
  181. <para>You can use the <command>dtinfogen validate</command>
  182. <indexterm><primary>Information Manager</primary>
  183. <secondary>commands</secondary>
  184. <tertiary>dtinfogen validate</tertiary></indexterm>
  185. command to perform SGML validation on bookcase specifications,
  186. on individual documents, or any other SGML conforming document.
  187. During the validation process <command>dtinfogen validate</command>:
  188. </para>
  189. <itemizedlist>
  190. <listitem>
  191. <para>
  192. Checks the input document's DTD to verify that it conforms to SGML.
  193. </para>
  194. </listitem>
  195. <listitem>
  196. <para>Verifies that the SGML markup in the input document is
  197. consistent with the markup language defined in the document's DTD.
  198. </para>
  199. </listitem>
  200. </itemizedlist>
  201. <para>
  202. If any documents are found to be invalid, error messages are
  203. issued by the <command>dtinfogen validate</command> program.
  204. All errors in files used to build an information library must
  205. be corrected before the data can be built.
  206. </para>
  207. <sect2>
  208. <title id="ByGm7JBlsoBt8oL">Running dtinfogen validate</title>
  209. <indexterm><primary>information libraries</primary>
  210. <secondary>document validation</secondary></indexterm>
  211. <para>
  212. The basic command line for the following example, which performs
  213. validation on a single-bookcase information library, is:
  214. </para>
  215. <programlisting>
  216. <userinput>dtinfogen validate ch03.sgm ch04.sgm ch05.sgm</userinput>
  217. </programlisting>
  218. <para>where</para>
  219. <para>
  220. <filename>ch03.sgm ch04.sgm ch05.sgm</filename>
  221. </para>
  222. <para>
  223. specifies the SGML documents that are to be validated.
  224. The <command>dtinfogen validate</command> command can be run
  225. against any valid SGML conforming document.
  226. </para>
  227. <para>
  228. Error messages are returned if a document is invalid.
  229. Here is an example of the type of errors returned against an
  230. example file <filename>ch05.sgm</filename>,
  231. which contains missing or invalid entity declarations.
  232. </para>
  233. <programlisting>
  234. %: <userinput>dtinfogen validate</userinput>
  235. nsgmls:ch05.sgm:12:1:E: cannot open "hal.gml" (No such file or directory)
  236. nsgmls:ch05.sgm:20:1:E: general entity "tab" not defined and no default entity
  237. ..............................
  238. ..............................
  239. ..............................
  240. dtinfogen: command failed: nsgmls -sg /usr/dt/infolib/C/SGML/dtinfo.decl ch05.sgm
  241. ch05.sgm
  242. </programlisting>
  243. </sect2>
  244. </sect1>
  245. <!--((((((((((((((((((((((((((((((((((((((((((((((((((-->
  246. <sect1>
  247. <title id="ki1SgFBr-1698oL">Building, Adding, and Replacing Bookcases in a Library</title>
  248. <indexterm><primary>information libraries</primary>
  249. <secondary>building</secondary>
  250. <tertiary>with dtinfogen build</tertiary>
  251. </indexterm>
  252. <para>
  253. This section describes how you use the
  254. <command>dtinfogen build</command> command to build a bookcase
  255. into a new information library, add a bookcase to an existing
  256. information library, and update the information database in an
  257. existing library.
  258. <indexterm><primary>Information Manager</primary>
  259. <secondary>commands</secondary><tertiary>dtinfogen build</tertiary>
  260. </indexterm>
  261. </para>
  262. <sect2>
  263. <title id="jI.RgFBe.1698oL">Build Considerations</title>
  264. <indexterm><primary>information libraries</primary>
  265. <secondary>build considerations</secondary></indexterm>
  266. <para>
  267. You can build information libraries of all sizes,
  268. containing any number of books and bookcases.
  269. You can have (but are not limited to) information libraries containing:
  270. </para>
  271. <itemizedlist>
  272. <listitem>
  273. <para>A single bookcase consisting of one or more books
  274. </para>
  275. </listitem>
  276. <listitem>
  277. <para>
  278. Multiple bookcases, each consisting of one or more books.
  279. </para>
  280. </listitem>
  281. </itemizedlist>
  282. <para>
  283. When designing an information library, you should give thought
  284. to its presentation in the Information Manager and to its reception
  285. by readers, many of whom may not be experienced users of on-line
  286. documentation.
  287. </para>
  288. <para>
  289. Information structure and information search capability
  290. are among the most important factors in the design of an
  291. on-line information library. Readers must be able to easily
  292. discern the structure of a book or set of books in a bookcase.
  293. In addition, they must be able to find the information they want quickly,
  294. through the use of clear hypertext links and through efficient search
  295. mechanisms.
  296. </para>
  297. <sect3>
  298. <title id="SKUExiBLxJ9X3cS">Library Configuration</title>
  299. <para>The Information Manager has very powerful search capabilities.
  300. However, the configuration of your on-line information library affects
  301. the efficiency of the search process.
  302. </para>
  303. <para>
  304. In general, the fewer bookcases you have in an information library,
  305. and the fewer books contained in each bookcase,
  306. the faster the build process will proceed. This type of information
  307. library structure can also be quickly and easily updated.
  308. </para>
  309. <para>
  310. Unfortunately, as the number of bookcases grows,
  311. this type of library structure becomes inefficient in terms
  312. of the browser's ability to search its contents for information.
  313. </para>
  314. <para>
  315. On the other hand, an information library that contains a
  316. smaller number of bookcases, each of which contains a relatively
  317. large number of books, will take much longer to build and to
  318. subsequently update. But search times for this type of library
  319. structure will be significantly shorter.
  320. </para>
  321. </sect3>
  322. <sect3>
  323. <title id="aKUExiBLxJ9X3cS">Build Space</title>
  324. <para>
  325. Before you build an information library, you must ensure that
  326. sufficient space is available in the appropriate locations for
  327. the build process to succeed.</para>
  328. <para>Upon build completion, an information library takes up
  329. about the same amount of space as the source from which it was built.
  330. However, during the build process itself, up to three times
  331. as much additional space will be required for temporary file storage.
  332. This additional space must be allocated as temporary build space,
  333. which is automatically removed upon completion of the build.
  334. The default location for temporary build space is
  335. <filename>/usr/tmp</filename>.
  336. </para>
  337. <para>
  338. If you find that the disk space available in
  339. <filename>/usr/tmp</filename> is less than three times the size of the
  340. original document source, you should use the <option>-T</option> option
  341. with the <command>dtinfogen build</command> command to specify a
  342. different location for the temporary build files, or set the <systemitem
  343. class="environvar">TMPDIR</systemitem> environment variable.
  344. </para>
  345. <caution>
  346. <para>
  347. The current version of the Information Manager has no concurrent-use
  348. locking mechanisms to prevent users from attempting to simultaneously
  349. build or modify the same information library. Take precautions to ensure
  350. that no other <command>dtinfogen</command> or Information Manager
  351. processes are accessing the information library when you run the
  352. <command>dtinfogen build</command> command. Concurrent use of the
  353. <command>dtinfogen</command> commands may cause an Information Manager
  354. failure.
  355. </para>
  356. </caution>
  357. </sect3>
  358. </sect2>
  359. </sect1>
  360. <!--((((((((((((((((((((((((((((((((((((((((((((((((((((-->
  361. <sect1>
  362. <title id="n4Ofh7JBpooBt8oL">Information Library Organization</title>
  363. <para>
  364. When you build an information library, your browser-readable
  365. files are organized in the structure depicted in the figure
  366. <link linkend="n9Ofh7JBpooBt8oL">Build Directory Structure</link>.
  367. </para>
  368. <figure>
  369. <title id="n9Ofh7JBpooBt8oL">Build Directory Structure</title>
  370. <graphic id="gr58" entityref="infoapg.fig.5"></graphic>
  371. </figure>
  372. <sect2>
  373. <title id="zOfh7JBpooBt8oL">Build Directory Structure</title>
  374. <indexterm><primary>Information Manager build directories</primary>
  375. <secondary>directory structure</secondary></indexterm>
  376. <para>
  377. The build directory structure shows:
  378. </para>
  379. <variablelist>
  380. <varlistentry>
  381. <term><replaceable>BC</replaceable><filename>.dbd</filename></term>
  382. <listitem>
  383. <para>
  384. This file is the document database for the bookcase
  385. <replaceable>BC</replaceable>. It contains all compiled text,
  386. graphics, and table data.
  387. </para>
  388. </listitem>
  389. </varlistentry>
  390. <varlistentry>
  391. <term><replaceable>BC</replaceable><filename>.dbi</filename></term>
  392. <listitem>
  393. <para>
  394. This file contains the index data for bookcase
  395. <replaceable>BC</replaceable>.
  396. </para>
  397. </listitem>
  398. </varlistentry>
  399. <varlistentry>
  400. <term><replaceable>BC</replaceable><filename>.sch</filename></term>
  401. <listitem>
  402. <para>
  403. This file describes the structure of the database.
  404. </para>
  405. </listitem>
  406. </varlistentry>
  407. <varlistentry>
  408. <term><filename>dtsearch</filename> directory</term>
  409. <listitem>
  410. <para>
  411. This directory contains all the files related to the full-text search engine.
  412. </para>
  413. </listitem>
  414. </varlistentry>
  415. <varlistentry>
  416. <term><filename>bookcase.map</filename></term>
  417. <listitem>
  418. <para>
  419. This file organizes the bookcases within the library.
  420. You use the <command>dtinfogen admin</command> command to modify this file.
  421. </para>
  422. </listitem>
  423. </varlistentry>
  424. <varlistentry>
  425. <term><replaceable>LIB</replaceable><filename>.oli</filename></term>
  426. <listitem>
  427. <para>
  428. The string used for <replaceable>LIB</replaceable> gives the library its file name.
  429. </para>
  430. </listitem>
  431. </varlistentry>
  432. </variablelist>
  433. </sect2>
  434. </sect1>
  435. <!--(((((((((((((((((((((((((((((((((((((((((((((((((-->
  436. <sect1>
  437. <title id="xXk7ubBtGL9X3cS">Building a New Library</title>
  438. <para>
  439. Here is an example of the basic <command>dtinfogen build</command>
  440. command line for building a new information library:
  441. </para>
  442. <programlisting>
  443. dtinfogen build <option>-T</option> <replaceable>/k1/local/daver/</replaceable> <option>-l</option> <replaceable>InfoLib1 DCE.bc INFOMGR.bc PROG.bc</replaceable>
  444. </programlisting>
  445. <para>
  446. where
  447. </para>
  448. <variablelist>
  449. <varlistentry>
  450. <term><option>-T</option> <replaceable>/k1/local/daver</replaceable></term>
  451. <listitem>
  452. <para>
  453. Specifies the directory in which temporary files generated
  454. during the build process will be placed.
  455. </para>
  456. </listitem>
  457. </varlistentry>
  458. <varlistentry>
  459. <term><option>-l</option> <replaceable>InfoLib1</replaceable></term>
  460. <listitem>
  461. <para>
  462. Specifies the name of the directory containing the information library.
  463. After the build, <filename>InfoLib1</filename>
  464. will contain the three bookcases specified in the command line
  465. arguments that follow.
  466. </para>
  467. </listitem>
  468. </varlistentry>
  469. <varlistentry>
  470. <term><replaceable>DCE.bc INFOMGR.bc PROG.bc</replaceable></term>
  471. <listitem>
  472. <para>
  473. Specify the file names of your bookcase specification files.
  474. Each bookcase specification contains the names of one or
  475. more books to be built. You can include as many bookcase
  476. specification file names on the command line as you wish.
  477. </para>
  478. </listitem>
  479. </varlistentry>
  480. </variablelist>
  481. <para><command>dtinfogen build</command> converts the documents
  482. specified in each of the bookcase specifications into browser-readable
  483. format and places them in the newly created information
  484. library directory <filename>InfoLib1</filename>.
  485. </para>
  486. <para>
  487. Assuming the names of the three bookcases
  488. (as specified by each bookcase's BOOKCASENAME element) are
  489. <systemitem>DCE</systemitem>, <systemitem>INFOMGR</systemitem>,
  490. and <systemitem>PROG</systemitem>, respectively,
  491. the <filename>InfoLib1</filename> directory now contains the
  492. bookcase directories <filename>DCE</filename>, <filename>INFOMGR</filename>,
  493. and <filename>PROG</filename>. Each bookcase, in turn, contains
  494. the document databases (books) specified by its BOOK element(s).
  495. </para>
  496. <para>
  497. The figure <link linkend="wKUExiBLxJ9X3cS">Creating a New Library</link>
  498. depicts the newly built <filename>InfoLib1</filename> library.
  499. </para>
  500. <figure>
  501. <title id="wKUExiBLxJ9X3cS">Creating a New Library</title>
  502. <graphic id="gr59" entityref="infoapg.fig.6"></graphic>
  503. </figure>
  504. </sect1>
  505. <!--((((((((((((((((((((((((((((((((((((((((((((((((((((((-->
  506. <sect1>
  507. <title id="n7Ktl2IBUXmBt8oL">Adding a Bookcase to an Existing Library</title>
  508. <indexterm><primary>bookcases</primary>
  509. <secondary>adding</secondary>
  510. <tertiary>with dtinfogen build</tertiary></indexterm>
  511. <para>
  512. In addition to creating a new Information Manager information
  513. library, you can also use <command>dtinfogen build</command> to add
  514. a bookcase that has not yet been built to an existing information library.
  515. In the example below, assume the argument
  516. <option>-l</option>&nbsp;<replaceable>InfoLib1</replaceable>
  517. is the name of an existing information library rather than the name
  518. of a new information library.
  519. </para>
  520. <programlisting>
  521. dtinfogen build <option>-l</option> <replaceable>InfoLib1 ORA.bc</replaceable></programlisting>
  522. <para>
  523. where
  524. </para>
  525. <variablelist>
  526. <varlistentry>
  527. <term><option>-l</option> <replaceable>InfoLib1</replaceable></term>
  528. <listitem>
  529. <para>
  530. is the name of the directory that contains the existing information library.
  531. </para>
  532. </listitem>
  533. </varlistentry>
  534. <varlistentry>
  535. <term><replaceable>ORA.bc</replaceable></term>
  536. <listitem>
  537. <para>
  538. is the file name of the bookcase specification file whose contents
  539. you are adding to the <filename>InfoLib1</filename> information library.
  540. You can include as many bookcase specification names on the command line
  541. as you wish.
  542. </para>
  543. </listitem>
  544. </varlistentry>
  545. </variablelist>
  546. <para>
  547. <command>dtinfogen build</command>
  548. converts the book documents in the bookcase specification file
  549. <filename>ORA.bc</filename> into browser-readable format and adds
  550. them to the existing information library directory
  551. <filename>InfoLib1</filename>.</para>
  552. <para>Assuming the name of the added bookcase (as specified
  553. by its BOOKCASENAME element) is <systemitem>ORA</systemitem>,
  554. the <filename>InfoLib1</filename> directory now contains the bookcase
  555. directories <systemitem>DCE</systemitem>,
  556. <systemitem>INFOMGR</systemitem>, <systemitem>PROG</systemitem>,
  557. and <systemitem>ORA</systemitem>.
  558. </para>
  559. <para>
  560. The figure <link linkend="bMUExiBLxJ9X3cS">Adding a Bookcase to an Existing
  561. Library</link> depicts the revised <filename>InfoLib1</filename>
  562. library.
  563. </para>
  564. <note>
  565. <para>
  566. Added bookcases are appended to the existing list of bookcases
  567. in the Information Manager Book List. The <command>dtinfogen admin</command>
  568. command can be used to rearrange the list after it is built.
  569. See the <command>dtinfogen(1)</command> man page.</para>
  570. </note>
  571. <figure>
  572. <title id="bMUExiBLxJ9X3cS">Adding a Bookcase to an Existing Library</title>
  573. <graphic id="gr60" entityref="infoapg.fig.7"></graphic>
  574. </figure>
  575. </sect1>
  576. <!--))))))))))))))))))))))))))))))))))))))))))))))))))))))-->
  577. <sect1>
  578. <title id="pOUExiBLxJ9X3cS">Replacing a Bookcase in an Existing Library</title>
  579. <indexterm><primary>bookcases</primary>
  580. <secondary>replacing</secondary><tertiary>with dtinfogen build</tertiary>
  581. </indexterm>
  582. <para>
  583. In addition to creating information libraries and adding bookcases
  584. to existing libraries, you can also replace specified bookcases
  585. in a library with the <command>dtinfogen build</command> command.
  586. In the example below, the <command>dtinfogen build</command> process
  587. is used to rebuild the bookcases <systemitem>INFOMGR</systemitem> and
  588. <systemitem>PROG</systemitem> and to overwrite the existing bookcases
  589. of the same name in the <filename>InfoLib1</filename> information library.
  590. </para>
  591. <programlisting>
  592. dtinfogen build <option>-l</option> <replaceable>InfoLib1 INFOMGR.bc PROG.bc</replaceable></programlisting>
  593. <para>
  594. where
  595. </para>
  596. <variablelist>
  597. <varlistentry>
  598. <term><option>-l</option> <replaceable>InfoLib1</replaceable></term>
  599. <listitem>
  600. <para>
  601. is the name of the directory that contains the existing information library.
  602. </para>
  603. </listitem>
  604. </varlistentry>
  605. <varlistentry>
  606. <term><replaceable>INFOMGR.bc PROG.bc</replaceable></term>
  607. <listitem>
  608. <para>
  609. are the file names of the bookcase specification files whose
  610. contents you are rebuilding in order to update the information
  611. library <filename>InfoLib1</filename>. You can include as
  612. many bookcase specification file names on the command line as you wish.
  613. </para>
  614. </listitem>
  615. </varlistentry>
  616. </variablelist>
  617. <para><command>dtinfogen build</command> rebuilds the books in the
  618. bookcase specification files <filename>INFOMGR.bc</filename> and
  619. <filename>PROG.bc</filename> and places them in the existing
  620. information library directory <filename>InfoLib1</filename>.
  621. </para>
  622. <para>
  623. The newly built bookcases, whose bookcase names are
  624. <systemitem>INFOMGR</systemitem> and <systemitem>PROG</systemitem>
  625. (as specified in the their respective BOOKCASENAME elements),
  626. overwrite the existing bookcases that have the same names.
  627. </para>
  628. <para>
  629. The figure <link linkend="n1PUExiBLxJ9X3cS">Replacing
  630. Bookcases in an Existing Library</link> depicts the revised
  631. <filename>InfoLib1</filename> library.
  632. </para>
  633. <figure>
  634. <title id="n1PUExiBLxJ9X3cS">Replacing Bookcases in an Existing Library</title>
  635. <graphic id="gr61" entityref="infoapg.fig.8"></graphic>
  636. </figure>
  637. </sect1>
  638. <!--((((((((((((((((((((((((((((((((((((((((((((((((((((((((-->
  639. <sect1>
  640. <title id="WmNvZbBE6K9X3cS">Updating Style Sheets in Built Bookcases</title>
  641. <indexterm><primary>style sheet</primary>
  642. <secondary>updating</secondary></indexterm>
  643. <indexterm><primary>Information Manager</primary>
  644. <secondary>commands</secondary><tertiary>dtinfogen update</tertiary></indexterm>
  645. <para>
  646. In Information Manager, you can change the formatting instructions
  647. for existing bookcases without rebuilding those databases.
  648. This capability gives you great flexibility in the way you handle
  649. books whose formatting characteristics must change to meet differing
  650. audience or industry requirements.
  651. </para>
  652. <para>
  653. You use the <command>dtinfogen update</command> command to reformat
  654. the books in existing information libraries by updating the style
  655. sheet information that controls their formatting.
  656. </para>
  657. <para>
  658. With <command>dtinfogen update</command> you can revise a style sheet
  659. and quickly see the results of your changes, or you can replace one
  660. style sheet with another and quickly reformat associated documents.</para>
  661. <para>When you run <command>dtinfogen update</command>, only the
  662. documents or document sections affected by the style sheet changes
  663. are reformatted.
  664. </para>
  665. <para>
  666. Before you run <command>dtinfogen update</command> to reformat documents
  667. in an information library:
  668. </para>
  669. <itemizedlist>
  670. <listitem>
  671. <para>
  672. Ensure that any changes you have made to the style sheet are valid.
  673. The <command>dtinfogen update</command> command validates the style
  674. sheet file during the update process.
  675. </para>
  676. </listitem>
  677. <listitem>
  678. <para>
  679. Set the appropriate environment variables for handling
  680. external entity references or specify the appropriate catalog file
  681. using the <option>-m</option> option when you run
  682. <command>dtinfogen update</command>.</para>
  683. </listitem>
  684. </itemizedlist>
  685. <caution>
  686. <para>Do not run the Information Manager or execute an
  687. <command>dtinfogen admin</command> process while updating a style sheet.
  688. </para>
  689. </caution>
  690. <sect2>
  691. <title id="CDdVddBydG9X3cS">Running dtinfogen update</title>
  692. <para>
  693. The basic command line for the following example,
  694. which reformats the documents and/or document sections
  695. that use the specified style sheet, is:
  696. </para>
  697. <programlisting>
  698. dtinfogen update <option>-l</option> <replaceable>InfoLib1</replaceable> <option>-b</option> <replaceable>INFOMGR style1.sty</replaceable></programlisting>
  699. <para>
  700. where
  701. </para>
  702. <variablelist>
  703. <varlistentry>
  704. <term><option>-l</option> <replaceable>InfoLib1</replaceable></term>
  705. <listitem>
  706. <para>
  707. Is the name of the directory that contains the existing information library.
  708. </para>
  709. </listitem>
  710. </varlistentry>
  711. <varlistentry>
  712. <term><option>-b</option> <replaceable>INFOMGR</replaceable></term>
  713. <listitem>
  714. <para>
  715. Is the name of the bookcase (as specified in the its BOOKCASENAME element)
  716. that includes the sections that will be reformatted by the
  717. specified style sheet.
  718. </para>
  719. </listitem>
  720. </varlistentry>
  721. <varlistentry>
  722. <term><replaceable>style1.sty</replaceable></term>
  723. <listitem>
  724. <para>
  725. Is the file name of the style sheet that will be applied
  726. during the <command>dtinfogen update</command> process.
  727. The style sheet you use must conform to
  728. <filename>StyleSheet.dtd</filename> as discussed
  729. in <link linkend="tgmdnkb6vm9x3cs">Understanding
  730. Information Manager Style Sheets</link>.
  731. </para>
  732. </listitem>
  733. </varlistentry>
  734. </variablelist>
  735. <para>
  736. After running <command>dtinfogen update</command> process you can
  737. open the information library using the Information Manager Book List
  738. window to see the effect of your changes.
  739. </para>
  740. <para>
  741. For related information, see:
  742. </para>
  743. <itemizedlist>
  744. <listitem>
  745. <para>the <command>dtinfogen(1)</command> man page</para>
  746. </listitem>
  747. <listitem>
  748. <para><link linkend="TcQg4bBSxI9X3cS">Creating a Bookcase Specification</link>
  749. </para>
  750. </listitem>
  751. <listitem>
  752. <para>
  753. <link linkend="j3fa6XBbiK9X3cS">Using Style Sheets</link></para>
  754. </listitem>
  755. <listitem>
  756. <para>
  757. <link linkend="tgmdnkb6vm9x3cs">Understanding Information Manager
  758. Style Sheets</link></para>
  759. </listitem>
  760. </itemizedlist>
  761. </sect2>
  762. </sect1>
  763. </chapter>