| 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("\nWarning: found 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 |