-
-
Document Structure
+
+
Document Structure
-There are currently five separate documents written in DocBook. Each document
-has a container source document which defines the DocBook environment and other
-document source files. These primary source files are located in
-doc/src/sgml/, along with many of the other source files
-used for the documentation. The primary source files are:
-
-
-
-postgres.sgml
-
-This is the integrated document, including all other documents as parts.
-Output is generated in
HTML since the browser interface
-makes it easy to move around all of the documentation by just clicking.
-The other documents are available in both
HTML and hardcopy.
-
-
-
+ There are currently five separate documents written in DocBook. Each document
+ has a container source document which defines the DocBook environment and other
+ document source files. These primary source files are located in
+ doc/src/sgml/, along with many of the other source files
+ used for the documentation. The primary source files are:
+
+
+
+ postgres.sgml
+
+ This is the integrated document, including all other documents as parts.
+
Output is generated in
HTML since the browser interface
+ makes it easy to move around all of the documentation by just clicking.
+
The other documents are available in both
HTML and hardcopy.
+
+
+
-
-tutorial.sgml
-
-The introductory tutorial, with examples. Does not include programming topics,
-and is intended to help a reader unfamiliar with
SQL.
-This is the "getting started" document.
-
-
-
+
+ tutorial.sgml
+
+ The introductory tutorial, with examples. Does not include programming topics,
+
and is intended to help a reader unfamiliar with
SQL.
+ This is the "getting started" document.
+
+
+
-
-user.sgml
-
-The User's Guide. Includes information on data types and user-level interfaces.
-This is the place to put information on "why".
-
-
-
+
+ user.sgml
+
+ The User's Guide. Includes information on data types and user-level interfaces.
+ This is the place to put information on "why".
+
+
+
-
-reference.sgml
-
-The Reference Manual. Includes
Postgres SQL syntax.
-This is the place to put information on "how".
-
-
-
+
+ reference.sgml
+
+
The Reference Manual. Includes
Postgres SQL syntax.
+ This is the place to put information on "how".
+
+
+
-
-programming.sgml
-
-The Programmer's Guide. Includes information on
Postgres-extensibility and on the programming interfaces.
-
-
-
+
+ programming.sgml
+
+
The Programmer's Guide. Includes information on
Postgres+ extensibility and on the programming interfaces.
+
+
+
-
-admin.sgml
-
-The Administrator's Guide. Include installation and release notes.
-
-
-
-
-
+
+ admin.sgml
+
+ The Administrator's Guide. Include installation and release notes.
+
+
+
+
+
+
-
+
-
DocBook has a rich set of tags and
-constructs, and a suprisingly large percentage are directly and
-obviously useful for well-formed documentation. The
-
Postgres documentation set has only
-recently been adapted to
SGML, and in the near
-future several sections of the set will be selected and maintained as
-prototypical examples of
DocBook usage.
-Also, a short summary of
DocBook tags will
-be included below.
-
+
+
Styles and Conventions
+
+
DocBook has a rich set of tags and
+ constructs, and a suprisingly large percentage are directly and
+ obviously useful for well-formed documentation. The
+
Postgres documentation set has only
+ recently been adapted to
SGML, and in the near
+ future several sections of the set will be selected and maintained as
+ prototypical examples of
DocBook usage.
+ Also, a short summary of
DocBook tags will
+ be included below.
+
-
+
-
-
SGML Authoring Tools
+
+
SGML Authoring Tools
-The current
Postgres documentation set was written using
-a plain text editor (or emacs/psgml; see below) with the content marked up using
-
+
The current
Postgres documentation set was written using
+ a plain text editor (or emacs/psgml; see below) with the content marked up using
+
-
SGML and
DocBook do not suffer
-from an oversupply of open-source authoring tools. The most common toolset is
-the emacs/xemacs editing package with the psgml feature extension.
-On some systems (e.g. RedHat Linux) these tools are provided in a typical full installation.
-
+
SGML and
DocBook do not suffer
+ from an oversupply of open-source authoring tools. The most common toolset is
+ the emacs/xemacs editing package with the psgml feature extension.
+ On some systems (e.g. RedHat Linux) these tools are provided in a typical full installation.
+
-
-
emacs/psgml
+
+
emacs/psgml
-an
SGML major mode. When properly configured,
-this will allow you to use
emacs to insert tags and
-check markup consistancy.
-
+
emacs (and
xemacs) have
+
an
SGML major mode. When properly configured,
+
this will allow you to use
emacs to insert tags and
+ check markup consistancy.
+
- Put the following in your ~/.emacs environment file:
+ Put the following in your ~/.emacs
+ environment file (adjusting the path names to be appropriate for
+ your system):
; ********** for SGML mode (psgml)
(setq sgml-catalog-files "/usr/lib/sgml/CATALOG")
(setq sgml-local-catalogs "/usr/lib/sgml/CATALOG")
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
-
+
-and add an entry in the same file
-for
SGML into the (existing) definition for
-auto-mode-alist:
+ and add an entry in the same file
+
for
SGML into the (existing) definition for
+ auto-mode-alist:
(setq
auto-mode-alist
'(("\\.sgml$" . sgml-mode)
))
-
+
-Each
SGML source file has the following block at the
-end of the file:
+
Each
SGML source file has the following block at the
+ end of the file:
!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
--
-
-
+
+
The
Postgres distribution includes a
parsed DTD definitions file reference.ced.
-You may find that
-
+ You may find that
+
-When using
emacs/psgml, a comfortable way of working with
-these separate files of book parts is to insert a proper DOCTYPE
-declaration while you're editing them. If you are working on this source, for instance,
-it's an appendix chapter, so you would specify the document as an "appendix" instance of
-a DocBook document by making the first line look like this:
+
When using
emacs/psgml, a comfortable way of working with
+ these separate files of book parts is to insert a proper DOCTYPE
+ declaration while you're editing them. If you are working on this source, for instance,
+ it's an appendix chapter, so you would specify the document as an "appendix" instance of
+ a DocBook document by making the first line look like this:
-!doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"
-
+ !doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"
+
-This means that anything and everything that reads
SGML will get it
-right, and I can verify the document with "nsgmls -s docguide.sgml".
-
+
This means that anything and everything that reads
SGML will get it
+ right, and I can verify the document with "nsgmls -s docguide.sgml".
+
-
-
-
+
+
+
Building Documentation
# documentation
-HSTYLE= /home/tgl/SGML/db107.d/docbook/html
-PSTYLE= /home/tgl/SGML/db107.d/docbook/print
+HSTYLE= /home/lockhart/SGML/db143.d/docbook/html
+PSTYLE= /home/lockhart/SGML/db143.d/docbook/print
where HSTYLE and PSTYLE determine the path to
% make install
-
-
FreeBSD specific howto
- To build the documentation on FreeBSD a number of ports will need to
- be installed.
-% cd /usr/ports/devel/gmake && make install
-% cd /usr/ports/textproc/docproj && make install
-% cd /usr/ports/textproc/docbook && make install
-% cd /usr/ports/textproc/dsssl-docbook-modular && make install
-
- Some enviornment variables need to be set (assumes you are running a sh
- based shell):
-export SMGL_ROOT=/usr/local/share/sgml
-SGML_CATALOG_FILES=/usr/local/share/sgml/jade/catalog
-SGML_CATALOG_FILES=/usr/local/share/sgml/html/catalog:$SGML_CATALOG_FILES
-SGML_CATALOG_FILES=/usr/local/share/sgml/iso8879/catalog:$SGML_CATALOG_FILES
-SGML_CATALOG_FILES=/usr/local/share/sgml/transpec/catalog:$SGML_CATALOG_FILES
-SGML_CATALOG_FILES=/usr/local/share/sgml/docbook/catalog:$SGML_CATALOG_FILES
-export SGML_CATALOG_FILES
- Make needs some special arguments, or these need to be added to your
-Makefile.custom:
-HSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/html/
-PSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/print/
-
- Of course you'll need to use gmake rather than just plain 'make' to build.
-
-
Postscript Hardcopy
- Several items must be addressed in generating Postscript
- hardcopy:
+ Several areas are addressed while generating Postscript
+ hardcopy.
+
Applixware <acronym>RTF</acronym> Cleanup
Toolsets
- We have documented experience with two installation methods for the
+ We have documented experience with three installation methods for the
various tools that are needed to process the documentation. One is
installation from
RPMs on
-
Linux, the other is a general installation
- from original distributions of the individual tools. Both will be
+
Linux, the second is installation from
+ FreeBSD port, and the last is a general installation
+ from original distributions of the individual tools. These will be
described below.
- We understand that there are some other packaged distributions for
- these tools.
FreeBSD seems to have them
- available. Please report package status to the docs mailing list and
+ There may be some other packaged distributions for
+ these tools. Please report package status to the docs mailing list and
we will include that information here.
-
<acronym>RPM</acronym> installation on</div>
<div class="diff rem">- <productname>Linux</productname>
+
<productname>Linux</productname> <acronym>RPM</acronym> Installation
+
+ The simplest installation for a RedHat-compatible Linux system
+ uses the
RPM set developed by Mark Galassi at
+ Cygnus. It should also be possible to install from sources, as
+ described in a subsequent section.
+
+
+
Installing RPMs
+
+
+ and related packages.
+
+
+
+
+ Install Norm Walsh's latest style sheets. Depending on the age
+ of the RPMs, the latest style sheets may be substantially
+ improved from those contained in the
RPMs.
+
+
+
+
+ Update your src/Makefile.custom to include
+ HSTYLE and PSTYLE definitions pointing to the style sheets.
+
+
+
+
+
+
+
FreeBSD Installation
+
+ There is a full set of ports of the
+ documentation tools available on FreeBSD. In fact, postgresql.org,
+ on which documentation is automatically updated every evening, is
+ a FreeBSD machine.
+
+
+
Installing FreeBSD Ports
+
+
+ To build the documentation on FreeBSD a number of ports will need to
+ be installed.
+% cd /usr/ports/devel/gmake && make install
+% cd /usr/ports/textproc/docproj && make install
+% cd /usr/ports/textproc/docbook && make install
+% cd /usr/ports/textproc/dsssl-docbook-modular && make install
+
+
+
+
+
+ Set environment variables
+ toolset.
+
+
+ This was not required for the FreeBSD machine at
+ postgresql.org, so you may not have to do this.
+
+
+
+export SMGL_ROOT=/usr/local/share/sgml
+SGML_CATALOG_FILES=/usr/local/share/sgml/jade/catalog
+SGML_CATALOG_FILES=/usr/local/share/sgml/html/catalog:$SGML_CATALOG_FILES
+SGML_CATALOG_FILES=/usr/local/share/sgml/iso8879/catalog:$SGML_CATALOG_FILES
+SGML_CATALOG_FILES=/usr/local/share/sgml/transpec/catalog:$SGML_CATALOG_FILES
+SGML_CATALOG_FILES=/usr/local/share/sgml/docbook/catalog:$SGML_CATALOG_FILES
+export SGML_CATALOG_FILES
+
+
+ (this is sh/bash syntax; adjust accordingly for csh/tcsh).
+
+
+
+
+ Make needs some special arguments, or these need to be added to your
+ Makefile.custom:
+HSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/html/
+PSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/print/
+
+
+ Of course you'll need to use gmake rather than just plain 'make' to build.
+
+
+
+
+
+
+
Debian Installation
- and related packages.
+ There is a full set of packages of the
+ documentation tools available for Debian.
+
+
Installing Debian Packages
+
+
+ Install jade, docbook, and unzip:
+
+apt-get install jade
+apt-get install docbook
+apt-get install docbook-stylesheets
+
+
+
+
+
+ Install the latest style sheets.
+
+
+
+
+ Verify that
unzip is installed, or
+ install the package:
+
+apt-get install unzip
+
+
+
+
+
+ Grab the latest stylesheet zipballs from
+
http://www.nwalsh.com/docbook/dsssl+ and unzip it somewhere (possibly /usr/share).
+
+
+
+
+
+
+ Edit src/Makefile.custom to add appropriate HSTYLE and PSTYLE
+ definitions:
+
+HSTYLE= /usr/share/docbook/html
+PSTYLE= /usr/share/docbook/print
+
+
+
+
-
Manual <span class="marked">installation of t</span>ools
+
Manual <span class="marked">Installation of T</span>ools
This is a brief run-through of the process of obtaining and
- and
DocBook. It may be the preferred toolset
- for working with
SGML but we have not had a chance to
- evaluate the new package.
-
+
+
projects / postgresql.git / commitdiff