mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-10-02 00:01:16 +02:00
348 lines
10 KiB
Plaintext
348 lines
10 KiB
Plaintext
<Appendix label="A">
|
|
<DocInfo>
|
|
<AuthorGroup>
|
|
<Author>
|
|
<FirstName>Thomas</FirstName>
|
|
<Surname>Lockhart</Surname>
|
|
</Author>
|
|
</AuthorGroup>
|
|
<Date>1998-02-26</Date>
|
|
</DocInfo>
|
|
|
|
<Title>Documentation</Title>
|
|
|
|
<Para>
|
|
<ProductName>Postgres</ProductName> documentation is written using
|
|
the <FirstTerm>Standard Generalized Markup Language</FirstTerm>
|
|
(<Acronym>SGML</Acronym>)
|
|
<ULink url="http://www.ora.com/davenport/"><ProductName>DocBook</ProductName></ULink>
|
|
<FirstTerm>Document Type Definition</FirstTerm> (<Acronym>DTD</Acronym>).
|
|
|
|
<Para>
|
|
Packaged documentation is available in both <FirstTerm>HTML</FirstTerm> and <FirstTerm>Postscript</FirstTerm>
|
|
formats. These are available as part of the standard <ProductName>Postgres</ProductName> installation.
|
|
We discuss here working with the documentation sources and generating documentation packages.
|
|
|
|
<Note>
|
|
<Para>
|
|
This is the first release of new <ProductName>Postgres</ProductName> documentation in three years.
|
|
The content and environment are in flux and still evolving.
|
|
</Para>
|
|
</Note>
|
|
|
|
<Sect1>
|
|
<Title>Introduction</Title>
|
|
|
|
<Para>
|
|
The purpose of <Acronym>SGML</Acronym> is to allow an author to specify the structure and content of
|
|
a document (e.g. using the <ProductName>DocBook</ProductName> <Acronym>DTD</Acronym>),
|
|
and to have the document style define
|
|
how that content is rendered into a final form
|
|
(e.g. using Norm Walsh's stylesheets).
|
|
|
|
<Para>
|
|
See
|
|
<ULink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">Introduction to DocBook</ULink>
|
|
for a nice "quickstart" summary of DocBook features.
|
|
<ULink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/">DocBook Elements</ULink>
|
|
provides a powerful cross-reference for features of <ProductName>DocBook</ProductName>.
|
|
|
|
<Para>
|
|
This documentation set is constructed using several tools,
|
|
including James Clark's
|
|
<ULink url="http://www.jclark.com/jade/"><ProductName>jade</ProductName></ULink>
|
|
and Norm Walsh's
|
|
<ULink url="http://www.berkshire.net/~norm/docbook/dsssl">Modular DocBook Stylesheets</ULink>.
|
|
|
|
<Para>
|
|
Currently, hardcopy is produced by importing <FirstTerm>Rich Text Format</FirstTerm> (<Acronym>RTF</Acronym>)
|
|
output from <Application>jade</Application> to <ProductName>ApplixWare</ProductName>
|
|
for minor formatting fixups then exporting as a Postscript file.
|
|
|
|
<Para>
|
|
<ULink url="http://sunsite.unc.edu/pub/packages/TeX/systems/unix/"><ProductName>TeX</ProductName></ULink>
|
|
is a supported format for <Application>jade</Application> output, but was not used at this time for
|
|
several reasons, including the inability to make minor format fixes before committing to hardcopy and
|
|
generally inadequate table support in the <ProductName>TeX</ProductName> stylesheets.
|
|
|
|
<Sect1>
|
|
<Title>Styles and Conventions</Title>
|
|
|
|
<Para>
|
|
<ProductName>DocBook</ProductName> has a rich set of tags and constructs, and a suprisingly large
|
|
percentage are directly and obviously useful for well-formed documentation.
|
|
The <ProductName>Postgres</ProductName> documentation set has only recently
|
|
been adapted to <Acronym>SGML</Acronym>, and in the near future several sections of the set
|
|
will be selected and maintained as prototypical examples of <ProductName>DocBook</ProductName>
|
|
usage. Also, a short summary of <ProductName>DocBook</ProductName> tags will be included below.
|
|
|
|
<!--
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE>SGML Constructs</TITLE>
|
|
<TITLEABBREV>SGML Constructs</TITLEABBREV>
|
|
<TGROUP COLS="2">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>SGML Tag</ENTRY>
|
|
<ENTRY>Usage</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
-->
|
|
|
|
</Sect1>
|
|
|
|
<Sect1>
|
|
<Title>Building Documentation</Title>
|
|
|
|
<Para>
|
|
HTML documentation packages can be generated from the SGML source by typing
|
|
|
|
<ProgramListing>
|
|
% cd doc/src
|
|
% make tutorial.tar.gz
|
|
% make user.tar.gz
|
|
% make admin.tar.gz
|
|
% make programmer.tar.gz
|
|
% make postgres.tar.gz
|
|
% make install
|
|
</ProgramListing>
|
|
</Para>
|
|
|
|
<Para>
|
|
These packages can be installed from the main documentation directory by typing
|
|
<ProgramListing>
|
|
% cd doc
|
|
% make install
|
|
</ProgramListing>
|
|
</Para>
|
|
|
|
<Sect1>
|
|
<Title>Toolsets</Title>
|
|
|
|
<Sect2>
|
|
<Title><ProductName>jade</ProductName></Title>
|
|
|
|
<Para>
|
|
The current stable release of <ProductName>jade</ProductName> is version 1.0.1.
|
|
</Para>
|
|
|
|
<Sect3>
|
|
<Title>Installation for Linux</Title>
|
|
|
|
<Para>
|
|
Install <ULink url="ftp://ftp.cygnus.com/pub/home/rosalia/"><Acronym>RPMs</Acronym></ULink>
|
|
for <ProductName>jade</ProductName> and related packages.
|
|
</Para>
|
|
</Sect3>
|
|
|
|
<Sect3>
|
|
<Title>Installation for non-Linux Platforms</Title>
|
|
|
|
<Para>
|
|
There are some other packaged distributions for jade. <ProductName>FreeBSD</ProductName> seems
|
|
to have one available. Please report package status to the docs mailing list and we will
|
|
include that information here.
|
|
|
|
<Para>
|
|
For other platforms, install <ULink url="ftp://ftp.cygnus.com/pub/eichin/docware/SOURCES/">sources</ULink>
|
|
for <ProductName>jade</ProductName> and related packages and build from scratch.
|
|
</Para>
|
|
</Sect3>
|
|
|
|
<Sect2>
|
|
<Title><ProductName>Modular Style Sheets</ProductName></Title>
|
|
|
|
<Para>
|
|
The current stable release of the <ProductName>Modular Style Sheets</ProductName> is version 1.0.7.
|
|
</Para>
|
|
|
|
<Sect1>
|
|
<Title>Hardcopy Generation for v6.3</Title>
|
|
|
|
<Para>
|
|
The hardcopy Postscript documentation is generated by converting the <Acronym>SGML</Acronym>
|
|
source code to <Acronym>RTF</Acronym>, then importing into Applixware. After a little cleanup
|
|
(see the following section) the output is "printed" to a postscript file.
|
|
|
|
<Para>
|
|
Some figures were redrawn to avoid having bitmap <Acronym>GIF</Acronym> files in the hardcopy
|
|
documentation. One figure, of the system catalogs, was sufficiently complex that there was
|
|
not time to redraw it. It was converted to fit using the following commands:
|
|
|
|
<ProgramListing>
|
|
% convert -v -geometry 400x400'>' figure03.gif con.gif
|
|
% convert -v -crop 400x380 con.gif connections.gif
|
|
</ProgramListing>
|
|
|
|
<Sect2>
|
|
<Title>RTF Cleanup Procedure</Title>
|
|
|
|
<Para>
|
|
Several items must be addressed in generating Postscript hardcopy:
|
|
|
|
<Procedure>
|
|
<Title>Applixware RTF Cleanup</Title>
|
|
|
|
<Para>
|
|
Applixware does not seem to do a complete job of importing RTF generated by jade/MSS. In particular,
|
|
all text is given the <Quote>Header1</Quote> style attribute label, although the text formatting itself
|
|
is acceptable. Also, the Table of Contents page numbers do not refer to the section listed in the
|
|
table, but rather refer to the page of the ToC itself.
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Generate the <Acronym>RTF</Acronym> input by typing
|
|
<ProgramListing>
|
|
% cd doc/src/sgml
|
|
% make tutorial.rtf
|
|
</ProgramListing>
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Open a new document in <ProductName>Applix Words</ProductName> and then import the RTF file.
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Print out the existing Table of Contents, to mark up in the following few steps.
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Insert figures into the document. Center each figure on the page using the centering margins button.
|
|
|
|
<Para>
|
|
Not all documents have figures. You can grep the SGML source files for the string <Quote>Graphic</Quote>
|
|
to identify those parts of the documentation which may have figures. A few figures are replicated in
|
|
various parts of the documentation.
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Work through the document, adjusting page breaks and table column widths.
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
If a bibliography is present, Applix Words seems to mark all remaining text after the first title
|
|
as having an underlined attribute. Select all remaining text, turn off underlining using the underlining button,
|
|
then explicitly underline each document and book title.
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Work through the document, marking up the ToC hardcopy with the actual page number of each ToC entry.
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Replace the right-justified incorrect page numbers in the ToC with correct values. This only takes a few
|
|
minutes per document.
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Save the document as native Applix Words format to allow easier last minute editing later.
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Export the document to a file in Postscript format.
|
|
</Para>
|
|
</Step>
|
|
|
|
<Step Performance="required">
|
|
<Para>
|
|
Compress the Postscript file using <Application>gzip</Application>. Place the compressed file into the
|
|
<FileName>doc</FileName> directory.
|
|
</Para>
|
|
</Step>
|
|
</Procedure>
|
|
|
|
</Sect2>
|
|
</Sect1>
|
|
|
|
<Sect1>
|
|
<Title>Alternate Toolsets</Title>
|
|
|
|
<Para>
|
|
The current stable release of <ProductName>sgml-tools</ProductName> is version 1.0.4.
|
|
The v1.0 release includes some restructuring of the directory tree
|
|
to more easily support additional document styles, possibly including <ProductName>DocBook</ProductName>.
|
|
The only version of <ProductName>sgml-tools</ProductName> evaluated for <ProductName>Postgres</ProductName> was v0.99.0.
|
|
</Para>
|
|
|
|
<Sect2>
|
|
<Title><ProductName>sgml-tools</ProductName></Title>
|
|
|
|
<Para>
|
|
Install
|
|
<ProductName>sgml-tools-0.99.0</ProductName>
|
|
</Para>
|
|
|
|
<Para>
|
|
Apply
|
|
<ULink url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml-tools-patches-0.99.0.tar.gz">
|
|
<ProductName>sgml-tools-patches</ProductName>
|
|
</ULink>
|
|
to the linuxdoc styles. These patches fix small problems with
|
|
table formatting and with figure file names on conversion to postscript or html.
|
|
</Para>
|
|
|
|
<Sect2>
|
|
<Title><ProductName>sgml2latex</ProductName></Title>
|
|
|
|
<Para>
|
|
The current stable release of <ProductName>sgml2latex</ProductName> is version 1.4.
|
|
I have misplaced the original reference
|
|
for this package, so will temporarily post it with this example.
|
|
</Para>
|
|
|
|
<Para>
|
|
Install <ULink url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml2latex-format.1.4.tar.gz">
|
|
<ProductName>sgml2latex</ProductName>
|
|
</ULink>.
|
|
</Para>
|
|
|
|
<Sect2>
|
|
<Title><ProductName>latex</ProductName></Title>
|
|
|
|
<Para>
|
|
Get and install <ProductName>texmf</ProductName>, <ProductName>teTeX</ProductName>,
|
|
or another package providing full tex/latex functionality.
|
|
</Para>
|
|
|
|
<Para>
|
|
Add the
|
|
<ULink url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/latex-styles-0.99.0.tar.gz">required styles</ULink>
|
|
linuxdoc-sgml.sty, linuxdoc-sgml-a4.sty isolatin.sty, qwertz.sty, and null.sty
|
|
to texmf/tex/latex/tools/ or the appropriate area.
|
|
<ProgramListing>
|
|
% cat latex-styles-0.99.0.tar.gz | (cd texmf/tex/latex/tools/; tar zxvf -)
|
|
</ProgramListing>
|
|
|
|
Run <ProductName>texhash</ProductName> to update the tex database.
|
|
</Para>
|
|
|
|
|
|
</Appendix>
|