Documentation/meson.build

   1 manpages = {
   2   # Category 1.
   3   'git-add.txt' : 1,
   4   'git-am.txt' : 1,
   5   'git-annotate.txt' : 1,
   6   'git-apply.txt' : 1,
   7   'git-archimport.txt' : 1,
   8   'git-archive.txt' : 1,
   9   'git-bisect.txt' : 1,
  10   'git-blame.txt' : 1,
  11   'git-branch.txt' : 1,
  12   'git-bugreport.txt' : 1,
  13   'git-bundle.txt' : 1,
  14   'git-cat-file.txt' : 1,
  15   'git-check-attr.txt' : 1,
  16   'git-check-ignore.txt' : 1,
  17   'git-check-mailmap.txt' : 1,
  18   'git-checkout-index.txt' : 1,
  19   'git-checkout.txt' : 1,
  20   'git-check-ref-format.txt' : 1,
  21   'git-cherry-pick.txt' : 1,
  22   'git-cherry.txt' : 1,
  23   'git-citool.txt' : 1,
  24   'git-clean.txt' : 1,
  25   'git-clone.txt' : 1,
  26   'git-column.txt' : 1,
  27   'git-commit-graph.txt' : 1,
  28   'git-commit-tree.txt' : 1,
  29   'git-commit.txt' : 1,
  30   'git-config.txt' : 1,
  31   'git-count-objects.txt' : 1,
  32   'git-credential-cache--daemon.txt' : 1,
  33   'git-credential-cache.txt' : 1,
  34   'git-credential-store.txt' : 1,
  35   'git-credential.txt' : 1,
  36   'git-cvsexportcommit.txt' : 1,
  37   'git-cvsimport.txt' : 1,
  38   'git-cvsserver.txt' : 1,
  39   'git-daemon.txt' : 1,
  40   'git-describe.txt' : 1,
  41   'git-diagnose.txt' : 1,
  42   'git-diff-files.txt' : 1,
  43   'git-diff-index.txt' : 1,
  44   'git-difftool.txt' : 1,
  45   'git-diff-tree.txt' : 1,
  46   'git-diff.txt' : 1,
  47   'git-fast-export.txt' : 1,
  48   'git-fast-import.txt' : 1,
  49   'git-fetch-pack.txt' : 1,
  50   'git-fetch.txt' : 1,
  51   'git-filter-branch.txt' : 1,
  52   'git-fmt-merge-msg.txt' : 1,
  53   'git-for-each-ref.txt' : 1,
  54   'git-for-each-repo.txt' : 1,
  55   'git-format-patch.txt' : 1,
  56   'git-fsck-objects.txt' : 1,
  57   'git-fsck.txt' : 1,
  58   'git-fsmonitor--daemon.txt' : 1,
  59   'git-gc.txt' : 1,
  60   'git-get-tar-commit-id.txt' : 1,
  61   'git-grep.txt' : 1,
  62   'git-gui.txt' : 1,
  63   'git-hash-object.txt' : 1,
  64   'git-help.txt' : 1,
  65   'git-hook.txt' : 1,
  66   'git-http-backend.txt' : 1,
  67   'git-http-fetch.txt' : 1,
  68   'git-http-push.txt' : 1,
  69   'git-imap-send.txt' : 1,
  70   'git-index-pack.txt' : 1,
  71   'git-init-db.txt' : 1,
  72   'git-init.txt' : 1,
  73   'git-instaweb.txt' : 1,
  74   'git-interpret-trailers.txt' : 1,
  75   'git-log.txt' : 1,
  76   'git-ls-files.txt' : 1,
  77   'git-ls-remote.txt' : 1,
  78   'git-ls-tree.txt' : 1,
  79   'git-mailinfo.txt' : 1,
  80   'git-mailsplit.txt' : 1,
  81   'git-maintenance.txt' : 1,
  82   'git-merge-base.txt' : 1,
  83   'git-merge-file.txt' : 1,
  84   'git-merge-index.txt' : 1,
  85   'git-merge-one-file.txt' : 1,
  86   'git-mergetool--lib.txt' : 1,
  87   'git-mergetool.txt' : 1,
  88   'git-merge-tree.txt' : 1,
  89   'git-merge.txt' : 1,
  90   'git-mktag.txt' : 1,
  91   'git-mktree.txt' : 1,
  92   'git-multi-pack-index.txt' : 1,
  93   'git-mv.txt' : 1,
  94   'git-name-rev.txt' : 1,
  95   'git-notes.txt' : 1,
  96   'git-p4.txt' : 1,
  97   'git-pack-objects.txt' : 1,
  98   'git-pack-redundant.txt' : 1,
  99   'git-pack-refs.txt' : 1,
 100   'git-patch-id.txt' : 1,
 101   'git-prune-packed.txt' : 1,
 102   'git-prune.txt' : 1,
 103   'git-pull.txt' : 1,
 104   'git-push.txt' : 1,
 105   'git-quiltimport.txt' : 1,
 106   'git-range-diff.txt' : 1,
 107   'git-read-tree.txt' : 1,
 108   'git-rebase.txt' : 1,
 109   'git-receive-pack.txt' : 1,
 110   'git-reflog.txt' : 1,
 111   'git-refs.txt' : 1,
 112   'git-remote-ext.txt' : 1,
 113   'git-remote-fd.txt' : 1,
 114   'git-remote.txt' : 1,
 115   'git-repack.txt' : 1,
 116   'git-replace.txt' : 1,
 117   'git-replay.txt' : 1,
 118   'git-request-pull.txt' : 1,
 119   'git-rerere.txt' : 1,
 120   'git-reset.txt' : 1,
 121   'git-restore.txt' : 1,
 122   'git-revert.txt' : 1,
 123   'git-rev-list.txt' : 1,
 124   'git-rev-parse.txt' : 1,
 125   'git-rm.txt' : 1,
 126   'git-send-email.txt' : 1,
 127   'git-send-pack.txt' : 1,
 128   'git-shell.txt' : 1,
 129   'git-sh-i18n--envsubst.txt' : 1,
 130   'git-sh-i18n.txt' : 1,
 131   'git-shortlog.txt' : 1,
 132   'git-show-branch.txt' : 1,
 133   'git-show-index.txt' : 1,
 134   'git-show-ref.txt' : 1,
 135   'git-show.txt' : 1,
 136   'git-sh-setup.txt' : 1,
 137   'git-sparse-checkout.txt' : 1,
 138   'git-stage.txt' : 1,
 139   'git-stash.txt' : 1,
 140   'git-status.txt' : 1,
 141   'git-stripspace.txt' : 1,
 142   'git-submodule.txt' : 1,
 143   'git-svn.txt' : 1,
 144   'git-switch.txt' : 1,
 145   'git-symbolic-ref.txt' : 1,
 146   'git-tag.txt' : 1,
 147   'git-unpack-file.txt' : 1,
 148   'git-unpack-objects.txt' : 1,
 149   'git-update-index.txt' : 1,
 150   'git-update-ref.txt' : 1,
 151   'git-update-server-info.txt' : 1,
 152   'git-upload-archive.txt' : 1,
 153   'git-upload-pack.txt' : 1,
 154   'git-var.txt' : 1,
 155   'git-verify-commit.txt' : 1,
 156   'git-verify-pack.txt' : 1,
 157   'git-verify-tag.txt' : 1,
 158   'git-version.txt' : 1,
 159   'git-web--browse.txt' : 1,
 160   'git-whatchanged.txt' : 1,
 161   'git-worktree.txt' : 1,
 162   'git-write-tree.txt' : 1,
 163   'git.txt' : 1,
 164   'gitk.txt' : 1,
 165   'gitweb.txt' : 1,
 166   'scalar.txt' : 1,
 167
 168   # Category 5.
 169   'gitattributes.txt' : 5,
 170   'gitformat-bundle.txt' : 5,
 171   'gitformat-chunk.txt' : 5,
 172   'gitformat-commit-graph.txt' : 5,
 173   'gitformat-index.txt' : 5,
 174   'gitformat-pack.txt' : 5,
 175   'gitformat-signature.txt' : 5,
 176   'githooks.txt' : 5,
 177   'gitignore.txt' : 5,
 178   'gitmailmap.txt' : 5,
 179   'gitmodules.txt' : 5,
 180   'gitprotocol-capabilities.txt' : 5,
 181   'gitprotocol-common.txt' : 5,
 182   'gitprotocol-http.txt' : 5,
 183   'gitprotocol-pack.txt' : 5,
 184   'gitprotocol-v2.txt' : 5,
 185   'gitrepository-layout.txt' : 5,
 186   'gitweb.conf.txt' : 5,
 187
 188   # Category 7.
 189   'gitcli.txt' : 7,
 190   'gitcore-tutorial.txt' : 7,
 191   'gitcredentials.txt' : 7,
 192   'gitcvs-migration.txt' : 7,
 193   'gitdiffcore.txt' : 7,
 194   'giteveryday.txt' : 7,
 195   'gitfaq.txt' : 7,
 196   'gitglossary.txt' : 7,
 197   'gitpacking.txt' : 7,
 198   'gitnamespaces.txt' : 7,
 199   'gitremote-helpers.txt' : 7,
 200   'gitrevisions.txt' : 7,
 201   'gitsubmodules.txt' : 7,
 202   'gittutorial-2.txt' : 7,
 203   'gittutorial.txt' : 7,
 204   'gitworkflows.txt' : 7,
 205 }
 206
 207 docs_backend = get_option('docs_backend')
 208 if docs_backend == 'auto'
 209   if find_program('asciidoc', required: false).found()
 210     docs_backend = 'asciidoc'
 211   elif find_program('asciidoctor', required: false).found()
 212     docs_backend = 'asciidoctor'
 213   else
 214     error('Neither asciidoc nor asciidoctor were found.')
 215   endif
 216 endif
 217
 218 if docs_backend == 'asciidoc'
 219   asciidoc = find_program('asciidoc', required: true)
 220   asciidoc_html = 'xhtml11'
 221   asciidoc_docbook = 'docbook'
 222   xmlto_extra = [ ]
 223
 224   asciidoc_conf = custom_target(
 225     command: [
 226       shell,
 227       meson.project_source_root() / 'GIT-VERSION-GEN',
 228       meson.project_source_root(),
 229       '@INPUT@',
 230       '@OUTPUT@',
 231     ],
 232     input: 'asciidoc.conf.in',
 233     output: 'asciidoc.conf',
 234     depends: [git_version_file],
 235     env: version_gen_environment,
 236   )
 237
 238   asciidoc_common_options = [
 239     asciidoc,
 240     '--conf-file=' + asciidoc_conf.full_path(),
 241     '--attribute=build_dir=' + meson.current_build_dir(),
 242   ]
 243
 244   documentation_deps = [
 245     asciidoc_conf,
 246   ]
 247 elif docs_backend == 'asciidoctor'
 248   asciidoctor = find_program('asciidoctor', required: true)
 249   asciidoc_html = 'xhtml5'
 250   asciidoc_docbook = 'docbook5'
 251   xmlto_extra = [
 252     '--skip-validation',
 253     '-x', meson.current_source_dir() / 'manpage.xsl',
 254   ]
 255
 256   asciidoctor_extensions = custom_target(
 257     command: [
 258       shell,
 259       meson.project_source_root() / 'GIT-VERSION-GEN',
 260       meson.project_source_root(),
 261       '@INPUT@',
 262       '@OUTPUT@',
 263     ],
 264     input: 'asciidoctor-extensions.rb.in',
 265     output: 'asciidoctor-extensions.rb',
 266     depends: [git_version_file],
 267     env: version_gen_environment,
 268   )
 269
 270   asciidoc_common_options = [
 271     asciidoctor,
 272     '--attribute', 'compat-mode',
 273     '--attribute', 'tabsize=8',
 274     '--attribute', 'litdd=&#x2d;&#x2d;',
 275     '--attribute', 'docinfo=shared',
 276     '--attribute', 'build_dir=' + meson.current_build_dir(),
 277     '--load-path', meson.current_build_dir(),
 278     '--require', 'asciidoctor-extensions',
 279   ]
 280
 281   documentation_deps = [
 282     asciidoctor_extensions,
 283   ]
 284 endif
 285
 286 git = find_program('git', required: false)
 287 xmlto = find_program('xmlto')
 288
 289 cmd_lists = [
 290   'cmds-ancillaryinterrogators.txt',
 291   'cmds-ancillarymanipulators.txt',
 292   'cmds-mainporcelain.txt',
 293   'cmds-plumbinginterrogators.txt',
 294   'cmds-plumbingmanipulators.txt',
 295   'cmds-synchingrepositories.txt',
 296   'cmds-synchelpers.txt',
 297   'cmds-guide.txt',
 298   'cmds-developerinterfaces.txt',
 299   'cmds-userinterfaces.txt',
 300   'cmds-purehelpers.txt',
 301   'cmds-foreignscminterface.txt',
 302 ]
 303
 304 documentation_deps += custom_target(
 305   command: [
 306     perl,
 307     '@INPUT@',
 308     meson.project_source_root(),
 309     meson.current_build_dir(),
 310   ] + cmd_lists,
 311   input: 'cmd-list.perl',
 312   output: cmd_lists
 313 )
 314
 315 foreach mode : [ 'diff', 'merge' ]
 316   documentation_deps += custom_target(
 317     command: [
 318       shell,
 319       '@INPUT@',
 320       '..',
 321       mode,
 322       '@OUTPUT@'
 323     ],
 324     env: [
 325       'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools',
 326     ],
 327     input: 'generate-mergetool-list.sh',
 328     output: 'mergetools-' + mode + '.txt',
 329   )
 330 endforeach
 331
 332 foreach manpage, category : manpages
 333   if get_option('docs').contains('man')
 334     manpage_xml_target = custom_target(
 335       command: asciidoc_common_options + [
 336         '--backend=' + asciidoc_docbook,
 337         '--doctype=manpage',
 338         '--out-file=@OUTPUT@',
 339         '@INPUT@',
 340       ],
 341       depends: documentation_deps,
 342       input: manpage,
 343       output: fs.stem(manpage) + '.xml',
 344     )
 345
 346     manpage_path = fs.stem(manpage) + '.' + category.to_string()
 347     manpage_target = custom_target(
 348       command: [
 349         xmlto,
 350         '-m', '@INPUT0@',
 351         '-m', '@INPUT1@',
 352         '--stringparam',
 353         'man.base.url.for.relative.links=' + get_option('prefix') / get_option('mandir'),
 354         'man',
 355         manpage_xml_target,
 356         '-o',
 357         meson.current_build_dir(),
 358       ] + xmlto_extra,
 359       input: [
 360         'manpage-normal.xsl',
 361         'manpage-bold-literal.xsl',
 362       ],
 363       output: manpage_path,
 364       install: true,
 365       install_dir: get_option('mandir') / 'man' + category.to_string(),
 366     )
 367   endif
 368
 369   if get_option('docs').contains('html')
 370     custom_target(
 371       command: asciidoc_common_options + [
 372         '--backend=' + asciidoc_html,
 373         '--doctype=manpage',
 374         '--out-file=@OUTPUT@',
 375         '@INPUT@',
 376       ],
 377       depends: documentation_deps,
 378       input: manpage,
 379       output: fs.stem(manpage) + '.html',
 380       install: true,
 381       install_dir: get_option('datadir') / 'doc/git-doc',
 382     )
 383   endif
 384 endforeach
 385
 386 if get_option('docs').contains('html')
 387   configure_file(
 388     input: 'docinfo-html.in',
 389     output: 'docinfo.html',
 390     copy: true,
 391     install: true,
 392     install_dir: get_option('datadir') / 'doc/git-doc',
 393   )
 394
 395   configure_file(
 396     input: 'docbook-xsl.css',
 397     output: 'docbook-xsl.css',
 398     copy: true,
 399     install: true,
 400     install_dir: get_option('datadir') / 'doc/git-doc',
 401   )
 402
 403   install_symlink('index.html',
 404     install_dir: get_option('datadir') / 'doc/git-doc',
 405     pointing_to: 'git.html',
 406   )
 407
 408   xsltproc = find_program('xsltproc')
 409
 410   user_manual_xml = custom_target(
 411     command: asciidoc_common_options + [
 412       '--backend=' + asciidoc_docbook,
 413       '--doctype=book',
 414       '--out-file=@OUTPUT@',
 415       '@INPUT@',
 416     ],
 417     input: 'user-manual.txt',
 418     output: 'user-manual.xml',
 419     depends: documentation_deps,
 420   )
 421
 422   custom_target(
 423     command: [
 424       xsltproc,
 425       '--xinclude',
 426       '--stringparam', 'html.stylesheet', 'docbook-xsl.css',
 427       '--param', 'generate.consistent.ids', '1',
 428       '--output', '@OUTPUT@',
 429       '@INPUT@',
 430       user_manual_xml,
 431     ],
 432     input: 'docbook.xsl',
 433     output: 'user-manual.html',
 434     install: true,
 435     install_dir: get_option('datadir') / 'doc/git-doc',
 436   )
 437
 438   articles = [
 439     'DecisionMaking.txt',
 440     'MyFirstContribution.txt',
 441     'MyFirstObjectWalk.txt',
 442     'ReviewingGuidelines.txt',
 443     'SubmittingPatches',
 444     'ToolsForGit.txt',
 445     'git-bisect-lk2009.txt',
 446     'git-tools.txt',
 447   ]
 448
 449   foreach article : articles
 450     custom_target(
 451       command: asciidoc_common_options + [
 452         '--backend=' + asciidoc_html,
 453         '--out-file=@OUTPUT@',
 454         '@INPUT@',
 455       ],
 456       input: article,
 457       output: fs.stem(article) + '.html',
 458       depends: documentation_deps,
 459       install: true,
 460       install_dir: get_option('datadir') / 'doc/git-doc',
 461     )
 462   endforeach
 463
 464   asciidoc_html_options = asciidoc_common_options + [
 465     '--backend=' + asciidoc_html,
 466     '--out-file=@OUTPUT@',
 467     '--attribute', 'git-relative-html-prefix=../',
 468     '@INPUT@',
 469   ]
 470
 471   subdir('howto')
 472   subdir('technical')
 473 endif
 474
 475 # Sanity check that we are not missing any tests present in 't/'. This check
 476 # only runs once at configure time and is thus best-effort, only. Furthermore,
 477 # it only verifies man pages for the sake of simplicity.
 478 configured_manpages = manpages.keys() + [ 'git-bisect-lk2009.txt', 'git-tools.txt' ]
 479 actual_manpages = run_command(shell, '-c', 'ls git*.txt scalar.txt',
 480   check: true,
 481   env: script_environment,
 482 ).stdout().strip().split('\n')
 483
 484 if configured_manpages != actual_manpages
 485   missing_manpage = [ ]
 486   foreach actual_manpage : actual_manpages
 487     if actual_manpage not in configured_manpages
 488       missing_manpage += actual_manpage
 489     endif
 490   endforeach
 491   if missing_manpage.length() > 0
 492     error('Man page found, but not configured:\n\n - ' + '\n - '.join(missing_manpage))
 493   endif
 494
 495   superfluous_manpage = [ ]
 496   foreach configured_manpage : configured_manpages
 497     if configured_manpage not in actual_manpages
 498       superfluous_manpage += configured_manpage
 499     endif
 500   endforeach
 501   if superfluous_manpage.length() > 0
 502     error('Man page configured, but not found:\n\n - ' + '\n - '.join(superfluous_manpage))
 503   endif
 504 endif