diff --git a/config/docbook.m4 b/config/docbook.m4 index 4304fa7ea13..d5503093530 100644 --- a/config/docbook.m4 +++ b/config/docbook.m4 @@ -1,11 +1,5 @@ # config/docbook.m4 -# PGAC_PROG_JADE -# -------------- -AC_DEFUN([PGAC_PROG_JADE], -[AC_CHECK_PROGS([JADE], [openjade jade])]) - - # PGAC_PROG_NSGMLS # ---------------- AC_DEFUN([PGAC_PROG_NSGMLS], @@ -44,59 +38,3 @@ rm -f conftest.sgml]) have_docbook=$pgac_cv_check_docbook AC_SUBST([have_docbook]) ])# PGAC_CHECK_DOCBOOK - - -# PGAC_PATH_DOCBOOK_STYLESHEETS -# ----------------------------- -AC_DEFUN([PGAC_PATH_DOCBOOK_STYLESHEETS], -[AC_ARG_VAR(DOCBOOKSTYLE, [location of DocBook stylesheets])dnl -AC_MSG_CHECKING([for DocBook stylesheets]) -AC_CACHE_VAL([pgac_cv_path_stylesheets], -[if test -n "$DOCBOOKSTYLE"; then - pgac_cv_path_stylesheets=$DOCBOOKSTYLE -else - for pgac_prefix in /usr /usr/local /opt /sw; do - for pgac_infix in share lib; do - for pgac_postfix in \ - sgml/stylesheets/nwalsh-modular \ - sgml/stylesheets/docbook \ - sgml/stylesheets/dsssl/docbook \ - sgml/docbook-dsssl \ - sgml/docbook/dsssl/modular \ - sgml/docbook/stylesheet/dsssl/modular \ - sgml/docbook/dsssl-stylesheets \ - sgml/dsssl/docbook-dsssl-nwalsh - do - pgac_candidate=$pgac_prefix/$pgac_infix/$pgac_postfix - if test -r "$pgac_candidate/html/docbook.dsl" \ - && test -r "$pgac_candidate/print/docbook.dsl" - then - pgac_cv_path_stylesheets=$pgac_candidate - break 3 - fi - done - done - done -fi]) -DOCBOOKSTYLE=$pgac_cv_path_stylesheets -AC_SUBST([DOCBOOKSTYLE]) -if test -n "$DOCBOOKSTYLE"; then - AC_MSG_RESULT([$DOCBOOKSTYLE]) -else - AC_MSG_RESULT(no) -fi])# PGAC_PATH_DOCBOOK_STYLESHEETS - - -# PGAC_PATH_COLLATEINDEX -# ---------------------- -# Some DocBook installations provide collateindex.pl in $DOCBOOKSTYLE/bin, -# but it's not necessarily marked executable, so we can't use AC_PATH_PROG -# to check for it there. Other installations just put it in the PATH. -AC_DEFUN([PGAC_PATH_COLLATEINDEX], -[AC_REQUIRE([PGAC_PATH_DOCBOOK_STYLESHEETS])dnl -if test -n "$DOCBOOKSTYLE" -a -r "$DOCBOOKSTYLE/bin/collateindex.pl"; then - COLLATEINDEX="$DOCBOOKSTYLE/bin/collateindex.pl" - AC_SUBST([COLLATEINDEX]) -else - AC_PATH_PROG(COLLATEINDEX, collateindex.pl) -fi])# PGAC_PATH_COLLATEINDEX diff --git a/configure b/configure index de8660d00db..99d05bf0841 100755 --- a/configure +++ b/configure @@ -629,14 +629,12 @@ ac_subst_vars='LTLIBOBJS vpath_build PG_VERSION_NUM PROVE +FOP OSX XSLTPROC XMLLINT DBTOEPUB -COLLATEINDEX -DOCBOOKSTYLE have_docbook -JADE NSGMLS TCL_SHLIB_LD_LIBS TCL_SHARED_BUILD @@ -869,8 +867,7 @@ PKG_CONFIG_LIBDIR ICU_CFLAGS ICU_LIBS LDFLAGS_EX -LDFLAGS_SL -DOCBOOKSTYLE' +LDFLAGS_SL' # Initialize some variables set by options. @@ -1568,8 +1565,6 @@ Some influential environment variables: ICU_LIBS linker flags for ICU, overriding pkg-config LDFLAGS_EX extra linker flags for linking executables only LDFLAGS_SL extra linker flags for linking shared libraries only - DOCBOOKSTYLE - location of DocBook stylesheets Use these variables to override the choices made by `configure' or to help it to find libraries and programs with nonstandard names/locations. @@ -15951,48 +15946,6 @@ fi test -n "$NSGMLS" && break done -for ac_prog in openjade jade -do - # Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 -$as_echo_n "checking for $ac_word... " >&6; } -if ${ac_cv_prog_JADE+:} false; then : - $as_echo_n "(cached) " >&6 -else - if test -n "$JADE"; then - ac_cv_prog_JADE="$JADE" # Let the user override the test. -else -as_save_IFS=$IFS; IFS=$PATH_SEPARATOR -for as_dir in $PATH -do - IFS=$as_save_IFS - test -z "$as_dir" && as_dir=. - for ac_exec_ext in '' $ac_executable_extensions; do - if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then - ac_cv_prog_JADE="$ac_prog" - $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 - break 2 - fi -done - done -IFS=$as_save_IFS - -fi -fi -JADE=$ac_cv_prog_JADE -if test -n "$JADE"; then - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $JADE" >&5 -$as_echo "$JADE" >&6; } -else - { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 -$as_echo "no" >&6; } -fi - - - test -n "$JADE" && break -done - { $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook V4.2" >&5 $as_echo_n "checking for DocBook V4.2... " >&6; } @@ -16029,93 +15982,6 @@ $as_echo "$pgac_cv_check_docbook" >&6; } have_docbook=$pgac_cv_check_docbook -{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook stylesheets" >&5 -$as_echo_n "checking for DocBook stylesheets... " >&6; } -if ${pgac_cv_path_stylesheets+:} false; then : - $as_echo_n "(cached) " >&6 -else - if test -n "$DOCBOOKSTYLE"; then - pgac_cv_path_stylesheets=$DOCBOOKSTYLE -else - for pgac_prefix in /usr /usr/local /opt /sw; do - for pgac_infix in share lib; do - for pgac_postfix in \ - sgml/stylesheets/nwalsh-modular \ - sgml/stylesheets/docbook \ - sgml/stylesheets/dsssl/docbook \ - sgml/docbook-dsssl \ - sgml/docbook/dsssl/modular \ - sgml/docbook/stylesheet/dsssl/modular \ - sgml/docbook/dsssl-stylesheets \ - sgml/dsssl/docbook-dsssl-nwalsh - do - pgac_candidate=$pgac_prefix/$pgac_infix/$pgac_postfix - if test -r "$pgac_candidate/html/docbook.dsl" \ - && test -r "$pgac_candidate/print/docbook.dsl" - then - pgac_cv_path_stylesheets=$pgac_candidate - break 3 - fi - done - done - done -fi -fi - -DOCBOOKSTYLE=$pgac_cv_path_stylesheets - -if test -n "$DOCBOOKSTYLE"; then - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $DOCBOOKSTYLE" >&5 -$as_echo "$DOCBOOKSTYLE" >&6; } -else - { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 -$as_echo "no" >&6; } -fi -if test -n "$DOCBOOKSTYLE" -a -r "$DOCBOOKSTYLE/bin/collateindex.pl"; then - COLLATEINDEX="$DOCBOOKSTYLE/bin/collateindex.pl" - -else - # Extract the first word of "collateindex.pl", so it can be a program name with args. -set dummy collateindex.pl; ac_word=$2 -{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 -$as_echo_n "checking for $ac_word... " >&6; } -if ${ac_cv_path_COLLATEINDEX+:} false; then : - $as_echo_n "(cached) " >&6 -else - case $COLLATEINDEX in - [\\/]* | ?:[\\/]*) - ac_cv_path_COLLATEINDEX="$COLLATEINDEX" # Let the user override the test with a path. - ;; - *) - as_save_IFS=$IFS; IFS=$PATH_SEPARATOR -for as_dir in $PATH -do - IFS=$as_save_IFS - test -z "$as_dir" && as_dir=. - for ac_exec_ext in '' $ac_executable_extensions; do - if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then - ac_cv_path_COLLATEINDEX="$as_dir/$ac_word$ac_exec_ext" - $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 - break 2 - fi -done - done -IFS=$as_save_IFS - - ;; -esac -fi -COLLATEINDEX=$ac_cv_path_COLLATEINDEX -if test -n "$COLLATEINDEX"; then - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $COLLATEINDEX" >&5 -$as_echo "$COLLATEINDEX" >&6; } -else - { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 -$as_echo "no" >&6; } -fi - - -fi for ac_prog in dbtoepub do # Extract the first word of "$ac_prog", so it can be a program name with args. @@ -16284,6 +16150,48 @@ fi test -n "$OSX" && break done +for ac_prog in fop +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +$as_echo_n "checking for $ac_word... " >&6; } +if ${ac_cv_prog_FOP+:} false; then : + $as_echo_n "(cached) " >&6 +else + if test -n "$FOP"; then + ac_cv_prog_FOP="$FOP" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then + ac_cv_prog_FOP="$ac_prog" + $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +FOP=$ac_cv_prog_FOP +if test -n "$FOP"; then + { $as_echo "$as_me:${as_lineno-$LINENO}: result: $FOP" >&5 +$as_echo "$FOP" >&6; } +else + { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 +$as_echo "no" >&6; } +fi + + + test -n "$FOP" && break +done + # # Check for test tools diff --git a/configure.in b/configure.in index b965f476692..c36c50384f9 100644 --- a/configure.in +++ b/configure.in @@ -2117,14 +2117,12 @@ fi # Check for DocBook and tools # PGAC_PROG_NSGMLS -PGAC_PROG_JADE PGAC_CHECK_DOCBOOK(4.2) -PGAC_PATH_DOCBOOK_STYLESHEETS -PGAC_PATH_COLLATEINDEX AC_CHECK_PROGS(DBTOEPUB, dbtoepub) AC_CHECK_PROGS(XMLLINT, xmllint) AC_CHECK_PROGS(XSLTPROC, xsltproc) AC_CHECK_PROGS(OSX, [osx sgml2xml sx]) +AC_CHECK_PROGS(FOP, fop) # # Check for test tools diff --git a/doc/src/sgml/.gitignore b/doc/src/sgml/.gitignore index 8197c0140de..a74513837f1 100644 --- a/doc/src/sgml/.gitignore +++ b/doc/src/sgml/.gitignore @@ -16,15 +16,7 @@ /features-unsupported.sgml /errcodes-table.sgml /version.sgml -/bookindex.sgml -/HTML.index # Assorted byproducts from building the above /postgres.xml /INSTALL.html /INSTALL.xml -/postgres-US.aux -/postgres-US.log -/postgres-US.out -/postgres-A4.aux -/postgres-A4.log -/postgres-A4.out diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 774d35de20e..6a2cbf26ee7 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -33,9 +33,10 @@ ifndef DBTOEPUB DBTOEPUB = $(missing) dbtoepub endif -ifndef JADE -JADE = $(missing) jade +ifndef FOP +FOP = $(missing) fop endif + SGMLINCLUDE = -D . -D $(srcdir) ifndef NSGMLS @@ -57,18 +58,11 @@ endif override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)' -GENERATED_SGML = bookindex.sgml version.sgml \ +GENERATED_SGML = version.sgml \ features-supported.sgml features-unsupported.sgml errcodes-table.sgml ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) -# Sometimes we don't want this one. -ALMOSTALLSGML := $(filter-out %bookindex.sgml,$(ALLSGML)) - -ifdef DOCBOOKSTYLE -CATALOG = -c $(DOCBOOKSTYLE)/catalog -endif - # Enable some extra warnings # -wfully-tagged needed to throw a warning on missing tags # for older tool chains, 2007-08-31 @@ -77,6 +71,7 @@ endif # noisy to turn on by default, unfortunately. override SPFLAGS += -wall -wno-unused-param -wno-empty -wfully-tagged + ## ## Man pages ## @@ -90,50 +85,9 @@ man-stamp: stylesheet-man.xsl postgres.xml ## -## HTML +## common files ## -.PHONY: draft - -JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html -ifeq ($(STYLE),website) -JADE.html.call += -V website-stylesheet -endif - -# The draft target creates HTML output in draft mode, without index (for faster build). -draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl - $(MKDIR_P) html - $(JADE.html.call) -V draft-mode $< - cp $(srcdir)/stylesheet.css html/ - -oldhtml: oldhtml-stamp - -oldhtml-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl - $(MAKE) check-tabs - $(MKDIR_P) html - $(JADE.html.call) -i include-index $< - cp $(srcdir)/stylesheet.css html/ - touch $@ - -# single-page HTML -postgres.html: postgres.sgml $(ALLSGML) stylesheet.dsl - $(JADE.html.call) -V nochunks -V rootchunk -V '(define %root-filename% #f)' -V '(define use-output-dir #f)' -i include-index $< - -# single-page text -postgres.txt: postgres.html - $(LYNX) -force_html -dump -nolist $< > $@ - -HTML.index: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl - @$(MKDIR_P) html - $(JADE.html.call) -V html-index $< - -bookindex.sgml: HTML.index -ifdef COLLATEINDEX - LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g -i 'bookindex' -o $@ $< -else - @$(missing) collateindex.pl $< $@ -endif - # Technically, this should depend on Makefile.global, but then # version.sgml would need to be rebuilt after every configure run, # even in distribution tarballs. So this is cheating a bit, but it @@ -154,67 +108,6 @@ features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_package errcodes-table.sgml: $(top_srcdir)/src/backend/utils/errcodes.txt generate-errcodes-table.pl $(PERL) $(srcdir)/generate-errcodes-table.pl $< > $@ -## -## Print -## - - -# RTF to allow minor editing for hardcopy -%.rtf: %.sgml $(ALLSGML) - $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t rtf -V rtf-backend -i output-print -i include-index postgres.sgml - -# TeX -# Regular TeX and pdfTeX have slightly differing requirements, so we -# need to distinguish the path we're taking. - -JADE.tex.call = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d $(srcdir)/stylesheet.dsl -t tex -V tex-backend -i output-print -i include-index - -%-A4.tex-ps: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< - -%-US.tex-ps: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $< - -%-A4.tex-pdf: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $< - -%-US.tex-pdf: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $< - -%.dvi: %.tex-ps - @rm -f $*.aux $*.log -# multiple runs are necessary to create proper intra-document links - jadetex $< - jadetex $< - jadetex $< - -# PostScript from TeX -postgres.ps: - $(error Invalid target; use postgres-A4.ps or postgres-US.ps as targets) - -%.ps: %.dvi - dvips -o $@ $< - -postgres.pdf: - $(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets) - -%.pdf: %.tex-pdf - @rm -f $*.aux $*.log $*.out -# multiple runs are necessary to create proper intra-document links - pdfjadetex $< - pdfjadetex $< - pdfjadetex $< - -# Cancel built-in suffix rules, interfering with PS building -.SUFFIXES: - - -# This generates an XML version of the flow-object tree. It's useful -# for debugging DSSSL code, and possibly to interface to some other -# tools that can make use of this. -%.fot: %.sgml $(ALLSGML) - $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t fot -i output-print -i include-index -o $@ $< - ## ## Generation of some text files. @@ -239,19 +132,19 @@ INSTALL.html: %.html : stylesheet-text.xsl %.xml $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@ INSTALL.xml: standalone-install.sgml installation.sgml version.sgml - $(OSX) -D. -x lower $(filter-out version.sgml,$^) >$@.tmp + $(OSX) $(SGMLINCLUDE) -x lower $(filter-out version.sgml,$^) >$@.tmp $(call mangle-xml,chapter) ## -## XSLT processing +## SGML->XML conversion ## # For obscure reasons, GNU make 3.81 complains about circular dependencies # if we try to do "make all" in a VPATH build without the explicit # $(srcdir) on the postgres.sgml dependency in this rule. GNU make bug? -postgres.xml: $(srcdir)/postgres.sgml $(ALMOSTALLSGML) - $(OSX) -D. -x lower -i include-xslt-index $< >$@.tmp +postgres.xml: $(srcdir)/postgres.sgml $(ALLSGML) + $(OSX) $(SGMLINCLUDE) -x lower $< >$@.tmp $(call mangle-xml,book) define mangle-xml @@ -261,6 +154,11 @@ $(PERL) -p -e 's/\[(aacute|acirc|aelig|agrave|amp|aring|atilde|auml|bull|copy|ea rm $@.tmp endef + +## +## HTML +## + ifeq ($(STYLE),website) XSLTPROC_HTML_FLAGS += --param website.stylesheet 1 endif @@ -277,6 +175,23 @@ htmlhelp: stylesheet-hh.xsl postgres.xml $(XMLLINT) --noout --valid postgres.xml $(XSLTPROC) $(XSLTPROCFLAGS) $^ +# single-page HTML +postgres.html: stylesheet-html-nochunk.xsl postgres.xml + $(XMLLINT) --noout --valid postgres.xml + $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $^ + +# single-page text +postgres.txt: postgres.html + $(LYNX) -force_html -dump -nolist $< > $@ + + +## +## Print +## + +postgres.pdf: + $(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets) + %-A4.fo: stylesheet-fo.xsl %.xml $(XMLLINT) --noout --valid $*.xml $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $^ @@ -285,13 +200,14 @@ htmlhelp: stylesheet-hh.xsl postgres.xml $(XMLLINT) --noout --valid $*.xml $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^ -FOP = fop - -.SECONDARY: postgres-A4.fo postgres-US.fo - -%-fop.pdf: %.fo +%.pdf: %.fo $(FOP) -fo $< -pdf $@ + +## +## EPUB +## + epub: postgres.epub postgres.epub: postgres.xml $(XMLLINT) --noout --valid $< @@ -321,7 +237,7 @@ MAKEINFO = makeinfo ## # Quick syntax check without style processing -check: postgres.sgml $(ALMOSTALLSGML) check-tabs +check: postgres.sgml $(ALLSGML) check-tabs $(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $< @@ -394,7 +310,7 @@ check-tabs: # keeping the dependencies satisfied. .SECONDARY: postgres.xml $(GENERATED_SGML) HTML.index .SECONDARY: INSTALL.html INSTALL.xml -.SECONDARY: %-A4.tex-ps %-US.tex-ps %-A4.tex-pdf %-US.tex-pdf +.SECONDARY: postgres-A4.fo postgres-US.fo clean: # text --- these are shipped, but not in this directory @@ -403,11 +319,13 @@ clean: # single-page output rm -f postgres.html postgres.txt # print - rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.fot -# index - rm -f HTML.index $(GENERATED_SGML) -# XSLT - rm -f postgres.xml *.tmp htmlhelp.hhp toc.hhc index.hhk *.fo + rm -f *.fo *.pdf +# generated SGML files + rm -f $(GENERATED_SGML) +# SGML->XML conversion + rm -f postgres.xml *.tmp +# HTML Help + rm -f htmlhelp.hhp toc.hhc index.hhk # EPUB rm -f postgres.epub # Texinfo diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 57b67137b15..810d4dac401 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -20,7 +20,7 @@ - PDF or PostScript, for printing + PDF, for printing @@ -37,8 +37,8 @@ HTML documentation and man pages are part of a - standard distribution and are installed by default. PDF and - PostScript format documentation is available separately for + standard distribution and are installed by default. PDF + format documentation is available separately for download. @@ -55,6 +55,15 @@ used, but technically they are not interchangeable. + + + The PostgreSQL documentation is currently being transitioned from DocBook + SGML and DSSSL style sheets to DocBook XML and XSLT style sheets. Be + careful to look at the instructions relating to the PostgreSQL version you + are dealing with, as the procedures and required tools will change. + + + DocBook allows an author to specify the structure and content of a technical document without worrying @@ -86,11 +95,11 @@ DocBook DTD - This is the definition of DocBook itself. We currently use - version 4.2; you cannot use later or earlier versions. You - need the SGML variant of the DocBook DTD, - but to build man pages you also need the XML - variant of the same version. + This is the definition of DocBook itself. We currently use version + 4.2; you cannot use later or earlier versions. You need + the SGML and the XML variant of + the DocBook DTD of the same version. These will usually be in separate + packages. @@ -99,51 +108,35 @@ ISO 8879 character entities - These are required by DocBook but are distributed separately + These are required by DocBook SGML but are distributed separately because they are maintained by ISO. - - DocBook DSSSL Stylesheets - - - These contain the processing instructions for converting the - DocBook sources to other formats, such as - HTML. - - - - DocBook XSL Stylesheets - This is another stylesheet for converting DocBook to other - formats. We currently use this to produce man pages and - optionally HTMLHelp. You can also use this toolchain to - produce HTML or PDF output, but official PostgreSQL releases - use the DSSSL stylesheets for that. + These contain the processing instructions for converting the + DocBook sources to other formats, such as + HTML. - The minimum required version is currently 1.74.0. + The minimum required version is currently 1.77.0, but it is recommended + to use the latest available version for best results. - OpenJade + OpenSP - This is the base package of SGML processing. - It contains an SGML parser, a - DSSSL processor (that is, a program to - convert SGML to other formats using - DSSSL stylesheets), as well as a number of - related tools. Jade is now being - maintained by the OpenJade group, no longer by James Clark. + This is the base package of SGML processing. Note + that we no longer need OpenJade, the DSSSL + processor, only the OpenSP package for converting SGML to XML. @@ -166,31 +159,17 @@ Libxslt for xsltproc - This is the processing tool to use with the XSLT stylesheets - (like jade is the processing tool for DSSSL - stylesheets). + xsltproc is an XSLT processor, that is, a program to + convert XML to other formats using XSLT stylesheets. - JadeTeX + FOP - If you want to, you can also install - JadeTeX to use - TeX as a formatting backend for - Jade. - JadeTeX can create PostScript or - PDF files (the latter with bookmarks). - - - - However, the output from JadeTeX is - inferior to what you get from the RTF - backend. Particular problem areas are tables and various - artifacts of vertical and horizontal spacing. Also, there is - no opportunity to manually polish the results. + This is a program for converting, among other things, XML to PDF. @@ -206,13 +185,23 @@ here. + + You can get away with not installing DocBook XML and the DocBook XSLT + stylesheets locally, because the required files will be downloaded from the + Internet and cached locally. This may in fact be the preferred solution if + your operating system packages provide only an old version of especially + the stylesheets or if no packages are available at all. See + the option for xmllint + and xsltproc for more information. + + Installation on Fedora, RHEL, and Derivatives To install the required packages, use: -yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade +yum install docbook-dtds docbook-style-xsl fop libxslt opensp @@ -243,21 +232,18 @@ yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade textproc/libxslt - textproc/openjade + textproc/fop + + + textproc/opensp - - A number of things from /usr/ports/print - (tex, jadetex) might - also be of interest. - - To install the required packages with pkg, use: -pkg install docbook-sgml docbook-xml docbook-xsl dsssl-docbook-modular libxslt openjade +pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp @@ -282,7 +268,7 @@ pkg install docbook-sgml docbook-xml docbook-xsl dsssl-docbook-modular libxslt o available for Debian GNU/Linux. To install, simply use: -apt-get install docbook docbook-dsssl docbook-xsl libxml2-utils openjade1.3 opensp xsltproc +apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc @@ -293,7 +279,7 @@ apt-get install docbook docbook-dsssl docbook-xsl libxml2-utils openjade1.3 open If you use MacPorts, the following will get you set up: -sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade opensp +sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp @@ -311,73 +297,24 @@ sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl lib - Installing OpenJade + Installing OpenSP - - - - The installation of OpenJade offers a GNU-style - ./configure; make; make install build - process. Details can be found in the OpenJade source - distribution. In a nutshell: + + The installation of OpenSP offers a GNU-style + ./configure; make; make install build process. + Details can be found in the OpenSP source distribution. In a nutshell: -./configure --enable-default-catalog=/usr/local/share/sgml/catalog +./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install - Be sure to remember where you put the default - catalog; you will need it below. You can also leave - it off, but then you will have to set the environment variable - SGML_CATALOG_FILES to point to the file - whenever you use jade later on. - (This method is also an option if OpenJade is already - installed and you want to install the rest of the toolchain - locally.) - - - - - Some users have reported encountering a segmentation fault using - OpenJade 1.4devel to build the PDFs, with a message like: - -openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted -make: *** [postgres-A4.tex-pdf] Segmentation fault - - Downgrading to OpenJade 1.3 should get rid of this error. - - - - - - - - Additionally, you should install the files - dsssl.dtd, fot.dtd, - style-sheet.dtd, and - catalog from the - dsssl directory somewhere, perhaps into - /usr/local/share/sgml/dsssl. It's - probably easiest to copy the entire directory: - -cp -R dsssl /usr/local/share/sgml - - - - - - - Finally, create the file - /usr/local/share/sgml/catalog and add - this line to it: - -CATALOG "dsssl/catalog" - - (This is a relative path reference to the file installed in - . Be sure to adjust it - if you chose your installation layout differently.) - - - + Be sure to remember where you put the default catalog; you + will need it below. You can also leave it off, but then you will have to + set the environment variable SGML_CATALOG_FILES to point + to the file whenever you use any programs from OpenSP later on. (This + method is also an option if OpenSP is already installed and you want to + install the rest of the toolchain locally.) + @@ -451,88 +388,6 @@ perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat - - - Installing the DocBook <acronym>DSSSL</acronym> Style Sheets - - - To install the style sheets, unzip and untar the distribution and - move it to a suitable place, for example - /usr/local/share/sgml. (The archive will - automatically create a subdirectory.) - -$ gunzip docbook-dsssl-1.xx.tar.gz -$ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar - - - - - The usual catalog entry in - /usr/local/share/sgml/catalog can also be - made: - -CATALOG "docbook-dsssl-1.xx/catalog" - - Because stylesheets change rather often, and it's sometimes - beneficial to try out alternative versions, - PostgreSQL doesn't use this catalog - entry. See for - information about how to select the stylesheets instead. - - - - - Installing <productname>JadeTeX</productname> - - - To install and use JadeTeX, you will - need a working installation of TeX and - LaTeX2e, including the supported - tools and - graphics packages, - Babel, - AMS fonts and - AMS-LaTeX, the - PSNFSS extension - and companion kit of the 35 fonts, the - dvips program for generating - PostScript, the macro packages - fancyhdr, - hyperref, - minitoc, - url and - ot2enc. All of these can be found on - your friendly neighborhood - CTAN site. - The installation of the TeX base - system is far beyond the scope of this introduction. Binary - packages should be available for any system that can run - TeX. - - - - Before you can use JadeTeX with the - PostgreSQL documentation sources, you - will need to increase the size of - TeX's internal data structures. - Details on this can be found in the JadeTeX - installation instructions. - - - - Once that is finished you can install JadeTeX: - -$ gunzip jadetex-xxx.tar.gz -$ tar xf jadetex-xxx.tar -$ cd jadetex -$ make install -$ mktexlsr - - The last two need to be done as root. - - - - @@ -547,28 +402,24 @@ CATALOG "docbook-dsssl-1.xx/catalog" checking for onsgmls... onsgmls -checking for openjade... openjade checking for DocBook V4.2... yes -checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular -checking for collateindex.pl... /usr/bin/collateindex.pl +checking for dbtoepub... dbtoepub +checking for xmllint... xmllint checking for xsltproc... xsltproc checking for osx... osx +checking for fop... fop If neither onsgmls nor nsgmls were found then some of the following tests - will be skipped. nsgmls is part of the Jade - package. You can pass the environment variables - JADE and NSGMLS to configure to point + will be skipped. nsgmls is part of the OpenSP + package. You can pass the environment variable + NSGMLS to configure to point to the programs if they are not found automatically. If DocBook V4.2 was not found then you did not install - the DocBook DTD kit in a place where Jade can find it, or you have + the DocBook DTD kit in a place where OpenSP can find it, or you have not set up the catalog files correctly. See the installation hints - above. The DocBook stylesheets are looked for in a number of - relatively standard places, but if you have them some other place - then you should set the environment variable - DOCBOOKSTYLE to the location and rerun - configure afterwards. + above. @@ -602,22 +453,6 @@ checking for osx... osx default simple style use: doc/src/sgml$ make STYLE=website html - - - - - To create a proper index, the build might process several identical - stages. If you do not care about the index, and just want to - proof-read the output, use draft: - -doc/src/sgml$ make draft - - - - - To build the documentation as a single HTML page, use: - -doc/src/sgml$ make postgres.html @@ -632,330 +467,68 @@ checking for osx... osx pages. The man pages are also distributed as a tar archive, similar to the HTML version. To create the man pages, use the commands: - -cd doc/src/sgml -make man - + +doc/src/sgml$ make man + - Print Output via <application>JadeTeX</application> + PDF - If you want to use JadeTex to produce a - printable rendition of the documentation, you can use one of the - following commands: + To produce a PDF rendition of the documentation + using FOP, you can use one of the following + commands, depending on the preferred paper format: - To generate PostScript via DVI in A4 format: + For A4 format: -doc/src/sgml$ make postgres-A4.ps - - In U.S. letter format: - -doc/src/sgml$ make postgres-US.ps +doc/src/sgml$ make postgres-A4.pdf - To make a PDF: - -doc/src/sgml$ make postgres-A4.pdf - - or: + For U.S. letter format: doc/src/sgml$ make postgres-US.pdf - (Of course you can also make a PDF version - from the PostScript, but if you generate PDF - directly, it will have hyperlinks and other enhanced features.) - When using JadeTeX to build the PostgreSQL documentation, you will - probably need to increase some of TeX's internal parameters. These - can be set in the file texmf.cnf. The following - settings worked at the time of this writing: + Because the PostgreSQL documentation is fairly + big, FOP will require a significant amount of + memory. Because of that, on some systems, the build will fail with a + memory-related error message. This can usually be fixed by configuring + Java heap settings in the configuration + file ~/.foprc, for example: -hash_extra.jadetex = 200000 -hash_extra.pdfjadetex = 200000 -pool_size.jadetex = 2000000 -pool_size.pdfjadetex = 2000000 -string_vacancies.jadetex = 150000 -string_vacancies.pdfjadetex = 150000 -max_strings.jadetex = 300000 -max_strings.pdfjadetex = 300000 -save_size.jadetex = 15000 -save_size.pdfjadetex = 15000 +# FOP binary distribution +FOP_OPTS='-Xmx1000m' +# Debian +JAVA_ARGS='-Xmx1000m' +# Red Hat +ADDITIONAL_FLAGS='-Xmx1000m' + There is a minimum amount of memory that is required, and to some extent + more memory appears to make things a bit faster. On systems with very + little memory (less than 1 GB), the build will either be very slow due to + swapping or will not work at all. - - - - Overflow Text - - Occasionally text is too wide for the printed margins, and in - extreme cases, too wide for the printed page, e.g. non-wrapped - text, wide tables. Overly wide text generates Overfull - hbox messages in the TeX log output file, e.g. - postgres-US.log or postgres-A4.log. - There are 72 points in an inch so anything reported as over 72 - points too wide will probably not fit on the printed page (assuming - one inch margins). To find the SGML text - causing the overflow, find the first page number mentioned above - the overflow message, e.g. [50 ###] (page 50), and - look at the page after that (e.g. page 51) in the PDF - file to see the overflow text and adjust the SGML - accordingly. + Other XSL-FO processors can also be used manually, but the automated build + process only supports FOP. - - Print Output via <acronym>RTF</acronym> - - - You can also create a printable version of the PostgreSQL - documentation by converting it to RTF and - applying minor formatting corrections using an office suite. - Depending on the capabilities of the particular office suite, you - can then convert the documentation to PostScript of - PDF. The procedure below illustrates this - process using Applixware. - - - - - It appears that current versions of the PostgreSQL documentation - trigger some bug in or exceed the size limit of OpenJade. If the - build process of the RTF version hangs for a - long time and the output file still has size 0, then you might have - hit that problem. (But keep in mind that a normal build takes 5 - to 10 minutes, so don't abort too soon.) - - - - - <productname>Applixware</productname> <acronym>RTF</acronym> Cleanup - - - OpenJade omits specifying a default - style for body text. In the past, this undiagnosed problem led to - a long process of table of contents generation. However, with - great help from the Applixware folks - the symptom was diagnosed and a workaround is available. - - - - - Generate the RTF version by typing: - -doc/src/sgml$ make postgres.rtf - - - - - - - Repair the RTF file to correctly specify all styles, in - particular the default style. If the document contains - refentry sections, one must also replace - formatting hints which tie a preceding paragraph to the current - paragraph, and instead tie the current paragraph to the - following one. A utility, fixrtf, is - available in doc/src/sgml to accomplish - these repairs: - -doc/src/sgml$ ./fixrtf --refentry postgres.rtf - - - - - The script adds {\s0 Normal;} as the zeroth - style in the document. According to - Applixware, the RTF standard would - prohibit adding an implicit zeroth style, though Microsoft Word - happens to handle this case. For repairing - refentry sections, the script replaces - \keepn tags with \keep. - - - - - - Open a new document in Applixware Words and - then import the RTF file. - - - - - - Generate a new table of contents (ToC) using - Applixware. - - - - - - Select the existing ToC lines, from the beginning of the first - character on the first line to the last character of the last - line. - - - - - - Build a new ToC using - ToolsBook - BuildingCreate Table of - Contents. Select the first three - levels of headers for inclusion in the ToC. This will replace - the existing lines imported in the RTF with a native - Applixware ToC. - - - - - - Adjust the ToC formatting by using - FormatStyle, - selecting each of the three ToC styles, and adjusting the - indents for First and - Left. Use the following values: - - - - - - Style - First Indent (inches) - Left Indent (inches) - - - - - - TOC-Heading 1 - 0.4 - 0.4 - - - - TOC-Heading 2 - 0.8 - 0.8 - - - - TOC-Heading 3 - 1.2 - 1.2 - - - - - - - - - - - - Work through the document to: - - - - - Adjust page breaks. - - - - - - Adjust table column widths. - - - - - - - - - Replace the right-justified page numbers in the Examples and - Figures portions of the ToC with correct values. This only takes - a few minutes. - - - - - - Delete the index section from the document if it is empty. - - - - - - Regenerate and adjust the table of contents. - - - - - - Select the ToC field. - - - - - - Select ToolsBook - BuildingCreate Table of - Contents. - - - - - - Unbind the ToC by selecting - ToolsField - EditingUnprotect. - - - - - - Delete the first line in the ToC, which is an entry for the - ToC itself. - - - - - - - - Save the document as native Applixware - Words format to allow easier last minute editing - later. - - - - - - Print the document - to a file in PostScript format. - - - - - Plain Text Files diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 6782f07aea6..e2aa1d2a0e1 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -193,7 +193,6 @@ - - - - - - - diff --git a/doc/src/sgml/fixrtf b/doc/src/sgml/fixrtf deleted file mode 100755 index 31cb5f85c0f..00000000000 --- a/doc/src/sgml/fixrtf +++ /dev/null @@ -1,46 +0,0 @@ -#!/bin/sh -# fixrtf - -# doc/src/sgml/fixrtf - -# Repair (slightly) damaged RTF generated by jade -# Applixware wants the s0 stylesheet defined, whereas -# M$Word does not care about it. -# (c) 2001, Thomas Lockhart, PostgreSQL Inc. - -flist="" -RPAT="" -for i in $@ ; do - case "$i" in - -r|--refentry) - RPAT='-e s/\\\keepn/\\\keep/g' - ;; - -?|--help) - echo "$0 [--refentry] ..." - exit 0 - ;; - -*) - echo "Command $i not recognized" - $0 --help - exit 1 - ;; - *) - flist="$flist $i" - esac -done - -if [ "$flist" = "" ] ; then - flist=*.rtf -fi - -for f in $flist ; do - echo -n "Repairing '$f' ..." - if [ -r $f ] ; then - (sed -e 's/{\\stylesheet{\\s1/{\\stylesheet{\\s0 Normal 0;}{\\s1/g' $RPAT $f > $f.new \ - && mv -f $f.new $f \ - && echo " done") || echo " failed" - else - echo " file not found" - fi -done -exit diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml index 7a9cf7f893d..b95b04f5d8e 100644 --- a/doc/src/sgml/install-windows.sgml +++ b/doc/src/sgml/install-windows.sgml @@ -517,16 +517,6 @@ $ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib'; - - DocBook DSSSL 1.79 - - Download from - - and uncompress in the subdirectory - docbook-dsssl-1.79. - - - ISO character entities diff --git a/doc/src/sgml/jadetex.cfg b/doc/src/sgml/jadetex.cfg deleted file mode 100644 index 875598f1514..00000000000 --- a/doc/src/sgml/jadetex.cfg +++ /dev/null @@ -1,89 +0,0 @@ -% doc/src/sgml/jadetex.cfg -% -% This file redefines \FlowObjectSetup and some related macros to greatly -% reduce the number of control sequence names created, and also to avoid -% creation of many useless hyperlink anchors (bookmarks) in PDF files. -% -% The original coding of \FlowObjectSetup defined a control sequence x@LABEL -% for pretty nearly every flow object in the file, whether that object was -% cross-referenced or not. Worse yet, it created a hyperlink anchor for -% every such object, which not only bloated the output PDF with useless -% anchors but consumed an additional control sequence name per anchor. -% This results in overrunning TeX's limited-size string pool. -% -% To fix, extend \PageLabel's already-existing mechanism whereby a p@LABEL -% control sequence is filled in only for labels that are referenced by at -% least one \Pageref call. We now also fill in p@LABEL for labels that are -% referenced by a \Link. Then, we can drop x@LABEL entirely, and use p@LABEL -% to control emission of both a hyperlink anchor and a page-number label. -% Now, both of those things are emitted for all and only the flow objects -% that have either a hyperlink reference or a page-number reference. -% We consume about one control sequence name per flow object plus one per -% referenced object, which is a lot better than three per flow object. -% -% (With a more invasive patch, we could track the need for an anchor and a -% page-number label separately, but that would probably require two control -% sequences for every flow object. Besides, many objects that have one kind -% of reference will have the other one too; that's certainly true for objects -% referenced in either the TOC or the index, for example.) -% -% -% In addition to checking p@LABEL not x@LABEL, this version of \FlowObjectSetup -% is fixed to clear \Label and \Element whether or not it emits an anchor -% and page label. Failure to do that seems to explain some pre-existing bugs -% in which certain SGML constructs weren't correctly cross-referenced. -% -\def\FlowObjectSetup#1{% -\ifDoFOBSet - \ifLabelElements - \ifx\Label\@empty\let\Label\Element\fi - \fi - \ifx\Label\@empty\else - \expandafter\ifx\csname p@\Label\endcsname\relax - \else - \bgroup - \ifNestedLink - \else - \hyper@anchorstart{\Label}\hyper@anchorend - \PageLabel{\Label}% - \fi - \egroup - \fi - \let\Label\@empty - \let\Element\@empty - \fi -\fi -} -% -% Adjust \PageLabel so that the p@NAME control sequence acquires a correct -% value immediately; this seems to be needed to avoid scenarios wherein -% additional TeX runs are needed to reach a stable state of the .aux file. -% -\def\PageLabel#1{% - \@bsphack - \expandafter\ifx\csname p@#1\endcsname\relax - \else - \protected@write\@auxout{}% - {\string\pagelabel{#1}{\thepage}}% - % Ensure the p@NAME control sequence acquires correct value immediately - \expandafter\xdef\csname p@#1\endcsname{\thepage}% - \fi - \@esphack} -% -% In \Link, add code to emit an aux-file entry if the p@NAME sequence isn't -% defined. Much as in \@Setref, this ensures we'll process the referenced -% item correctly on the next TeX run. -% -\def\Link#1{% - \begingroup - \SetupICs{#1}% - \ifx\Label\@empty\let\Label\Element\fi -% \typeout{Made a Link at \the\inputlineno, to \Label}% - \hyper@linkstart{\LinkType}{\Label}% - \NestedLinktrue - % If p@NAME control sequence isn't defined, emit dummy def to aux file - % so it will get defined properly on next run, much as in \@Setref - \expandafter\ifx\csname p@\Label\endcsname\relax - \immediate\write\@mainaux{\string\pagelabel{\Label}{qqq}}% - \fi -} diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 4e169d1b189..8a3bfc9b0d3 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -277,7 +277,6 @@ &biblio; - - ]]> + diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl new file mode 100644 index 00000000000..72fac1e806f --- /dev/null +++ b/doc/src/sgml/stylesheet-html-common.xsl @@ -0,0 +1,266 @@ + + +%common.entities; +]> + + + + + + + +pgsql-docs@postgresql.org +2 + + + + + + + + + + + + + + , + + + + + + + + + + ISBN + + + + + + + + + +appendix toc,title +article/appendix nop +article toc,title +book toc,title +chapter toc,title +part toc,title +preface toc,title +qandadiv toc +qandaset toc +reference toc,title +sect1 toc +sect2 toc +sect3 toc +sect4 toc +sect5 toc +section toc +set toc,title + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +

+ + + + + + + + + + + + +

+ + + + + + +
+

+ + + +

+
+ + + + + + + +
+
+ + + + + + +
+

+ + + +

+
+ + + + + + + +
+
+ + + + + + + + + + + +
+ + + + + + + + + + +
+ + + + + + +

+ +

+ +
+ + + + + + + +
+
+ + + + + + + + + + + + + + | + + + + + + + + + + + diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl new file mode 100644 index 00000000000..ffd2012e918 --- /dev/null +++ b/doc/src/sgml/stylesheet-html-nochunk.xsl @@ -0,0 +1,12 @@ + + + + + + + + + diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl deleted file mode 100644 index 05cab9a5f3d..00000000000 --- a/doc/src/sgml/stylesheet.dsl +++ /dev/null @@ -1,798 +0,0 @@ - - - - - - -]]> - - -]]> - -]> - - - - - - - - - -(define draft-mode #f) - -(define pgsql-docs-list "pgsql-docs@postgresql.org") - -;; Don't show manpage volume numbers -(define %refentry-xref-manvolnum% #f) - -;; Don't use graphics for callouts. (We could probably do that, but -;; it needs extra work.) -(define %callout-graphics% #f) - -;; Show comments during the development stage. -(define %show-comments% draft-mode) - -;; Don't append period if run-in title ends with any of these -;; characters. We had to add the colon here. This is fixed in -;; stylesheets version 1.71, so it can be removed sometime. -(define %content-title-end-punct% - '(#\. #\! #\? #\:)) - -;; No automatic punctuation after honorific name parts -(define %honorific-punctuation% "") - -;; Change display of some elements -(element command ($mono-seq$)) -(element envar ($mono-seq$)) -(element lineannotation ($italic-seq$)) -(element literal ($mono-seq$)) -(element option ($mono-seq$)) -(element parameter ($mono-seq$)) -(element structfield ($mono-seq$)) -(element structname ($mono-seq$)) -(element symbol ($mono-seq$)) -(element token ($mono-seq$)) -(element type ($mono-seq$)) -(element varname ($mono-seq$)) -(element (programlisting emphasis) ($bold-seq$)) ;; to highlight sections of code - -;; Special support for Tcl synopses -(element optional - (if (equal? (attribute-string (normalize "role")) "tcl") - (make sequence - (literal "?") - ($charseq$) - (literal "?")) - (make sequence - (literal %arg-choice-opt-open-str%) - ($charseq$) - (literal %arg-choice-opt-close-str%)))) - -;; Avoid excessive cross-reference labels -(define (auto-xref-indirect? target ancestor) - (cond -; ;; Always add indirect references to another book -; ((member (gi ancestor) (book-element-list)) -; #t) - ;; Add indirect references to the section or component a block - ;; is in iff chapters aren't autolabelled. (Otherwise "Figure 1-3" - ;; is sufficient) - ((and (member (gi target) (block-element-list)) - (not %chapter-autolabel%)) - #t) - ;; Add indirect references to the component a section is in if - ;; the sections are not autolabelled - ((and (member (gi target) (section-element-list)) - (member (gi ancestor) (component-element-list)) - (not %section-autolabel%)) - #t) - (else #f))) - - -;; Bibliography things - -;; Use the titles of bibliography entries in cross-references -(define biblio-xref-title #t) - -;; Process bibliography entry components in the order shown below, not -;; in the order they appear in the document. (I suppose this should -;; be made to fit some publishing standard.) -(define %biblioentry-in-entry-order% #f) - -(define (biblioentry-inline-elements) - (list - (normalize "author") - (normalize "authorgroup") - (normalize "title") - (normalize "subtitle") - (normalize "volumenum") - (normalize "edition") - (normalize "othercredit") - (normalize "contrib") - (normalize "editor") - (normalize "publishername") - (normalize "confgroup") - (normalize "publisher") - (normalize "isbn") - (normalize "issn") - (normalize "pubsnumber") - (normalize "date") - (normalize "pubdate") - (normalize "pagenums") - (normalize "bibliomisc"))) - -(mode biblioentry-inline-mode - - (element confgroup - (make sequence - (literal "Proc. ") - (next-match))) - - (element isbn - (make sequence - (literal "ISBN ") - (process-children))) - - (element issn - (make sequence - (literal "ISSN ") - (process-children)))) - - -;; The rules in the default stylesheet for productname format it as a -;; paragraph. This may be suitable for productname directly within -;; *info, but it's nonsense when productname is used inline, as we do. -(mode book-titlepage-recto-mode - (element (para productname) ($charseq$))) -(mode book-titlepage-verso-mode - (element (para productname) ($charseq$))) -;; Add more here if needed... - - -;; Replace a sequence of whitespace in a string by a single space -(define (normalize-whitespace str #!optional (whitespace '(#\space #\U-000D))) - (let loop ((characters (string->list str)) - (result '()) - (prev-was-space #f)) - (if (null? characters) - (list->string (reverse result)) - (let ((c (car characters)) - (rest (cdr characters))) - (if (member c whitespace) - (if prev-was-space - (loop rest result #t) - (loop rest (cons #\space result) #t)) - (loop rest (cons c result) #f)))))) - - - - -string (time) #t))))) - - -;; Block elements are allowed in PARA in DocBook, but not in P in -;; HTML. With %fix-para-wrappers% turned on, the stylesheets attempt -;; to avoid putting block elements in HTML P tags by outputting -;; additional end/begin P pairs around them. -(define %fix-para-wrappers% #t) - -;; ...but we need to do some extra work to make the above apply to PRE -;; as well. (mostly pasted from dbverb.dsl) -(define ($verbatim-display$ indent line-numbers?) - (let ((content (make element gi: "PRE" - attributes: (list - (list "CLASS" (gi))) - (if (or indent line-numbers?) - ($verbatim-line-by-line$ indent line-numbers?) - (process-children))))) - (if %shade-verbatim% - (make element gi: "TABLE" - attributes: ($shade-verbatim-attr$) - (make element gi: "TR" - (make element gi: "TD" - content))) - (make sequence - (para-check) - content - (para-check 'restart))))) - -;; ...and for notes. -(element note - (make sequence - (para-check) - ($admonition$) - (para-check 'restart))) - -;;; XXX The above is very ugly. It might be better to run 'tidy' on -;;; the resulting *.html files. - - -;; Format multiple terms in varlistentry vertically, instead -;; of comma-separated. -(element (varlistentry term) - (make sequence - (process-children-trim) - (if (not (last-sibling?)) - (make empty-element gi: "BR") - (empty-sosofo)))) - - -;; Customization of header -;; - make title a link to the home page -;; - add tool tips to Prev/Next links -;; - add Up link -;; (overrides dbnavig.dsl) -(define (default-header-nav-tbl-noff elemnode prev next prevsib nextsib) - (let* ((r1? (nav-banner? elemnode)) - (r1-sosofo (make element gi: "TR" - (make element gi: "TH" - attributes: (list - (list "COLSPAN" "4") - (list "ALIGN" "center") - (list "VALIGN" "bottom")) - (make element gi: "A" - attributes: (list - (list "HREF" (href-to (nav-home elemnode)))) - (nav-banner elemnode))))) - (r2? (or (not (node-list-empty? prev)) - (not (node-list-empty? next)) - (nav-context? elemnode))) - (r2-sosofo (make element gi: "TR" - (make element gi: "TD" - attributes: (list - (list "WIDTH" "10%") - (list "ALIGN" "left") - (list "VALIGN" "top")) - (if (node-list-empty? prev) - (make entity-ref name: "nbsp") - (make element gi: "A" - attributes: (list - (list "TITLE" (element-title-string prev)) - (list "HREF" - (href-to - prev)) - (list "ACCESSKEY" - "P")) - (gentext-nav-prev prev)))) - (make element gi: "TD" - attributes: (list - (list "WIDTH" "10%") - (list "ALIGN" "left") - (list "VALIGN" "top")) - (if (nav-up? elemnode) - (nav-up elemnode) - (nav-home-link elemnode))) - (make element gi: "TD" - attributes: (list - (list "WIDTH" "60%") - (list "ALIGN" "center") - (list "VALIGN" "bottom")) - (nav-context elemnode)) - (make element gi: "TD" - attributes: (list - (list "WIDTH" "20%") - (list "ALIGN" "right") - (list "VALIGN" "top")) - (if (node-list-empty? next) - (make entity-ref name: "nbsp") - (make element gi: "A" - attributes: (list - (list "TITLE" (element-title-string next)) - (list "HREF" - (href-to - next)) - (list "ACCESSKEY" - "N")) - (gentext-nav-next next))))))) - (if (or r1? r2?) - (make element gi: "DIV" - attributes: '(("CLASS" "NAVHEADER")) - (make element gi: "TABLE" - attributes: (list - (list "SUMMARY" "Header navigation table") - (list "WIDTH" %gentext-nav-tblwidth%) - (list "BORDER" "0") - (list "CELLPADDING" "0") - (list "CELLSPACING" "0")) - (if r1? r1-sosofo (empty-sosofo)) - (if r2? r2-sosofo (empty-sosofo))) - (make empty-element gi: "HR" - attributes: (list - (list "ALIGN" "LEFT") - (list "WIDTH" %gentext-nav-tblwidth%)))) - (empty-sosofo)))) - - -;; Put index "quicklinks" (A | B | C | ...) at the top of the bookindex page. - -(element index - (let ((preamble (node-list-filter-by-not-gi - (children (current-node)) - (list (normalize "indexentry")))) - (indexdivs (node-list-filter-by-gi - (children (current-node)) - (list (normalize "indexdiv")))) - (entries (node-list-filter-by-gi - (children (current-node)) - (list (normalize "indexentry"))))) - (html-document - (with-mode head-title-mode - (literal (element-title-string (current-node)))) - (make element gi: "DIV" - attributes: (list (list "CLASS" (gi))) - ($component-separator$) - ($component-title$) - (if (node-list-empty? indexdivs) - (empty-sosofo) - (make element gi: "P" - attributes: (list (list "CLASS" "INDEXDIV-QUICKLINKS")) - (with-mode indexdiv-quicklinks-mode - (process-node-list indexdivs)))) - (process-node-list preamble) - (if (node-list-empty? entries) - (empty-sosofo) - (make element gi: "DL" - (process-node-list entries))))))) - - -(mode indexdiv-quicklinks-mode - (element indexdiv - (make sequence - (make element gi: "A" - attributes: (list (list "HREF" (href-to (current-node)))) - (element-title-sosofo)) - (if (not (last-sibling?)) - (literal " | ") - (literal ""))))) - - -;; Changed to strip and normalize index term content (overrides -;; dbindex.dsl) -(define (htmlindexterm) - (let* ((attr (gi (current-node))) - (content (data (current-node))) - (string (strip (normalize-whitespace content))) ;; changed - (sortas (attribute-string (normalize "sortas")))) - (make sequence - (make formatting-instruction data: attr) - (if sortas - (make sequence - (make formatting-instruction data: "[") - (make formatting-instruction data: sortas) - (make formatting-instruction data: "]")) - (empty-sosofo)) - (make formatting-instruction data: " ") - (make formatting-instruction data: string) - (htmlnewline)))) - - -]]> - - - - - (string->number (attribute-string (normalize "columns"))) 0) - (string->number (attribute-string (normalize "columns"))) - 1) - 1)) - (members (select-elements (children (current-node)) (normalize "member")))) - (cond - ((equal? type (normalize "inline")) - (if (equal? (gi (parent (current-node))) - (normalize "para")) - (process-children) - (make paragraph - space-before: %para-sep% - space-after: %para-sep% - start-indent: (inherited-start-indent)))) - ((equal? type (normalize "vert")) - (my-simplelist-vert members)) - ((equal? type (normalize "horiz")) - (simplelist-table 'row cols members))))) - -(element member - (let ((type (inherited-attribute-string (normalize "type")))) - (cond - ((equal? type (normalize "inline")) - (make sequence - (process-children) - (if (not (last-sibling?)) - (literal ", ") - (literal "")))) - ((equal? type (normalize "vert")) - (make paragraph - space-before: 0pt - space-after: 0pt)) - ((equal? type (normalize "horiz")) - (make paragraph - quadding: 'start - (process-children)))))) - - -;; Jadetex doesn't handle links to the content of tables, so -;; indexterms that point to table entries will go nowhere. We fix -;; this by pointing the index entry to the table itself instead, which -;; should be equally useful in practice. - -(define (find-parent-table nd) - (let ((table (ancestor-member nd ($table-element-list$)))) - (if (node-list-empty? table) - nd - table))) - -;; (The function below overrides the one in print/dbindex.dsl.) - -(define (indexentry-link nd) - (let* ((id (attribute-string (normalize "role") nd)) - (prelim-target (find-indexterm id)) - (target (find-parent-table prelim-target)) - (preferred (not (node-list-empty? - (select-elements (children (current-node)) - (normalize "emphasis"))))) - (sosofo (if (node-list-empty? target) - (literal "?") - (make link - destination: (node-list-address target) - (with-mode toc-page-number-mode - (process-node-list target)))))) - (if preferred - (make sequence - font-weight: 'bold - sosofo) - sosofo))) - - -;; By default, the part and reference title pages get wrong page -;; numbers: The first title page gets roman numerals carried over from -;; preface/toc -- we want Arabic numerals. We also need to make sure -;; that page-number-restart is set of #f explicitly, because otherwise -;; it will carry over from the previous component, which is not good. -;; -;; (This looks worse than it is. It's copied from print/dbttlpg.dsl -;; and common/dbcommon.dsl and modified in minor detail.) - -(define (first-part?) - (let* ((book (ancestor (normalize "book"))) - (nd (ancestor-member (current-node) - (append - (component-element-list) - (division-element-list)))) - (bookch (children book))) - (let loop ((nl bookch)) - (if (node-list-empty? nl) - #f - (if (equal? (gi (node-list-first nl)) (normalize "part")) - (if (node-list=? (node-list-first nl) nd) - #t - #f) - (loop (node-list-rest nl))))))) - -(define (first-reference?) - (let* ((book (ancestor (normalize "book"))) - (nd (ancestor-member (current-node) - (append - (component-element-list) - (division-element-list)))) - (bookch (children book))) - (let loop ((nl bookch)) - (if (node-list-empty? nl) - #f - (if (equal? (gi (node-list-first nl)) (normalize "reference")) - (if (node-list=? (node-list-first nl) nd) - #t - #f) - (loop (node-list-rest nl))))))) - - -(define (part-titlepage elements #!optional (side 'recto)) - (let ((nodelist (titlepage-nodelist - (if (equal? side 'recto) - (reference-titlepage-recto-elements) - (reference-titlepage-verso-elements)) - elements)) - ;; partintro is a special case... - (partintro (node-list-first - (node-list-filter-by-gi elements (list (normalize "partintro")))))) - (if (part-titlepage-content? elements side) - (make simple-page-sequence - page-n-columns: %titlepage-n-columns% - ;; Make sure that page number format is correct. - page-number-format: ($page-number-format$) - ;; Make sure that the page number is set to 1 if this is the - ;; first part in the book - page-number-restart?: (first-part?) - input-whitespace-treatment: 'collapse - use: default-text-style - - ;; This hack is required for the RTF backend. If an external-graphic - ;; is the first thing on the page, RTF doesn't seem to do the right - ;; thing (the graphic winds up on the baseline of the first line - ;; of the page, left justified). This "one point rule" fixes - ;; that problem. - (make paragraph - line-spacing: 1pt - (literal "")) - - (let loop ((nl nodelist) (lastnode (empty-node-list))) - (if (node-list-empty? nl) - (empty-sosofo) - (make sequence - (if (or (node-list-empty? lastnode) - (not (equal? (gi (node-list-first nl)) - (gi lastnode)))) - (part-titlepage-before (node-list-first nl) side) - (empty-sosofo)) - (cond - ((equal? (gi (node-list-first nl)) (normalize "subtitle")) - (part-titlepage-subtitle (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "title")) - (part-titlepage-title (node-list-first nl) side)) - (else - (part-titlepage-default (node-list-first nl) side))) - (loop (node-list-rest nl) (node-list-first nl))))) - - (if (and %generate-part-toc% - %generate-part-toc-on-titlepage% - (equal? side 'recto)) - (make display-group - (build-toc (current-node) - (toc-depth (current-node)))) - (empty-sosofo)) - - ;; PartIntro is a special case - (if (and (equal? side 'recto) - (not (node-list-empty? partintro)) - %generate-partintro-on-titlepage%) - ($process-partintro$ partintro #f) - (empty-sosofo))) - - (empty-sosofo)))) - - -(define (reference-titlepage elements #!optional (side 'recto)) - (let ((nodelist (titlepage-nodelist - (if (equal? side 'recto) - (reference-titlepage-recto-elements) - (reference-titlepage-verso-elements)) - elements)) - ;; partintro is a special case... - (partintro (node-list-first - (node-list-filter-by-gi elements (list (normalize "partintro")))))) - (if (reference-titlepage-content? elements side) - (make simple-page-sequence - page-n-columns: %titlepage-n-columns% - ;; Make sure that page number format is correct. - page-number-format: ($page-number-format$) - ;; Make sure that the page number is set to 1 if this is the - ;; first part in the book - page-number-restart?: (first-reference?) - input-whitespace-treatment: 'collapse - use: default-text-style - - ;; This hack is required for the RTF backend. If an external-graphic - ;; is the first thing on the page, RTF doesn't seem to do the right - ;; thing (the graphic winds up on the baseline of the first line - ;; of the page, left justified). This "one point rule" fixes - ;; that problem. - (make paragraph - line-spacing: 1pt - (literal "")) - - (let loop ((nl nodelist) (lastnode (empty-node-list))) - (if (node-list-empty? nl) - (empty-sosofo) - (make sequence - (if (or (node-list-empty? lastnode) - (not (equal? (gi (node-list-first nl)) - (gi lastnode)))) - (reference-titlepage-before (node-list-first nl) side) - (empty-sosofo)) - (cond - ((equal? (gi (node-list-first nl)) (normalize "author")) - (reference-titlepage-author (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "authorgroup")) - (reference-titlepage-authorgroup (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "corpauthor")) - (reference-titlepage-corpauthor (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "editor")) - (reference-titlepage-editor (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "subtitle")) - (reference-titlepage-subtitle (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "title")) - (reference-titlepage-title (node-list-first nl) side)) - (else - (reference-titlepage-default (node-list-first nl) side))) - (loop (node-list-rest nl) (node-list-first nl))))) - - (if (and %generate-reference-toc% - %generate-reference-toc-on-titlepage% - (equal? side 'recto)) - (make display-group - (build-toc (current-node) - (toc-depth (current-node)))) - (empty-sosofo)) - - ;; PartIntro is a special case - (if (and (equal? side 'recto) - (not (node-list-empty? partintro)) - %generate-partintro-on-titlepage%) - ($process-partintro$ partintro #f) - (empty-sosofo))) - - (empty-sosofo)))) - -]]> - - - - - - diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl index e36e8cc5cc7..c9fb7b225cf 100644 --- a/doc/src/sgml/stylesheet.xsl +++ b/doc/src/sgml/stylesheet.xsl @@ -1,8 +1,4 @@ - -%common.entities; -]> + - - -pgsql-docs@postgresql.org -2 @@ -34,252 +27,6 @@ - - - - - - - - - - - - , - - - - - - - - - - ISBN - - - - - - - - - -appendix toc,title -article/appendix nop -article toc,title -book toc,title -chapter toc,title -part toc,title -preface toc,title -qandadiv toc -qandaset toc -reference toc,title -sect1 toc -sect2 toc -sect3 toc -sect4 toc -sect5 toc -section toc -set toc,title - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -

- - - - - - - - - - - - -

- - - - - - -
-

- - - -

-
- - - - - - - -
-
- - - - - - -
-

- - - -

-
- - - - - - - -
-
- - - - - - - - - - - -
- - - - - - - - - - -
- - - - - - -

- -

- -
- - - - - - - -
-
- - - - - - - - - - - - - - | - - - - - - - - - - -