diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index e510b84944..c663fbe3aa 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -8,7 +8,7 @@ # # # IDENTIFICATION -# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.42 2001/10/09 18:45:59 petere Exp $ +# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.43 2001/11/08 23:46:29 petere Exp $ # #---------------------------------------------------------------------------- @@ -26,7 +26,7 @@ endif ifndef JADE JADE = jade endif -SGMLINCLUDE = -D $(srcdir) -D $(srcdir)/ref -D $(srcdir)/../graphics +SGMLINCLUDE = -D $(srcdir) -D $(srcdir)/ref ifndef NSGMLS NSGMLS = nsgmls @@ -36,6 +36,9 @@ ifndef SGMLSPL SGMLSPL = sgmlspl endif +CONVERT = convert +EPSTOPDF = epstopdf + # docbook2man generates man pages from docbook refentry source code. @@ -89,9 +92,8 @@ $(addsuffix .html, $(ALLBOOKS)): %.html: %.sgml $(ALLSGML) stylesheet.dsl $(JADE.html) book-decl.sgml $< ln -sf index.html $@ -tutorial.html: clientserver.gif programmer.html: catalogs.gif connections.gif -postgres.html: clientserver.gif catalogs.gif connections.gif +postgres.html: catalogs.gif connections.gif COLLATEINDEX = $(PERL) $(DOCBOOKSTYLE)/bin/collateindex.pl -f -g -t 'Index' @@ -117,9 +119,12 @@ endif $(addsuffix .rtf, $(ALLBOOKS)): %.rtf: %.sgml $(ALLSGML) stylesheet.dsl $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) -c $(CATALOG) -d stylesheet.dsl -t rtf -V rtf-backend -i output-print book-decl.sgml $< -# TeX and DVI -$(addsuffix .tex, $(ALLBOOKS)): %.tex: %.sgml $(ALLSGML) stylesheet.dsl - $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) -c $(CATALOG) -d stylesheet.dsl -t tex -V tex-backend -i output-print book-decl.sgml $< +# TeX +# Regular TeX and pdfTeX have slightly differing requirements, so we +# need to distinguish the path we're taking. + +$(addsuffix .tex-ps, $(ALLBOOKS)): %.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl + $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) -c $(CATALOG) -d stylesheet.dsl -t tex -V tex-backend -i output-print -V texdvi-output -o $@ book-decl.sgml $< # TeX transforms '--' into en-dashes. This hack should go away when # OpenJade is fixed (ver. 1.4?) $(PERL) -pi -e 's/\-\-/\\mbox{}-\\mbox{}-\\mbox{}/g' $@ @@ -127,7 +132,19 @@ $(addsuffix .tex, $(ALLBOOKS)): %.tex: %.sgml $(ALLSGML) stylesheet.dsl $(PERL) -pi -e 's/\>\>/\\mbox{}>\\mbox{}>\\mbox{}/g' $@ $(PERL) -pi -e "s/\'\'/\\\\mbox{}'\\\\mbox{}'\\\\mbox{}/g" $@ -%.dvi: %.tex +programmer.tex-ps: catalogs.eps connections.eps + +$(addsuffix .tex-pdf, $(ALLBOOKS)): %.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl + $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) -c $(CATALOG) -d stylesheet.dsl -t tex -V tex-backend -i output-print -V texpdf-output -o $@ book-decl.sgml $< + $(PERL) -pi -e 's/\-\-/\\mbox{}-\\mbox{}-\\mbox{}/g' $@ + $(PERL) -pi -e 's/\<\\>/\\mbox{}>\\mbox{}>\\mbox{}/g' $@ + $(PERL) -pi -e "s/\'\'/\\\\mbox{}'\\\\mbox{}'\\\\mbox{}/g" $@ + +programmer.tex-pdf: catalogs.pdf connections.pdf + +%.dvi: %.tex-ps + @rm $*.aux $*.log jadetex $< jadetex $< jadetex $< @@ -136,17 +153,31 @@ $(addsuffix .tex, $(ALLBOOKS)): %.tex: %.sgml $(ALLSGML) stylesheet.dsl %.ps: %.dvi dvips -o $@ $< -%.pdf: %.tex +%.pdf: %.tex-pdf + @rm $*.aux $*.log $*.out pdfjadetex $< pdfjadetex $< pdfjadetex $< +# 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. +$(addsuffix .fot, $(ALLBOOKS)): %.fot: %.sgml $(ALLSGML) stylesheet.dsl + $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) -c $(CATALOG) -d stylesheet.dsl -t fot -i output-print -o $@ book-decl.sgml $< + + # Graphics %.gif: cp $(srcdir)/../graphics/$@ . +%.eps: %.gif + $(CONVERT) $< eps:$@ + +%.pdf: %.eps + $(EPSTOPDF) $< + ## ## Semi-automatic generation of some text files. @@ -201,6 +232,6 @@ clean distclean maintainer-clean: # man rm -rf *.1 *.$(DEFAULTSECTION) man1 man$(DEFAULTSECTION) manpage.refs manpage.links manpage.log # print - rm -f *.rtf *.tex *.dvi *.aux *.log *.ps *.pdf *.out + rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.eps *.fot # index rm -f HTML.index bookindex.sgml setindex.sgml diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl index 80d9462d23..50f92730ed 100644 --- a/doc/src/sgml/stylesheet.dsl +++ b/doc/src/sgml/stylesheet.dsl @@ -1,4 +1,4 @@ - + @@ -24,15 +24,34 @@ + + + + (define pgsql-docs-list "pgsql-docs@postgresql.org") +;; Don't show manpage volume numbers (define %refentry-xref-manvolnum% #f) -(define %callout-graphics% #f) -(define %show-comments% #f) +;; Don't use graphics for callouts. (We could probably do that, but +;; it needs extra work.) +(define %callout-graphics% #f) + +;; Don't show comments. (We ought to show them, at least during the +;; development stage.) +(define %show-comments% #f) + +;; 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 envar ($mono-seq$)) (element lineannotation ($italic-seq$)) (element structfield ($mono-seq$)) (element structname ($mono-seq$)) @@ -40,10 +59,62 @@ (element type ($mono-seq$)) -;; 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. +;; 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 "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"))) + +(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))) + + (element pagenums + (make sequence + (literal "p. ") + (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 set-titlepage-recto-mode (element (para productname) ($charseq$))) (mode set-titlepage-verso-mode @@ -55,10 +126,11 @@ ;; Add more here if needed... - -(define %section-autolabel% #t) +string (time) #t))))) +;; Create an index (define html-index #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 @@ -135,24 +209,49 @@ ]]> + + + = (string->number "1.73") 1.73))) +;; Default graphic format: Jadetex wants eps, pdfjadetex wants pdf. +;; (Note that pdfjadetex will not accept eps, that's why we need to +;; create a different .tex file for each.) What works with RTF? + +(define texpdf-output #f) ;; override from command line + +(define %graphic-default-extension% + (cond (tex-backend (if texpdf-output "pdf" "eps")) + (rtf-backend "gif") + (else "XXX"))) + +;; Need to add pdf here so that the above works. Default setup +;; doesn't know about PDF. +(define preferred-mediaobject-extensions + (list "eps" "ps" "jpg" "jpeg" "pdf" "png")) + ;; Format legalnotice justified and with space between paragraphs. (mode book-titlepage-verso-mode @@ -164,10 +263,32 @@ font-size: (* 0.8 (inherited-font-size)) space-before: (* 0.8 %para-sep%) space-after: (* 0.8 %para-sep%) + first-line-start-indent: (if (is-first-para) + (* 0.8 %para-indent-firstpara%) + (* 0.8 %para-indent%)) (process-children)))) -;; Fix spacing bug in variablelists +;; Fix spacing problems in variablelists + +(element (varlistentry term) + (make paragraph + space-before: (if (first-sibling?) + %para-sep% + 0pt) + keep-with-next?: #t + (process-children))) + +(define %varlistentry-indent% 2em) + +(element (varlistentry listitem) + (make sequence + start-indent: (+ (inherited-start-indent) %varlistentry-indent%) + (process-children))) + + +;; Whitespace fixes for itemizedlists and orderedlists + (define (process-listitem-content) (if (absolute-first-sibling?) (make sequence @@ -175,8 +296,8 @@ (next-match))) -;; Default stylesheets format simplelists are tables. This just -;; spells trouble for Jade. +;; Default stylesheets format simplelists as tables. This spells +;; trouble for Jade. So we just format them as plain lines. (define %simplelist-indent% 1em) @@ -227,11 +348,231 @@ 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 (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-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)))) + (reference-titlepage-before (node-list-first nl) side) + (empty-sosofo)) + (cond + ((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)))) + + +(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)))) + ]]> + + + + +