mirror of
https://git.postgresql.org/git/postgresql.git
synced 2025-01-30 19:00:29 +08:00
Update makefile to generate man pages.
Include first cut at instructions for man pages in docguide.sgml. Fix markup.
This commit is contained in:
Thomas G. Lockhart
parent
7b09d4bacb
commit
07c0de7d9d
@ -8,23 +8,24 @@
|
|||||||
#
|
#
|
||||||
#
|
#
|
||||||
# IDENTIFICATION
|
# 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= ../..
|
PGDOCS= ../..
|
||||||
SRCDIR= ../../../src
|
SRCDIR= ../../../src
|
||||||
|
D2MDIR= ../docbook2man
|
||||||
|
|
||||||
# This is where the default stylesheets appear on my system.
|
# This is where the default stylesheets appear on my system.
|
||||||
# Probably no need to change this; rather, put definitions
|
# Probably no need to change this; rather, put definitions
|
||||||
# for HSTYLE and PSTYLE and/or for HDSL and PDSL
|
# for HSTYLE and PSTYLE and/or for HDSL and PDSL
|
||||||
# in Makefile.custom in your code src directory.
|
# in Makefile.custom in your code src directory.
|
||||||
|
|
||||||
HSTYLE=/usr/lib/sgml/stylesheets/jade/docbook/html
|
#HSTYLE=/usr/lib/sgml/stylesheets/nwalsh-modular/html
|
||||||
PSTYLE=/usr/lib/sgml/stylesheets/jade/docbook/print
|
#PSTYLE=/usr/lib/sgml/stylesheets/nwalsh-modular/print
|
||||||
|
|
||||||
#HSTYLE=/home/tgl/SGML/db107.d/docbook/html
|
HSTYLE=/opt/sgml/current/docbook/html
|
||||||
#PSTYLE=/home/tgl/SGML/db107.d/docbook/print
|
PSTYLE=/opt/sgml/current/docbook/print
|
||||||
|
|
||||||
HDSL=$(HSTYLE)/docbook.dsl
|
HDSL=$(HSTYLE)/docbook.dsl
|
||||||
PDSL=$(PSTYLE)/docbook.dsl
|
PDSL=$(PSTYLE)/docbook.dsl
|
||||||
@ -57,6 +58,46 @@ ifneq ($(PDSL), )
|
|||||||
PRINTOPTS= -d $(PDSL)
|
PRINTOPTS= -d $(PDSL)
|
||||||
endif
|
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
|
.PRECIOUS: postgres.tex postgres.dvi
|
||||||
.PHONY: install all clean distclean
|
.PHONY: install all clean distclean
|
||||||
|
|
||||||
@ -66,8 +107,26 @@ install::
|
|||||||
|
|
||||||
all::
|
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::
|
clean::
|
||||||
(rm -rf HTML.manifest *.html *.htm)
|
(rm -rf HTML.manifest *.html *.htm man1 manl manpage*)
|
||||||
|
|
||||||
distclean::
|
distclean::
|
||||||
$(MAKE) clean
|
$(MAKE) clean
|
||||||
@ -76,16 +135,11 @@ distclean::
|
|||||||
# Generic production rules
|
# Generic production rules
|
||||||
#
|
#
|
||||||
|
|
||||||
# Compressed file
|
%.1: ref/%.sgml
|
||||||
|
nsgmls $< | sgmlspl $(D2MDIR)/docbook2man-spec.pl --defsection 1
|
||||||
|
|
||||||
%.gz: %
|
%.l: ref/%.sgml
|
||||||
(gzip -f $<)
|
nsgmls $< | sgmlspl $(D2MDIR)/docbook2man-spec.pl --defsection l
|
||||||
|
|
||||||
# TAR file for HTML package
|
|
||||||
|
|
||||||
%.tar: %.html # %.ps
|
|
||||||
($(TAR) cf $@ $*.html index.html *.htm *.gif) # $*.ps
|
|
||||||
(rm -rf index.html *.htm)
|
|
||||||
|
|
||||||
# HTML
|
# HTML
|
||||||
# Include some softlinks to the generic default file names
|
# Include some softlinks to the generic default file names
|
||||||
|
|||||||
@ -4,7 +4,8 @@
|
|||||||
<note>
|
<note>
|
||||||
<title>Author</title>
|
<title>Author</title>
|
||||||
<para>
|
<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
|
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.
|
of O.Univ.Prof.Dr. Georg Gottlob and Univ.Ass. Mag. Katrin Seyr.
|
||||||
</para>
|
</para>
|
||||||
@ -239,17 +240,18 @@
|
|||||||
|
|
||||||
<para>
|
<para>
|
||||||
A detailed description of <application>yacc</application> or
|
A detailed description of <application>yacc</application> or
|
||||||
the grammar rules given
|
the grammar rules given in <filename>gram.y</filename> would be
|
||||||
in <filename>gram.y</filename> would be beyond the scope of this paper. There are
|
beyond the scope of this paper. There are many books and
|
||||||
many books and documents dealing with <application>lex</application>
|
documents dealing with <application>lex</application> and
|
||||||
and <application>yacc</application>. You
|
<application>yacc</application>. You should be familiar with
|
||||||
should be familiar with <application>yacc</application> before you start to study the
|
<application>yacc</application> before you start to study the
|
||||||
grammar given in <filename>gram.y</filename> otherwise you won't understand what
|
grammar given in <filename>gram.y</filename> otherwise you won't
|
||||||
happens there.
|
understand what happens there.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<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
|
for the processing of a query we use an example to illustrate the
|
||||||
changes made to these data structures in every stage.
|
changes made to these data structures in every stage.
|
||||||
</para>
|
</para>
|
||||||
@ -271,10 +273,9 @@
|
|||||||
have already been defined.
|
have already been defined.
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
select s.sname, se.pno
|
select s.sname, se.pno
|
||||||
from supplier s, sells se
|
from supplier s, sells se
|
||||||
where s.sno > 2 and
|
where s.sno > 2 and s.sno = se.sno;
|
||||||
s.sno = se.sno;
|
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
</example>
|
</example>
|
||||||
|
|||||||
@ -1,5 +1,5 @@
|
|||||||
<!--
|
<!--
|
||||||
$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
|
Documentation Guide
|
||||||
Thomas Lockhart
|
Thomas Lockhart
|
||||||
|
|
||||||
@ -817,15 +817,15 @@ be included below.
|
|||||||
</thead>
|
</thead>
|
||||||
<tbody>
|
<tbody>
|
||||||
<row>
|
<row>
|
||||||
<entry><sgmltag>Book</sgmltag></entry>
|
<entry><sgmltag>book</sgmltag></entry>
|
||||||
<entry>Delimits a Book element</entry>
|
<entry>Delimits a Book element</entry>
|
||||||
</row>
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry><sgmltag>Chapter</sgmltag></entry>
|
<entry><sgmltag>chapter</sgmltag></entry>
|
||||||
<entry>Delimits a Chapter element</entry>
|
<entry>Delimits a Chapter element</entry>
|
||||||
</row>
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry><sgmltag>Appendix</sgmltag></entry>
|
<entry><sgmltag>appendix</sgmltag></entry>
|
||||||
<entry><sgmltag>Delimits a Appendix element</sgmltag></entry>
|
<entry><sgmltag>Delimits a Appendix element</sgmltag></entry>
|
||||||
</row>
|
</row>
|
||||||
</tbody>
|
</tbody>
|
||||||
@ -932,19 +932,20 @@ right, and I can verify the document with "nsgmls -s docguide.sgml".
|
|||||||
</sect2>
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Building Documentation</title>
|
<title>Building Documentation</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
GNU <application>make</application> is used to build documentation from the DocBook sources.
|
GNU <application>make</application> is used to build documentation
|
||||||
There are a few environment definitions which may need to be set or modified for your installation.
|
from the DocBook sources. There are a few environment definitions
|
||||||
The <filename>Makefile</filename> looks for
|
which may need to be set or modified for your installation.
|
||||||
<filename>doc/../src/Makefile</filename>
|
The <filename>Makefile</filename> looks for
|
||||||
and (implicitly) for
|
<filename>doc/../src/Makefile</filename> and (implicitly) for
|
||||||
<filename>doc/../src/Makefile.custom</filename>
|
<filename>doc/../src/Makefile.custom</filename> to obtain
|
||||||
to obtain environment information. On my system, the <filename>src/Makefile.custom</filename> looks like
|
environment information. On my system, the
|
||||||
|
<filename>src/Makefile.custom</filename> looks like
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
# Makefile.custom
|
# Makefile.custom
|
||||||
# Thomas Lockhart 1998-03-01
|
# Thomas Lockhart 1998-03-01
|
||||||
|
|
||||||
@ -956,23 +957,26 @@ YFLAGS+= -v
|
|||||||
|
|
||||||
HSTYLE= /home/tgl/SGML/db107.d/docbook/html
|
HSTYLE= /home/tgl/SGML/db107.d/docbook/html
|
||||||
PSTYLE= /home/tgl/SGML/db107.d/docbook/print
|
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>
|
where HSTYLE and PSTYLE determine the path to
|
||||||
and hardcopy (print) stylesheets, respectively. These stylesheet file names are for Norm Walsh's
|
<filename>docbook.dsl</filename> for <acronym>HTML</acronym>
|
||||||
Modular Style Sheets; if other stylesheets are used then one can define HDSL and PDSL as the full path
|
and hardcopy (print) stylesheets, respectively. These stylesheet
|
||||||
and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.
|
file names are for Norm Walsh's
|
||||||
On many systems, these stylesheets will be found in packages installed in
|
<productname>Modular Style Sheets</productname>; if other
|
||||||
<filename>/usr/lib/sgml/</filename>,
|
stylesheets are used then one can define HDSL and PDSL as the full path
|
||||||
<filename>/usr/share/lib/sgml/</filename>,
|
and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.
|
||||||
or
|
On many systems, these stylesheets will be found in packages installed in
|
||||||
<filename>/usr/local/lib/sgml/</filename>.
|
<filename>/usr/lib/sgml/</filename>,
|
||||||
</para>
|
<filename>/usr/share/lib/sgml/</filename>,
|
||||||
|
or
|
||||||
|
<filename>/usr/local/lib/sgml/</filename>.
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<acronym>HTML</acronym> documentation packages can be generated from the <acronym>SGML</acronym> source by
|
<acronym>HTML</acronym> documentation packages can be generated
|
||||||
typing
|
from the <acronym>SGML</acronym> source by typing
|
||||||
<programlisting>
|
<programlisting>
|
||||||
% cd doc/src
|
% cd doc/src
|
||||||
% make tutorial.tar.gz
|
% make tutorial.tar.gz
|
||||||
% make user.tar.gz
|
% make user.tar.gz
|
||||||
@ -980,17 +984,73 @@ typing
|
|||||||
% make programmer.tar.gz
|
% make programmer.tar.gz
|
||||||
% make postgres.tar.gz
|
% make postgres.tar.gz
|
||||||
% make install
|
% make install
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
These packages can be installed from the main documentation directory
|
These packages can be installed from the main documentation directory
|
||||||
by typing
|
by typing
|
||||||
<programlisting>
|
<programlisting>
|
||||||
% cd doc
|
% cd doc
|
||||||
% make install
|
% make install
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para></sect1>
|
</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>
|
<sect1>
|
||||||
<title>Hardcopy Generation for v6.5</title>
|
<title>Hardcopy Generation for v6.5</title>
|
||||||
|
|||||||
@ -738,8 +738,8 @@
|
|||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
PgDatabase data;
|
PgDatabase data;
|
||||||
data.exec("create table foo (a int4, b char16, d float8)");
|
data.Exec("create table foo (a int4, b char16, d float8)");
|
||||||
data.exec("copy foo from stdin");
|
data.Exec("copy foo from stdin");
|
||||||
data.putline("3\etHello World\et4.5\en");
|
data.putline("3\etHello World\et4.5\en");
|
||||||
data.putline("4\etGoodbye World\et7.11\en");
|
data.putline("4\etGoodbye World\et7.11\en");
|
||||||
&...
|
&...
|
||||||
|
|||||||
@ -95,6 +95,8 @@
|
|||||||
<tgroup cols="4">
|
<tgroup cols="4">
|
||||||
<thead>
|
<thead>
|
||||||
<row>
|
<row>
|
||||||
|
<entry>
|
||||||
|
</entry>
|
||||||
<entry>
|
<entry>
|
||||||
Dirty Read
|
Dirty Read
|
||||||
</entry>
|
</entry>
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user