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
|
||||
# $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
|
||||
@ -57,6 +58,46 @@ ifneq ($(PDSL), )
|
||||
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
|
||||
|
||||
@ -66,8 +107,26 @@ install::
|
||||
|
||||
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
|
||||
@ -76,16 +135,11 @@ distclean::
|
||||
# Generic production rules
|
||||
#
|
||||
|
||||
# Compressed file
|
||||
%.1: ref/%.sgml
|
||||
nsgmls $< | sgmlspl $(D2MDIR)/docbook2man-spec.pl --defsection 1
|
||||
|
||||
%.gz: %
|
||||
(gzip -f $<)
|
||||
|
||||
# TAR file for HTML package
|
||||
|
||||
%.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
|
||||
|
||||
@ -4,7 +4,8 @@
|
||||
<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>
|
||||
@ -239,17 +240,18 @@
|
||||
|
||||
<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>
|
||||
@ -271,10 +273,9 @@
|
||||
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>
|
||||
|
||||
@ -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
|
||||
Thomas Lockhart
|
||||
|
||||
@ -817,15 +817,15 @@ be included below.
|
||||
</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>
|
||||
@ -932,19 +932,20 @@ right, and I can verify the document with "nsgmls -s docguide.sgml".
|
||||
</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>
|
||||
<programlisting>
|
||||
# Makefile.custom
|
||||
# Thomas Lockhart 1998-03-01
|
||||
|
||||
@ -956,23 +957,26 @@ YFLAGS+= -v
|
||||
|
||||
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>
|
||||
<para>
|
||||
<acronym>HTML</acronym> documentation packages can be generated
|
||||
from the <acronym>SGML</acronym> source by typing
|
||||
<programlisting>
|
||||
% cd doc/src
|
||||
% make tutorial.tar.gz
|
||||
% make user.tar.gz
|
||||
@ -980,17 +984,73 @@ typing
|
||||
% 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>
|
||||
<para>
|
||||
These packages can be installed from the main documentation directory
|
||||
by typing
|
||||
<programlisting>
|
||||
% 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>
|
||||
|
||||
@ -738,8 +738,8 @@
|
||||
|
||||
<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");
|
||||
&...
|
||||
|
||||
@ -95,6 +95,8 @@
|
||||
<tgroup cols="4">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>
|
||||
</entry>
|
||||
<entry>
|
||||
Dirty Read
|
||||
</entry>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user