diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 31ca3f5757a..c7e8f68d2f7 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,5 +1,5 @@ - -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: + + 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. - - - + + + 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 -SGML DocBook tags. - + + The current Postgres documentation set was written using + a plain text editor (or emacs/psgml; see below) with the content marked up using + SGML DocBook tags. + - -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 - -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. - + + 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 @@ -900,37 +830,37 @@ sgml-indent-data:t 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 @@ -955,8 +885,8 @@ YFLAGS+= -v # 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 @@ -995,36 +925,6 @@ PSTYLE= /home/tgl/SGML/db107.d/docbook/print % 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. - - @@ -1203,8 +1103,9 @@ $ make man Postscript Hardcopy - Several items must be addressed in generating Postscript - hardcopy: + Several areas are addressed while generating Postscript + hardcopy. + Applixware <acronym>RTF</acronym> Cleanup @@ -1314,34 +1215,193 @@ $ make man 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 - <productname>Linux</productname> + <productname>Linux</productname> <acronym>RPM</acronym> Installation - Install - RPMs for Jade - and related packages. + 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 + + + + Install + RPMs for Jade + 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. + + + - Manual installation of tools + 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 + to access the jade + 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 + + + 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 Installation of Tools This is a brief run-through of the process of obtaining and @@ -1882,10 +1942,8 @@ dvips postgres.dvi sgml-tools v2.x - now supports jade - and DocBook. It may be the preferred toolset - for working with SGML but we have not had a chance to - evaluate the new package. + supports jade + and DocBook. - + +