git-commit-vandalism/Documentation
Jeff King c08fd6388c doc: put literal block delimiter around table
The git-read-tree manpage has a table that is meant to
be shown with its spacing exactly as it is in the source. We
mark it as a "literal paragraph" by indenting each line by
at least one space. This renders OK with asciidoc for both
the HTML and manpage versions.

But there are two problems when we render it with
asciidoctor.

The first is that some lines mix tabs and spaces.  Even if
asciidoctor is correctly configured for 8-space tabs, it
seems to handle this case differently, soaking up some of
the initial literal-paragraph spaces and mis-aligning the
table text.

The second problem is that the table uses blank lines to
group rows. But as blank lines separate paragraphs in
asciidoc, this actually means that each chunk of the table
is rendered in its own pre-formatted <div> block. This
happens even with vanilla asciidoc, but there's no visible
result because the literal paragraphs aren't styled in any
special way. But with asciidoctor (or at least the styles
used on git-scm.com), literal paragraphs are styled with a
different background.  This breaks the table into a visually
distracting sequence of chunks.

We can fix both by adding a literal-paragraph block
delimiter. That turns the whole table into a single block
(for both implementations) and causes asciidoctor to render
the indentation as it is in the source.

Reported-at: https://github.com/git/git-scm.com/issues/1023
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-09-24 10:09:45 +09:00
..
howto Merge branch 'po/fix-doc-merge-base-illustration' into maint 2016-10-28 09:01:21 -07:00
RelNotes Git 2.12.4 2017-07-30 15:06:06 -07:00
technical Merge branch 'sb/in-core-index-doc' 2017-01-31 13:14:59 -08:00
.gitattributes
.gitignore doc: generate a list of valid merge tools 2013-02-02 21:46:52 -08:00
asciidoc.conf Documentation: avoid poor-man's small caps GIT 2013-02-01 13:53:25 -08:00
asciidoctor-extensions.rb Documentation: implement linkgit macro for Asciidoctor 2017-01-31 12:18:18 -08:00
blame-options.txt Merge branch 'bc/blame-doc-fix' 2017-02-24 10:48:08 -08: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 command-list: prepare machinery for upcoming "common groups" section 2015-05-21 13:03:37 -07:00
CodingGuidelines CodingGuidelines: clarify multi-line brace style 2017-01-17 14:32:47 -08:00
config.txt Merge branch 'km/config-grammofix' into maint 2017-03-28 13:52:29 -07:00
date-formats.txt Merge branch 'lr/doc-fix-cet' into maint 2017-01-17 15:19:08 -08:00
diff-config.txt Merge branch 'rh/diff-orderfile-doc' 2017-01-23 15:59:23 -08:00
diff-format.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
diff-generate-patch.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
diff-heuristic-options.txt diff: retire "compaction" heuristics 2016-12-23 12:32:22 -08:00
diff-options.txt Merge branch 'rh/diff-orderfile-doc' 2017-01-23 15:59:23 -08:00
docbook-xsl.css
docbook.xsl
everyday.txto Documentation: fix linkgit references 2016-05-09 15:44:14 -07:00
fetch-options.txt Merge branch 'nd/shallow-deepen' 2016-10-10 14:03:50 -07:00
fix-texi.perl
fmt-merge-msg-config.txt Documentation: include 'merge.branchdesc' for merge and config as well 2015-05-28 12:38:46 -07:00
git-add.txt add: document the chmod option 2016-09-12 15:03:32 -07:00
git-am.txt Merge branch 'mm/doc-tt' 2016-07-13 11:24:14 -07:00
git-annotate.txt blame: honor the diff heuristic options and config 2016-09-19 10:25:11 -07:00
git-apply.txt git-apply.txt: mention the behavior inside a subdir 2016-03-24 10:16:52 -07:00
git-archimport.txt Documentation: the name of the system is 'Git', not 'git' 2013-02-01 13:53:33 -08:00
git-archive.txt docs: clarify remote restrictions for git-upload-archive 2014-02-28 09:55:35 -08:00
git-bisect-lk2009.txt doc: more consistency in environment variables format 2016-06-08 12:04:37 -07:00
git-bisect.txt Merge branch 'ad/bisect-terms' into maint 2017-01-31 13:32:10 -08:00
git-blame.txt Merge branch 'jc/blame-reverse' 2016-10-10 14:03:51 -07:00
git-branch.txt doc: add note about ignoring '--no-create-reflog' 2017-02-01 15:53:40 -08:00
git-bundle.txt transport: drop support for git-over-rsync 2016-02-01 13:07:41 -08:00
git-cat-file.txt cat-file: support --textconv/--filters in batch mode 2016-09-11 14:48:15 -07:00
git-check-attr.txt usage: do not insist that standard input must come from a file 2015-10-16 15:27:52 -07:00
git-check-ignore.txt Documentation: fix linkgit references 2016-05-09 15:44:14 -07:00
git-check-mailmap.txt builtin: add git-check-mailmap command 2013-07-13 10:19:37 -07:00
git-check-ref-format.txt git-check-ref-format: clarify documentation for --normalize 2017-02-21 13:02:42 -08:00
git-checkout-index.txt
git-checkout.txt checkout.txt: document a common case that ignores ambiguation rules 2016-09-21 08:44:41 -07:00
git-cherry-pick.txt Merge branch 'mm/doc-tt' into maint 2016-07-28 11:25:54 -07:00
git-cherry.txt Documentation: revamp git-cherry(1) 2013-11-27 12:16:49 -08:00
git-citool.txt
git-clean.txt doc: typeset short command-line options as literal 2016-06-28 08:20:52 -07:00
git-clone.txt Merge branch 'nd/shallow-deepen' 2016-10-10 14:03:50 -07:00
git-column.txt doc: remote author/documentation sections from more pages 2014-01-27 08:34:34 -08:00
git-commit-tree.txt Merge branch 'mm/doc-tt' into maint 2016-07-28 11:25:54 -07:00
git-commit.txt git-commit.txt: list post-rewrite in HOOKS section 2017-03-20 10:53:29 -07:00
git-config.txt Merge branch 'dg/document-git-c-in-git-config-doc' into maint 2016-09-08 21:35:56 -07: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 credential-cache: close stderr in daemon process 2014-09-16 11:11:58 -07:00
git-credential-cache.txt credential-cache--daemon: disallow relative socket path 2016-02-23 12:56:27 -08:00
git-credential-store.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-credential.txt Documentation: make AsciiDoc links always point to HTML files 2013-09-06 14:49:06 -07:00
git-cvsexportcommit.txt Documentation: the name of the system is 'Git', not 'git' 2013-02-01 13:53:33 -08:00
git-cvsimport.txt Merge branch 'jk/doc-cvs-update' into maint 2016-10-03 13:22:25 -07:00
git-cvsserver.txt doc: typeset HEAD and variants as literal 2016-06-28 08:36:45 -07:00
git-daemon.txt doc: typeset HEAD and variants as literal 2016-06-28 08:36:45 -07:00
git-describe.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-diff-files.txt
git-diff-index.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-diff-tree.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-diff.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
git-difftool.txt Document the --no-gui option in difftool 2017-02-08 13:30:28 -08:00
git-fast-export.txt doc: convert \--option to --option 2015-05-12 22:14:46 -07:00
git-fast-import.txt Merge branch 'mm/doc-tt' 2016-07-13 11:24:14 -07:00
git-fetch-pack.txt upload-pack: optionally allow fetching any sha1 2016-11-18 13:06:14 -08:00
git-fetch.txt Merge branch 'mm/push-social-engineering-attack-doc' into maint 2017-01-17 15:19:10 -08:00
git-filter-branch.txt filter-branch: fix --prune-empty on parentless commits 2017-03-03 12:43:37 -08:00
git-fmt-merge-msg.txt Documentation/fmt-merge-msg: fix markup in example 2016-10-28 05:51:51 -07:00
git-for-each-ref.txt Merge branch 'jk/trailers-placeholder-in-pretty' 2016-12-19 14:45:34 -08:00
git-format-patch.txt doc: change erroneous --[no]-whatever into --[no-]whatever 2017-03-20 10:04:57 -07:00
git-fsck-objects.txt
git-fsck.txt fsck: optionally show more helpful info for broken links 2016-07-18 15:15:59 -07:00
git-gc.txt docs/git-gc: fix default value for --aggressiveDepth 2017-02-24 09:59:12 -08:00
git-get-tar-commit-id.txt usage: do not insist that standard input must come from a file 2015-10-16 15:27:52 -07:00
git-grep.txt grep: enable recurse-submodules to work on <tree> objects 2016-12-22 11:47:33 -08: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 usage: do not insist that standard input must come from a file 2015-10-16 15:27:52 -07:00
git-help.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-http-backend.txt doc: more consistency in environment variables format 2016-06-08 12:04:37 -07:00
git-http-fetch.txt Documentation: the name of the system is 'Git', not 'git' 2013-02-01 13:53:33 -08:00
git-http-push.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-imap-send.txt imap-send: use cURL automatically when NO_OPENSSL defined 2015-03-10 15:19:05 -07:00
git-index-pack.txt index-pack: add --max-input-size=<size> option 2016-08-24 12:31:05 -07:00
git-init-db.txt Documentation: the name of the system is 'Git', not 'git' 2013-02-01 13:53:33 -08:00
git-init.txt init: document dotfiles exclusion on template copy 2017-02-17 15:57:21 -08:00
git-instaweb.txt doc: change configuration variables format 2016-06-08 12:04:55 -07:00
git-interpret-trailers.txt doc: mention user-configured trailers 2016-11-21 12:49:57 -08:00
git-log.txt Merge branch 'mj/log-show-signature-conf' 2016-07-11 10:31:08 -07:00
git-ls-files.txt ls-files: add pathspec matching for submodules 2016-10-10 12:14:58 -07:00
git-ls-remote.txt ls-remote: add support for showing symrefs 2016-01-19 10:07:56 -08:00
git-ls-tree.txt doc: typeset HEAD and variants as literal 2016-06-28 08:36:45 -07:00
git-mailinfo.txt Merge branch 'va/mailinfo-doc-typofix' into maint 2016-05-26 13:17:14 -07:00
git-mailsplit.txt mailsplit: support unescaping mboxrd messages 2016-06-06 11:14:43 -07:00
git-merge-base.txt doc: fix merge-base ASCII art tab spacing 2016-10-21 09:46:48 -07:00
git-merge-file.txt merge-file: clamp exit code to maximum 127 2015-10-29 12:10:23 -07:00
git-merge-index.txt The name of the hash function is "SHA-1", not "SHA1" 2013-04-15 11:08:37 -07:00
git-merge-one-file.txt
git-merge-tree.txt use 'tree-ish' instead of 'treeish' 2013-09-04 15:02:56 -07:00
git-merge.txt merge: add '--continue' option as a synonym for 'git commit' 2016-12-14 10:02:04 -08:00
git-mergetool--lib.txt Documentation: the name of the system is 'Git', not 'git' 2013-02-01 13:53:33 -08:00
git-mergetool.txt mergetool: honor -O<orderfile> 2016-10-11 10:04:31 -07:00
git-mktag.txt usage: do not insist that standard input must come from a file 2015-10-16 15:27:52 -07:00
git-mktree.txt doc: typeset short command-line options as literal 2016-06-28 08:20:52 -07:00
git-mv.txt doc: typeset short command-line options as literal 2016-06-28 08:20:52 -07:00
git-name-rev.txt use 'commit-ish' instead of 'committish' 2013-09-04 15:03:03 -07:00
git-notes.txt doc: typeset short command-line options as literal 2016-06-28 08:20:52 -07:00
git-p4.txt Merge branch 'ls/p4-retry-thrice' 2017-01-18 15:12:12 -08:00
git-pack-objects.txt document git-repack interaction of pack.threads and pack.windowMemory 2016-08-10 10:55:13 -07:00
git-pack-redundant.txt
git-pack-refs.txt Documentation: remove --prune from pack-refs examples 2013-07-18 16:23:46 -07:00
git-parse-remote.txt
git-patch-id.txt usage: do not insist that standard input must come from a file 2015-10-16 15:27:52 -07:00
git-prune-packed.txt Documentation: adjust document title underlining 2014-10-13 13:35:18 -07:00
git-prune.txt worktree: new place for "git prune --worktrees" 2015-06-29 08:48:44 -07:00
git-pull.txt Merge branch 'mm/push-social-engineering-attack-doc' into maint 2017-01-17 15:19:10 -08:00
git-push.txt Merge branch 'bw/push-submodule-only' 2017-02-10 12:52:23 -08:00
git-quiltimport.txt doc: more consistency in environment variables format 2016-06-08 12:04:37 -07:00
git-read-tree.txt doc: put literal block delimiter around table 2017-09-24 10:09:45 +09:00
git-rebase.txt Merge branch 'nd/rebase-forget' 2016-12-19 14:45:35 -08:00
git-receive-pack.txt receive-pack: allow a maximum input size to be specified 2016-08-24 12:31:05 -07:00
git-reflog.txt git-reflog: add exists command 2015-07-21 14:08:14 -07:00
git-remote-ext.txt doc: add some crossrefs between manual pages 2014-11-11 14:47:04 -08:00
git-remote-fd.txt Spelling fixes 2016-08-11 14:35:42 -07:00
git-remote-helpers.txto Rename {git- => git}remote-helpers.txt 2013-02-01 14:12:34 -08:00
git-remote-testgit.txt Merge branch 'jk/remote-helpers-doc' 2013-02-07 14:41:45 -08:00
git-remote.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-repack.txt Merge branch 'ms/document-pack-window-memory-is-per-thread' 2016-08-12 09:47:35 -07:00
git-replace.txt doc: change environment variables format 2016-06-08 12:04:37 -07:00
git-request-pull.txt doc: show usage of branch description 2015-09-14 12:50:33 -07:00
git-rerere.txt *config.txt: stick to camelCase naming convention 2015-03-13 22:13:46 -07:00
git-reset.txt reset: add an example of how to split a commit into two 2017-02-16 13:38:02 -08:00
git-rev-list.txt Merge branch 'jk/date-local' 2015-10-05 12:30:13 -07:00
git-rev-parse.txt rev-parse doc: pass "--" to rev-parse in the --prefix example 2017-01-10 13:22:19 -08:00
git-revert.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-rm.txt rm: better document side effects when removing a submodule 2014-01-07 14:34:06 -08:00
git-send-email.txt doc: change erroneous --[no]-whatever into --[no-]whatever 2017-03-20 10:04:57 -07:00
git-send-pack.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-sh-i18n--envsubst.txt correct a few doubled-word nits in comments and documentation 2012-03-28 11:18:35 -07:00
git-sh-i18n.txt
git-sh-setup.txt doc: more consistency in environment variables format 2016-06-08 12:04:37 -07:00
git-shell.txt doc: typeset short command-line options as literal 2016-06-28 08:20:52 -07:00
git-shortlog.txt shortlog: test and document --committer option 2016-12-16 09:39:10 -08:00
git-show-branch.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-show-index.txt usage: do not insist that standard input must come from a file 2015-10-16 15:27:52 -07:00
git-show-ref.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-show.txt doc: convert \--option to --option 2015-05-12 22:14:46 -07:00
git-stage.txt Documentation: adjust document title underlining 2014-10-13 13:35:18 -07:00
git-stash.txt Documentation/stash: remove mention of git reset --hard 2017-02-13 14:20:38 -08:00
git-status.txt git-status.txt: describe --porcelain=v2 format 2016-08-11 11:15:56 -07:00
git-stripspace.txt usage: do not insist that standard input must come from a file 2015-10-16 15:27:52 -07:00
git-submodule.txt Merge branch 'jk/doc-submodule-markup-fix' 2017-02-15 14:56:40 -08:00
git-svn.txt git-svn: document useLogAuthor and addAuthorFrom config keys 2016-12-12 10:49:50 -08:00
git-symbolic-ref.txt git symbolic-ref --delete $symref 2012-10-21 12:17:38 -07:00
git-tag.txt Merge branch 'cw/log-updates-for-all-refs-really' 2017-02-03 11:25:19 -08:00
git-tools.txt Documentation/git-tools: retire manually-maintained list 2015-07-28 13:21:59 -07:00
git-unpack-file.txt
git-unpack-objects.txt unpack-objects: add --max-input-size=<size> option 2016-08-24 12:31:05 -07:00
git-update-index.txt doc: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-update-ref.txt update-ref and tag: add --create-reflog arg 2015-07-21 14:08:35 -07:00
git-update-server-info.txt Documentation: use [verse] for SYNOPSIS sections 2011-07-06 14:26:26 -07:00
git-upload-archive.txt Documentation: match underline with the text 2015-10-22 10:16:12 -07:00
git-upload-pack.txt upload-pack.c: use parse-options API 2016-05-31 10:17:20 -07:00
git-var.txt Documentation: the name of the system is 'Git', not 'git' 2013-02-01 13:53:33 -08:00
git-verify-commit.txt Merge branch 'dn/gpg-doc' into maint 2016-07-06 13:06:36 -07:00
git-verify-pack.txt git-verify-pack.txt: fix inconsistent spelling of "packfile" 2015-05-17 11:24:57 -07:00
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: typeset long command-line options as literal 2016-06-28 08:36:45 -07:00
git-whatchanged.txt whatchanged: document its historical nature 2013-08-13 09:01:54 -07:00
git-worktree.txt Merge branch 'bc/worktree-doc-fix-detached' 2017-02-24 10:48:10 -08:00
git-write-tree.txt
git.txt Git 2.12.3 2017-05-05 13:33:22 +09:00
gitattributes.txt docs: warn about possible '=' in clean/smudge filter process values 2016-12-06 11:29:52 -08:00
gitcli.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
gitcore-tutorial.txt Merge branch 'sb/doc-unify-bottom' 2017-02-15 12:54:20 -08:00
gitcredentials.txt credential: let empty credential specs reset helper list 2016-02-26 10:58:14 -08:00
gitcvs-migration.txt Merge branch 'sb/doc-unify-bottom' 2017-02-15 12:54:20 -08:00
gitdiffcore.txt docs/diffcore: unquote "Complete Rewrites" in headers 2017-02-28 11:34:38 -08:00
giteveryday.txt giteveryday: unbreak rendering with AsciiDoctor 2017-01-07 14:03:40 -08:00
gitglossary.txt Documentation: unify bottom "part of git suite" lines 2017-02-09 15:14:01 -08:00
githooks.txt push options: {pre,post}-receive hook learns about push options 2016-07-14 15:50:17 -07:00
gitignore.txt doc: change configuration variables format 2016-06-08 12:04:55 -07:00
gitk.txt Merge branch 'sb/remove-gitview' 2017-01-18 15:12:18 -08:00
gitmodules.txt Merge branch 'bw/submodule-branch-dot-doc' into maint 2016-10-28 09:01:19 -07:00
gitnamespaces.txt doc: mention transfer data leaks in more places 2016-11-14 11:23:07 -08:00
gitremote-helpers.txt Merge branch 'jk/doc-remote-helpers-markup-fix' 2017-02-15 14:56:40 -08:00
gitrepository-layout.txt Merge branch 'sb/doc-unify-bottom' 2017-02-15 12:54:20 -08:00
gitrevisions.txt doc: gitrevisions - clarify 'latter case' is revision walk 2016-08-13 19:36:44 -07:00
gittutorial-2.txt Documentation: unify bottom "part of git suite" lines 2017-02-09 15:14:01 -08:00
gittutorial.txt Documentation: unify bottom "part of git suite" lines 2017-02-09 15:14:01 -08:00
gitweb.conf.txt gitweb: use highlight's shebang detection 2016-09-25 16:39:11 -07:00
gitweb.txt doc: change environment variables format 2016-06-08 12:04:37 -07:00
gitworkflows.txt Documentation: unify bottom "part of git suite" lines 2017-02-09 15:14:01 -08:00
glossary-content.txt Merge branch 'rn/glossary-typofix' into HEAD 2016-05-18 14:40:14 -07:00
howto-index.sh howto-index.sh: use the $( ... ) construct for command substitution 2014-04-17 11:14:57 -07:00
i18n.txt Documentation/i18n.txt: clarify character encoding support 2015-07-01 14:55:53 -07:00
install-doc-quick.sh
install-webdoc.sh install-webdoc.sh: use the $( ... ) construct for command substitution 2014-04-17 11:14:58 -07:00
line-range-format.txt Documentation: change -L:<regex> to -L:<funcname> 2015-04-20 11:05:50 -07:00
lint-gitlink.perl ci: validate "linkgit:" in documentation 2016-05-10 11:15:04 -07:00
mailmap.txt Merge branch 'jk/mailmap-from-blob' 2013-01-05 23:41:42 -08:00
Makefile Merge branch 'bc/use-asciidoctor-opt' 2017-02-02 13:36:57 -08:00
manpage-1.72.xsl
manpage-base-url.xsl.in
manpage-base.xsl Documentation: use "spurious .sp" XSLT if DOCBOOK_SUPPRESS_SP is set 2009-04-01 11:02:42 -07:00
manpage-bold-literal.xsl
manpage-normal.xsl Documentation: move "spurious .sp" code into manpage-base.xsl 2009-03-27 00:33:19 -07:00
manpage-quote-apos.xsl
manpage-suppress-sp.xsl
merge-config.txt doc: change environment variables format 2016-06-08 12:04:37 -07:00
merge-options.txt Merge branch 'kf/gpg-sig-verification-doc' 2016-05-17 14:38:39 -07:00
merge-strategies.txt merge-strategies.txt: fix typo 2016-02-22 10:42:52 -08:00
pretty-formats.txt pretty: add %(trailers) format for displaying trailers of a commit message 2016-12-11 13:58:41 -08:00
pretty-options.txt Merge branch 'tr/doc-tt' into maint 2016-07-06 13:06:34 -07:00
pull-fetch-param.txt docs: Explain the purpose of fetch's and pull's <refspec> parameter. 2014-06-12 09:59:13 -07:00
rev-list-options.txt rev-list-options.txt: update --all about HEAD 2017-02-08 13:37:32 -08:00
revisions.txt revision: new rev^-n shorthand for rev^n..rev 2016-09-27 10:59:28 -07:00
sequencer.txt
SubmittingPatches doc: clarify distinction between sign-off and pgp-signing 2017-01-27 13:41:30 -08:00
texi.xsl Documentation: add XSLT to fix DocBook for Texinfo 2017-01-23 10:56:53 -08:00
transfer-data-leaks.txt doc: mention transfer data leaks in more places 2016-11-14 11:23:07 -08:00
urls-remotes.txt Documentation: match underline with the text 2015-10-22 10:16:12 -07:00
urls.txt transport: drop support for git-over-rsync 2016-02-01 13:07:41 -08:00
user-manual.conf docs: monospace listings in docbook output 2012-08-07 14:30:52 -07:00
user-manual.txt asciidoctor: fix user-manual to be built by asciidoctor 2017-01-13 10:30:16 -08:00