开通博客赚积分
发布资源赚积分
分类

源码开发语言/平台
当前位置：首页 > 源码/资料 > 数据库系统 > 查看源码
docguide.sgml
资源名称：postgresql-6.5.2.tar.gz　[点击查看]
上传用户：blenddy
上传日期：2007-01-07
资源大小：6495k
文件大小：76k
源码类别：

数据库系统

开发平台：

Unix_Linux

docguide.sgml：源码内容
  1. <!--
  2. $Header: /usr/local/cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.18 1999/07/06 17:19:41 thomas Exp $
  3. Documentation Guide
  4. Thomas Lockhart
  6. Revision 1.15  1999/05/27 15:49:07  thomas
  7. Markup fixes.
  8. Update for v6.5 release.
  10. Revision 1.12  1998/12/18 16:17:29  thomas
  11. Include more details on editing with Emacs.
  12. Remove mention of the old "migration" flat files.
  13. Change URLs for resources to point to areas, not particular files.
  14.  That way things stay correct even when version of tools change.
  15.  Suggested by Vince Vielhaber.
  17. Revision 1.11  1998/10/30 19:36:57  thomas
  18. Minor editing and markup changes as a result of preparing the Postscript
  19.  documentation for v6.4.
  20. Bigger updates to the installation instructions (install and config).
  22. Revision 1.8  1998/08/17 16:17:07  thomas
  23. Bring document list closer to up to day.
  24. Add a note on sgml-tools that they are now working with jade and so
  25.  may become the toolset of choice in the future.
  27. -->
  29. <appendix label="DG2" id="docguide">
  30.  <docinfo>
  31.   <authorgroup>
  32.    <author>
  33.     <firstname>Thomas</firstname>
  34.     <surname>Lockhart</surname>
  35.    </author>
  36.    <author>
  37.     <firstname>Tom Ivar</firstname>
  38.     <surname>Helbekkmo</surname>
  39.    </author>
  40.   </authorgroup>
  41.   <date>1999-05-27</date>
  42.  </docinfo>
  44.  <title>Documentation</title>
  46.  <para>
  47.   The purpose of documentation is to make <productname>Postgres</productname>
  48.   easier to learn, use, and develop.
  49.   The documentation set should describe the <productname>Postgres</productname>
  50.   system, language, and interfaces.
  51.   It should be able to answer
  52.   common questions and to allow a user to find those answers on his own
  53.   without resorting to mailing list support.
  54.  </para>
  56.  <sect1>
  57.   <title>Documentation Roadmap</title>
  59.   <para>
  60.    <productname>Postgres</productname> has four primary documentation
  61.    formats:
  63.    <itemizedlist>
  64.     <listitem><para>
  65.       Plain text for pre-installation information.
  66.      </para></listitem>
  67.     <listitem><para>
  68.       <acronym>HTML</acronym>, for on-line browsing and reference.
  69.      </para></listitem>
  70.     <listitem><para>
  71.       Hardcopy, for in-depth reading and reference.
  72.      </para></listitem>
  73.     <listitem><para>
  74.       <acronym>man pages</acronym>, for quick reference.
  75.      </para></listitem>
  76.    </itemizedlist>
  77.   </para>
  79.   <para>
  80.    <table tocentry="1">
  81.     <title><productname>Postgres</productname> Documentation Products</title>
  82.     <tgroup cols="2">
  83.      <thead>
  84.       <row>
  85.        <entry>
  86. File
  87.        </entry>
  88.        <entry>
  89. Description
  90.        </entry>
  91.       </row>
  92.      </thead>
  94.      <tbody>
  95.       <row>
  96.        <entry>./COPYRIGHT</entry><entry>Copyright notice</entry>
  97.       </row>
  98.       <row>
  99.        <entry>./INSTALL</entry>
  100.        <entry>Installation instructions (text from sgml->rtf->text)</entry>
  101.       </row>
  102.       <row>
  103.        <entry>./README</entry>
  104.        <entry>Introductory info</entry>
  105.       </row>
  106.       <row>
  107.        <entry>./register.txt</entry>
  108.        <entry>Registration message during make</entry>
  109.       </row>
  110.       <row>
  111.        <entry>./doc/bug.template</entry>
  112.        <entry>Bug report template</entry>
  113.       </row>
  114.       <row>
  115.        <entry>./doc/postgres.tar.gz</entry>
  116.        <entry>Integrated docs (<acronym>HTML</acronym>)</entry>
  117.       </row>
  118.       <row>
  119.        <entry>./doc/programmer.ps.gz</entry>
  120.        <entry>Programmer's Guide (Postscript)</entry>
  121.       </row>
  122.       <row>
  123.        <entry>./doc/programmer.tar.gz</entry>
  124.        <entry>Programmer's Guide (<acronym>HTML</acronym>)</entry>
  125.       </row>
  126.       <row>
  127.        <entry>./doc/reference.ps.gz</entry>
  128.        <entry>Reference Manual (Postscript)</entry>
  129.       </row>
  130.       <row>
  131.        <entry>./doc/reference.tar.gz</entry>
  132.        <entry>Reference Manual (<acronym>HTML</acronym>)</entry>
  133.       </row>
  134.       <row>
  135.        <entry>./doc/tutorial.ps.gz</entry>
  136.        <entry>Introduction (Postscript)</entry>
  137.       </row>
  138.       <row>
  139.        <entry>./doc/tutorial.tar.gz</entry>
  140.        <entry>Introduction (<acronym>HTML</acronym>)</entry>
  141.       </row>
  142.       <row>
  143.        <entry>./doc/user.ps.gz</entry>
  144.        <entry>User's Guide (Postscript)</entry></row>
  145.       <row>
  146.        <entry>./doc/user.tar.gz</entry>
  147.        <entry>User's Guide (<acronym>HTML</acronym>)</entry>
  148.       </row>
  149.      </tbody>
  150.     </tgroup>
  151.    </table>
  152.   </para>
  154.   <para>
  155.    There are man pages available, as well as a large number
  156.    of plain-text README-type files throughout the <productname>Postgres</productname>
  157.    source tree.
  158.   </para>
  159.  </sect1>
  161.  <sect1>
  162.   <title>The Documentation Project</title>
  164.   <para>
  165.    Packaged documentation is available in both
  166.    <acronym>HTML</acronym> and <firstterm>Postscript</firstterm>
  167.    formats. These are available as part of the standard
  168.    <productname>Postgres</productname> installation. We discuss here
  169.    working with the documentation sources and generating documentation
  170.    packages.
  171.   </para>
  173.   <para>
  174.    The documentation sources are written using <acronym>SGML</acronym>
  175.    markup of plain text files.
  176.    The purpose of <productname>DocBook</productname> <acronym>SGML</acronym>
  177.    is to allow an author to
  178.    specify the structure and content of a technical document (using the
  179.    <productname>DocBook</productname> <acronym>DTD</acronym>),  and to
  180.    have a document style define how that content is rendered into a
  181.    final form (e.g. using Norm Walsh's 
  182.    <productname>Modular Style Sheets</productname>).</para>
  184.   <para>
  185.    See
  186.    <ulink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">
  187.     Introduction to DocBook</ulink>
  188.    for a nice "quickstart" summary of DocBook features.
  189.    <ulink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/">
  190.     DocBook Elements</ulink>
  191.    provides a powerful cross-reference for features of
  192.    <productname>DocBook</productname>.
  193.   </para>
  195.   <para>
  196.    This documentation set is constructed using several tools, including
  197.    James Clark's 
  198.    <ulink url="http://www.jclark.com/jade/">
  199.     <productname>jade</productname></ulink>
  200.    and Norm Walsh's 
  201.    <ulink url="http://www.nwalsh.com/docbook/dsssl/">
  202.     Modular DocBook Stylesheets</ulink>.
  203.   </para>
  205.   <para>
  206.    Currently, hardcopy is produced by importing
  207.    <firstterm>Rich Text Format</firstterm> (<acronym>RTF</acronym>) output from
  208.    <application>jade</application> into
  209.    <productname>ApplixWare</productname> for minor formatting fixups, then
  210.    exporting as a Postscript file.</para>
  212.   <para>
  213.    <ulink url="http://sunsite.unc.edu/pub/packages/TeX/systems/unix/">
  214.     <productname>TeX</productname></ulink> is a supported format for
  215.    <application>jade</application> output, but is not used at this time
  216.    for several reasons, including the inability to make minor format
  217.    fixes before committing to hardcopy and generally inadequate table
  218.    support in the <productname>TeX</productname>
  219.    stylesheets.</para>
  221.  </sect1>
  223. <sect1>
  224. <title>Documentation Sources</title>
  226. <para>
  227. Documentation sources include plain text files, man pages, and html. However,
  228. most new <productname>Postgres</productname> documentation will be written using the
  229. <firstterm>Standard Generalized Markup Language</firstterm>
  230. (<acronym>SGML</acronym>) 
  231. <ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink>
  232.  <firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>).
  233. Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>.
  234. </para>
  236. <para>
  237. The purpose of <acronym>SGML</acronym> is to allow an author to
  238. specify the structure and content of a document (e.g. using the
  239. <productname>DocBook</productname> <acronym>DTD</acronym>),  and to
  240. have the document style define how that content is rendered into a
  241. final form (e.g. using Norm Walsh's stylesheets).
  242. </para>
  244. <para>
  245. Documentation has accumulated from several sources. As we integrate
  246. and assimilate existing documentation into a coherent documentation set,
  247. the older versions will become obsolete and will be removed from the
  248. distribution. However, this will not happen immediately, and will not
  249. happen to all documents at the same time. To ease the transition, and
  250. to help guide developers and writers, we have defined a transition roadmap.
  251. </para>
  253. <para>
  254. Here is the documentation plan for v6.5:
  256. <itemizedlist>
  257. <listitem>
  258. <para>
  259. Start compiling index information for the User's and Administrator's Guides.
  260. </para>
  261. </listitem>
  263. <listitem>
  264. <para>
  265. Write more sections for the User's Guide covering areas outside the reference pages.
  266. This would include introductory information and suggestions for approaches to typical
  267. design problems.
  268. </para>
  269. </listitem>
  271. <listitem>
  272. <para>
  273. Merge information in the existing man pages into the reference pages and User's Guide.
  274. Condense the man pages down to reminder information, with references into the
  275. primary doc set.
  276. </para>
  277. </listitem>
  279. <listitem>
  280. <para>
  281. Convert the new sgml reference pages to new man pages, replacing the existing man pages.
  282. </para>
  283. </listitem>
  285. <listitem>
  286. <para>
  287. Convert all source graphics to CGM format files for portability. Currently we mostly have
  288. Applix Graphics sources from which we can generate .gif output. One graphic is only
  289. available in .gif and .ps, and should be redrawn or removed.
  290. </para>
  291. </listitem>
  293. </itemizedlist>
  294. </para>
  296. <sect2>
  297. <title>Document Structure</title>
  299. <para>
  300. There are currently five separate documents written in DocBook. Each document
  301. has a container source document which defines the DocBook environment and other
  302. document source files. These primary source files are located in 
  303. <filename>doc/src/sgml/</filename>, along with many of the other source files
  304. used for the documentation. The primary source files are:
  306. <variablelist>
  307. <varlistentry>
  308. <term>postgres.sgml</term>
  309. <listitem>
  310. <para>
  311. This is the integrated document, including all other documents as parts.
  312. Output is generated in <acronym>HTML</acronym> since the browser interface
  313. makes it easy to move around all of the documentation by just clicking.
  314. The other documents are available in both <acronym>HTML</acronym> and hardcopy.
  315. </para>
  316. </listitem>
  317. </varlistentry>
  319. <varlistentry>
  320. <term>tutorial.sgml</term>
  321. <listitem>
  322. <para>
  323. The introductory tutorial, with examples. Does not include programming topics,
  324. and is intended to help a reader unfamiliar with <acronym>SQL</acronym>.
  325. This is the "getting started" document.
  326. </para>
  327. </listitem>
  328. </varlistentry>
  330. <varlistentry>
  331. <term>user.sgml</term>
  332. <listitem>
  333. <para>
  334. The User's Guide. Includes information on data types and user-level interfaces.
  335. This is the place to put information on "why".
  336. </para>
  337. </listitem>
  338. </varlistentry>
  340. <varlistentry>
  341. <term>reference.sgml</term>
  342. <listitem>
  343. <para>
  344. The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
  345. This is the place to put information on "how".
  346. </para>
  347. </listitem>
  348. </varlistentry>
  350. <varlistentry>
  351. <term>programming.sgml</term>
  352. <listitem>
  353. <para>
  354. The Programmer's Guide. Includes information on <productname>Postgres</productname>
  355. extensibility and on the programming interfaces.
  356. </para>
  357. </listitem>
  358. </varlistentry>
  360. <varlistentry>
  361. <term>admin.sgml</term>
  362. <listitem>
  363. <para>
  364. The Administrator's Guide. Include installation and release notes.
  365. </para>
  366. </listitem>
  367. </varlistentry>
  368. </variablelist>
  369. </para>
  371. <!--
  372. Disable for the hardcopy production release.
  373. Too much tabular info and not very helpful in hardcopy.
  374. - thomas 1998-10-27
  375. -->
  376. </sect2>
  378. <sect2>
  379. <title>Documentation Files</title>
  381. <para>
  382. <table tocentry="1">
  383. <title><productname>Postgres</productname> Documentation Sources</title>
  384. <tgroup cols="3">
  385. <thead>
  386. <row>
  387. <entry>
  388. File
  389. </entry>
  390. <entry>
  391. Status
  392. </entry>
  393. </row>
  394. </thead>
  396. <tbody>
  397. <row><entry> ./doc/src/graphics/catalogs.gif </entry><entry> Output file </entry></row>
  398. <row><entry> ./doc/src/graphics/clientserver.ag </entry><entry> Source file. Convert to CGM </entry></row>
  399. <row><entry> ./doc/src/graphics/clientserver.gif </entry><entry> Output file </entry></row>
  400. <row><entry> ./doc/src/graphics/connections.ag </entry><entry> Source file. Convert to CGM </entry></row>
  401. <row><entry> ./doc/src/graphics/connections.gif </entry><entry> Output file </entry></row>
  402. <row><entry> ./doc/src/graphics/layout.ag </entry><entry> Source file. Convert to CGM </entry></row>
  403. <row><entry> ./doc/src/graphics/layout.gif </entry><entry> Output file </entry></row>
  404. <row><entry> ./doc/src/sgml/about.sgml </entry><entry> New document </entry></row>
  405. <row><entry> ./doc/src/sgml/admin.sgml </entry><entry> Administrator's Guide container </entry></row>
  406. <row><entry> ./doc/src/sgml/advanced.sgml </entry><entry> Converted </entry></row>
  407. <row><entry> ./doc/src/sgml/arch-dev.sgml </entry><entry> Converted </entry></row>
  408. <row><entry> ./doc/src/sgml/arch-pg.sgml </entry><entry> Converted </entry></row>
  409. <row><entry> ./doc/src/sgml/arch.sgml </entry><entry> Converted </entry></row>
  410. <row><entry> ./doc/src/sgml/array.sgml </entry><entry> Converted </entry></row>
  411. <row><entry> ./doc/src/sgml/biblio.sgml </entry><entry> New document </entry></row>
  412. <row><entry> ./doc/src/sgml/bki.sgml </entry><entry> Converted from bki.5 </entry></row>
  413. <row><entry> ./doc/src/sgml/compiler.sgml </entry><entry> New document </entry></row>
  414. <row><entry> ./doc/src/sgml/config.sgml </entry><entry> New document </entry></row>
  415. <row><entry> ./doc/src/sgml/contacts.sgml </entry><entry> Docs contributors? Not used. Either complete or discard </entry></row>
  416. <row><entry> ./doc/src/sgml/datatype.sgml </entry><entry> New document </entry></row>
  417. <row><entry> ./doc/src/sgml/dfunc.sgml </entry><entry> Converted </entry></row>
  418. <row><entry> ./doc/src/sgml/docguide.sgml </entry><entry> Documentation info. New document </entry></row>
  419. <row><entry> ./doc/src/sgml/ecpg.sgml </entry><entry> ecpg eSQL pre-compiler docs </entry></row>
  420. <row><entry> ./doc/src/sgml/environ.sgml </entry><entry> Converted </entry></row>
  421. <row><entry> ./doc/src/sgml/extend.sgml </entry><entry> Converted </entry></row>
  422. <row><entry> ./doc/src/sgml/func-ref.sgml </entry><entry> Converted </entry></row>
  423. <row><entry> ./doc/src/sgml/func.sgml </entry><entry> Converted </entry></row>
  424. <row><entry> ./doc/src/sgml/geqo.sgml </entry><entry> GEQO genetic optimizer docs </entry></row>
  425. <row><entry> ./doc/src/sgml/gist.sgml </entry><entry> New from mailing list </entry></row>
  426. <row><entry> ./doc/src/sgml/history.sgml </entry><entry> New document </entry></row>
  427. <row><entry> ./doc/src/sgml/indices.sgml </entry><entry> New document </entry></row>
  428. <row><entry> ./doc/src/sgml/info.sgml </entry><entry> New document </entry></row>
  429. <row><entry> ./doc/src/sgml/inherit.sgml </entry><entry> Converted </entry></row>
  430. <row><entry> ./doc/src/sgml/install.sgml </entry><entry> Installation instructions </entry></row>
  431. <row><entry> ./doc/src/sgml/intro-ag.sgml </entry><entry> Admin Guide intro. Converted </entry></row>
  432. <row><entry> ./doc/src/sgml/intro-pg.sgml </entry><entry> Programmers Guide intro. Converted </entry></row>
  433. <row><entry> ./doc/src/sgml/intro.sgml </entry><entry> Users Guide intro </entry></row>
  434. <row><entry> ./doc/src/sgml/jdbc.sgml </entry><entry> New document from Peter Mount </entry></row>
  435. <row><entry> ./doc/src/sgml/keys.sgml </entry><entry> New document </entry></row>
  436. <row><entry> ./doc/src/sgml/legal.sgml </entry><entry> Copyright etc. for intros </entry></row>
  437. <row><entry> ./doc/src/sgml/libpgtcl.sgml </entry><entry> Converted </entry></row>
  438. <row><entry> ./doc/src/sgml/libpq++.sgml </entry><entry> C++ library. Converted </entry></row>
  439. <row><entry> ./doc/src/sgml/libpq.sgml </entry><entry> C library </entry></row>
  440. <row><entry> ./doc/src/sgml/lobj.sgml </entry><entry> Large objects </entry></row>
  441. <row><entry> ./doc/src/sgml/manage.sgml </entry><entry> Converted </entry></row>
  442. <row><entry> ./doc/src/sgml/notation.sgml </entry><entry> Docs notation for intros </entry></row>
  443. <row><entry> ./doc/src/sgml/odbc.sgml </entry><entry> ODBC driver </entry></row>
  444. <row><entry> ./doc/src/sgml/oper.sgml </entry><entry> Converted </entry></row>
  445. <row><entry> ./doc/src/sgml/page.sgml </entry><entry> On-disk storage scheme </entry></row>
  446. <row><entry> ./doc/src/sgml/pg_options.sgml </entry><entry> Backend configuration </entry></row>
  447. <row><entry> ./doc/src/sgml/pgaccess.sgml </entry><entry> Converted </entry></row>
  448. <row><entry> ./doc/src/sgml/ports.sgml </entry><entry> Supported/unsupported platforms </entry></row>
  449. <row><entry> ./doc/src/sgml/postgres.sgml </entry><entry> Container for all docs. Best for html output </entry></row>
  450. <row><entry> ./doc/src/sgml/programmer.sgml </entry><entry> Programmer's Guide </entry></row>
  451. <row><entry> ./doc/src/sgml/protocol.sgml </entry><entry> Converted </entry></row>
  452. <row><entry> ./doc/src/sgml/psql.sgml </entry><entry> Converted </entry></row>
  453. <row><entry> ./doc/src/sgml/query-ug.sgml </entry><entry> Converted </entry></row>
  454. <row><entry> ./doc/src/sgml/query.sgml </entry><entry> Converted </entry></row>
  455. <row><entry> ./doc/src/sgml/recovery.sgml </entry><entry> Database recovery </entry></row>
  456. <row><entry> ./doc/src/sgml/reference.sgml </entry><entry> Converted </entry></row>
  457. <row><entry> ./doc/src/sgml/regress.sgml </entry><entry> Regression testing </entry></row>
  458. <row><entry> ./doc/src/sgml/release.sgml </entry><entry> Converted </entry></row>
  459. <row><entry> ./doc/src/sgml/rules.sgml </entry><entry> Rule system </entry></row>
  460. <row><entry> ./doc/src/sgml/runtime.sgml </entry><entry> Runtime environment. New for v6.4 </entry></row>
  461. <row><entry> ./doc/src/sgml/security.sgml </entry><entry> Server security </entry></row>
  462. <row><entry> ./doc/src/sgml/signals.sgml </entry><entry> System signals for backend.  </entry></row>
  463. <row><entry> ./doc/src/sgml/spi.sgml </entry><entry> Converted. Original removed </entry></row>
  464. <row><entry> ./doc/src/sgml/start-ag.sgml </entry><entry> Converted </entry></row>
  465. <row><entry> ./doc/src/sgml/start.sgml </entry><entry> Converted </entry></row>
  466. <row><entry> ./doc/src/sgml/storage.sgml </entry><entry> Converted </entry></row>
  467. <row><entry> ./doc/src/sgml/syntax.sgml </entry><entry> SQL syntax. In UG </entry></row>
  468. <row><entry> ./doc/src/sgml/trigger.sgml </entry><entry> Converted </entry></row>
  469. <row><entry> ./doc/src/sgml/tutorial.sgml </entry><entry> Container for tutorial </entry></row>
  470. <row><entry> ./doc/src/sgml/typeconv.sgml </entry><entry> Datatype conversion. New for v6.4. In UG </entry></row>
  471. <row><entry> ./doc/src/sgml/user.sgml </entry><entry> User's Guide </entry></row>
  472. <row><entry> ./doc/src/sgml/xaggr.sgml </entry><entry> Converted </entry></row>
  473. <row><entry> ./doc/src/sgml/xfunc.sgml </entry><entry> Converted </entry></row>
  474. <row><entry> ./doc/src/sgml/xindex.sgml </entry><entry> Converted </entry></row>
  475. <row><entry> ./doc/src/sgml/xoper.sgml </entry><entry> Converted </entry></row>
  476. <row><entry> ./doc/src/sgml/xplang.sgml </entry><entry> Programming Language. New for v6.4 </entry></row>
  477. <row><entry> ./doc/src/sgml/xtypes.sgml </entry><entry> Converted </entry></row>
  478. <row><entry> ./doc/src/sgml/y2k.sgml </entry><entry> Y2K statement. New for v6.4 </entry></row>
  479. <row><entry> ./doc/src/sgml/ref/abort.sgml </entry><entry> New for v6.4 </entry></row>
  480. <row><entry> ./doc/src/sgml/ref/allfiles.sgml </entry><entry> List of files in ref/ (internal) </entry></row>
  481. <row><entry> ./doc/src/sgml/ref/alter_table.sgml </entry><entry> New for v6.4 </entry></row>
  482. <row><entry> ./doc/src/sgml/ref/alter_user.sgml </entry><entry> New for v6.4 </entry></row>
  483. <row><entry> ./doc/src/sgml/ref/begin.sgml </entry><entry> New for v6.4 </entry></row>
  484. <row><entry> ./doc/src/sgml/ref/close.sgml </entry><entry> New for v6.4 </entry></row>
  485. <row><entry> ./doc/src/sgml/ref/cluster.sgml </entry><entry> New for v6.4 </entry></row>
  486. <row><entry> ./doc/src/sgml/ref/commands.sgml </entry><entry> List of commands (internal) </entry></row>
  487. <row><entry> ./doc/src/sgml/ref/commit.sgml </entry><entry> New for v6.4 </entry></row>
  488. <row><entry> ./doc/src/sgml/ref/copy.sgml </entry><entry> New for v6.4 </entry></row>
  489. <row><entry> ./doc/src/sgml/ref/create_aggregate.sgml </entry><entry> New for v6.4 </entry></row>
  490. <row><entry> ./doc/src/sgml/ref/create_database.sgml </entry><entry> New for v6.4 </entry></row>
  491. <row><entry> ./doc/src/sgml/ref/create_function.sgml </entry><entry> New for v6.4 </entry></row>
  492. <row><entry> ./doc/src/sgml/ref/create_index.sgml </entry><entry> New for v6.4 </entry></row>
  493. <row><entry> ./doc/src/sgml/ref/create_language.sgml </entry><entry> New for v6.4 </entry></row>
  494. <row><entry> ./doc/src/sgml/ref/create_operator.sgml </entry><entry> New for v6.4 </entry></row>
  495. <row><entry> ./doc/src/sgml/ref/create_rule.sgml </entry><entry> New for v6.4 </entry></row>
  496. <row><entry> ./doc/src/sgml/ref/create_sequence.sgml </entry><entry> New for v6.4 </entry></row>
  497. <row><entry> ./doc/src/sgml/ref/create_table.sgml </entry><entry> New for v6.4 </entry></row>
  498. <row><entry> ./doc/src/sgml/ref/create_trigger.sgml </entry><entry> New for v6.4 </entry></row>
  499. <row><entry> ./doc/src/sgml/ref/create_type.sgml </entry><entry> New for v6.4 </entry></row>
  500. <row><entry> ./doc/src/sgml/ref/create_user.sgml </entry><entry> New for v6.4 </entry></row>
  501. <row><entry> ./doc/src/sgml/ref/create_view.sgml </entry><entry> New for v6.4 </entry></row>
  502. <row><entry> ./doc/src/sgml/ref/createdb.sgml </entry><entry> New for v6.4 </entry></row>
  503. <row><entry> ./doc/src/sgml/ref/createuser.sgml </entry><entry> New for v6.4 </entry></row>
  504. <row><entry> ./doc/src/sgml/ref/declare.sgml </entry><entry> New for v6.4 </entry></row>
  505. <row><entry> ./doc/src/sgml/ref/delete.sgml </entry><entry> New for v6.4 </entry></row>
  506. <row><entry> ./doc/src/sgml/ref/destroydb.sgml </entry><entry> New for v6.4 </entry></row>
  507. <row><entry> ./doc/src/sgml/ref/destroyuser.sgml </entry><entry> New for v6.4 </entry></row>
  508. <row><entry> ./doc/src/sgml/ref/drop_aggregate.sgml </entry><entry> New for v6.4 </entry></row>
  509. <row><entry> ./doc/src/sgml/ref/drop_database.sgml </entry><entry> New for v6.4 </entry></row>
  510. <row><entry> ./doc/src/sgml/ref/drop_function.sgml </entry><entry> New for v6.4 </entry></row>
  511. <row><entry> ./doc/src/sgml/ref/drop_index.sgml </entry><entry> New for v6.4 </entry></row>
  512. <row><entry> ./doc/src/sgml/ref/drop_language.sgml </entry><entry> New for v6.4 </entry></row>
  513. <row><entry> ./doc/src/sgml/ref/drop_operator.sgml </entry><entry> New for v6.4 </entry></row>
  514. <row><entry> ./doc/src/sgml/ref/drop_rule.sgml </entry><entry> New for v6.4 </entry></row>
  515. <row><entry> ./doc/src/sgml/ref/drop_sequence.sgml </entry><entry> New for v6.4 </entry></row>
  516. <row><entry> ./doc/src/sgml/ref/drop_table.sgml </entry><entry> New for v6.4 </entry></row>
  517. <row><entry> ./doc/src/sgml/ref/drop_trigger.sgml </entry><entry> New for v6.4 </entry></row>
  518. <row><entry> ./doc/src/sgml/ref/drop_type.sgml </entry><entry> New for v6.4 </entry></row>
  519. <row><entry> ./doc/src/sgml/ref/drop_user.sgml </entry><entry> New for v6.4 </entry></row>
  520. <row><entry> ./doc/src/sgml/ref/drop_view.sgml </entry><entry> New for v6.4 </entry></row>
  521. <row><entry> ./doc/src/sgml/ref/explain.sgml </entry><entry> New for v6.4 </entry></row>
  522. <row><entry> ./doc/src/sgml/ref/fetch.sgml </entry><entry> New for v6.4 </entry></row>
  523. <row><entry> ./doc/src/sgml/ref/grant.sgml </entry><entry> New for v6.4 </entry></row>
  524. <row><entry> ./doc/src/sgml/ref/initdb.sgml </entry><entry> New for v6.4 </entry></row>
  525. <row><entry> ./doc/src/sgml/ref/initlocation.sgml </entry><entry> New for v6.4 </entry></row>
  526. <row><entry> ./doc/src/sgml/ref/insert.sgml </entry><entry> New for v6.4 </entry></row>
  527. <row><entry> ./doc/src/sgml/ref/listen.sgml </entry><entry> New for v6.4 </entry></row>
  528. <row><entry> ./doc/src/sgml/ref/load.sgml </entry><entry> New for v6.4 </entry></row>
  529. <row><entry> ./doc/src/sgml/ref/lock.sgml </entry><entry> New for v6.4 </entry></row>
  530. <row><entry> ./doc/src/sgml/ref/move.sgml </entry><entry> New for v6.4 </entry></row>
  531. <row><entry> ./doc/src/sgml/ref/notify.sgml </entry><entry> New for v6.4 </entry></row>
  532. <row><entry> ./doc/src/sgml/ref/pg_dump.sgml </entry><entry> New for v6.4 </entry></row>
  533. <row><entry> ./doc/src/sgml/ref/pg_dumpall.sgml </entry><entry> New for v6.4 </entry></row>
  534. <row><entry> ./doc/src/sgml/ref/psql-ref.sgml </entry><entry> New for v6.4 </entry></row>
  535. <row><entry> ./doc/src/sgml/ref/reset.sgml </entry><entry> New for v6.4 </entry></row>
  536. <row><entry> ./doc/src/sgml/ref/revoke.sgml </entry><entry> New for v6.4 </entry></row>
  537. <row><entry> ./doc/src/sgml/ref/rollback.sgml </entry><entry> New for v6.4 </entry></row>
  538. <row><entry> ./doc/src/sgml/ref/select.sgml </entry><entry> New for v6.4 </entry></row>
  539. <row><entry> ./doc/src/sgml/ref/set.sgml </entry><entry> New for v6.4 </entry></row>
  540. <row><entry> ./doc/src/sgml/ref/show.sgml </entry><entry> New for v6.4 </entry></row>
  541. <row><entry> ./doc/src/sgml/ref/update.sgml </entry><entry> New for v6.4 </entry></row>
  542. <row><entry> ./doc/src/sgml/ref/vacuum.sgml </entry><entry> New for v6.4 </entry></row>
  543. <row><entry> ./doc/src/sgml/ref/unlisten.sgml </entry><entry> New for v6.4 </entry></row>
  544. <row><entry> ./doc/src/sgml/ref/vacuumdb.sgml </entry><entry> New for v6.4 </entry></row>
  545. <row><entry> ./doc/src/sgml/ref/pg_upgrade.sgml </entry><entry> New for v6.4 </entry></row>
  546. </tbody>
  547. </tgroup>
  548. </table>
  549. </para>
  550. </sect2>
  552. <sect2>
  553. <title>Document Conversion</title>
  555. <para>
  556. <table tocentry="1">
  557. <title><productname>Postgres</productname> Documentation Sources</title>
  558. <tgroup cols="3">
  559. <thead>
  560. <row>
  561. <entry>
  562. File
  563. </entry>
  564. <entry>
  565. Status
  566. </entry>
  567. </row>
  568. </thead>
  570. <tbody>
  571. <row><entry> ./HISTORY </entry><entry> Obsolete. Converted to release.sgml </entry></row>
  572. <row><entry> ./README </entry><entry> Not converted </entry></row>
  573. <row><entry> ./INSTALL </entry><entry> Obsolete. Converted to install.sgml </entry></row>
  574. <row><entry> ./contrib/README </entry><entry> Not converted </entry></row>
  575. <row><entry> ./contrib/apache_logging/README </entry><entry> Not converted </entry></row>
  576. <row><entry> ./contrib/array/array_iterator.doc </entry><entry> Not converted </entry></row>
  577. <row><entry> ./contrib/datetime/datetime_functions.doc </entry><entry> Not converted </entry></row>
  578. <row><entry> ./contrib/earthdistance/README </entry><entry> Not converted </entry></row>
  579. <row><entry> ./contrib/int8/README </entry><entry> Not converted </entry></row>
  580. <row><entry> ./contrib/ip_and_mac/README </entry><entry> Not converted </entry></row>
  581. <row><entry> ./contrib/lo/README </entry><entry> Not converted </entry></row>
  582. <row><entry> ./contrib/mSQL-interface/README </entry><entry> Not converted </entry></row>
  583. <row><entry> ./contrib/noupdate/noup.example </entry><entry> Not converted </entry></row>
  584. <row><entry> ./contrib/pginterface/README </entry><entry> Not converted </entry></row>
  585. <row><entry> ./contrib/sequence/set_sequence.sql.in </entry><entry> Not converted </entry></row>
  586. <row><entry> ./contrib/soundex/soundex.sql.in </entry><entry> Not converted </entry></row>
  587. <row><entry> ./contrib/spi/README </entry><entry> Not converted </entry></row>
  588. <row><entry> ./contrib/spi/autoinc.example </entry><entry> Not converted </entry></row>
  589. <row><entry> ./contrib/spi/insert_username.example </entry><entry> Not converted </entry></row>
  590. <row><entry> ./contrib/spi/refint.example </entry><entry> Not converted </entry></row>
  591. <row><entry> ./contrib/spi/timetravel.example </entry><entry> Not converted </entry></row>
  592. <row><entry> ./contrib/string/string_io.sql.in </entry><entry> Not converted </entry></row>
  593. <row><entry> ./contrib/unixdate/unixdate.sql </entry><entry> Not converted </entry></row>
  594. <row><entry> ./contrib/userlock/user_locks.doc </entry><entry> Not converted </entry></row>
  595. <row><entry> ./doc/FAQ </entry><entry> Not converted </entry></row>
  596. <row><entry> ./doc/FAQ_DEV </entry><entry> Not converted </entry></row>
  597. <row><entry> ./doc/FAQ_FreeBSD </entry><entry> Not converted </entry></row>
  598. <row><entry> ./doc/FAQ_Irix </entry><entry> Not converted </entry></row>
  599. <row><entry> ./doc/FAQ_Linux </entry><entry> Not converted </entry></row>
  600. <row><entry> ./doc/TODO </entry><entry> Not converted </entry></row>
  601. <row><entry> ./doc/README.GEQO </entry><entry> Removed. Superceded by geqo.sgml </entry></row>
  602. <row><entry> ./doc/README.fsync </entry><entry> Assimilate into Admin Guide </entry></row>
  603. <row><entry> ./doc/README.locale </entry><entry> Assimilate into Admin Guide </entry></row>
  604. <row><entry> ./doc/README.mb </entry><entry> Assimilate into Admin Guide </entry></row>
  605. <row><entry> ./doc/README.mb.jp </entry><entry> Not converted </entry></row>
  606. <row><entry> ./doc/README.support </entry><entry> Not converted </entry></row>
  607. <row><entry> ./doc/TODO.GEQO </entry><entry> Removed. Superceded by geqo.sgml </entry></row>
  608. <row><entry> ./doc/userguide.ps </entry><entry> Removed (converted to SGML) </entry></row>
  609. <row><entry> ./src/DEVELOPERS </entry><entry> Not converted </entry></row>
  610. <row><entry> ./src/backend/access/nbtree/README </entry><entry> Not converted </entry></row>
  611. <row><entry> ./src/backend/catalog/README </entry><entry> Not converted </entry></row>
  612. <row><entry> ./src/backend/libpq/pg_hba.conf.sample </entry><entry> Not converted </entry></row>
  613. <row><entry> ./src/backend/libpq/pg_ident.conf.sample </entry><entry> Not converted </entry></row>
  614. <row><entry> ./src/backend/nodes/README </entry><entry> Not converted </entry></row>
  615. <row><entry> ./src/backend/optimizer/README </entry><entry> Not converted </entry></row>
  616. <row><entry> ./src/backend/optimizer/geqo/pg_geqo.sample </entry><entry> Not converted </entry></row>
  617. <row><entry> ./src/backend/optimizer/plan/README </entry><entry> Not converted </entry></row>
  618. <row><entry> ./src/backend/parser/README </entry><entry> Not converted </entry></row>
  619. <row><entry> ./src/backend/port/dynloader/README.dlfcn.aix </entry><entry> Not converted </entry></row>
  620. <row><entry> ./src/backend/regex/COPYRIGHT </entry><entry> Not converted </entry></row>
  621. <row><entry> ./src/backend/regex/WHATSNEW </entry><entry> Not converted </entry></row>
  622. <row><entry> ./src/backend/regex/re_format.7 </entry><entry> Not converted </entry></row>
  623. <row><entry> ./src/backend/regex/regex.3 </entry><entry> Not converted </entry></row>
  624. <row><entry> ./src/backend/storage/ipc/README </entry><entry> Not converted </entry></row>
  625. <row><entry> ./src/backend/storage/lmgr/README </entry><entry> Not converted </entry></row>
  626. <row><entry> ./src/backend/storage/smgr/README </entry><entry> Not converted </entry></row>
  627. <row><entry> ./src/bin/pg_dump/README </entry><entry> Not converted </entry></row>
  628. <row><entry> ./src/bin/pgaccess/README.pga </entry><entry> Not converted </entry></row>
  629. <row><entry> ./src/bin/pgaccess/formdemo.sql </entry><entry> Not converted </entry></row>
  630. <row><entry> ./src/bin/pgtclsh/README </entry><entry> Not converted </entry></row>
  631. <row><entry> ./src/data/charset.conf </entry><entry> Not converted </entry></row>
  632. <row><entry> ./src/data/koi-alt.tab </entry><entry> Not converted </entry></row>
  633. <row><entry> ./src/data/koi-iso.tab </entry><entry> Not converted </entry></row>
  634. <row><entry> ./src/data/koi-koi.tab </entry><entry> Not converted </entry></row>
  635. <row><entry> ./src/data/koi-mac.tab </entry><entry> Not converted </entry></row>
  636. <row><entry> ./src/data/koi-win.tab </entry><entry> Not converted </entry></row>
  637. <row><entry> ./src/interfaces/ecpg/ChangeLog </entry><entry> Not converted </entry></row>
  638. <row><entry> ./src/interfaces/ecpg/TODO </entry><entry> Not converted </entry></row>
  639. <row><entry> ./src/interfaces/jdbc/README </entry><entry> Not converted </entry></row>
  640. <row><entry> ./src/interfaces/jdbc/README_6.3 </entry><entry> Not converted </entry></row>
  641. <row><entry> ./src/interfaces/jdbc/example/ImageViewer.java </entry><entry> Not converted </entry></row>
  642. <row><entry> ./src/interfaces/jdbc/example/basic.java </entry><entry> Not converted </entry></row>
  643. <row><entry> ./src/interfaces/jdbc/example/blobtest.java </entry><entry> Not converted </entry></row>
  644. <row><entry> ./src/interfaces/jdbc/example/datestyle.java </entry><entry> Not converted </entry></row>
  645. <row><entry> ./src/interfaces/jdbc/example/psql.java </entry><entry> Not converted </entry></row>
  646. <row><entry> ./src/interfaces/libpgtcl/README </entry><entry> Not converted </entry></row>
  647. <row><entry> ./src/interfaces/libpq/README </entry><entry> Not converted </entry></row>
  648. <row><entry> ./src/interfaces/libpq++/README </entry><entry> Not converted </entry></row>
  649. <row><entry> ./src/interfaces/libpq++/examples/testlibpq0.cc </entry><entry> Not converted </entry></row>
  650. <row><entry> ./src/interfaces/libpq++/examples/testlibpq1.cc </entry><entry> Not converted </entry></row>
  651. <row><entry> ./src/interfaces/libpq++/examples/testlibpq2.cc </entry><entry> Not converted </entry></row>
  652. <row><entry> ./src/interfaces/libpq++/examples/testlibpq2.sql </entry><entry> Not converted </entry></row>
  653. <row><entry> ./src/interfaces/libpq++/examples/testlibpq3.cc </entry><entry> Not converted </entry></row>
  654. <row><entry> ./src/interfaces/libpq++/examples/testlibpq3.sql </entry><entry> Not converted </entry></row>
  655. <row><entry> ./src/interfaces/libpq++/examples/testlibpq4.cc </entry><entry> Not converted </entry></row>
  656. <row><entry> ./src/interfaces/libpq++/examples/testlibpq4.sql </entry><entry> Not converted </entry></row>
  657. <row><entry> ./src/interfaces/libpq++/examples/testlibpq5.cc </entry><entry> Not converted </entry></row>
  658. <row><entry> ./src/interfaces/libpq++/examples/testlibpq5.sql </entry><entry> Not converted </entry></row>
  659. <row><entry> ./src/interfaces/libpq++/examples/testlibpq6.cc </entry><entry> Not converted </entry></row>
  660. <row><entry> ./src/interfaces/libpq++/examples/testlo.cc </entry><entry> Not converted </entry></row>
  661. <row><entry> ./src/interfaces/odbc/license.txt </entry><entry> Not converted </entry></row>
  662. <row><entry> ./src/interfaces/odbc/notice.txt </entry><entry> Not converted </entry></row>
  663. <row><entry> ./src/interfaces/odbc/readme.txt </entry><entry> Not converted </entry></row>
  664. <row><entry> ./src/interfaces/perl5/MANIFEST </entry><entry> Not converted </entry></row>
  665. <row><entry> ./src/interfaces/perl5/Changes </entry><entry> Not converted </entry></row>
  666. <row><entry> ./src/interfaces/perl5/eg/example.newstyle </entry><entry> Not converted </entry></row>
  667. <row><entry> ./src/interfaces/perl5/README </entry><entry> Not converted </entry></row>
  668. <row><entry> ./src/interfaces/python/Announce </entry><entry> Not converted </entry></row>
  669. <row><entry> ./src/interfaces/python/ChangeLog </entry><entry> Not converted </entry></row>
  670. <row><entry> ./src/interfaces/python/README </entry><entry> Not converted </entry></row>
  671. <row><entry> ./src/interfaces/python/tutorial/advanced.py </entry><entry> Not converted </entry></row>
  672. <row><entry> ./src/interfaces/python/tutorial/advanced.pyc </entry><entry> Not converted </entry></row>
  673. <row><entry> ./src/interfaces/python/tutorial/basics.py </entry><entry> Not converted </entry></row>
  674. <row><entry> ./src/interfaces/python/tutorial/func.py </entry><entry> Not converted </entry></row>
  675. <row><entry> ./src/interfaces/python/tutorial/func.pyc </entry><entry> Not converted </entry></row>
  676. <row><entry> ./src/interfaces/python/tutorial/pgtools.py </entry><entry> Not converted </entry></row>
  677. <row><entry> ./src/interfaces/python/tutorial/pgtools.pyc </entry><entry> Not converted </entry></row>
  678. <row><entry> ./src/interfaces/python/tutorial/syscat.py </entry><entry> Not converted </entry></row>
  679. <row><entry> ./src/interfaces/python/tutorial/syscat.pyc </entry><entry> Not converted </entry></row>
  680. <row><entry> ./src/man/README </entry><entry> Not converted </entry></row>
  681. <row><entry> ./src/man/abort.l </entry><entry> Not converted </entry></row>
  682. <row><entry> ./src/man/alter_table.l </entry><entry> Not converted </entry></row>
  683. <row><entry> ./src/man/alter_user.l </entry><entry> Split into Reference and Admin Guide </entry></row>
  684. <row><entry> ./src/man/begin.l </entry><entry> Not converted </entry></row>
  685. <row><entry> ./src/man/catalogs.3 </entry><entry> Catalog synopsis. Move to Programmer's Guide? </entry></row>
  686. <row><entry> ./src/man/cleardbdir.1 </entry><entry> Not converted </entry></row>
  687. <row><entry> ./src/man/close.l </entry><entry> Not converted </entry></row>
  688. <row><entry> ./src/man/cluster.l </entry><entry> Not converted </entry></row>
  689. <row><entry> ./src/man/commit.l </entry><entry> Not converted </entry></row>
  690. <row><entry> ./src/man/copy.l </entry><entry> Not converted </entry></row>
  691. <row><entry> ./src/man/create_aggregate.l </entry><entry> Not converted </entry></row>
  692. <row><entry> ./src/man/create_database.l </entry><entry> Not converted </entry></row>
  693. <row><entry> ./src/man/create_function.l </entry><entry> Not converted </entry></row>
  694. <row><entry> ./src/man/create_index.l </entry><entry> Not converted </entry></row>
  695. <row><entry> ./src/man/create_language.l </entry><entry> Not converted </entry></row>
  696. <row><entry> ./src/man/create_operator.l </entry><entry> Not converted </entry></row>
  697. <row><entry> ./src/man/create_rule.l </entry><entry> Not converted </entry></row>
  698. <row><entry> ./src/man/create_sequence.l </entry><entry> Not converted </entry></row>
  699. <row><entry> ./src/man/create_table.l </entry><entry> Not converted </entry></row>
  700. <row><entry> ./src/man/create_trigger.l </entry><entry> Not converted </entry></row>
  701. <row><entry> ./src/man/create_type.l </entry><entry> Not converted </entry></row>
  702. <row><entry> ./src/man/create_user.l </entry><entry> Not converted </entry></row>
  703. <row><entry> ./src/man/create_version.l </entry><entry> Not converted </entry></row>
  704. <row><entry> ./src/man/create_view.l </entry><entry> Not converted </entry></row>
  705. <row><entry> ./src/man/createdb.1 </entry><entry> Not converted </entry></row>
  706. <row><entry> ./src/man/createuser.1 </entry><entry> Not converted </entry></row>
  707. <row><entry> ./src/man/declare.l </entry><entry> Not converted </entry></row>
  708. <row><entry> ./src/man/delete.l </entry><entry> Not converted </entry></row>
  709. <row><entry> ./src/man/destroydb.1 </entry><entry> Not converted </entry></row>
  710. <row><entry> ./src/man/destroyuser.1 </entry><entry> Not converted </entry></row>
  711. <row><entry> ./src/man/drop.l </entry><entry> Not converted </entry></row>
  712. <row><entry> ./src/man/drop_aggregate.l </entry><entry> Not converted </entry></row>
  713. <row><entry> ./src/man/drop_database.l </entry><entry> Not converted </entry></row>
  714. <row><entry> ./src/man/drop_function.l </entry><entry> Not converted </entry></row>
  715. <row><entry> ./src/man/drop_index.l </entry><entry> Not converted </entry></row>
  716. <row><entry> ./src/man/drop_language.l </entry><entry> Not converted </entry></row>
  717. <row><entry> ./src/man/drop_operator.l </entry><entry> Not converted </entry></row>
  718. <row><entry> ./src/man/drop_rule.l </entry><entry> Not converted </entry></row>
  719. <row><entry> ./src/man/drop_sequence.l </entry><entry> Not converted </entry></row>
  720. <row><entry> ./src/man/drop_table.l </entry><entry> Not converted </entry></row>
  721. <row><entry> ./src/man/drop_trigger.l </entry><entry> Not converted </entry></row>
  722. <row><entry> ./src/man/drop_type.l </entry><entry> Not converted </entry></row>
  723. <row><entry> ./src/man/drop_user.l </entry><entry> Not converted </entry></row>
  724. <row><entry> ./src/man/drop_view.l </entry><entry> Not converted </entry></row>
  725. <row><entry> ./src/man/end.l </entry><entry> Not converted </entry></row>
  726. <row><entry> ./src/man/ecpg.1 </entry><entry> Short man page. Retain </entry></row>
  727. <row><entry> ./src/man/explain.l </entry><entry> Not converted </entry></row>
  728. <row><entry> ./src/man/fetch.l </entry><entry> Not converted </entry></row>
  729. <row><entry> ./src/man/grant.l </entry><entry> Not converted </entry></row>
  730. <row><entry> ./src/man/initdb.1 </entry><entry> Not converted </entry></row>
  731. <row><entry> ./src/man/initlocation.1 </entry><entry> Not converted </entry></row>
  732. <row><entry> ./src/man/insert.l </entry><entry> Not converted </entry></row>
  733. <row><entry> ./src/man/ipcclean.1 </entry><entry> Not converted </entry></row>
  734. <row><entry> ./src/man/listen.l </entry><entry> Not converted </entry></row>
  735. <row><entry> ./src/man/load.l </entry><entry> Not converted </entry></row>
  736. <row><entry> ./src/man/lock.l </entry><entry> Not converted </entry></row>
  737. <row><entry> ./src/man/move.l </entry><entry> Not converted </entry></row>
  738. <row><entry> ./src/man/notify.l </entry><entry> Not converted </entry></row>
  739. <row><entry> ./src/man/pg_dump.1 </entry><entry> Assimilate into Admin Guide </entry></row>
  740. <row><entry> ./src/man/pg_dumpall.1 </entry><entry> Assimilate into Admin Guide </entry></row>
  741. <row><entry> ./src/man/pg_upgrade.1 </entry><entry> Assimilate into Admin Guide </entry></row>
  742. <row><entry> ./src/man/pg_hba.conf.5 </entry><entry> Assimilate into Admin Guide </entry></row>
  743. <row><entry> ./src/man/pg_passwd.1 </entry><entry> Assimilate into Admin Guide </entry></row>
  744. <row><entry> ./src/man/pgintro.1 </entry><entry> Assimilate into User's Guide? </entry></row>
  745. <row><entry> ./src/man/postgres.1 </entry><entry> Assimilate into User's, Admin Guides </entry></row>
  746. <row><entry> ./src/man/postmaster.1 </entry><entry> Assimilate into User's, Admin Guides </entry></row>
  747. <row><entry> ./src/man/psql.1 </entry><entry> Not converted </entry></row>
  748. <row><entry> ./src/man/reset.l </entry><entry> Not converted </entry></row>
  749. <row><entry> ./src/man/revoke.l </entry><entry> Not converted </entry></row>
  750. <row><entry> ./src/man/rollback.l </entry><entry> Not converted </entry></row>
  751. <row><entry> ./src/man/select.l </entry><entry> Not converted </entry></row>
  752. <row><entry> ./src/man/set.l </entry><entry> Not converted </entry></row>
  753. <row><entry> ./src/man/show.l </entry><entry> Not converted </entry></row>
  754. <row><entry> ./src/man/sql.l </entry><entry> Not converted </entry></row>
  755. <row><entry> ./src/man/update.l </entry><entry> Not converted </entry></row>
  756. <row><entry> ./src/man/vacuum.l </entry><entry> Not converted </entry></row>
  757. <row><entry> ./src/pl/tcl/INSTALL </entry><entry> Not converted </entry></row>
  758. <row><entry> ./src/pl/tcl/modules/README </entry><entry> Not converted </entry></row>
  759. <row><entry> ./src/pl/tcl/license.terms </entry><entry> Not converted </entry></row>
  760. <row><entry> ./src/pl/tcl/test/README </entry><entry> Not converted </entry></row>
  761. <row><entry> ./src/pl/tcl/test/runtest </entry><entry> Not converted </entry></row>
  762. <row><entry> ./src/pl/tcl/test/test.expected </entry><entry> Not converted </entry></row>
  763. <row><entry> ./src/pl/tcl/test/test_mklang.sql </entry><entry> Not converted </entry></row>
  764. <row><entry> ./src/pl/tcl/test/test_queries.sql </entry><entry> Not converted </entry></row>
  765. <row><entry> ./src/pl/tcl/test/test_setup.sql </entry><entry> Not converted </entry></row>
  766. <row><entry> ./src/test/bench/WISC-README </entry><entry> Not converted </entry></row>
  767. <row><entry> ./src/test/locale/README </entry><entry> Not converted </entry></row>
  768. <row><entry> ./src/test/performance/results/PgSQL.970926 </entry><entry> Not converted </entry></row>
  769. <row><entry> ./src/test/regress/README </entry><entry> Not converted </entry></row>
  770. <row><entry> ./src/test/suite/README </entry><entry> Not converted </entry></row>
  771. <row><entry> ./src/tools/RELEASE_CHANGES </entry><entry> Not converted </entry></row>
  772. <row><entry> ./src/tools/SQL_keywords </entry><entry> Not converted </entry></row>
  773. <row><entry> ./src/tools/backend/README </entry><entry> Not converted </entry></row>
  774. <row><entry> ./src/tools/backend/flow.fig </entry><entry> Not converted </entry></row>
  775. <row><entry> ./src/tools/backend/flow.jpg </entry><entry> Not converted </entry></row>
  776. <row><entry> ./src/tools/make_keywords.README </entry><entry> Not converted </entry></row>
  777. <row><entry> ./src/tools/entab/entab.man </entry><entry> Not converted </entry></row>
  778. <row><entry> ./src/tools/make_diff/README </entry><entry> Not converted </entry></row>
  779. <row><entry> ./src/tools/mkldexport/README </entry><entry> Not converted </entry></row>
  780. <row><entry> ./src/tools/pgindent/README </entry><entry> Not converted </entry></row>
  781. <row><entry> ./src/tutorial/README </entry><entry> Not converted </entry></row>
  782. <row><entry> ./src/utils/README </entry><entry> Not converted </entry></row>
  783. <row><entry> ./lib/pg_hba.conf.sample </entry><entry> Not converted </entry></row>
  784. <row><entry> ./lib/pg_geqo.sample </entry><entry> Not converted </entry></row>
  785. </tbody>
  786. </tgroup>
  787. </table>
  788. </para>
  789. </sect2>
  791. <sect2>
  792. <title>Styles and Conventions</title>
  794. <para>
  795. <productname>DocBook</productname> has a rich set of tags and
  796. constructs, and a suprisingly large percentage are directly and
  797. obviously useful for well-formed documentation. The
  798. <productname>Postgres</productname> documentation set has only
  799. recently been adapted to <acronym>SGML</acronym>, and in the near
  800. future several sections of the set will be selected and maintained as
  801. prototypical examples of <productname>DocBook</productname> usage.
  802. Also, a short summary of <productname>DocBook</productname> tags will
  803. be included below.
  804. </para>
  806. <!--
  807. <para>
  808. <table tocentry="1">
  809. <title>SGML Constructs</title>
  810. <titleabbrev>SGML Constructs</titleabbrev>
  811. <tgroup cols="2">
  812. <thead>
  813.   <row>
  814.     <entry>SGML Tag</entry>
  815.     <entry>Usage</entry>
  816.   </row>
  817. </thead>
  818. <tbody>
  819.   <row>
  820.     <entry><sgmltag>book</sgmltag></entry>
  821.     <entry>Delimits a Book element</entry>
  822.   </row>
  823.   <row>
  824.     <entry><sgmltag>chapter</sgmltag></entry>
  825.     <entry>Delimits a Chapter element</entry>
  826.   </row>
  827.   <row>
  828.     <entry><sgmltag>appendix</sgmltag></entry>
  829.     <entry><sgmltag>Delimits a Appendix element</sgmltag></entry>
  830.   </row>
  831. </tbody>
  832. </tgroup>
  833. </table>
  834. </para>
  835. -->
  836. </sect2>
  838. <sect2>
  839. <title>SGML Authoring Tools</title>
  841. <para>
  842. The current <acronym>Postgres</acronym> documentation set was written using
  843. a plain text editor (or emacs/psgml; see below) with the content marked up using 
  844. <acronym>SGML</acronym> DocBook tags.
  845. </para>
  847. <para>
  848. <acronym>SGML</acronym> and <productname>DocBook</productname> do not suffer
  849. from an oversupply of open-source authoring tools. The most common toolset is
  850. the emacs/xemacs editing package with the psgml feature extension.
  851. On some systems (e.g. RedHat Linux) these tools are provided in a typical full installation.
  852. </para>
  854. <sect3>
  855. <title>emacs/psgml</title>
  857. <para>
  858. <application>emacs</application> (and <application>xemacs</application>) have
  859. an <acronym>SGML</acronym> <firstterm>major mode</firstterm>. When properly configured,
  860. this will allow you to use <application>emacs</application> to insert tags and
  861. check markup consistancy.
  862. </para>
  864. <para>
  865.      Put the following in your <filename>~/.emacs</filename> environment file:
  867. <programlisting>
  868. ; ********** for SGML mode (psgml)
  870. (setq sgml-catalog-files "/usr/lib/sgml/CATALOG")
  871. (setq sgml-local-catalogs "/usr/lib/sgml/CATALOG")
  873. (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
  874. </programlisting>
  876. and add an entry in the same file
  877. for <acronym>SGML</acronym> into the (existing) definition for
  878. auto-mode-alist:
  880. <programlisting>
  881. (setq
  882.   auto-mode-alist
  883.   '(("\.sgml$" . sgml-mode)
  884.    ))
  885. </programlisting>
  887. Each <acronym>SGML</acronym> source file has the following block at the
  888. end of the file:
  890. <programlisting>
  891. <sgmltag>!-- Keep this comment at the end of the file
  892. Local variables:
  893. mode: sgml
  894. sgml-omittag:t
  895. sgml-shorttag:t
  896. sgml-minimize-attributes:nil
  897. sgml-always-quote-attributes:t
  898. sgml-indent-step:1
  899. sgml-indent-data:t
  900. sgml-parent-document:nil
  901. sgml-default-dtd-file:"./reference.ced"
  902. sgml-exposed-tags:nil
  903. sgml-local-catalogs:"/usr/lib/sgml/catalog"
  904. sgml-local-ecat-files:nil
  905. End:
  906. --</sgmltag>
  907. </programlisting>
  908. </para>
  910. <para>
  911.      The <productname>Postgres</productname> distribution includes a
  912.      parsed DTD definitions file <filename>reference.ced</filename>.
  913. You may find that
  914. </para>
  916. <para>
  917. When using <application>emacs</application>/psgml, a comfortable way of working with
  918. these separate files of book parts is to insert a proper DOCTYPE
  919. declaration while you're editing them.  If you are working on this source, for instance,
  920. it's an appendix chapter, so you would specify the document as an "appendix" instance of
  921. a DocBook document by making the first line look like this:
  923. <programlisting>
  924. <sgmltag>!doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"</sgmltag>
  925. </programlisting>
  927. This means that anything and everything that reads <acronym>SGML</acronym> will get it
  928. right, and I can verify the document with "nsgmls -s docguide.sgml".
  929. </para>
  931. </sect3>
  932. </sect2>
  933. </sect1>
  935.  <sect1>
  936.   <title>Building Documentation</title>
  938.   <para>
  939.    GNU <application>make</application> is used to build documentation
  940.    from the DocBook sources. There are a few environment definitions
  941.    which may need to be set or modified for your installation.
  942.    The <filename>Makefile</filename> looks for
  943.    <filename>doc/../src/Makefile</filename> and (implicitly) for
  944.    <filename>doc/../src/Makefile.custom</filename> to obtain
  945.    environment information. On my system, the
  946.    <filename>src/Makefile.custom</filename> looks like
  948.    <programlisting>
  949. # Makefile.custom
  950. # Thomas Lockhart 1998-03-01
  952. POSTGRESDIR= /opt/postgres/current
  953. CFLAGS+= -m486
  954. YFLAGS+= -v
  956. # documentation
  958. HSTYLE= /home/tgl/SGML/db107.d/docbook/html
  959. PSTYLE= /home/tgl/SGML/db107.d/docbook/print
  960.    </programlisting>
  962.    where HSTYLE and PSTYLE determine the path to
  963.    <filename>docbook.dsl</filename> for <acronym>HTML</acronym>
  964.    and hardcopy (print) stylesheets, respectively. These stylesheet
  965.    file names are for Norm Walsh's
  966.    <productname>Modular Style Sheets</productname>; if other
  967.    stylesheets are used then one can define HDSL and PDSL as the full path
  968.    and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.
  969.    On many systems, these stylesheets will be found in packages installed in 
  970.    <filename>/usr/lib/sgml/</filename>,
  971.    <filename>/usr/share/lib/sgml/</filename>,
  972.    or
  973.    <filename>/usr/local/lib/sgml/</filename>.
  974.   </para>
  976.   <para>
  977.    <acronym>HTML</acronym> documentation packages can be generated
  978.    from the <acronym>SGML</acronym> source by typing
  979.    <programlisting>
  980. % cd doc/src
  981. % make tutorial.tar.gz
  982. % make user.tar.gz
  983. % make admin.tar.gz
  984. % make programmer.tar.gz
  985. % make postgres.tar.gz
  986. % make install
  987.    </programlisting>
  988.   </para>
  990.   <para>
  991.    These packages can be installed from the main documentation directory
  992.    by typing
  993.    <programlisting>
  994. % cd doc
  995. % make install
  996.    </programlisting>
  997.   </para>
  998.  </sect1>
  1000.  <sect1>
  1001.   <title>Manpages</title>
  1003.   <para>
  1004.    We use the <application>docbook2man</application> utility to
  1005.    convert <productname>DocBook</productname>
  1006.    <sgmltag>REFENTRY</sgmltag> pages to *roff output suitable for man
  1007.    pages. At the time of writing, the utility required patching to
  1008.    successfully run on the <productname>Postgres</productname> markup, 
  1009.    and we added a small amount of new functionality to allow setting
  1010.    the man page section in the output file name.
  1011.   </para>
  1013.   <para>
  1014.    <application>docbook2man</application> is written in perl, and
  1015.    requires the CPAN package <literal>SGMLSpm</literal> to run. Also,
  1016.    it requires <application>nsgmls</application> to be available,
  1017.    which is included in the <application>jade</application>
  1018.    distribution. After installing these packages, then simply run
  1020.    <programlisting>
  1021. $ cd doc/src
  1022. $ make man
  1023.    </programlisting>
  1025.    which will result in a tar file being generated in the
  1026.    <filename>doc/src</filename> directory.
  1027.   </para>
  1029.   <procedure>
  1030.    <title>docbook2man Installation Procedure</title>
  1032.    <step performance="required">
  1033.     <para>
  1034.      Install the <application>docbook2man</application> package,
  1035.      available at
  1036.      <ulink url="http://shell.ipoline.com/~elmert/comp/docbook2X/">http://shell.ipoline.com/~elmert/comp/docbook2X/</ulink>
  1037.     </para>
  1038.    </step>
  1040.    <step performance="required">
  1041.     <para>
  1042.      Install the SGMLSpm perl module, available from CPAN mirrors.
  1043.     </para>
  1044.    </step>
  1046.    <step performance="required">
  1047.     <para>
  1048.      Install <application>nsgmls</application> if not already
  1049.      available from your <application>jade</application> installation.
  1050.     </para>
  1051.    </step>
  1052.   </procedure>
  1053.  </sect1>
  1055.  <sect1>
  1056.   <title>Hardcopy Generation for v6.5</title>
  1058.   <para>
  1059.    The hardcopy Postscript documentation is generated by converting the
  1060.    <acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
  1061.    importing into <productname>ApplixWare-4.4.1</productname>. 
  1062.    After a little cleanup (see the following
  1063.    section) the output is "printed" to a postscript file.
  1064.   </para>
  1066. <!--
  1067.   <para>
  1068.    Some figures were redrawn to avoid having bitmap
  1069.    <acronym>GIF</acronym> files in the hardcopy documentation. One
  1070.    figure, of the system catalogs, was sufficiently complex that there
  1071.    was  not time to redraw it. It was converted to fit using the
  1072.    following commands:
  1074.    <programlisting>
  1075. % convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif
  1076. % convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif
  1077.    </programlisting>
  1079.   </para>
  1080. -->
  1082.   <sect2>
  1083.    <title>Text Hardcopy</title>
  1085.    <para>
  1086.     <filename>INSTALL</filename> and <filename>HISTORY</filename> are
  1087.     updated for each release. For historical reasons, these files are
  1088.     in plain text, but are derived from the newer
  1089.     <acronym>SGML</acronym> sources.
  1090.    </para>
  1092.    <procedure>
  1093.     <title>Plain Text Generation</title>
  1095.     <para>
  1096.      Both <filename>INSTALL</filename> and
  1097.      <filename>HISTORY</filename> are generated from existing
  1098.      <acronym>SGML</acronym> sources. They are extracted from the same 
  1099.      intermediate <acronym>RTF</acronym> file.
  1100.     </para>
  1102.     <step performance="required">
  1103.      <para>
  1104.       Generate <acronym>RTF</acronym> by typing:
  1105.       <programlisting>
  1106. % cd doc/src/sgml
  1107. % make installation.rtf
  1108.       </programlisting>
  1109.      </para>
  1110.     </step>
  1111.       
  1112.     <step performance="required">
  1113.      <para>
  1114.       Import <filename>installation.rtf</filename> into
  1115.       <productname>Applix Words</productname>.
  1116.      </para>
  1117.     </step>
  1119.     <step performance="required">
  1120.      <para>
  1121.       Set the page width and margins.
  1122.      </para>
  1124.      <substeps>
  1125.       <step performance="required">
  1126.        <para>
  1127. Adjust the page width in File.PageSetup to 10 inches.
  1128.        </para>
  1129.       </step>
  1131.       <step performance="required">
  1132.        <para>
  1133. Select all text.
  1134. Adjust the right margin using the ruler to 9.5 inches. This
  1135. will give a maximum column width of 79 characters, within the
  1136. 80 columns upper limit goal.
  1137.        </para>
  1138.       </step>
  1139.      </substeps>
  1140.     </step>
  1142.     <step performance="required">
  1143.      <para>
  1144.       Lop off the parts of the document which are not needed.
  1145.      </para>
  1147.      <para>
  1148.       For <filename>INSTALL</filename>, remove all release notes from
  1149.       the end of the text, except for those from the current release.
  1150.       For <filename>HISTORY</filename>, remove all text up to the
  1151.       release notes, preserving and modifying the title and ToC.
  1152.      </para>
  1153.     </step>
  1155.     <step performance="required">
  1156.      <para>
  1157.       Export the result as <quote>ASCII Layout</quote>.
  1158.      </para>
  1159.     </step>
  1161.     <step performance="required">
  1162.      <para>
  1163.       Using emacs or vi, clean up the tabular information in
  1164.       <filename>INSTALL</filename>. Remove the <quote>mailto</quote>
  1165.       <acronym>URLs</acronym> for the porting contributors to shrink
  1166.       the column heights.
  1167.      </para>
  1168.     </step>
  1169.    </procedure>
  1170.   </sect2>
  1172.   <sect2>
  1173.    <title>Postscript Hardcopy</title>
  1175.    <para>
  1176.     Several items must be addressed in generating Postscript
  1177.     hardcopy:</para>
  1179.    <procedure>
  1180.     <title>Applixware <acronym>RTF</acronym> Cleanup</title>
  1182.     <para>
  1183.      Applixware does not seem to do a complete job of importing <acronym>RTF</acronym>
  1184.      generated by jade/MSS. In particular, all text is given the
  1185.      <quote>Header1</quote> style attribute label, although the text
  1186.      formatting itself is acceptable. Also, the Table of Contents page
  1187.      numbers do not refer to the section listed in the table, but rather
  1188.      refer to the page of the ToC itself.</para>
  1190.     <step performance="required">
  1191.      <para>
  1192.       Generate the <acronym>RTF</acronym> input by typing (for example):
  1193.       <programlisting>
  1194. % cd doc/src/sgml
  1195. % make tutorial.rtf
  1196.       </programlisting>
  1197.      </para>
  1198.     </step>
  1200.     <step performance="required">
  1201.      <para>
  1202.       Open a new document in <productname>Applix Words</productname> and
  1203.       then import the <acronym>RTF</acronym> file.
  1204.      </para>
  1205.     </step>
  1207.     <step performance="required">
  1208.      <para>
  1209.       Print out the existing Table of Contents, to mark up in the following
  1210.       few steps.
  1211.      </para>
  1212.     </step>
  1214.     <step performance="required">
  1215.      <para>
  1216.       Insert figures into the document. Center each figure on the page using
  1217.       the centering margins button.</para>
  1219.      <para>
  1220.       Not all documents have figures.
  1221.       You can grep the <acronym>SGML</acronym> source files for
  1222.       the string <quote>graphic</quote> to identify those parts of the
  1223.       documentation which may have figures. A few figures are replicated in
  1224.       various parts of the documentation.
  1225.      </para>
  1226.     </step>
  1228.     <step performance="required">
  1229.      <para>
  1230.       Work through the document, adjusting page breaks and table column
  1231.       widths.
  1232.      </para>
  1233.     </step>
  1235.     <step performance="required">
  1236.      <para>
  1237.       If a bibliography is present, Applix Words seems to mark all remaining
  1238.       text after the first title as having an underlined attribute. Select
  1239.       all remaining text, turn off underlining using the underlining button,
  1240.       then explicitly underline each document and book title.
  1241.      </para>
  1242.     </step>
  1244.     <step performance="required">
  1245.      <para>
  1246.       Work through the document, marking up the ToC hardcopy with the actual
  1247.       page number of each ToC entry.
  1248.      </para>
  1249.     </step>
  1251.     <step performance="required">
  1252.      <para>
  1253.       Replace the right-justified incorrect page numbers in the ToC with
  1254.       correct values. This only takes a few minutes per document.
  1255.      </para>
  1256.     </step>
  1258.     <step performance="required">
  1259.      <para>
  1260.       Save the document as native Applix Words format to allow easier last
  1261.       minute editing later.
  1262.      </para>
  1263.     </step>
  1265.     <step performance="required">
  1266.      <para>
  1267.       <quote>Print</quote> the document
  1268.       to a file in Postscript format.
  1269.      </para>
  1270.     </step>
  1272.     <step performance="required">
  1273.      <para>
  1274.       Compress the Postscript file using <application>gzip</application>.
  1275.       Place the compressed file into the <filename>doc</filename> directory.
  1276.      </para>
  1277.     </step>
  1278.    </procedure>
  1280.   </sect2>
  1281. </sect1>
  1283. <sect1>
  1284. <title>Toolsets</title>
  1286. <para>
  1287. We have documented experience with two installation methods for the
  1288. various tools that are needed to process the documentation.  One is
  1289. installation from <acronym>RPM</acronym>s on
  1290. <productname>Linux</productname>, the other is a general installation
  1291. from original distributions of the individual tools.  Both will be
  1292. described below.</para>
  1294. <para>
  1295. We understand that there are some other packaged distributions for
  1296. these tools.  <productname>FreeBSD</productname> seems to have them
  1297. available.  Please report package status to the docs mailing list and
  1298. we will include that information here.
  1299. </para>
  1301. <sect2>
  1302. <title><acronym>RPM</acronym> installation on
  1303. <productname>Linux</productname></title>
  1305. <para>
  1306. Install <ulink url="ftp://ftp.cygnus.com/pub/home/rosalia/">
  1307. <acronym>RPM</acronym>s</ulink> for <productname>Jade</productname>
  1308. and related packages.
  1309. </para>
  1310. </sect2>
  1312. <sect2>
  1313. <title>Manual installation of tools</title>
  1315. <para>
  1316. This is a brief run-through of the process of obtaining and
  1317. installing the software you'll need to edit DocBook source with Emacs
  1318. and process it with Norman Walsh's DSSSL style sheets to create <acronym>HTML</acronym>
  1319. and <acronym>RTF</acronym>.
  1320. </para>
  1322. <para>
  1323. These instructions do not cover new <application>jade</application>/DocBook
  1324. support in the 
  1325. <ulink url="http://www.sgmltools.org/"><productname>sgml-tools</productname></ulink>
  1326. package. The authors have not tried this package since it adopted DocBook, 
  1327. but it is almost certainly a good candidate for use.
  1328. </para>
  1330. <sect3><title>Prerequisites</title>
  1332. <para>What you need:
  1334. <itemizedlist>
  1335. <listitem><para>A working installation of GCC 2.7.2</para></listitem>
  1336. <listitem><para>A working installation of Emacs 19.19 or later</para></listitem>
  1337. <listitem><para>An unzip program for UNIX to unpack things</para></listitem>
  1338. </itemizedlist>
  1340. </para>
  1342. <para>What you must fetch:
  1344. <itemizedlist>
  1345. <listitem>
  1346. <para><ulink url="ftp://ftp.jclark.com/pub/jade/">
  1347. James Clark's <productname>Jade</productname></ulink>
  1348. (version 1.1 in file <filename>jade1_1.zip</filename> was current at the time of writing)
  1349. </para></listitem>
  1350. <listitem>
  1351. <para><ulink url="http://www.ora.com/davenport/docbook/current/docbk30.zip">
  1352. <productname>DocBook</productname> version 3.0</ulink>
  1353. </para></listitem>
  1354. <listitem>
  1355. <para><ulink url="http://nwalsh.com/docbook/dsssl/">
  1356. Norman Walsh's <productname>Modular Stylesheets</productname></ulink>
  1357. (version 1.19 was used to produce these documents)
  1358. </para></listitem>
  1359. <listitem>
  1360. <para><ulink url="ftp://ftp.lysator.liu.se/pub/sgml/">
  1361. Lennart Staflin's <productname>PSGML</productname></ulink>
  1362. (version 1.0.1 in <filename>psgml-1.0.1.tar.gz</filename> was available at the time of writing)
  1363. </para></listitem>
  1364. </itemizedlist>
  1366. </para>
  1368. <para>Important URLs:
  1370. <itemizedlist>
  1371. <listitem><para><ulink url="http://www.jclark.com/jade/">
  1372. The <productname>Jade</productname> web page</ulink></para></listitem>
  1373. <listitem><para><ulink url="http://www.ora.com/davenport/">
  1374. The <productname>DocBook</productname> web page</ulink></para></listitem>
  1375. <listitem><para><ulink url="http://nwalsh.com/docbook/dsssl/">
  1376. The <productname>Modular Stylesheets</productname> web page</ulink>
  1377. </para></listitem>
  1378. <listitem><para>
  1379. <ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
  1380. The <productname>PSGML</productname> web page</ulink></para></listitem>
  1381. <listitem><para><ulink url="http://www.infotek.no/sgmltool/guide.htm">
  1382. Steve Pepper's Whirlwind Guide</ulink></para></listitem>
  1383. <listitem><para><ulink url="http://www.sil.org/sgml/publicSW.html">
  1384. Robin Cover's database of <acronym>SGML</acronym> software</ulink></para></listitem>
  1385. </itemizedlist>
  1386. </para>
  1388. </sect3>
  1390. <sect3>
  1391. <title>Installing Jade</title>
  1393. <procedure>
  1394. <title>Installing Jade</title>
  1396. <step performance="required">
  1397. <para>
  1398. Read the installation instructions at the above listed
  1399. URL.
  1400. </para>
  1401. </step>
  1403. <step performance="required">
  1404. <para>
  1405. Unzip the distribution kit in a suitable place.  The command to do
  1406. this will be something like
  1407. <programlisting>
  1408. unzip -aU jade1_1.zip
  1409. </programlisting>
  1410. </para>
  1411. </step>
  1413. <step performance="required">
  1414. <para><productname>Jade</productname> is not built using
  1415. <productname>GNU Autoconf</productname>, so you'll need to edit a
  1416. <filename>Makefile</filename> yourself.  Since James Clark has been
  1417. good enough to prepare his kit for it, it is a good idea to make a
  1418. build directory (named for your machine architecture, perhaps) under
  1419. the main directory of the <productname>Jade</productname>
  1420. distribution, copy the file <filename>Makefile</filename> from the
  1421. main directory into it, edit it there, and then run
  1422. <command>make</command> there.</para>
  1424. <para>However, the <filename>Makefile</filename> does need to be
  1425. edited.  There is a file called <filename>Makefile.jade</filename> in
  1426. the main directory, which is intended to be used with <command>make -f
  1427. Makefile.jade</command> when building <productname>Jade</productname>
  1428. (as opposed to just <productname>SP</productname>, the <acronym>SGML</acronym> parser kit
  1429. that <productname>Jade</productname> is built upon). We suggest that
  1430. you don't do that, though, since there is more that you need to change
  1431. than what is in <filename>Makefile.jade</filename>, so you'd have to
  1432. edit one of them anyway.</para>
  1434. <para>Go through the <filename>Makefile</filename>, reading James'
  1435. instructions and editing as needed.  There are various variables that
  1436. need to be set.  Here is a collected summary of the most important
  1437. ones, with typical values:
  1438. <programlisting>
  1439. prefix = /usr/local
  1440. XDEFINES = -DSGML_CATALOG_FILES_DEFAULT="/usr/local/share/sgml/catalog"
  1441. XLIBS = -lm
  1442. RANLIB = ranlib
  1443. srcdir = ..
  1444. XLIBDIRS = grove spgrove style
  1445. XPROGDIRS = jade
  1446. </programlisting>
  1447. Note the specification of where to find the default catalog of
  1448. <acronym>SGML</acronym> support files -- you may want to change that
  1449. to something more suitable for your own installation.  If your system
  1450. doesn't need the above settings for the math library and the
  1451. <command>ranlib</command> command, leave them as they are in the
  1452. <filename>Makefile</filename>.
  1453. </para>
  1454. </step>
  1456. <step performance="required">
  1457. <para>Type <command>make</command> to build Jade and the various
  1458. <productname>SP</productname> tools.</para>
  1459. </step>
  1461. <step performance="required">
  1462. <para>Once the software is built, <command>make install</command> will
  1463. do the obvious.</para>
  1464. </step>
  1465. </procedure>
  1466. </sect3>
  1468. <sect3>
  1469. <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
  1471. <procedure>
  1472. <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
  1474. <step performance="required">
  1475. <para>You'll want to place the files that make up the
  1476. <productname>DocBook</productname> <acronym>DTD</acronym> kit in the
  1477. directory you built <productname>Jade</productname> to expect them in,
  1478. which, if you followed our suggestion above, is
  1479. <filename>/usr/local/share/sgml/</filename>.  In addition to the
  1480. actual <productname>DocBook</productname> files, you'll need to have a
  1481. <filename>catalog</filename> file in place, for the mapping of
  1482. document type specifications and external entity references to actual
  1483. files in that directory.  You'll also want the <acronym>ISO</acronym>
  1484. character set mappings, and probably one or more versions of
  1485. <acronym>HTML</acronym>.</para>
  1487. <para>One way to install the various <acronym>DTD</acronym> and
  1488. support files and set up the <filename>catalog</filename> file, is to
  1489. collect them all into the above mentioned directory, use a single file
  1490. named <filename>CATALOG</filename> to describe them all, and then
  1491. create the file <filename>catalog</filename> as a catalog pointer to
  1492. the former, by giving it the single line of content:
  1493. <programlisting>
  1494. CATALOG /usr/local/share/sgml/CATALOG
  1495. </programlisting>
  1496. </para>
  1497. </step>
  1499. <step performance="required">
  1500. <para>
  1501. The <filename>CATALOG</filename> file should then contain three types
  1502. of lines.  The first is the (optional) <acronym>SGML</acronym>
  1503. declaration, thus:
  1504. <programlisting>
  1505. SGMLDECL docbook.dcl
  1506. </programlisting>
  1507. Next, the various references to <acronym>DTD</acronym> and entity
  1508. files must be resolved.  For the <productname>DocBook</productname>
  1509. files, these lines look like this:
  1510. <programlisting>
  1511. PUBLIC "-//Davenport//DTD DocBook V3.0//EN" docbook.dtd
  1512. PUBLIC "-//USA-DOD//DTD Table Model 951010//EN" cals-tbl.dtd
  1513. PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
  1514. PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
  1515. PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
  1516. </programlisting>
  1517. </para>
  1518. </step>
  1520. <step performance="required">
  1521. <para>
  1522. Of course, a file containing these comes with the
  1523. <productname>DocBook</productname> kit.  Note that the last item on
  1524. each of these lines is a file name, given here without a path.  You
  1525. can put the files in subdirectories of your main
  1526. <acronym>SGML</acronym> directory if you like, of course, and modify
  1527. the reference in the <filename>CATALOG</filename> file.
  1528. <productname>DocBook</productname> also references the
  1529. <acronym>ISO</acronym> character set entities, so you need to fetch
  1530. and install these (they are available from several sources, and are
  1531. easily found by way of the URLs listed above), along with catalog
  1532. entries for all of them, such as:
  1533. <programlisting>
  1534. PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN" ISO/ISOlat1
  1535. </programlisting>
  1536. Note how the file name here contains a directory name, showing that
  1537. we've placed the <acronym>ISO</acronym> entity files in a subdirectory
  1538. named <filename>ISO</filename>.  Again, proper catalog entries should
  1539. accompany the entity kit you fetch.
  1540. </para>
  1541. </step>
  1543. </procedure>
  1544. </sect3>
  1546. <sect3>
  1547. <title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
  1549. <procedure>
  1550. <title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
  1552. <step performance="required">
  1553. <para>Read the installation instructions at the above listed
  1554. URL.</para>
  1555. </step>
  1557. <step performance="required">
  1558. <para>To install Norman's style sheets, simply unzip the distribution
  1559. kit in a suitable place.  A good place to dot this would be
  1560. <filename>/usr/local/share</filename>, which places the kit in a
  1561. directory tree under <filename>/usr/local/share/docbook</filename>.
  1562. The command will be something like
  1563. <programlisting>
  1564. unzip -aU db119.zip
  1565. </programlisting>
  1566. </para>
  1567. </step>
  1569. <step performance="required">
  1570. <para>One way to test the installation is to build the
  1571. <acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the
  1572. <citetitle><productname>PostgreSQL</productname> User's Guide</citetitle>.
  1573. </para>
  1575. <substeps>
  1577. <step performance="required">
  1578. <para>
  1579. To build the <acronym>HTML</acronym> files,
  1580.  go to the <acronym>SGML</acronym> source
  1581. directory, <filename>doc/src/sgml</filename>, and say
  1582. <programlisting>
  1583. jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
  1584. </programlisting>
  1585. </para>
  1587. <para>
  1588. <filename>book1.htm</filename> is the top level node of the output..
  1589. </para>
  1590. </step>
  1592. <step performance="required">
  1593. <para>
  1594. To generate the <acronym>RTF</acronym> output, ready for importing
  1595. into your favorite word processing system and printing, type:
  1596. <programlisting>
  1597. jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
  1598. </programlisting>
  1599. </para>
  1600. </step>
  1602. </substeps>
  1603. </step>
  1605. </procedure>
  1606. </sect3>
  1608. <sect3>
  1609. <title>Installing <productname>PSGML</productname></title>
  1611. <procedure>
  1612. <title>Installing <productname>PSGML</productname></title>
  1614. <step performance="required">
  1615. <para>Read the installation instructions at the above listed
  1616. URL.</para>
  1617. </step>
  1619. <step performance="required">
  1620. <para>Unpack the distribution file, run configure, make and make
  1621. install to put the byte-compiled files and info library in place.
  1622. </para>
  1623. </step>
  1625. <step performance="required" id="psgml-setup">
  1626. <para>
  1627. Then add the following lines to your
  1628. <filename>/usr/local/share/emacs/site-lisp/site-start.el</filename>
  1629. file to make <productname>Emacs</productname> properly load
  1630. <productname>PSGML</productname> when needed:
  1631. <programlisting>
  1632. (setq load-path
  1633.       (cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
  1634. (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
  1635. </programlisting>
  1636. </para>
  1637. </step>
  1639. <step performance="optional">
  1640. <para>
  1641. If you want to use <productname>PSGML</productname> when editing
  1642. <acronym>HTML</acronym> too, also add this:
  1643. <programlisting>
  1644. (setq auto-mode-alist
  1645.       (cons '("\.s?html?\'" . sgml-mode) auto-mode-alist))
  1646. </programlisting>
  1647. </para>
  1648. </step>
  1650. <step performance="optional">
  1651. <para>There is one important thing to note with
  1652. <productname>PSGML</productname>: its author assumed that your main
  1653. <acronym>SGML</acronym> <acronym>DTD</acronym> directory would be
  1654. <filename>/usr/local/lib/sgml</filename>.  If, as in the examples in
  1655. this chapter, you use <filename>/usr/local/share/sgml</filename>, you
  1656. have to compensate for this.
  1657. </para>
  1659. <substeps>
  1660. <step performance="optional">
  1661. <para>
  1662. You can set the
  1663. <filename>SGML_CATALOG_FILES</filename> environment variable.
  1664. </para>
  1665. </step>
  1667. <step performance="optional">
  1668. <para>
  1669. You can
  1670. customize your <productname>PSGML</productname> installation (its
  1671. manual tells you how).
  1672. </para>
  1673. </step>
  1675. <step performance="optional">
  1676. <para>
  1677. You can even edit the source file
  1678. <filename>psgml.el</filename> before compiling and installing
  1679. <productname>PSGML</productname>, changing the hard-coded paths to
  1680. match your own default.</para>
  1681. </step>
  1683. </substeps>
  1684. </step>
  1686. </procedure>
  1687. </sect3>
  1689. <sect3><title>Installing <productname>JadeTeX</productname></title>
  1691. <para>If you want to, you can also install
  1692. <productname>JadeTeX</productname> to use
  1693. <productname>TeX</productname> as a formatting backend for
  1694. <productname>Jade</productname>.  Note that this is still quite
  1695. unpolished software, and will generate printed output that is inferior
  1696. to what you get from the <acronym>RTF</acronym> backend.  Still, it
  1697. works all right, especially for simpler documents that don't use
  1698. tables, and as both <productname>JadeTeX</productname> and the style
  1699. sheets are under continuous improvement, it will certainly get better
  1700. over time.</para>
  1702. <para>To install and use <productname>JadeTeX</productname>, you will
  1703. need a working installation of <productname>TeX</productname> and
  1704. <productname>LaTeX2e</productname>, including the supported
  1705. <productname>tools</productname> and
  1706. <productname>graphics</productname> packages,
  1707. <productname>Babel</productname>, <productname><acronym>AMS</acronym>
  1708. fonts</productname> and <productname>AMS-LaTeX</productname>, the
  1709. <productname><acronym>PSNFSS</acronym></productname> extension and
  1710. companion kit of "the 35 fonts", the <productname>dvips</productname>
  1711. program for generating <productname>PostScript</productname>, the
  1712. macro packages <productname>fancyhdr</productname>,
  1713. <productname>hyperref</productname>,
  1714. <productname>minitoc</productname>, <productname>url</productname> and
  1715. <productname>ot2enc</productname>, and of course
  1716. <productname>JadeTeX</productname> itself.  All of these can be found
  1717. on your friendly neighborhood <acronym>CTAN</acronym> site.</para>
  1719. <para><productname>JadeTeX</productname> does not at the time of
  1720. writing come with much of an installation guide, but there is a
  1721. <filename>makefile</filename> which shows what is needed.  It also
  1722. includes a directory <filename>cooked</filename>, wherein you'll find
  1723. some of the macro packages it needs, but not all, and not complete --
  1724. at least last we looked.</para>
  1726. <para>Before building the <filename>jadetex.fmt</filename> format
  1727. file, you'll probably want to edit the
  1728. <filename>jadetex.ltx</filename> file, to change the configuration of
  1729. <productname>Babel</productname> to suit your locality.  The line to
  1730. change looks something like
  1731. <programlisting>
  1732. RequirePackage[german,french,english]{babel}[1997/01/23]
  1733. </programlisting>
  1734. and you should obviously list only the languages you actually need,
  1735. and have configured <productname>Babel</productname> for.</para>
  1737. <para>With <productname>JadeTeX</productname> working, you should be
  1738. able to generate and format <productname>TeX</productname> output for
  1739. the <productname>PostgreSQL</productname> manuals by giving the
  1740. commands (as above, in the <filename>doc/src/sgml</filename>
  1741. directory)
  1742. <programlisting>
  1743. jade -t tex -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
  1744. jadetex postgres.tex
  1745. jadetex postgres.tex
  1746. dvips postgres.dvi
  1747. </programlisting>
  1748. Of course, when you do this, <productname>TeX</productname> will stop
  1749. during the second run, and tell you that its capacity has been
  1750. exceeded.  This is, as far as we can tell, because of the way
  1751. <productname>JadeTeX</productname> generates cross referencing
  1752. information.  <productname>TeX</productname> can, of course, be
  1753. compiled with larger data structure sizes.  The details of this will
  1754. vary according to your installation.
  1755. </para>
  1757. </sect3>
  1759. </sect2>
  1760. </sect1>
  1762. <sect1>
  1763. <title>Alternate Toolsets</title>
  1765. <para>
  1766. <productname>sgml-tools</productname> v2.x
  1767. now supports <application>jade</application>
  1768. and <productname>DocBook</productname>. It may be the preferred toolset
  1769. for working with <acronym>SGML</acronym> but we have not had a chance to
  1770. evaluate the new package.
  1771. </para>
  1773. <!--
  1775. <para>
  1776. The current stable release of <productname>sgml-tools</productname> is
  1777. version 1.0.4. The v1.0 release includes some restructuring of the
  1778. directory tree to more easily support additional document styles,
  1779. possibly including <productname>DocBook</productname>. The only
  1780. version of <productname>sgml-tools</productname> evaluated for
  1781. <productname>Postgres</productname> was v0.99.0. 
  1782. </para>
  1784. <sect2>
  1785. <title><productname>sgml-tools</productname></title>
  1787. <para>
  1788. Install
  1789. <productname>sgml-tools-0.99.0</productname>.
  1790. </para>
  1792. <para>
  1793. Apply  <ulink
  1794. url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml-tools-patches-0.99.0.tar.gz">
  1795. <productname>sgml-tools-patches</productname> </ulink> to the linuxdoc
  1796. styles. These patches fix small problems with table formatting and
  1797. with figure file names on conversion to postscript or html.
  1798. </para></sect2>
  1800. <sect2>
  1801. <title><productname>sgml2latex</productname></title>
  1803. <para>
  1804. The current stable release of <productname>sgml2latex</productname> is
  1805. version 1.4. I have misplaced the original reference for this package,
  1806. so will temporarily post it with this example.
  1807. </para>
  1809. <para>
  1810. Install <ulink
  1811. url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml2latex-format.1.4.tar.gz">
  1812. <productname>sgml2latex</productname> </ulink>.
  1813. </para></sect2>
  1815. <sect2>
  1816. <title><productname>latex</productname></title>
  1818. <para>
  1819. Get and install <productname>texmf</productname>,
  1820. <productname>teTeX</productname>, or another package providing full
  1821. tex/latex functionality.
  1822. </para>
  1824. <para>
  1825. Add the 
  1826. <ulink
  1827. url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/latex-styles-0.99.0.tar.gz">required styles</ulink>
  1828. linuxdoc-sgml.sty, linuxdoc-sgml-a4.sty isolatin.sty, qwertz.sty, and
  1829. null.sty to texmf/tex/latex/tools/ or the appropriate area.
  1831. <programlisting>
  1832. % cat latex-styles-0.99.0.tar.gz | (cd texmf/tex/latex/tools/; tar zxvf -)
  1833. </programlisting>
  1835. Run <productname>texhash</productname> to update the tex database.
  1836. </para></sect2></sect1>
  1838. -->
  1839. </sect1>
  1840. </appendix>
  1842. <!-- Keep this comment at the end of the file
  1843. Local variables:
  1844. mode: sgml
  1845. sgml-omittag:nil
  1846. sgml-shorttag:t
  1847. sgml-minimize-attributes:nil
  1848. sgml-always-quote-attributes:t
  1849. sgml-indent-step:1
  1850. sgml-indent-data:t
  1851. sgml-parent-document:nil
  1852. sgml-default-dtd-file:"./reference.ced"
  1853. sgml-exposed-tags:nil
  1854. sgml-local-catalogs:"/usr/lib/sgml/catalog"
  1855. sgml-local-ecat-files:nil
  1856. End:
  1857. -->