1 files changed, 347 insertions, 0 deletions
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
new file mode 100644
index 00000000000..4b2a59602a3
--- /dev/null
+++ b/doc/src/sgml/docguide.sgml
@@ -0,0 +1,347 @@
+<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>