Add info on debian package installation of sgml toolkits.
This commit is contained in:
Thomas G. Lockhart
parent
fd54baa945
commit
acaa064fa8
@ -1,5 +1,5 @@
|
|||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.24 2000/01/18 06:10:54 momjian Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.25 2000/02/02 16:22:45 thomas Exp $
|
||||||
Documentation Guide
|
Documentation Guide
|
||||||
Thomas Lockhart
|
Thomas Lockhart
|
||||||
|
|
||||||
@ -220,161 +220,164 @@ Add a note on sgml-tools that they are now working with jade and so
|
|||||||
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Documentation Sources</title>
|
<title>Documentation Sources</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Documentation sources include plain text files, man pages, and html. However,
|
Documentation sources include plain text files, man pages, and html. However,
|
||||||
most new <productname>Postgres</productname> documentation will be written using the
|
most new <productname>Postgres</productname> documentation will be written using the
|
||||||
<firstterm>Standard Generalized Markup Language</firstterm>
|
<firstterm>Standard Generalized Markup Language</firstterm>
|
||||||
(<acronym>SGML</acronym>)
|
(<acronym>SGML</acronym>)
|
||||||
<ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink>
|
<ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink>
|
||||||
<firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>).
|
<firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>).
|
||||||
Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>.
|
Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The purpose of <acronym>SGML</acronym> is to allow an author to
|
The purpose of <acronym>SGML</acronym> is to allow an author to
|
||||||
specify the structure and content of a document (e.g. using the
|
specify the structure and content of a document (e.g. using the
|
||||||
<productname>DocBook</productname> <acronym>DTD</acronym>), and to
|
<productname>DocBook</productname> <acronym>DTD</acronym>), and to
|
||||||
have the document style define how that content is rendered into a
|
have the document style define how that content is rendered into a
|
||||||
final form (e.g. using Norm Walsh's stylesheets).
|
final form (e.g. using Norm Walsh's stylesheets).
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Documentation has accumulated from several sources. As we integrate
|
Documentation has accumulated from several sources. As we integrate
|
||||||
and assimilate existing documentation into a coherent documentation set,
|
and assimilate existing documentation into a coherent documentation set,
|
||||||
the older versions will become obsolete and will be removed from the
|
the older versions will become obsolete and will be removed from the
|
||||||
distribution. However, this will not happen immediately, and will not
|
distribution. However, this will not happen immediately, and will not
|
||||||
happen to all documents at the same time. To ease the transition, and
|
happen to all documents at the same time. To ease the transition, and
|
||||||
to help guide developers and writers, we have defined a transition roadmap.
|
to help guide developers and writers, we have defined a transition roadmap.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<!--
|
||||||
Here is the documentation plan for v6.5:
|
<para>
|
||||||
|
Here is the documentation plan for v6.5:
|
||||||
|
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Start compiling index information for the User's and Administrator's Guides.
|
Start compiling index information for the User's and Administrator's Guides.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Write more sections for the User's Guide covering areas outside the reference pages.
|
Write more sections for the User's Guide covering areas outside the reference pages.
|
||||||
This would include introductory information and suggestions for approaches to typical
|
This would include introductory information and suggestions for approaches to typical
|
||||||
design problems.
|
design problems.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Merge information in the existing man pages into the reference pages and User's Guide.
|
Merge information in the existing man pages into the reference pages and User's Guide.
|
||||||
Condense the man pages down to reminder information, with references into the
|
Condense the man pages down to reminder information, with references into the
|
||||||
primary doc set.
|
primary doc set.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Convert the new sgml reference pages to new man pages, replacing the existing man pages.
|
Convert the new sgml reference pages to new man pages, replacing the existing man pages.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Convert all source graphics to CGM format files for portability. Currently we mostly have
|
Convert all source graphics to CGM format files for portability. Currently we mostly have
|
||||||
Applix Graphics sources from which we can generate .gif output. One graphic is only
|
Applix Graphics sources from which we can generate .gif output. One graphic is only
|
||||||
available in .gif and .ps, and should be redrawn or removed.
|
available in .gif and .ps, and should be redrawn or removed.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
|
-->
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>Document Structure</title>
|
<title>Document Structure</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
There are currently five separate documents written in DocBook. Each document
|
There are currently five separate documents written in DocBook. Each document
|
||||||
has a container source document which defines the DocBook environment and other
|
has a container source document which defines the DocBook environment and other
|
||||||
document source files. These primary source files are located in
|
document source files. These primary source files are located in
|
||||||
<filename>doc/src/sgml/</filename>, along with many of the other source files
|
<filename>doc/src/sgml/</filename>, along with many of the other source files
|
||||||
used for the documentation. The primary source files are:
|
used for the documentation. The primary source files are:
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>postgres.sgml</term>
|
<term>postgres.sgml</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
This is the integrated document, including all other documents as parts.
|
This is the integrated document, including all other documents as parts.
|
||||||
Output is generated in <acronym>HTML</acronym> since the browser interface
|
Output is generated in <acronym>HTML</acronym> since the browser interface
|
||||||
makes it easy to move around all of the documentation by just clicking.
|
makes it easy to move around all of the documentation by just clicking.
|
||||||
The other documents are available in both <acronym>HTML</acronym> and hardcopy.
|
The other documents are available in both <acronym>HTML</acronym> and hardcopy.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>tutorial.sgml</term>
|
<term>tutorial.sgml</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The introductory tutorial, with examples. Does not include programming topics,
|
The introductory tutorial, with examples. Does not include programming topics,
|
||||||
and is intended to help a reader unfamiliar with <acronym>SQL</acronym>.
|
and is intended to help a reader unfamiliar with <acronym>SQL</acronym>.
|
||||||
This is the "getting started" document.
|
This is the "getting started" document.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>user.sgml</term>
|
<term>user.sgml</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The User's Guide. Includes information on data types and user-level interfaces.
|
The User's Guide. Includes information on data types and user-level interfaces.
|
||||||
This is the place to put information on "why".
|
This is the place to put information on "why".
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>reference.sgml</term>
|
<term>reference.sgml</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
|
The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
|
||||||
This is the place to put information on "how".
|
This is the place to put information on "how".
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>programming.sgml</term>
|
<term>programming.sgml</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The Programmer's Guide. Includes information on <productname>Postgres</productname>
|
The Programmer's Guide. Includes information on <productname>Postgres</productname>
|
||||||
extensibility and on the programming interfaces.
|
extensibility and on the programming interfaces.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>admin.sgml</term>
|
<term>admin.sgml</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The Administrator's Guide. Include installation and release notes.
|
The Administrator's Guide. Include installation and release notes.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
Disable for the hardcopy production release.
|
Disable for the hardcopy production release.
|
||||||
Too much tabular info and not very helpful in hardcopy.
|
Too much tabular info and not very helpful in hardcopy.
|
||||||
- thomas 1998-10-27
|
- thomas 1998-10-27
|
||||||
-->
|
-->
|
||||||
</sect2>
|
|
||||||
|
|
||||||
|
<!--
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>Documentation Files</title>
|
<title>Documentation Files</title>
|
||||||
|
|
||||||
@ -677,83 +680,6 @@ Status
|
|||||||
<row><entry> ./src/interfaces/python/tutorial/pgtools.pyc </entry><entry> Not converted </entry></row>
|
<row><entry> ./src/interfaces/python/tutorial/pgtools.pyc </entry><entry> Not converted </entry></row>
|
||||||
<row><entry> ./src/interfaces/python/tutorial/syscat.py </entry><entry> Not converted </entry></row>
|
<row><entry> ./src/interfaces/python/tutorial/syscat.py </entry><entry> Not converted </entry></row>
|
||||||
<row><entry> ./src/interfaces/python/tutorial/syscat.pyc </entry><entry> Not converted </entry></row>
|
<row><entry> ./src/interfaces/python/tutorial/syscat.pyc </entry><entry> Not converted </entry></row>
|
||||||
<row><entry> ./src/man/README </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/abort.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/alter_table.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/alter_user.l </entry><entry> Split into Reference and Admin Guide </entry></row>
|
|
||||||
<row><entry> ./src/man/begin.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/catalogs.3 </entry><entry> Catalog synopsis. Move to Programmer's Guide? </entry></row>
|
|
||||||
<row><entry> ./src/man/cleardbdir.1 </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/close.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/cluster.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/commit.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/copy.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_aggregate.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_database.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_function.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_index.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_language.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_operator.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_rule.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_sequence.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_table.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_trigger.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_type.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_user.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_version.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/create_view.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/createdb.1 </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/createuser.1 </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/declare.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/delete.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/destroydb.1 </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/destroyuser.1 </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_aggregate.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_database.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_function.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_index.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_language.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_operator.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_rule.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_sequence.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_table.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_trigger.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_type.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_user.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/drop_view.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/end.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/ecpg.1 </entry><entry> Short man page. Retain </entry></row>
|
|
||||||
<row><entry> ./src/man/explain.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/fetch.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/grant.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/initdb.1 </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/initlocation.1 </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/insert.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/ipcclean.1 </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/listen.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/load.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/lock.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/move.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/notify.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/pg_dump.1 </entry><entry> Assimilate into Admin Guide </entry></row>
|
|
||||||
<row><entry> ./src/man/pg_dumpall.1 </entry><entry> Assimilate into Admin Guide </entry></row>
|
|
||||||
<row><entry> ./src/man/pg_upgrade.1 </entry><entry> Assimilate into Admin Guide </entry></row>
|
|
||||||
<row><entry> ./src/man/pg_hba.conf.5 </entry><entry> Assimilate into Admin Guide </entry></row>
|
|
||||||
<row><entry> ./src/man/pg_passwd.1 </entry><entry> Assimilate into Admin Guide </entry></row>
|
|
||||||
<row><entry> ./src/man/pgintro.1 </entry><entry> Assimilate into User's Guide? </entry></row>
|
|
||||||
<row><entry> ./src/man/postgres.1 </entry><entry> Assimilate into User's, Admin Guides </entry></row>
|
|
||||||
<row><entry> ./src/man/postmaster.1 </entry><entry> Assimilate into User's, Admin Guides </entry></row>
|
|
||||||
<row><entry> ./src/man/psql.1 </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/reset.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/revoke.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/rollback.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/select.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/set.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/show.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/sql.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/update.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/man/vacuum.l </entry><entry> Not converted </entry></row>
|
|
||||||
<row><entry> ./src/pl/tcl/INSTALL </entry><entry> Not converted </entry></row>
|
<row><entry> ./src/pl/tcl/INSTALL </entry><entry> Not converted </entry></row>
|
||||||
<row><entry> ./src/pl/tcl/modules/README </entry><entry> Not converted </entry></row>
|
<row><entry> ./src/pl/tcl/modules/README </entry><entry> Not converted </entry></row>
|
||||||
<row><entry> ./src/pl/tcl/license.terms </entry><entry> Not converted </entry></row>
|
<row><entry> ./src/pl/tcl/license.terms </entry><entry> Not converted </entry></row>
|
||||||
@ -788,20 +714,22 @@ Status
|
|||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
-->
|
||||||
<title>Styles and Conventions</title>
|
|
||||||
|
|
||||||
<para>
|
<sect2>
|
||||||
<productname>DocBook</productname> has a rich set of tags and
|
<title>Styles and Conventions</title>
|
||||||
constructs, and a suprisingly large percentage are directly and
|
|
||||||
obviously useful for well-formed documentation. The
|
<para>
|
||||||
<productname>Postgres</productname> documentation set has only
|
<productname>DocBook</productname> has a rich set of tags and
|
||||||
recently been adapted to <acronym>SGML</acronym>, and in the near
|
constructs, and a suprisingly large percentage are directly and
|
||||||
future several sections of the set will be selected and maintained as
|
obviously useful for well-formed documentation. The
|
||||||
prototypical examples of <productname>DocBook</productname> usage.
|
<productname>Postgres</productname> documentation set has only
|
||||||
Also, a short summary of <productname>DocBook</productname> tags will
|
recently been adapted to <acronym>SGML</acronym>, and in the near
|
||||||
be included below.
|
future several sections of the set will be selected and maintained as
|
||||||
</para>
|
prototypical examples of <productname>DocBook</productname> usage.
|
||||||
|
Also, a short summary of <productname>DocBook</productname> tags will
|
||||||
|
be included below.
|
||||||
|
</para>
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
<para>
|
<para>
|
||||||
@ -833,61 +761,63 @@ be included below.
|
|||||||
</table>
|
</table>
|
||||||
</para>
|
</para>
|
||||||
-->
|
-->
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>SGML Authoring Tools</title>
|
<title>SGML Authoring Tools</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The current <acronym>Postgres</acronym> documentation set was written using
|
The current <acronym>Postgres</acronym> documentation set was written using
|
||||||
a plain text editor (or emacs/psgml; see below) with the content marked up using
|
a plain text editor (or emacs/psgml; see below) with the content marked up using
|
||||||
<acronym>SGML</acronym> DocBook tags.
|
<acronym>SGML</acronym> DocBook tags.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<acronym>SGML</acronym> and <productname>DocBook</productname> do not suffer
|
<acronym>SGML</acronym> and <productname>DocBook</productname> do not suffer
|
||||||
from an oversupply of open-source authoring tools. The most common toolset is
|
from an oversupply of open-source authoring tools. The most common toolset is
|
||||||
the emacs/xemacs editing package with the psgml feature extension.
|
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.
|
On some systems (e.g. RedHat Linux) these tools are provided in a typical full installation.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<sect3>
|
<sect3>
|
||||||
<title>emacs/psgml</title>
|
<title>emacs/psgml</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<application>emacs</application> (and <application>xemacs</application>) have
|
<application>emacs</application> (and <application>xemacs</application>) have
|
||||||
an <acronym>SGML</acronym> <firstterm>major mode</firstterm>. When properly configured,
|
an <acronym>SGML</acronym> <firstterm>major mode</firstterm>. When properly configured,
|
||||||
this will allow you to use <application>emacs</application> to insert tags and
|
this will allow you to use <application>emacs</application> to insert tags and
|
||||||
check markup consistancy.
|
check markup consistancy.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Put the following in your <filename>~/.emacs</filename> environment file:
|
Put the following in your <filename>~/.emacs</filename>
|
||||||
|
environment file (adjusting the path names to be appropriate for
|
||||||
|
your system):
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
; ********** for SGML mode (psgml)
|
; ********** for SGML mode (psgml)
|
||||||
|
|
||||||
(setq sgml-catalog-files "/usr/lib/sgml/CATALOG")
|
(setq sgml-catalog-files "/usr/lib/sgml/CATALOG")
|
||||||
(setq sgml-local-catalogs "/usr/lib/sgml/CATALOG")
|
(setq sgml-local-catalogs "/usr/lib/sgml/CATALOG")
|
||||||
|
|
||||||
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
|
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
and add an entry in the same file
|
and add an entry in the same file
|
||||||
for <acronym>SGML</acronym> into the (existing) definition for
|
for <acronym>SGML</acronym> into the (existing) definition for
|
||||||
auto-mode-alist:
|
auto-mode-alist:
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
(setq
|
(setq
|
||||||
auto-mode-alist
|
auto-mode-alist
|
||||||
'(("\\.sgml$" . sgml-mode)
|
'(("\\.sgml$" . sgml-mode)
|
||||||
))
|
))
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
Each <acronym>SGML</acronym> source file has the following block at the
|
Each <acronym>SGML</acronym> source file has the following block at the
|
||||||
end of the file:
|
end of the file:
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
<sgmltag>!-- Keep this comment at the end of the file
|
<sgmltag>!-- Keep this comment at the end of the file
|
||||||
Local variables:
|
Local variables:
|
||||||
mode: sgml
|
mode: sgml
|
||||||
@ -900,37 +830,37 @@ sgml-indent-data:t
|
|||||||
sgml-parent-document:nil
|
sgml-parent-document:nil
|
||||||
sgml-default-dtd-file:"./reference.ced"
|
sgml-default-dtd-file:"./reference.ced"
|
||||||
sgml-exposed-tags:nil
|
sgml-exposed-tags:nil
|
||||||
sgml-local-catalogs:"/usr/lib/sgml/catalog"
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
||||||
sgml-local-ecat-files:nil
|
sgml-local-ecat-files:nil
|
||||||
End:
|
End:
|
||||||
--</sgmltag>
|
--</sgmltag>
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <productname>Postgres</productname> distribution includes a
|
The <productname>Postgres</productname> distribution includes a
|
||||||
parsed DTD definitions file <filename>reference.ced</filename>.
|
parsed DTD definitions file <filename>reference.ced</filename>.
|
||||||
You may find that
|
You may find that
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
When using <application>emacs</application>/psgml, a comfortable way of working with
|
When using <application>emacs</application>/psgml, a comfortable way of working with
|
||||||
these separate files of book parts is to insert a proper DOCTYPE
|
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,
|
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
|
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:
|
a DocBook document by making the first line look like this:
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
<sgmltag>!doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"</sgmltag>
|
<sgmltag>!doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"</sgmltag>
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
This means that anything and everything that reads <acronym>SGML</acronym> will get it
|
This means that anything and everything that reads <acronym>SGML</acronym> will get it
|
||||||
right, and I can verify the document with "nsgmls -s docguide.sgml".
|
right, and I can verify the document with "nsgmls -s docguide.sgml".
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</sect3>
|
</sect3>
|
||||||
</sect2>
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Building Documentation</title>
|
<title>Building Documentation</title>
|
||||||
@ -955,8 +885,8 @@ YFLAGS+= -v
|
|||||||
|
|
||||||
# documentation
|
# documentation
|
||||||
|
|
||||||
HSTYLE= /home/tgl/SGML/db107.d/docbook/html
|
HSTYLE= /home/lockhart/SGML/db143.d/docbook/html
|
||||||
PSTYLE= /home/tgl/SGML/db107.d/docbook/print
|
PSTYLE= /home/lockhart/SGML/db143.d/docbook/print
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
where HSTYLE and PSTYLE determine the path to
|
where HSTYLE and PSTYLE determine the path to
|
||||||
@ -995,36 +925,6 @@ PSTYLE= /home/tgl/SGML/db107.d/docbook/print
|
|||||||
% make install
|
% make install
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
<sect2>
|
|
||||||
<title>FreeBSD specific howto</title>
|
|
||||||
<para>
|
|
||||||
To build the documentation on FreeBSD a number of ports will need to
|
|
||||||
be installed.
|
|
||||||
<programlisting>
|
|
||||||
% 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
|
|
||||||
</programlisting>
|
|
||||||
Some enviornment variables need to be set (assumes you are running a sh
|
|
||||||
based shell):
|
|
||||||
<programlisting>
|
|
||||||
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 </programlisting>
|
|
||||||
Make needs some special arguments, or these need to be added to your
|
|
||||||
Makefile.custom:
|
|
||||||
<programlisting>
|
|
||||||
HSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/html/
|
|
||||||
PSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/print/
|
|
||||||
</programlisting>
|
|
||||||
Of course you'll need to use gmake rather than just plain 'make' to build.
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
@ -1203,8 +1103,9 @@ $ make man
|
|||||||
<title>Postscript Hardcopy</title>
|
<title>Postscript Hardcopy</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Several items must be addressed in generating Postscript
|
Several areas are addressed while generating Postscript
|
||||||
hardcopy:</para>
|
hardcopy.
|
||||||
|
</para>
|
||||||
|
|
||||||
<procedure>
|
<procedure>
|
||||||
<title>Applixware <acronym>RTF</acronym> Cleanup</title>
|
<title>Applixware <acronym>RTF</acronym> Cleanup</title>
|
||||||
@ -1314,34 +1215,193 @@ $ make man
|
|||||||
<title>Toolsets</title>
|
<title>Toolsets</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
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
|
various tools that are needed to process the documentation. One is
|
||||||
installation from <acronym>RPM</acronym>s on
|
installation from <acronym>RPM</acronym>s on
|
||||||
<productname>Linux</productname>, the other is a general installation
|
<productname>Linux</productname>, the second is installation from
|
||||||
from original distributions of the individual tools. Both will be
|
FreeBSD <firstterm>port</firstterm>, and the last is a general installation
|
||||||
|
from original distributions of the individual tools. These will be
|
||||||
described below.
|
described below.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
We understand that there are some other packaged distributions for
|
There may be some other packaged distributions for
|
||||||
these tools. <productname>FreeBSD</productname> seems to have them
|
these tools. Please report package status to the docs mailing list and
|
||||||
available. Please report package status to the docs mailing list and
|
|
||||||
we will include that information here.
|
we will include that information here.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title><acronym>RPM</acronym> installation on
|
<title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
|
||||||
<productname>Linux</productname></title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Install <ulink url="ftp://ftp.cygnus.com/pub/home/rosalia/">
|
The simplest installation for a RedHat-compatible Linux system
|
||||||
<acronym>RPM</acronym>s</ulink> for <productname>Jade</productname>
|
uses the <acronym>RPM</acronym> set developed by Mark Galassi at
|
||||||
and related packages.
|
Cygnus. It should also be possible to install from sources, as
|
||||||
|
described in a subsequent section.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
<procedure>
|
||||||
|
<title>Installing RPMs</title>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Install <ulink url="ftp://ftp.cygnus.com/pub/home/rosalia/">
|
||||||
|
<acronym>RPM</acronym>s</ulink> for <productname>Jade</productname>
|
||||||
|
and related packages.
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="optional">
|
||||||
|
<para>
|
||||||
|
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 <acronym>RPM</acronym>s.
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Update your <filename>src/Makefile.custom</filename> to include
|
||||||
|
HSTYLE and PSTYLE definitions pointing to the style sheets.
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
</procedure>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>Manual installation of tools</title>
|
<title>FreeBSD Installation</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
There is a full set of <firstterm>ports</firstterm> of the
|
||||||
|
documentation tools available on FreeBSD. In fact, postgresql.org,
|
||||||
|
on which documentation is automatically updated every evening, is
|
||||||
|
a FreeBSD machine.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<procedure>
|
||||||
|
<title>Installing FreeBSD Ports</title>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
To build the documentation on FreeBSD a number of ports will need to
|
||||||
|
be installed.
|
||||||
|
<programlisting>
|
||||||
|
% 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
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="optional">
|
||||||
|
<para>
|
||||||
|
Set environment variables
|
||||||
|
to access the <application>jade</application>
|
||||||
|
toolset.
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>
|
||||||
|
This was not required for the FreeBSD machine at
|
||||||
|
postgresql.org, so you may not have to do this.
|
||||||
|
</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
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
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
(this is sh/bash syntax; adjust accordingly for csh/tcsh).
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Make needs some special arguments, or these need to be added to your
|
||||||
|
Makefile.custom:
|
||||||
|
<programlisting>
|
||||||
|
HSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/html/
|
||||||
|
PSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/print/
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
Of course you'll need to use gmake rather than just plain 'make' to build.
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
</procedure>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Debian Installation</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
There is a full set of packages of the
|
||||||
|
documentation tools available for Debian.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<procedure>
|
||||||
|
<title>Installing Debian Packages</title>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Install jade, docbook, and unzip:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
apt-get install jade
|
||||||
|
apt-get install docbook
|
||||||
|
apt-get install docbook-stylesheets
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="optional">
|
||||||
|
<para>
|
||||||
|
Install the latest style sheets.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<substeps>
|
||||||
|
<step performance="optional">
|
||||||
|
<para>
|
||||||
|
Verify that <application>unzip</application> is installed, or
|
||||||
|
install the package:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
apt-get install unzip
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Grab the latest stylesheet zipballs from
|
||||||
|
<ulink url="http://www.nwalsh.com/docbook/dsssl">http://www.nwalsh.com/docbook/dsssl</ulink>
|
||||||
|
and unzip it somewhere (possibly /usr/share).
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
</substeps>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Edit src/Makefile.custom to add appropriate HSTYLE and PSTYLE
|
||||||
|
definitions:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
HSTYLE= /usr/share/docbook/html
|
||||||
|
PSTYLE= /usr/share/docbook/print
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
</procedure>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Manual Installation of Tools</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This is a brief run-through of the process of obtaining and
|
This is a brief run-through of the process of obtaining and
|
||||||
@ -1882,10 +1942,8 @@ dvips postgres.dvi
|
|||||||
|
|
||||||
<para>
|
<para>
|
||||||
<productname>sgml-tools</productname> v2.x
|
<productname>sgml-tools</productname> v2.x
|
||||||
now supports <application>jade</application>
|
supports <application>jade</application>
|
||||||
and <productname>DocBook</productname>. It may be the preferred toolset
|
and <productname>DocBook</productname>.
|
||||||
for working with <acronym>SGML</acronym> but we have not had a chance to
|
|
||||||
evaluate the new package.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
@ -1954,12 +2012,13 @@ Run <productname>texhash</productname> to update the tex database.
|
|||||||
</para></sect2></sect1>
|
</para></sect2></sect1>
|
||||||
|
|
||||||
-->
|
-->
|
||||||
</sect1>
|
|
||||||
|
</sect1>
|
||||||
</appendix>
|
</appendix>
|
||||||
|
|
||||||
<!-- Keep this comment at the end of the file
|
<!-- Keep this comment at the end of the file
|
||||||
Local variables:
|
Local variables:
|
||||||
mode: sgml
|
mode:sgml
|
||||||
sgml-omittag:nil
|
sgml-omittag:nil
|
||||||
sgml-shorttag:t
|
sgml-shorttag:t
|
||||||
sgml-minimize-attributes:nil
|
sgml-minimize-attributes:nil
|
||||||
@ -1969,7 +2028,7 @@ sgml-indent-data:t
|
|||||||
sgml-parent-document:nil
|
sgml-parent-document:nil
|
||||||
sgml-default-dtd-file:"./reference.ced"
|
sgml-default-dtd-file:"./reference.ced"
|
||||||
sgml-exposed-tags:nil
|
sgml-exposed-tags:nil
|
||||||
sgml-local-catalogs:"/usr/lib/sgml/catalog"
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
||||||
sgml-local-ecat-files:nil
|
sgml-local-ecat-files:nil
|
||||||
End:
|
End:
|
||||||
-->
|
-->
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user