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 # In Git-based trees these files
  11 # don't exist, unless explicitly built, so we skip the installation in
  12 # that case.
  13
  14
  15 # Make "html" the default target, since that is what most people tend
  16 # to want to use.
  17 html:
  18 # Note that all is *not* the default target in this directory
  19 all: html man
  20
  21 # We don't need the tree-wide headers or install support here.
  22 NO_GENERATED_HEADERS=yes
  23 NO_TEMP_INSTALL=yes
  24
  25 subdir = doc/src/sgml
  26 top_builddir = ../../..
  27 include $(top_builddir)/src/Makefile.global
  28
  29
  30
  31 ifndef DBTOEPUB
  32 DBTOEPUB = $(missing) dbtoepub
  33 endif
  34
  35 ifndef FOP
  36 FOP = $(missing) fop
  37 endif
  38
  39 PANDOC = pandoc
  40
  41 XMLINCLUDE = --path . --path $(srcdir)
  42
  43 ifdef XMLLINT
  44 XMLLINT := $(XMLLINT) --nonet
  45 else
  46 XMLLINT = $(missing) xmllint
  47 endif
  48
  49 ifdef XSLTPROC
  50 XSLTPROC := $(XSLTPROC) --nonet
  51 else
  52 XSLTPROC = $(missing) xsltproc
  53 endif
  54
  55 override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)'
  56
  57
  58 GENERATED_SGML = version.sgml \
  59         features-supported.sgml features-unsupported.sgml errcodes-table.sgml \
  60         keywords-table.sgml targets-meson.sgml wait_event_types.sgml
  61
  62 ALL_SGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
  63
  64 ALL_IMAGES := $(wildcard $(srcdir)/images/*.svg)
  65
  66
  67 # Run validation only once, common to all subsequent targets.  While
  68 # we're at it, also resolve all entities (that is, copy all included
  69 # files into one big file).  This helps tools that don't understand
  70 # vpath builds (such as dbtoepub).
  71 postgres-full.xml: postgres.sgml $(ALL_SGML)
  72         $(XMLLINT) $(XMLINCLUDE) --output $@ --noent --valid $<
  73
  74
  75 ##
  76 ## Man pages
  77 ##
  78
  79 man: man-stamp
  80
  81 man-stamp: stylesheet-man.xsl postgres-full.xml
  82         $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $^
  83         touch $@
  84
  85
  86 ##
  87 ## common files
  88 ##
  89
  90 # Technically, this should depend on Makefile.global, but then
  91 # version.sgml would need to be rebuilt after every configure run.  So
  92 # this is cheating a bit, but it will achieve the goal of updating the
  93 # version number when it changes.
  94 version.sgml: $(top_srcdir)/configure
  95         { \
  96           echo "<!ENTITY version \"$(VERSION)\">"; \
  97           echo "<!ENTITY majorversion \"$(MAJORVERSION)\">"; \
  98         } > $@
  99
 100 features-supported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt
 101         $(PERL) $(srcdir)/mk_feature_tables.pl YES $^ > $@
 102
 103 features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt
 104         $(PERL) $(srcdir)/mk_feature_tables.pl NO $^ > $@
 105
 106 errcodes-table.sgml: $(top_srcdir)/src/backend/utils/errcodes.txt generate-errcodes-table.pl
 107         $(PERL) $(srcdir)/generate-errcodes-table.pl $< > $@
 108
 109 keywords-table.sgml: $(top_srcdir)/src/include/parser/kwlist.h $(wildcard $(srcdir)/keywords/sql*.txt) generate-keywords-table.pl
 110         $(PERL) $(srcdir)/generate-keywords-table.pl $(srcdir) > $@
 111
 112 wait_event_types.sgml: $(top_srcdir)/src/backend/utils/activity/wait_event_names.txt $(top_srcdir)/src/backend/utils/activity/generate-wait_event_types.pl
 113         $(PERL) $(top_srcdir)/src/backend/utils/activity/generate-wait_event_types.pl --docs $<
 114
 115 targets-meson.sgml: targets-meson.txt $(srcdir)/generate-targets-meson.pl
 116         $(PERL) $(srcdir)/generate-targets-meson.pl $^ > $@
 117
 118
 119 ##
 120 ## HTML
 121 ##
 122
 123 ifeq ($(STYLE),website)
 124 XSLTPROC_HTML_FLAGS += --param website.stylesheet 1
 125 endif
 126
 127 html: html-stamp
 128
 129 html-stamp: stylesheet.xsl postgres-full.xml $(ALL_IMAGES)
 130         $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
 131         touch $@
 132
 133 # single-page HTML
 134 postgres.html: stylesheet-html-nochunk.xsl postgres-full.xml $(ALL_IMAGES)
 135         $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
 136
 137 # single-page text
 138 postgres.txt: postgres.html
 139         $(PANDOC) -t plain -o $@ $<
 140
 141
 142 ##
 143 ## Print
 144 ##
 145
 146 postgres.pdf pdf:
 147         $(error Invalid target;  use postgres-A4.pdf or postgres-US.pdf as targets)
 148
 149 XSLTPROC_FO_FLAGS += --stringparam img.src.path '$(srcdir)/'
 150
 151 # XSL Formatting Objects (FO), https://en.wikipedia.org/wiki/XSL_Formatting_Objects
 152 %-A4.fo: stylesheet-fo.xsl %-full.xml
 153         $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type A4 -o $@ $^
 154
 155 %-US.fo: stylesheet-fo.xsl %-full.xml
 156         $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type USletter -o $@ $^
 157
 158 # There is no easy way to pipe output and capture its return code,
 159 # so add a final line to report the return code.
 160 %.pdf: %.fo $(ALL_IMAGES)
 161         { LANG=C $(FOP) -fo $< -pdf $@ 2>&1; echo "FOP_RETURN $$?"; } | \
 162         $(AWK) 'BEGIN { warn = 0 }  $$1 != "FOP_RETURN" { print }  /not available in font/ { warn = 1 }  \
 163         END { if (warn != 0) print("\nFound characters that cannot be output in the PDF document;  see README.non-ASCII"); \
 164         if ($$2 != 0) { exit $$2} }' 1>&2
 165
 166
 167 ##
 168 ## EPUB
 169 ##
 170
 171 epub: postgres.epub
 172 postgres.epub: postgres-full.xml $(ALL_IMAGES)
 173 ifeq ($(vpath_build),yes)
 174         $(MKDIR_P) images
 175         cp $(ALL_IMAGES) images/
 176 endif
 177         $(DBTOEPUB) -o $@ $<
 178
 179
 180 ##
 181 ## Experimental Texinfo targets
 182 ##
 183
 184 DB2X_TEXIXML = db2x_texixml
 185 DB2X_XSLTPROC = db2x_xsltproc
 186 MAKEINFO = makeinfo
 187
 188 %.texixml: %-full.xml
 189         $(DB2X_XSLTPROC) -s texi -g output-file=$(basename $@) $< -o $@
 190
 191 %.texi: %.texixml
 192         $(DB2X_TEXIXML) --encoding=utf-8 $< --to-stdout > $@
 193
 194 %.info: %.texi
 195         $(MAKEINFO) --enable-encoding --no-split --no-validate $< -o $@
 196
 197
 198 ##
 199 ## Check
 200 ##
 201
 202 # Quick syntax check without style processing
 203 check: postgres.sgml $(ALL_SGML) check-tabs check-nbsp
 204         $(XMLLINT) $(XMLINCLUDE) --noout --valid $<
 205
 206
 207 ##
 208 ## Install
 209 ##
 210
 211 install: install-html install-man
 212
 213 installdirs:
 214         $(MKDIR_P) '$(DESTDIR)$(htmldir)'/html $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))
 215
 216 # If the install used a man directory shared with other applications, this will remove all files.
 217 uninstall:
 218         rm -f '$(DESTDIR)$(htmldir)/html/'* $(addprefix  '$(DESTDIR)$(mandir)'/man, 1/* 3/* $(sqlmansectnum)/*)
 219
 220
 221 ## Install html
 222
 223 install-html: html installdirs
 224         cp -R html '$(DESTDIR)$(htmldir)'
 225
 226
 227 ## Install man
 228
 229 install-man: man installdirs
 230
 231 sqlmansect ?= 7
 232 sqlmansectnum = $(shell expr X'$(sqlmansect)' : X'\([0-9]\)')
 233
 234 # Before we install the man pages, we massage the section numbers to
 235 # follow the local conventions.
 236 #
 237 ifeq ($(sqlmansectnum),7)
 238 install-man:
 239         cp -R man1 man3 man7 '$(DESTDIR)$(mandir)'
 240
 241 else # sqlmansectnum != 7
 242 fix_sqlmansectnum = sed -e '/^\.TH/s/"7"/"$(sqlmansect)"/' \
 243                         -e 's/\\fR(7)/\\fR($(sqlmansectnum))/g' \
 244                         -e '1s/^\.so man7/.so man$(sqlmansectnum)/g;1s/^\(\.so.*\)\.7$$/\1.$(sqlmansect)/g'
 245
 246 man: fixed-man-stamp
 247
 248 fixed-man-stamp: man-stamp
 249         @$(MKDIR_P) $(addprefix fixedman/,man1 man3 man$(sqlmansectnum))
 250         for file in man1/*.1; do $(fix_sqlmansectnum) $$file >fixedman/man1/`basename $$file` || exit; done
 251         for file in man3/*.3; do $(fix_sqlmansectnum) $$file >fixedman/man3/`basename $$file` || exit; done
 252         for file in man7/*.7; do $(fix_sqlmansectnum) $$file >fixedman/man$(sqlmansectnum)/`basename $$file | sed s/\.7$$/.$(sqlmansect)/` || exit; done
 253
 254 install-man:
 255         cp -R $(foreach dir,man1 man3 man$(sqlmansectnum),fixedman/$(dir)) '$(DESTDIR)$(mandir)'
 256
 257 clean: clean-man
 258 .PHONY: clean-man
 259 clean-man:
 260         rm -rf fixedman/ fixed-man-stamp
 261
 262 endif # sqlmansectnum != 7
 263
 264 # tabs are harmless, but it is best to avoid them in SGML files
 265 check-tabs:
 266         @( ! grep '     ' $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml $(srcdir)/*.xsl) ) || \
 267         (echo "Tabs appear in SGML/XML files" 1>&2;  exit 1)
 268
 269 # Non-breaking spaces are harmless, but it is best to avoid them in SGML files.
 270 # Use perl command because non-GNU grep or sed could not have hex escape sequence.
 271 check-nbsp:
 272         @ ( $(PERL) -ne '/\xC2\xA0/ and print("$$ARGV:$$_"),$$n++; END {exit($$n>0)}' \
 273           $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml $(srcdir)/*.xsl $(srcdir)/images/*.xsl) ) || \
 274         (echo "Non-breaking spaces appear in SGML/XML files" 1>&2;  exit 1)
 275
 276 ##
 277 ## Clean
 278 ##
 279
 280 # This allows removing some files from the distribution tarballs while
 281 # keeping the dependencies satisfied.
 282 .SECONDARY: $(GENERATED_SGML)
 283 .SECONDARY: postgres-full.xml
 284 .SECONDARY: postgres-A4.fo postgres-US.fo
 285
 286 clean:
 287 # single-page output
 288         rm -f postgres.html postgres.txt
 289 # print
 290         rm -f *.fo *.pdf
 291 # generated SGML files
 292         rm -f $(GENERATED_SGML)
 293         rm -f postgres-full.xml
 294 # EPUB
 295         rm -f postgres.epub
 296 # Texinfo
 297         rm -f *.texixml *.texi *.info db2texi.refs
 298
 299 distclean: clean
 300 # HTML
 301         rm -fr html/ html-stamp
 302 # man
 303         rm -rf man1/ man3/ man7/ man-stamp