doc/src/sgml/meson.build

   1 # Copyright (c) 2022-2025, PostgreSQL Global Development Group
   2
   3 docs = []
   4 installdocs = []
   5 alldocs = []
   6 doc_generated = []
   7
   8 version_sgml = configure_file(
   9   input: 'version.sgml.in',
  10   output: 'version.sgml',
  11   configuration: cdata,
  12 )
  13 configure_files += version_sgml
  14
  15 doc_generated += custom_target('features-supported.sgml',
  16   input: files(
  17     '../../../src/backend/catalog/sql_feature_packages.txt',
  18     '../../../src/backend/catalog/sql_features.txt',
  19   ),
  20   output: 'features-supported.sgml',
  21   command: [perl, files('mk_feature_tables.pl'), 'YES', '@INPUT@'],
  22   build_by_default: false,
  23   install: false,
  24   capture: true,
  25 )
  26
  27 doc_generated += custom_target('features-unsupported.sgml',
  28   input: files(
  29     '../../../src/backend/catalog/sql_feature_packages.txt',
  30     '../../../src/backend/catalog/sql_features.txt',
  31   ),
  32   output: 'features-unsupported.sgml',
  33   command: [perl, files('mk_feature_tables.pl'), 'NO', '@INPUT@'],
  34   build_by_default: false,
  35   install: false,
  36   capture: true,
  37 )
  38
  39 doc_generated += custom_target('errcodes-table.sgml',
  40   input: files(
  41     '../../../src/backend/utils/errcodes.txt'),
  42   output: 'errcodes-table.sgml',
  43   command: [perl, files('generate-errcodes-table.pl'), '@INPUT@'],
  44   build_by_default: false,
  45   install: false,
  46   capture: true,
  47 )
  48
  49 doc_generated += custom_target('wait_event_types.sgml',
  50   input: files(
  51     '../../../src/backend/utils/activity/wait_event_names.txt'),
  52   output: 'wait_event_types.sgml',
  53   command: [perl,
  54     files('../../../src/backend/utils/activity/generate-wait_event_types.pl'),
  55     '--outdir', '@OUTDIR@', '--docs', '@INPUT@'],
  56   build_by_default: false,
  57   install: false,
  58   capture: false,
  59 )
  60
  61 # FIXME: this actually has further inputs, adding depfile support to
  62 # generate-keywords-table.pl is probably the best way to address that
  63 # robustly.
  64 doc_generated += custom_target('keywords-table.sgml',
  65   input: files(
  66     '../../../src/include/parser/kwlist.h'),
  67   output: 'keywords-table.sgml',
  68   command: [perl, files('generate-keywords-table.pl'), '@CURRENT_SOURCE_DIR@'],
  69   build_by_default: false,
  70   install: false,
  71   capture: true,
  72 )
  73
  74 doc_generated += custom_target('targets-meson.sgml',
  75   input: files('targets-meson.txt'),
  76   output: 'targets-meson.sgml',
  77   command: [perl, files('generate-targets-meson.pl'), '@INPUT@'],
  78   build_by_default: false,
  79   install: false,
  80   capture: true,
  81 )
  82
  83 # For everything else we need at least xmllint
  84 if not xmllint_bin.found()
  85   subdir_done()
  86 endif
  87
  88 pandoc = find_program('pandoc', native: true, required: false)
  89
  90 xmltools_wrapper = [
  91   python, files('xmltools_dep_wrapper'),
  92   '--targetname', '@OUTPUT@', '--depfile', '@DEPFILE@'
  93 ]
  94
  95 xmllint = xmltools_wrapper + [
  96   '--tool', xmllint_bin, '--',
  97 ]
  98
  99 # Run validation only once, common to all subsequent targets.  While
 100 # we're at it, also resolve all entities (that is, copy all included
 101 # files into one big file).  This helps tools that don't understand
 102 # vpath builds (such as dbtoepub).
 103 postgres_full_xml = custom_target('postgres-full.xml',
 104   input: 'postgres.sgml',
 105   output: 'postgres-full.xml',
 106   depfile: 'postgres-full.xml.d',
 107   command: [xmllint, '--nonet', '--noent', '--valid',
 108             '--path', '@OUTDIR@', '-o', '@OUTPUT@', '@INPUT@'],
 109   depends: doc_generated,
 110   build_by_default: false,
 111 )
 112 docs += postgres_full_xml
 113 alldocs += postgres_full_xml
 114
 115
 116 if xsltproc_bin.found()
 117   xsltproc_flags = [
 118     '--nonet',
 119     '--stringparam', 'pg.version', pg_version,
 120     '--path', '@OUTDIR@', '--path', '@CURRENT_SOURCE_DIR@',
 121   ]
 122
 123   xsltproc = xmltools_wrapper + [
 124     '--tool', xsltproc_bin, '--',
 125   ]
 126
 127   xsltproc_html_flags = xsltproc_flags
 128   if get_option('docs_html_style') == 'website'
 129     xsltproc_html_flags += ['--param', 'website.stylesheet', '1']
 130   endif
 131 endif
 132
 133
 134 #
 135 # Full documentation as html, text
 136 #
 137 if docs_dep.found()
 138   html = custom_target('html',
 139     input: ['stylesheet.xsl', postgres_full_xml],
 140     output: 'html',
 141     depfile: 'html.d',
 142     command: [xsltproc, '-o', '@OUTDIR@/', xsltproc_html_flags, '@INPUT@'],
 143     build_by_default: false,
 144   )
 145   alldocs += html
 146
 147   install_doc_html = custom_target('install-html',
 148     output: 'install-html',
 149     command: [
 150       python, install_files, '--prefix', dir_prefix,
 151       '--install-dir-contents', dir_doc_html, html],
 152     build_always_stale: true, build_by_default: false,
 153   )
 154   alias_target('html', html)
 155   alias_target('install-html', install_doc_html)
 156
 157   # build and install multi-page html docs as part of docs target
 158   docs += html
 159   installdocs += install_doc_html
 160
 161
 162   # single-page HTML
 163   postgres_html = custom_target('postgres.html',
 164     input: ['stylesheet-html-nochunk.xsl', postgres_full_xml],
 165     output: 'postgres.html',
 166     depfile: 'postgres.html.d',
 167     command: [xsltproc, '-o', '@OUTPUT@', xsltproc_html_flags, '@INPUT@'],
 168     build_by_default: false,
 169   )
 170   alldocs += postgres_html
 171
 172   # single-page text
 173   if pandoc.found()
 174     postgres_txt = custom_target('postgres.txt',
 175       input: [postgres_html],
 176       output: 'postgres.txt',
 177       command: [pandoc, '-t', 'plain', '-o', '@OUTPUT@', '@INPUT@'],
 178       build_by_default: false,
 179     )
 180     alldocs += postgres_txt
 181   endif
 182 endif
 183
 184
 185 #
 186 # Man pages
 187 #
 188 if docs_dep.found()
 189   # FIXME: implement / consider sqlmansectnum logic
 190   man = custom_target('man',
 191     input: ['stylesheet-man.xsl', postgres_full_xml],
 192     output: ['man1', 'man3', 'man7'],
 193     depfile: 'man.d',
 194     command: [xsltproc, '-o', '@OUTDIR@/', xsltproc_html_flags, '@INPUT@'],
 195     build_by_default: false,
 196   )
 197   alldocs += man
 198
 199   install_doc_man = custom_target('install-man',
 200     output: 'install-man',
 201     input: man,
 202     command: [
 203       python, install_files, '--prefix', dir_prefix,
 204       '--install-dirs', dir_man, '@INPUT@'],
 205     build_always_stale: true, build_by_default: false,
 206   )
 207   alias_target('man', man)
 208   alias_target('install-man', install_doc_man)
 209
 210   # built and installed as part of the docs target
 211   installdocs += install_doc_man
 212   docs += man
 213 endif
 214
 215
 216 #
 217 # Full documentation as PDF
 218 #
 219 if docs_pdf_dep.found()
 220   xsltproc_fo_flags = xsltproc_flags + [
 221     '--stringparam', 'img.src.path', meson.current_source_dir() + '/'
 222   ]
 223
 224   foreach format, detail: {'A4': 'A4', 'US': 'USletter'}
 225     postgres_x_fo_f = 'postgres-@0@.fo'.format(format)
 226     postgres_x_fo_dep = 'postgres-@0@.fo.d'.format(format)
 227     postgres_x_pdf_f = 'postgres-@0@.pdf'.format(format)
 228
 229     postgres_x_fo = custom_target(postgres_x_fo_f,
 230       input: ['stylesheet-fo.xsl', postgres_full_xml],
 231       output: postgres_x_fo_f,
 232       depfile: postgres_x_fo_dep,
 233       command: [xsltproc, xsltproc_fo_flags,
 234                 '--stringparam', 'paper.type', detail,
 235                 '-o', '@OUTPUT@', '@INPUT@'],
 236       build_by_default: false,
 237     )
 238
 239     postgres_x_pdf = custom_target(postgres_x_pdf_f,
 240       input: [postgres_x_fo],
 241       output: [postgres_x_pdf_f],
 242       command: [fop, '-fo', '@INPUT@', '-pdf', '@OUTPUT@'],
 243       build_by_default: false,
 244     )
 245     alldocs += postgres_x_pdf
 246   endforeach
 247 endif
 248
 249
 250 #
 251 # epub
 252 #
 253
 254 # This was previously implemented using dbtoepub - but that doesn't seem to
 255 # support running in build != source directory (i.e. VPATH builds already
 256 # weren't supported).
 257 if pandoc.found() and xsltproc_bin.found()
 258   postgres_epub = custom_target('postgres.epub',
 259     input: postgres_full_xml,
 260     output: 'postgres.epub',
 261     command: [pandoc, '-f', 'docbook', '-t', 'epub', '-o', '@OUTPUT@', '--resource-path=@CURRENT_SOURCE_DIR@',
 262               '@INPUT@'],
 263     build_by_default: false,
 264   )
 265   alldocs += postgres_epub
 266 endif
 267
 268
 269 ##
 270 ## Experimental Texinfo targets
 271 ##
 272
 273 db2x_xsltproc = find_program('db2x_xsltproc', native: true, required: false)
 274 db2x_texixml = find_program('db2x_texixml', native: true, required: false)
 275 makeinfo = find_program('makeinfo', native: true, required: false)
 276
 277 if xsltproc_bin.found() and db2x_texixml.found() and db2x_xsltproc.found() and makeinfo.found()
 278   postgres_texixml = custom_target('postgres.texixml',
 279     output: 'postgres.texixml',
 280     command: [db2x_xsltproc, '-s', 'texi',
 281               '-g', 'output-file=postgres',
 282               postgres_full_xml, '-o', '@OUTPUT@'],
 283     build_by_default: false,
 284   )
 285   postgres_texi = custom_target('postgres.texi',
 286     output: 'postgres.texi',
 287     command: [db2x_texixml, '--encoding=utf-8', postgres_texixml,
 288               '--output-dir=@OUTDIR@'],
 289     build_by_default: false,
 290   )
 291   postgres_info = custom_target('postgres.info',
 292     output: 'postgres.info',
 293     command: [makeinfo, '--enable-encoding', '--no-split', '--no-validate',
 294               postgres_texi, '-o', '@OUTPUT0@'],
 295     build_by_default: false,
 296   )
 297   alldocs += postgres_info
 298 endif
 299
 300
 301 if docs_dep.found()
 302   alias_target('docs', docs)
 303   alias_target('install-docs', installdocs)
 304 endif
 305
 306 if alldocs.length() != 0
 307   alias_target('alldocs', alldocs)
 308 endif