undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
f6461b82b9
git-commit-vandalism/Documentation
History
brian m. carlson f6461b82b9 Documentation: fix build with Asciidoctor 2 
Our documentation toolchain has traditionally been built around DocBook
4.5.  This version of DocBook is the last DTD-based version of DocBook.
In 2009, DocBook 5 was introduced using namespaces and its syntax is
expressed in RELAX NG, which is more expressive and allows a wider
variety of syntax forms.

Asciidoctor, one of the alternatives for building our documentation,
moved support for DocBook 4.5 out of core in its recent 2.0 release and
now only supports DocBook 5 in the main release.  The DocBoook 4.5
converter is still available as a separate component, but this is not
available in most distro packages.  This would not be a problem but for
the fact that we use xmlto, which is still stuck in the DocBook 4.5 era.

xmlto performs DTD validation as part of the build process.  This is not
problematic for DocBook 4.5, which has a valid DTD, but it clearly
cannot work for DocBook 5, since no DTD can adequately express its full
syntax.  In addition, even if xmlto did support RELAX NG validation,
that wouldn't be sufficient because it uses the libxml2-based xmllint to
do so, which has known problems with validating interleaves in RELAX NG.

Fortunately, there's an easy way forward: ask Asciidoctor to use its
DocBook 5 backend and tell xmlto to skip validation.  Asciidoctor has
supported DocBook 5 since v0.1.4 in 2013 and xmlto has supported
skipping validation for probably longer than that.

We also need to teach xmlto how to use the namespaced DocBook XSLT
stylesheets instead of the non-namespaced ones it usually uses.
Normally these stylesheets are interchangeable, but the non-namespaced
ones have a bug that causes them not to strip whitespace automatically
from certain elements when namespaces are in use.  This results in
additional whitespace at the beginning of list elements, which is
jarring and unsightly.

We can do this by passing a custom stylesheet with the -x option that
simply imports the namespaced stylesheets via a URL.  Any system with
support for XML catalogs will automatically look this URL up and
reference a local copy instead without us having to know where this
local copy is located.  We know that anyone using xmlto will already
have catalogs set up properly since the DocBook 4.5 DTD used during
validation is also looked up via catalogs.  All major Linux
distributions distribute the necessary stylesheets and have built-in
catalog support, and Homebrew does as well, albeit with a requirement to
set an environment variable to enable catalog support.

On the off chance that someone lacks support for catalogs, it is
possible for xmlto (via xmllint) to download the stylesheets from the
URLs in question, although this will likely perform poorly enough to
attract attention.  People still have the option of using the prebuilt
documentation that we ship, so happily this should not be an impediment.

Finally, we need to filter out some messages from other stylesheets that
occur when invoking dblatex in the CI job.  This tool strips namespaces
much like the unnamespaced DocBook stylesheets and prints similar
messages.  If we permit these messages to be printed to standard error,
our documentation CI job will fail because we check standard error for
unexpected output.  Due to dblatex's reliance on Python 2, we may need
to revisit its use in the future, in which case this problem may go
away, but this can be delayed until a future patch.

The final message we filter is due to libxslt on modern Debian and
Ubuntu.  The patch which they use to implement reproducible ID
generation also prints messages about the ID generation.  While this
doesn't affect our current CI images since they use Ubuntu 16.04 which
lacks this patch, if we upgrade to Ubuntu 18.04 or a modern Debian,
these messages will appear and, like the above messages, cause a CI
failure.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-16 12:20:39 -07:00
..
config doc: fix repeated words 2019-08-11 17:40:07 -07:00
howto doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
RelNotes Git 2.22.1 2019-08-11 17:41:39 -07:00
technical doc: fix repeated words 2019-08-11 17:40:07 -07:00
.gitattributes
.gitignore Merge branch 'js/misc-doc-fixes' 2019-05-09 00:37:27 +09:00
asciidoc.conf
asciidoctor-extensions.rb asciidoctor-extensions: fix spurious space after linkgit 2019-03-11 18:22:07 +09:00
blame-options.txt blame: add config options for the output of ignored or unblamable lines 2019-05-16 11:36:23 +09:00
build-docdep.perl
cat-texi.perl Documentation: remove unneeded argument in cat-texi.perl 2017-01-23 10:56:47 -08:00
cmd-list.perl
CodingGuidelines Merge branch 'jc/post-c89-rules-doc' into maint 2019-07-29 12:38:23 -07:00
config.txt config: learn the "onbranch:" includeIf condition 2019-06-05 14:38:28 -07:00
date-formats.txt Merge branch 'lr/doc-fix-cet' into maint 2017-01-17 15:19:08 -08:00
diff-format.txt log,diff-tree: add --combined-all-paths option 2019-02-07 20:15:25 -08:00
diff-generate-patch.txt log,diff-tree: add --combined-all-paths option 2019-02-07 20:15:25 -08:00
diff-options.txt Merge branch 'nd/diff-parseopt-3' 2019-04-16 19:28:03 +09:00
doc-diff doc-diff: add --cut-header-footer 2019-03-18 15:54:17 +09:00
docbook-xsl.css
docbook.xsl
everyday.txto
fetch-options.txt Merge branch 'ds/fetch-disable-force-notice' 2019-07-09 15:25:46 -07:00
fix-texi.perl
git-add.txt docs: move core.excludesFile from git-add to gitignore 2019-03-08 09:12:45 +09:00
git-am.txt am/cherry-pick/rebase/revert: document --rerere-autoupdate 2019-03-18 10:24:56 +09:00
git-annotate.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-apply.txt Merge branch 'nd/diff-apply-ita' 2018-06-25 13:22:36 -07:00
git-archimport.txt git-archimport.1: specify what kind of Arch we're talking about 2018-09-21 09:28:58 -07:00
git-archive.txt
git-bisect-lk2009.txt doc: fix ASCII art tab spacing 2018-10-23 12:23:09 +09:00
git-bisect.txt Merge branch 'ak/bisect-doc-typofix' 2018-04-25 13:28:56 +09:00
git-blame.txt blame: add the ability to ignore commits and their changes 2019-05-16 11:36:23 +09:00
git-branch.txt Merge branch 'po/doc-branch' into maint 2019-07-29 12:38:16 -07:00
git-bundle.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-cat-file.txt Merge branch 'dt/cat-file-batch-ambiguous' 2019-02-06 22:05:21 -08:00
git-check-attr.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-check-ignore.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-check-mailmap.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-check-ref-format.txt doc: promote "git switch" 2019-04-02 13:57:00 +09:00
git-checkout-index.txt
git-checkout.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
git-cherry-pick.txt cherry-pick/revert: add --skip option 2019-07-02 12:08:08 -07:00
git-cherry.txt
git-citool.txt
git-clean.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
git-clone.txt Merge branch 'qn/clone-doc-use-long-form' 2019-07-11 15:16:48 -07:00
git-column.txt git-column.txt: fix section header 2018-12-26 15:29:30 -08:00
git-commit-graph.txt commit-graph: verify chains with --shallow mode 2019-06-19 20:46:26 -07:00
git-commit-tree.txt commit-tree: utilize parse-options api 2019-03-08 10:31:24 +09:00
git-commit.txt doc: promote "git restore" 2019-05-07 13:04:48 +09:00
git-config.txt Merge branch 'ma/asciidoctor-fixes-more' 2019-04-16 19:28:04 +09:00
git-count-objects.txt count-objects: report alternates via verbose mode 2016-10-10 13:52:37 -07:00
git-credential-cache--daemon.txt
git-credential-cache.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-credential-store.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-credential.txt
git-cvsexportcommit.txt
git-cvsimport.txt Merge branch 'jk/doc-cvs-update' into maint 2016-10-03 13:22:25 -07:00
git-cvsserver.txt doc: typo: s/can not/cannot/ and s/is does/does/ 2019-08-05 10:05:24 -07:00
git-daemon.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-describe.txt describe doc: remove '7-char' abbreviation reference 2019-04-08 17:24:51 +09:00
git-diff-files.txt
git-diff-index.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-diff-tree.txt Documentation/git-diff-tree.txt: fix formatting 2019-04-01 15:17:47 +09:00
git-diff.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-difftool.txt difftool: fallback on merge.guitool 2019-05-13 23:11:59 +09:00
git-fast-export.txt doc: fix repeated words 2019-08-11 17:40:07 -07:00
git-fast-import.txt doc: fix repeated words 2019-08-11 17:40:07 -07:00
git-fetch-pack.txt Documentation: fix several one-character-off spelling errors 2018-04-09 14:15:02 +09:00
git-fetch.txt doc: typo: s/can not/cannot/ and s/is does/does/ 2019-08-05 10:05:24 -07:00
git-filter-branch.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-fmt-merge-msg.txt config.txt: move fmt-merge-msg-config.txt to config/ 2018-10-29 10:17:01 +09:00
git-for-each-ref.txt ref-filter: add worktreepath atom 2019-05-07 13:45:53 +09:00
git-format-patch.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
git-fsck-objects.txt
git-fsck.txt Documentation/git-fsck.txt: include fsck.* config variables 2019-07-29 10:41:18 -07:00
git-gc.txt gc docs: remove incorrect reference to gc.auto=0 2019-04-08 17:01:10 +09:00
git-get-tar-commit-id.txt
git-grep.txt Documentation: turn middle-of-line tabs into spaces 2019-03-07 09:25:32 +09:00
git-gui.txt doc: git-gui browser does not default to HEAD 2017-01-13 12:23:28 -08:00
git-hash-object.txt hash-object doc: stop mentioning git-cvsimport 2019-05-28 10:47:42 -07:00
git-help.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-http-backend.txt Documentation: turn middle-of-line tabs into spaces 2019-03-07 09:25:32 +09:00
git-http-fetch.txt http-fetch: make -a standard behaviour 2018-04-24 10:55:02 +09:00
git-http-push.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-imap-send.txt git-imap-send.txt: move imap.* to a separate file 2018-10-29 10:17:02 +09:00
git-index-pack.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-init-db.txt
git-init.txt Merge branch 'km/init-doc-typofix' 2019-02-06 22:05:21 -08:00
git-instaweb.txt git-instaweb: add Python builtin http.server support 2019-01-28 10:57:44 -08:00
git-interpret-trailers.txt interpret-trailers.txt: start the desc line with a capital letter 2019-04-01 15:49:47 +09:00
git-log.txt documentation: mention --no-use-mailmap and log.mailmap false setting 2019-07-15 11:44:26 -07:00
git-ls-files.txt doc/ls-files: put nested list for "-t" option into block 2019-04-23 10:25:04 +09:00
git-ls-remote.txt Documentation: turn middle-of-line tabs into spaces 2019-03-07 09:25:32 +09:00
git-ls-tree.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-mailinfo.txt
git-mailsplit.txt
git-merge-base.txt doc: promote "git switch" 2019-04-02 13:57:00 +09:00
git-merge-file.txt
git-merge-index.txt
git-merge-one-file.txt
git-merge-tree.txt
git-merge.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
git-mergetool--lib.txt mergetool: use get_merge_tool function 2019-05-13 23:11:59 +09:00
git-mergetool.txt mergetool: fallback to tool when guitool unavailable 2019-05-13 23:11:59 +09:00
git-mktag.txt
git-mktree.txt Documentation: normalize spelling of 'normalised' 2018-04-09 14:15:07 +09:00
git-multi-pack-index.txt multi-pack-index: prepare 'repack' subcommand 2019-06-11 10:34:40 -07:00
git-mv.txt
git-name-rev.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-notes.txt Documentation: turn middle-of-line tabs into spaces 2019-03-07 09:25:32 +09:00
git-p4.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-pack-objects.txt doc: fix repeated words 2019-08-11 17:40:07 -07:00
git-pack-redundant.txt
git-pack-refs.txt
git-parse-remote.txt
git-patch-id.txt doc: remove unsupported parameter from patch-id 2017-07-28 14:41:32 -07:00
git-prune-packed.txt
git-prune.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-pull.txt doc: typo: s/can not/cannot/ and s/is does/does/ 2019-08-05 10:05:24 -07:00
git-push.txt doc: fix repeated words 2019-08-11 17:40:07 -07:00
git-quiltimport.txt git-quiltimport: add --keep-non-patch option 2019-01-07 15:29:34 -08:00
git-range-diff.txt range-diff doc: add a section about output stability 2018-11-12 12:05:38 +09:00
git-read-tree.txt Merge branch 'nd/checkout-m' 2019-04-25 16:41:14 +09:00
git-rebase.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
git-receive-pack.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-reflog.txt reflog expire: cover reflog from all worktrees 2018-10-22 13:32:54 +09:00
git-remote-ext.txt Merge branch 'js/check-docs-exe' 2019-04-22 11:14:46 +09:00
git-remote-fd.txt docs: move gitremote-helpers into section 7 2019-04-01 14:00:53 +09:00
git-remote-helpers.txto docs: move gitremote-helpers into section 7 2019-04-01 14:00:53 +09:00
git-remote.txt doc: promote "git switch" 2019-04-02 13:57:00 +09:00
git-repack.txt doc: fix repeated words 2019-08-11 17:40:07 -07:00
git-replace.txt replace: introduce --convert-graft-file 2018-04-30 11:12:30 +09:00
git-request-pull.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-rerere.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
git-reset.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
git-restore.txt restore: fix typo in docs 2019-08-05 12:39:39 -07:00
git-rev-list.txt rev-list: teach --no-object-names to enable piping 2019-06-20 13:13:04 -07:00
git-rev-parse.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-revert.txt Merge branch 'ra/cherry-pick-revert-skip' 2019-07-19 11:30:21 -07:00
git-rm.txt treewide: correct several "up-to-date" to "up to date" 2017-08-23 12:17:22 -07:00
git-send-email.txt Merge branch 'cm/send-email-document-req-modules' 2019-06-21 11:24:10 -07:00
git-send-pack.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-sh-i18n--envsubst.txt
git-sh-i18n.txt
git-sh-setup.txt
git-shell.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-shortlog.txt git-[short]log.txt: unify quoted standalone -- 2018-04-18 12:49:26 +09:00
git-show-branch.txt Documentation/git-show-branch: avoid literal {apostrophe} 2019-04-10 12:05:03 +09:00
git-show-index.txt show-index: update documentation for index v2 2018-05-29 00:28:22 +09:00
git-show-ref.txt git-show-ref.txt: fix order of flags 2019-01-10 10:29:05 -08:00
git-show.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-stage.txt
git-stash.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
git-status.txt Documentation/git-status: fix titles in porcelain v2 section 2019-04-01 17:46:26 +09:00
git-stripspace.txt
git-submodule.txt Merge branch 'dl/submodule-set-branch' 2019-04-25 16:41:18 +09:00
git-svn.txt Merge branch 'tz/git-svn-doc-markup-fix' 2019-05-09 00:37:23 +09:00
git-switch.txt Declare both git-switch and git-restore experimental 2019-05-07 13:04:48 +09:00
git-symbolic-ref.txt
git-tag.txt tag: add tag.gpgSign config option to force all tags be GPG-signed 2019-06-05 14:39:28 -07:00
git-tools.txt doc: replace or.cz gitwiki link with git.wiki.kernel.org 2017-04-20 22:05:37 -07:00
git-unpack-file.txt
git-unpack-objects.txt
git-update-index.txt Merge branch 'jc/update-index-doc' 2018-08-20 11:33:50 -07:00
git-update-ref.txt Merge branch 'ah/doc-updates' into maint 2018-11-21 22:58:07 +09:00
git-update-server-info.txt update-server-info: avoid needless overwrites 2019-05-15 14:07:37 +09:00
git-upload-archive.txt
git-upload-pack.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-var.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-verify-commit.txt
git-verify-pack.txt
git-verify-tag.txt builtin/verify-tag: add --format to verify-tag 2017-01-17 16:10:22 -08:00
git-web--browse.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-whatchanged.txt
git-worktree.txt doc: fix typos in man pages 2019-03-18 14:45:21 +09:00
git-write-tree.txt
git.txt Merge branch 'sg/git-C-empty-doc' 2019-07-11 15:16:48 -07:00
gitattributes.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
gitcli.txt doc: promote "git restore" 2019-05-07 13:04:48 +09:00
gitcore-tutorial.txt doc: promote "git switch" 2019-04-02 13:57:00 +09:00
gitcredentials.txt doc: clarify gitcredentials path component matching 2018-09-27 15:24:50 -07:00
gitcvs-migration.txt Merge branch 'sb/doc-unify-bottom' 2017-02-15 12:54:20 -08:00
gitdiffcore.txt log -G: ignore binary files 2018-12-26 14:59:37 -08:00
giteveryday.txt doc: promote "git restore" 2019-05-07 13:04:48 +09:00
gitglossary.txt Documentation: unify bottom "part of git suite" lines 2017-02-09 15:14:01 -08:00
githooks.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
gitignore.txt Merge branch 'an/ignore-doc-update' into maint 2019-07-25 14:27:13 -07:00
gitk.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
gitmodules.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
gitnamespaces.txt doc: mention transfer data leaks in more places 2016-11-14 11:23:07 -08:00
gitremote-helpers.txt Merge branch 'js/check-docs-exe' 2019-04-22 11:14:46 +09:00
gitrepository-layout.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
gitrevisions.txt push doc: correct lies about how push refspecs work 2018-08-31 14:04:06 -07:00
gitsubmodules.txt gitsubmodules: align html and nroff lists 2019-05-28 09:42:06 -07:00
gittutorial-2.txt doc: promote "git restore" 2019-05-07 13:04:48 +09:00
gittutorial.txt doc: promote "git restore" 2019-05-07 13:04:48 +09:00
gitweb.conf.txt Merge branch 'cb/doco-mono' 2019-04-22 11:14:45 +09:00
gitweb.txt doc: don't use git.kernel.org as example gitweb URL 2019-06-24 12:37:21 -07:00
gitworkflows.txt doc: promote "git switch" 2019-04-02 13:57:00 +09:00
glossary-content.txt doc: typo: s/can not/cannot/ and s/is does/does/ 2019-08-05 10:05:24 -07:00
howto-index.sh
i18n.txt doc: camelCase the i18n config variables to improve readability 2017-07-17 15:11:26 -07:00
install-doc-quick.sh install-doc-quick: allow specifying what ref to install 2017-12-12 16:49:40 -08:00
install-webdoc.sh
line-range-format.txt
lint-gitlink.perl
mailmap.txt
Makefile Documentation: fix build with Asciidoctor 2 2019-09-16 12:20:39 -07:00
manpage-1.72.xsl
manpage-base-url.xsl.in
manpage-base.xsl
manpage-bold-literal.xsl
manpage-normal.xsl
manpage-quote-apos.xsl
manpage-suppress-sp.xsl
manpage.xsl Documentation: fix build with Asciidoctor 2 2019-09-16 12:20:39 -07:00
merge-options.txt Merge branch 'vv/merge-squash-with-explicit-commit' into maint 2019-07-25 14:27:10 -07:00
merge-strategies.txt merge: add merge.renames config setting 2018-05-08 16:19:41 +09:00
MyFirstContribution.txt doc: improve usage string in MyFirstContribution 2019-06-24 10:55:38 -07:00
pretty-formats.txt Merge branch 'aw/pretty-trailers' 2019-03-07 09:59:52 +09:00
pretty-options.txt
pull-fetch-param.txt fetch doc: correct grammar in --force docs 2018-09-20 09:40:03 -07:00
rev-list-options.txt Merge branch 'jk/check-connected-with-alternates' 2019-07-19 11:30:21 -07:00
revisions.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
sequencer.txt cherry-pick/revert: add --skip option 2019-07-02 12:08:08 -07:00
SubmittingPatches doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
texi.xsl Documentation: add XSLT to fix DocBook for Texinfo 2017-01-23 10:56:53 -08:00
trace2-target-values.txt trace2: update docs to describe system/global config settings 2019-04-16 13:37:07 +09:00
transfer-data-leaks.txt doc: mention transfer data leaks in more places 2016-11-14 11:23:07 -08:00
urls-remotes.txt
urls.txt docs: move gitremote-helpers into section 7 2019-04-01 14:00:53 +09:00
user-manual.conf
user-manual.txt doc: promote "git restore" 2019-05-07 13:04:48 +09:00