granicus.if.org Git - postgresql/blob - doc/src/sgml/Makefile

   1 #----------------------------------------------------------------------------
   2 #
   3 # PostgreSQL documentation makefile
   4 #
   5 # doc/src/sgml/Makefile
   6 #
   7 #----------------------------------------------------------------------------
   8
   9 # This makefile is for building and installing the documentation.
  10 # When a release tarball is created, the documentation files are
  11 # prepared using the distprep target.  In Git-based trees these files
  12 # don't exist, unless explicitly built, so we skip the installation in
  13 # that case.
  14
  15
  16 # Make "html" the default target, since that is what most people tend
  17 # to want to use.
  18 html:
  19
  20 NO_TEMP_INSTALL=yes
  21
  22 subdir = doc/src/sgml
  23 top_builddir = ../../..
  24 include $(top_builddir)/src/Makefile.global
  25
  26
  27 all: html man
  28
  29 distprep: html distprep-man
  30
  31
  32 ifndef DBTOEPUB
  33 DBTOEPUB = $(missing) dbtoepub
  34 endif
  35
  36 ifndef JADE
  37 JADE = $(missing) jade
  38 endif
  39 SGMLINCLUDE = -D . -D $(srcdir)
  40
  41 ifndef NSGMLS
  42 NSGMLS = $(missing) nsgmls
  43 endif
  44
  45 ifndef OSX
  46 OSX = $(missing) osx
  47 endif
  48
  49 ifndef XMLLINT
  50 XMLLINT = $(missing) xmllint
  51 endif
  52
  53 ifndef XSLTPROC
  54 XSLTPROC = $(missing) xsltproc
  55 endif
  56
  57 override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)'
  58
  59
  60 GENERATED_SGML = bookindex.sgml version.sgml \
  61         features-supported.sgml features-unsupported.sgml errcodes-table.sgml
  62
  63 ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
  64
  65 # Sometimes we don't want this one.
  66 ALMOSTALLSGML := $(filter-out %bookindex.sgml,$(ALLSGML))
  67
  68 ifdef DOCBOOKSTYLE
  69 CATALOG = -c $(DOCBOOKSTYLE)/catalog
  70 endif
  71
  72 # Enable some extra warnings
  73 # -wfully-tagged needed to throw a warning on missing tags
  74 # for older tool chains, 2007-08-31
  75 # Note: try "make SPFLAGS=-wxml" to catch a lot of other dubious constructs,
  76 # in particular < and & that haven't been made into entities.  It's far too
  77 # noisy to turn on by default, unfortunately.
  78 override SPFLAGS += -wall -wno-unused-param -wno-empty -wfully-tagged
  79
  80 ##
  81 ## Man pages
  82 ##
  83
  84 man distprep-man: man-stamp
  85
  86 man-stamp: stylesheet-man.xsl postgres.xml
  87         $(XMLLINT) --noout --valid postgres.xml
  88         $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $^
  89         touch $@
  90
  91
  92 ##
  93 ## HTML
  94 ##
  95
  96 .PHONY: draft
  97
  98 JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html
  99 ifeq ($(STYLE),website)
 100 JADE.html.call += -V website-stylesheet
 101 endif
 102
 103 # The draft target creates HTML output in draft mode, without index (for faster build).
 104 draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
 105         $(MKDIR_P) html
 106         $(JADE.html.call) -V draft-mode $<
 107         cp $(srcdir)/stylesheet.css html/
 108
 109 html: html-stamp
 110
 111 html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl
 112         $(MAKE) check-tabs
 113         $(MKDIR_P) html
 114         $(JADE.html.call) -i include-index $<
 115         cp $(srcdir)/stylesheet.css html/
 116         touch $@
 117
 118 # single-page HTML
 119 postgres.html: postgres.sgml $(ALLSGML) stylesheet.dsl
 120         $(JADE.html.call) -V nochunks -V rootchunk -V '(define %root-filename% #f)' -V '(define use-output-dir #f)' -i include-index $<
 121
 122 # single-page text
 123 postgres.txt: postgres.html
 124         $(LYNX) -force_html -dump -nolist $< > $@
 125
 126 HTML.index: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
 127         @$(MKDIR_P) html
 128         $(JADE.html.call) -V html-index $<
 129
 130 bookindex.sgml: HTML.index
 131 ifdef COLLATEINDEX
 132         LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g -i 'bookindex' -o $@ $<
 133 else
 134         @$(missing) collateindex.pl $< $@
 135 endif
 136
 137 # Technically, this should depend on Makefile.global, but then
 138 # version.sgml would need to be rebuilt after every configure run,
 139 # even in distribution tarballs.  So this is cheating a bit, but it
 140 # will achieve the goal of updating the version number when it
 141 # changes.
 142 version.sgml: $(top_srcdir)/configure
 143         { \
 144           echo "<!ENTITY version \"$(VERSION)\">"; \
 145           echo "<!ENTITY majorversion \"$(MAJORVERSION)\">"; \
 146         } > $@
 147
 148 features-supported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt
 149         $(PERL) $(srcdir)/mk_feature_tables.pl YES $^ > $@
 150
 151 features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt
 152         $(PERL) $(srcdir)/mk_feature_tables.pl NO $^ > $@
 153
 154 errcodes-table.sgml: $(top_srcdir)/src/backend/utils/errcodes.txt generate-errcodes-table.pl
 155         $(PERL) $(srcdir)/generate-errcodes-table.pl $< > $@
 156
 157 ##
 158 ## Print
 159 ##
 160
 161
 162 # RTF to allow minor editing for hardcopy
 163 %.rtf: %.sgml $(ALLSGML)
 164         $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t rtf -V rtf-backend -i output-print  -i include-index postgres.sgml
 165
 166 # TeX
 167 # Regular TeX and pdfTeX have slightly differing requirements, so we
 168 # need to distinguish the path we're taking.
 169
 170 JADE.tex.call = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d $(srcdir)/stylesheet.dsl -t tex -V tex-backend -i output-print -i include-index
 171
 172 %-A4.tex-ps: %.sgml $(ALLSGML)
 173         $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $<
 174
 175 %-US.tex-ps: %.sgml $(ALLSGML)
 176         $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $<
 177
 178 %-A4.tex-pdf: %.sgml $(ALLSGML)
 179         $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $<
 180
 181 %-US.tex-pdf: %.sgml $(ALLSGML)
 182         $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $<
 183
 184 %.dvi: %.tex-ps
 185         @rm -f $*.aux $*.log
 186 # multiple runs are necessary to create proper intra-document links
 187         jadetex $<
 188         jadetex $<
 189         jadetex $<
 190
 191 # PostScript from TeX
 192 postgres.ps:
 193         $(error Invalid target;  use postgres-A4.ps or postgres-US.ps as targets)
 194
 195 %.ps: %.dvi
 196         dvips -o $@ $<
 197
 198 postgres.pdf:
 199         $(error Invalid target;  use postgres-A4.pdf or postgres-US.pdf as targets)
 200
 201 %.pdf: %.tex-pdf
 202         @rm -f $*.aux $*.log $*.out
 203 # multiple runs are necessary to create proper intra-document links
 204         pdfjadetex $<
 205         pdfjadetex $<
 206         pdfjadetex $<
 207
 208 # Cancel built-in suffix rules, interfering with PS building
 209 .SUFFIXES:
 210
 211
 212 # This generates an XML version of the flow-object tree.  It's useful
 213 # for debugging DSSSL code, and possibly to interface to some other
 214 # tools that can make use of this.
 215 %.fot: %.sgml $(ALLSGML)
 216         $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t fot -i output-print -i include-index -o $@ $<
 217
 218
 219 ##
 220 ## Semi-automatic generation of some text files.
 221 ##
 222
 223 JADE.text = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-text -t sgml
 224 ICONV = iconv
 225 LYNX = lynx
 226
 227 # The documentation may contain non-ASCII characters (mostly for
 228 # contributor names), which lynx converts to the encoding determined
 229 # by the current locale.  To get text output that is deterministic and
 230 # easily readable by everyone, we make lynx produce LATIN1 and then
 231 # convert that to ASCII with transliteration for the non-ASCII characters.
 232 # Official releases were historically built on FreeBSD, which has limited
 233 # locale support and is very picky about locale name spelling.  The
 234 # below has been finely tuned to run on FreeBSD and Linux/glibc.
 235 INSTALL: % : %.html
 236         $(PERL) -p -e 's/<H(1|2)$$/<H\1 align=center/g' $< | LC_ALL=en_US.ISO8859-1 $(LYNX) -force_html -dump -nolist -stdin | $(ICONV) -f latin1 -t us-ascii//TRANSLIT > $@
 237
 238 INSTALL.html: standalone-install.sgml installation.sgml version.sgml
 239         $(JADE.text) -V nochunks standalone-install.sgml installation.sgml > $@
 240
 241
 242 ##
 243 ## XSLT processing
 244 ##
 245
 246 # For obscure reasons, GNU make 3.81 complains about circular dependencies
 247 # if we try to do "make all" in a VPATH build without the explicit
 248 # $(srcdir) on the postgres.sgml dependency in this rule.  GNU make bug?
 249 postgres.xml: $(srcdir)/postgres.sgml $(ALMOSTALLSGML)
 250         $(OSX) -D. -x lower -i include-xslt-index $< >postgres.xmltmp
 251         $(PERL) -p -e 's/\[(aacute|acirc|aelig|agrave|amp|aring|atilde|auml|bull|copy|eacute|egrave|gt|iacute|lt|mdash|nbsp|ntilde|oacute|ocirc|oslash|ouml|pi|quot|scaron|uuml) *\]/\&\1;/gi;' \
 252                    -e '$$_ .= qq{<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\n} if $$. == 1;' \
 253           <postgres.xmltmp > $@
 254         rm postgres.xmltmp
 255 # ' hello Emacs
 256
 257 ifeq ($(STYLE),website)
 258 XSLTPROC_HTML_FLAGS += --param website.stylesheet 1
 259 endif
 260
 261 xslthtml: xslthtml-stamp
 262
 263 xslthtml-stamp: stylesheet.xsl postgres.xml
 264         $(XMLLINT) --noout --valid postgres.xml
 265         $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^
 266         cp $(srcdir)/stylesheet.css html/
 267         touch $@
 268
 269 htmlhelp: stylesheet-hh.xsl postgres.xml
 270         $(XMLLINT) --noout --valid postgres.xml
 271         $(XSLTPROC) $(XSLTPROCFLAGS) $^
 272
 273 %-A4.fo.tmp: stylesheet-fo.xsl %.xml
 274         $(XMLLINT) --noout --valid $*.xml
 275         $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $^
 276
 277 %-US.fo.tmp: stylesheet-fo.xsl %.xml
 278         $(XMLLINT) --noout --valid $*.xml
 279         $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^
 280
 281 FOP = fop
 282
 283 # reformat FO output so that locations of errors are easier to find
 284 %.fo: %.fo.tmp
 285         $(XMLLINT) --format --output $@ $^
 286
 287 .SECONDARY: postgres-A4.fo postgres-US.fo
 288
 289 %-fop.pdf: %.fo
 290         $(FOP) -fo $< -pdf $@
 291
 292 epub: postgres.epub
 293 postgres.epub: postgres.xml
 294         $(XMLLINT) --noout --valid $<
 295         $(DBTOEPUB) $<
 296
 297
 298 ##
 299 ## Experimental Texinfo targets
 300 ##
 301
 302 DB2X_TEXIXML = db2x_texixml
 303 DB2X_XSLTPROC = db2x_xsltproc
 304 MAKEINFO = makeinfo
 305
 306 %.texixml: %.xml
 307         $(DB2X_XSLTPROC) -s texi -g output-file=$(basename $@) $< -o $@
 308
 309 %.texi: %.texixml
 310         $(DB2X_TEXIXML) --encoding=iso-8859-1//TRANSLIT $< --to-stdout > $@
 311
 312 %.info: %.texi
 313         $(MAKEINFO) --enable-encoding --no-split --no-validate $< -o $@
 314
 315
 316 ##
 317 ## Check
 318 ##
 319
 320 # Quick syntax check without style processing
 321 check: postgres.sgml $(ALMOSTALLSGML) check-tabs
 322         $(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $<
 323
 324
 325 ##
 326 ## Install
 327 ##
 328
 329 install: install-html install-man
 330
 331 installdirs:
 332         $(MKDIR_P) '$(DESTDIR)$(htmldir)'/html $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))
 333
 334 # If the install used a man directory shared with other applications, this will remove all files.
 335 uninstall:
 336         rm -f '$(DESTDIR)$(htmldir)/html/'* $(addprefix  '$(DESTDIR)$(mandir)'/man, 1/* 3/* $(sqlmansectnum)/*)
 337
 338
 339 ## Install html
 340
 341 install-html: html installdirs
 342         cp -R $(call vpathsearch,html) '$(DESTDIR)$(htmldir)'
 343
 344
 345 ## Install man
 346
 347 install-man: man installdirs
 348
 349 sqlmansect ?= 7
 350 sqlmansectnum = $(shell expr X'$(sqlmansect)' : X'\([0-9]\)')
 351
 352 # Before we install the man pages, we massage the section numbers to
 353 # follow the local conventions.
 354 #
 355 ifeq ($(sqlmansectnum),7)
 356 install-man:
 357         cp -R $(foreach dir,man1 man3 man7,$(call vpathsearch,$(dir))) '$(DESTDIR)$(mandir)'
 358
 359 else # sqlmansectnum != 7
 360 fix_sqlmansectnum = sed -e '/^\.TH/s/"7"/"$(sqlmansect)"/' \
 361                         -e 's/\\fR(7)/\\fR($(sqlmansectnum))/g' \
 362                         -e '1s/^\.so man7/.so man$(sqlmansectnum)/g;1s/^\(\.so.*\)\.7$$/\1.$(sqlmansect)/g'
 363
 364 man: fixed-man-stamp
 365
 366 fixed-man-stamp: man-stamp
 367         @$(MKDIR_P) $(addprefix fixedman/,man1 man3 man$(sqlmansectnum))
 368         for file in $(call vpathsearch,man1)/*.1; do $(fix_sqlmansectnum) $$file >fixedman/man1/`basename $$file` || exit; done
 369         for file in $(call vpathsearch,man3)/*.3; do $(fix_sqlmansectnum) $$file >fixedman/man3/`basename $$file` || exit; done
 370         for file in $(call vpathsearch,man7)/*.7; do $(fix_sqlmansectnum) $$file >fixedman/man$(sqlmansectnum)/`basename $$file | sed s/\.7$$/.$(sqlmansect)/` || exit; done
 371
 372 install-man:
 373         cp -R $(foreach dir,man1 man3 man$(sqlmansectnum),fixedman/$(dir)) '$(DESTDIR)$(mandir)'
 374
 375 clean: clean-man
 376 .PHONY: clean-man
 377 clean-man:
 378         rm -rf fixedman/ fixed-man-stamp
 379
 380 endif # sqlmansectnum != 7
 381
 382 # tabs are harmless, but it is best to avoid them in SGML files
 383 check-tabs:
 384         @( ! grep '     ' $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml $(srcdir)/*.dsl $(srcdir)/*.xsl) ) || (echo "Tabs appear in SGML/XML files" 1>&2;  exit 1)
 385
 386 ##
 387 ## Clean
 388 ##
 389
 390 # This allows removing some files from the distribution tarballs while
 391 # keeping the dependencies satisfied.
 392 .SECONDARY: postgres.xml $(GENERATED_SGML) HTML.index
 393 .SECONDARY: INSTALL.html
 394 .SECONDARY: %-A4.tex-ps %-US.tex-ps %-A4.tex-pdf %-US.tex-pdf
 395
 396 clean:
 397 # text --- these are shipped, but not in this directory
 398         rm -f INSTALL
 399         rm -f INSTALL.html
 400 # single-page output
 401         rm -f postgres.html postgres.txt
 402 # print
 403         rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.fot
 404 # index
 405         rm -f HTML.index $(GENERATED_SGML)
 406 # XSLT
 407         rm -f postgres.xml postgres.xmltmp htmlhelp.hhp toc.hhc index.hhk *.fo *.fo.tmp
 408 # EPUB
 409         rm -f postgres.epub
 410 # Texinfo
 411         rm -f *.texixml *.texi *.info db2texi.refs
 412
 413 distclean: clean
 414
 415 maintainer-clean: distclean
 416 # HTML
 417         rm -fr html/ html-stamp
 418 # man
 419         rm -rf man1/ man3/ man7/ man-stamp