Include first cut at instructions for man pages in docguide.sgml.
Fix markup.
#
#
# IDENTIFICATION
-# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.7 1998/10/30 19:36:51 thomas Exp $
+# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.8 1999/07/06 17:19:41 thomas Exp $
#
#----------------------------------------------------------------------------
PGDOCS= ../..
SRCDIR= ../../../src
+D2MDIR= ../docbook2man
# This is where the default stylesheets appear on my system.
# Probably no need to change this; rather, put definitions
# for HSTYLE and PSTYLE and/or for HDSL and PDSL
# in Makefile.custom in your code src directory.
-HSTYLE=/usr/lib/sgml/stylesheets/jade/docbook/html
-PSTYLE=/usr/lib/sgml/stylesheets/jade/docbook/print
+#HSTYLE=/usr/lib/sgml/stylesheets/nwalsh-modular/html
+#PSTYLE=/usr/lib/sgml/stylesheets/nwalsh-modular/print
-#HSTYLE=/home/tgl/SGML/db107.d/docbook/html
-#PSTYLE=/home/tgl/SGML/db107.d/docbook/print
+HSTYLE=/opt/sgml/current/docbook/html
+PSTYLE=/opt/sgml/current/docbook/print
HDSL=$(HSTYLE)/docbook.dsl
PDSL=$(PSTYLE)/docbook.dsl
PRINTOPTS= -d $(PDSL)
endif
+MANSOURCES= $(wildcard ref/*.sgml)
+
+APPLICATIONS= createdb.sgml createuser.sgml \
+ destroydb.sgml destroyuser.sgml \
+ initdb.sgml initlocation.sgml \
+ pg_dump.sgml \
+ pg_dumpall.sgml \
+ pg_upgrade.sgml \
+ pgaccess-ref.sgml \
+ pgadmin-ref.sgml \
+ postgres-ref.sgml \
+ postmaster.sgml \
+ psql-ref.sgml \
+ vacuumdb.sgml
+
+COMMANDS= abort.sgml alter_table.sgml alter_user.sgml \
+ begin.sgml \
+ close.sgml cluster.sgml commit.sgml copy.sgml \
+ create_aggregate.sgml create_database.sgml create_function.sgml create_index.sgml \
+ create_language.sgml create_operator.sgml create_rule.sgml create_sequence.sgml \
+ create_table.sgml create_table_as.sgml create_trigger.sgml create_type.sgml \
+ create_user.sgml create_view.sgml \
+ declare.sgml delete.sgml \
+ drop_aggregate.sgml drop_database.sgml drop_function.sgml drop_index.sgml \
+ drop_language.sgml drop_operator.sgml drop_rule.sgml drop_sequence.sgml \
+ drop_table.sgml drop_trigger.sgml drop_type.sgml drop_user.sgml drop_view.sgml \
+ explain.sgml fetch.sgml grant.sgml \
+ insert.sgml listen.sgml load.sgml lock.sgml move.sgml \
+ notify.sgml \
+ reset.sgml revoke.sgml rollback.sgml \
+ select.sgml select_into.sgml set.sgml show.sgml \
+ unlisten.sgml update.sgml vacuum.sgml
+
+FUNCTIONS= current_date.sgml current_time.sgml current_timestamp.sgml current_user.sgml
+
+APPSOURCES= $(addprefix ref/, $(APPLICATIONS))
+SQLSOURCES= $(addprefix ref/, $(COMMANDS))
+APPTARGETS= $(APPLICATIONS:.sgml=.1)
+SQLTARGETS= $(COMMANDS:.sgml=.l)
+
.PRECIOUS: postgres.tex postgres.dvi
.PHONY: install all clean distclean
all::
+#man:: .manlist
+# for f in `cat .manlist` ; do \
+# nsgmls $f | sgmlspl ../docbook2man/docbook2man-spec.pl --lowercase; \
+# done
+#
+#.manlist: $(MANSOURCES)
+# (grep -iE '<refentry([ ]|>)' $(MANSOURCES) | cut -f 1 -d : | sort | uniq) > .manlist
+
+man1: $(APPTARGETS)
+ $(RM) -rf man1
+ if [ ! -d man1 ]; then mkdir man1; fi
+ mv *.1 man1/
+
+manl: $(SQLTARGETS)
+ $(RM) -rf manl/*
+ if [ ! -d manl ]; then mkdir manl; fi
+ mv *.l manl/
+
clean::
- (rm -rf HTML.manifest *.html *.htm)
+ (rm -rf HTML.manifest *.html *.htm man1 manl manpage*)
distclean::
$(MAKE) clean
# Generic production rules
#
-# Compressed file
-
-%.gz: %
- (gzip -f $<)
-
-# TAR file for HTML package
+%.1: ref/%.sgml
+ nsgmls $< | sgmlspl $(D2MDIR)/docbook2man-spec.pl --defsection 1
-%.tar: %.html # %.ps
- ($(TAR) cf $@ $*.html index.html *.htm *.gif) # $*.ps
- (rm -rf index.html *.htm)
+%.l: ref/%.sgml
+ nsgmls $< | sgmlspl $(D2MDIR)/docbook2man-spec.pl --defsection l
# HTML
# Include some softlinks to the generic default file names
<note>
<title>Author</title>
<para>
- This chapter originally appeared as a part of <xref linkend="SIM98" endterm="SIM98">, Stefan Simkovics'
+ This chapter originally appeared as a part of
+ <xref linkend="SIM98" endterm="SIM98">, Stefan Simkovics'
Master's Thesis prepared at Vienna University of Technology under the direction
of O.Univ.Prof.Dr. Georg Gottlob and Univ.Ass. Mag. Katrin Seyr.
</para>
<para>
A detailed description of <application>yacc</application> or
- the grammar rules given
- in <filename>gram.y</filename> would be beyond the scope of this paper. There are
- many books and documents dealing with <application>lex</application>
- and <application>yacc</application>. You
-
should be familiar with <application>yacc</application> before you start to study the
- grammar given in <filename>gram.y</filename> otherwise you won't understand what
- happens there.
+ the grammar rules given in <filename>gram.y</filename> would be
+ beyond the scope of this paper. There are many books and
+ documents dealing with <application>lex</application> and
+ <application>yacc</application>. You should be familiar with
+ <application>yacc</application> before you start to study the
+ grammar given in <filename>gram.y</filename> otherwise you won't
+ understand what happens there.
</para>
<para>
- For a better understanding of the data structures used in <productname>Postgres</productname>
+ For a better understanding of the data structures used in
+ <productname>Postgres</productname>
for the processing of a query we use an example to illustrate the
changes made to these data structures in every stage.
</para>
have already been defined.
<programlisting>
- select s.sname, se.pno
- from supplier s, sells se
- where s.sno > 2 and
- s.sno = se.sno;
+select s.sname, se.pno
+ from supplier s, sells se
+ where s.sno > 2 and s.sno = se.sno;
</programlisting>
</para>
</example>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.17 1999/06/23 06:19:36 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.18 1999/07/06 17:19:41 thomas Exp $
Documentation Guide
Thomas Lockhart
</thead>
<tbody>
<row>
- <entry><sgmltag>Book</sgmltag></entry>
+ <entry><sgmltag>book</sgmltag></entry>
<entry>Delimits a Book element</entry>
</row>
<row>
- <entry><sgmltag>Chapter</sgmltag></entry>
+ <entry><sgmltag>chapter</sgmltag></entry>
<entry>Delimits a Chapter element</entry>
</row>
<row>
- <entry><sgmltag>Appendix</sgmltag></entry>
+ <entry><sgmltag>appendix</sgmltag></entry>
<entry><sgmltag>Delimits a Appendix element</sgmltag></entry>
</row>
</tbody>
</sect2>
</sect1>
-<sect1>
-<title>Building Documentation</title>
+ <sect1>
+ <title>Building Documentation</title>
-<para>
-GNU <application>make</application> is used to build documentation from the DocBook sources.
-There are a few environment definitions which may need to be set or modified for your installation.
-The <filename>Makefile</filename> looks for
-<filename>doc/../src/Makefile</filename>
-and (implicitly) for
-<filename>doc/../src/Makefile.custom</filename>
-to obtain environment information. On my system, the <filename>src/Makefile.custom</filename> looks like
+ <para>
+ GNU <application>make</application> is used to build documentation
+ from the DocBook sources. There are a few environment definitions
+ which may need to be set or modified for your installation.
+ The <filename>Makefile</filename> looks for
+ <filename>doc/../src/Makefile</filename> and (implicitly) for
+ <filename>doc/../src/Makefile.custom</filename> to obtain
+ environment information. On my system, the
+ <filename>src/Makefile.custom</filename> looks like
-<programlisting>
# Makefile.custom
# Thomas Lockhart 1998-03-01
HSTYLE= /home/tgl/SGML/db107.d/docbook/html
PSTYLE= /home/tgl/SGML/db107.d/docbook/print
-</programlisting>
+ </programlisting>
-where HSTYLE and PSTYLE determine the path to <filename>docbook.dsl</filename> for <acronym>HTML</acronym>
-and hardcopy (print) stylesheets, respectively. These stylesheet file names are for Norm Walsh's
-Modular Style Sheets; if other stylesheets are used then one can define HDSL and PDSL as the full path
-and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.
-On many systems, these stylesheets will be found in packages installed in
-<filename>/usr/lib/sgml/</filename>,
-<filename>/usr/share/lib/sgml/</filename>,
-or
-<filename>/usr/local/lib/sgml/</filename>.
-</para>
+ where HSTYLE and PSTYLE determine the path to
+ <filename>docbook.dsl</filename> for <acronym>HTML</acronym>
+ and hardcopy (print) stylesheets, respectively. These stylesheet
+ file names are for Norm Walsh's
+ <productname>Modular Style Sheets</productname>; if other
+ stylesheets are used then one can define HDSL and PDSL as the full path
+ and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.
+ On many systems, these stylesheets will be found in packages installed in
+ <filename>/usr/lib/sgml/</filename>,
+ <filename>/usr/share/lib/sgml/</filename>,
+ or
+ <filename>/usr/local/lib/sgml/</filename>.
+ </para>
-<para>
-<acronym>HTML</acronym> documentation packages can be generated from the <acronym>SGML</acronym> source by
-typing
-<programlisting>
+ <acronym>HTML</acronym> documentation packages can be generated
+ from the <acronym>SGML</acronym> source by typing
% cd doc/src
% make tutorial.tar.gz
% make user.tar.gz
% make programmer.tar.gz
% make postgres.tar.gz
% make install
-</programlisting>
-</para>
+ </programlisting>
+ </para>
-<para>
-These packages can be installed from the main documentation directory
-by typing
-<programlisting>
+ These packages can be installed from the main documentation directory
+ by typing
% cd doc
% make install
-</programlisting>
-</para></sect1>
+ </programlisting>
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Manpages</title>
+
+ <para>
+ We use the <application>docbook2man</application> utility to
+ convert <productname>DocBook</productname>
+ <sgmltag>REFENTRY</sgmltag> pages to *roff output suitable for man
+ pages. At the time of writing, the utility required patching to
+ successfully run on the <productname>Postgres</productname> markup,
+ and we added a small amount of new functionality to allow setting
+ the man page section in the output file name.
+ </para>
+
+ <para>
+ <application>docbook2man</application> is written in perl, and
+ requires the CPAN package <literal>SGMLSpm</literal> to run. Also,
+ it requires <application>nsgmls</application> to be available,
+ which is included in the <application>jade</application>
+ distribution. After installing these packages, then simply run
+
+ <programlisting>
+$ cd doc/src
+$ make man
+ </programlisting>
+
+ which will result in a tar file being generated in the
+ <filename>doc/src</filename> directory.
+ </para>
+
+ <procedure>
+ <title>docbook2man Installation Procedure</title>
+
+ <step performance="required">
+ <para>
+ Install the <application>docbook2man</application> package,
+ available at
+ <ulink url="http://shell.ipoline.com/~elmert/comp/docbook2X/">http://shell.ipoline.com/~elmert/comp/docbook2X/</ulink>
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Install the SGMLSpm perl module, available from CPAN mirrors.
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Install <application>nsgmls</application> if not already
+ available from your <application>jade</application> installation.
+ </para>
+ </step>
+ </procedure>
+ </sect1>
<sect1>
<title>Hardcopy Generation for v6.5</title>
<programlisting>
PgDatabase data;
- data.exec("create table foo (a int4, b char16, d float8)");
- data.exec("copy foo from stdin");
+ data.Exec("create table foo (a int4, b char16, d float8)");
+ data.Exec("copy foo from stdin");
data.putline("3\etHello World\et4.5\en");
data.putline("4\etGoodbye World\et7.11\en");
&...
<tgroup cols="4">
<thead>
<row>
+ <entry>
+ </entry>
<entry>
Dirty Read
</entry>
projects / thirdparty / postgresql.git / commitdiff
