From 510074f9f0131a04322d6a3d2a51c87e6db243f9 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Thu, 6 Apr 2017 22:03:52 -0400 Subject: [PATCH] Remove use of Jade and DSSSL All documentation is now built using XSLT. Remove all references to Jade, DSSSL, also JadeTex and some other outdated tooling. For chunked HTML builds, this changes nothing, but removes the transitional "oldhtml" target. The single-page HTML build is ported over to XSLT. For PDF builds, this removes the JadeTex builds and moves the FOP builds in their place. --- config/docbook.m4 | 62 -- configure | 180 ++--- configure.in | 4 +- doc/src/sgml/.gitignore | 8 - doc/src/sgml/Makefile | 174 ++--- doc/src/sgml/docguide.sgml | 619 +++--------------- doc/src/sgml/filelist.sgml | 12 - doc/src/sgml/fixrtf | 46 -- doc/src/sgml/install-windows.sgml | 10 - doc/src/sgml/jadetex.cfg | 89 --- doc/src/sgml/postgres.sgml | 3 +- doc/src/sgml/stylesheet-html-common.xsl | 266 ++++++++ doc/src/sgml/stylesheet-html-nochunk.xsl | 12 + doc/src/sgml/stylesheet.dsl | 798 ----------------------- doc/src/sgml/stylesheet.xsl | 255 +------- src/Makefile.global.in | 5 +- 16 files changed, 468 insertions(+), 2075 deletions(-) delete mode 100755 doc/src/sgml/fixrtf delete mode 100644 doc/src/sgml/jadetex.cfg create mode 100644 doc/src/sgml/stylesheet-html-common.xsl create mode 100644 doc/src/sgml/stylesheet-html-nochunk.xsl delete mode 100644 doc/src/sgml/stylesheet.dsl diff --git a/config/docbook.m4 b/config/docbook.m4 index 4304fa7ea1..d550309353 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 de8660d00d..99d05bf084 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 b965f47669..c36c50384f 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 8197c0140d..a74513837f 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 774d35de20..6a2cbf26ee 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,12 +200,13 @@ htmlhelp: stylesheet-hh.xsl postgres.xml $(XMLLINT) --noout --valid $*.xml $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^ -FOP = fop +%.pdf: %.fo + $(FOP) -fo $< -pdf $@ -.SECONDARY: postgres-A4.fo postgres-US.fo -%-fop.pdf: %.fo - $(FOP) -fo $< -pdf $@ +## +## EPUB +## epub: postgres.epub postgres.epub: postgres.xml @@ -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 57b67137b1..810d4dac40 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 + DocBook XSL 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. - - 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: - -doc/src/sgml$ make postgres-A4.ps - - In U.S. letter format: + For A4 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 6782f07aea..e2aa1d2a0e 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 31cb5f85c0..0000000000 --- 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 7a9cf7f893..b95b04f5d8 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 875598f151..0000000000 --- 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 4e169d1b18..8a3bfc9b0d 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 0000000000..72fac1e806 --- /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 0000000000..ffd2012e91 --- /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 05cab9a5f3..0000000000 --- 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 e36e8cc5cc..c9fb7b225c 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 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -

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

- - - - - - -
-

- - - -

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

- - - -

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

- -

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