From 6cf378f0cbe7c7f944637892caeb9058c90a185a Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 26 Apr 2012 04:51:57 -0400 Subject: docs: stop using asciidoc no-inline-literal In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: foo bar which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor ` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential..\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/config.txt | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'Documentation/config.txt') diff --git a/Documentation/config.txt b/Documentation/config.txt index c081657be7..b7d2757d0b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -463,8 +463,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported. core.excludesfile:: In addition to '.gitignore' (per-directory) and '.git/info/exclude', git looks into this file for patterns - of files which are not meant to be tracked. "{tilde}/" is expanded - to the value of `$HOME` and "{tilde}user/" to the specified user's + of files which are not meant to be tracked. "`~/`" is expanded + to the value of `$HOME` and "`~user/`" to the specified user's home directory. See linkgit:gitignore[5]. core.askpass:: @@ -845,7 +845,7 @@ commit.status:: commit.template:: Specify a file to use as the template for new commit messages. - "{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the + "`~/`" is expanded to the value of `$HOME` and "`~user/`" to the specified user's home directory. credential.helper:: @@ -970,7 +970,7 @@ format.thread:: a boolean value, or `shallow` or `deep`. `shallow` threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the - `\--in-reply-to`, and the first patch mail, in this order. + `--in-reply-to`, and the first patch mail, in this order. `deep` threading makes every mail a reply to the previous one. A true boolean value is the same as `shallow`, and a false value disables threading. @@ -1401,7 +1401,7 @@ instaweb.port:: interactive.singlekey:: In interactive commands, allow the user to provide one-letter input with a single key (i.e., without hitting enter). - Currently this is used by the `\--patch` mode of + Currently this is used by the `--patch` mode of linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1], linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this setting is silently ignored if portable keystroke input @@ -1409,13 +1409,13 @@ interactive.singlekey:: log.abbrevCommit:: If true, makes linkgit:git-log[1], linkgit:git-show[1], and - linkgit:git-whatchanged[1] assume `\--abbrev-commit`. You may - override this option with `\--no-abbrev-commit`. + linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may + override this option with `--no-abbrev-commit`. log.date:: Set the default date-time mode for the 'log' command. Setting a value for log.date is similar to using 'git log''s - `\--date` option. Possible values are `relative`, `local`, + `--date` option. Possible values are `relative`, `local`, `default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1] for details. @@ -1605,18 +1605,18 @@ pack.indexVersion:: and this config option ignored whenever the corresponding pack is larger than 2 GB. + -If you have an old git that does not understand the version 2 `{asterisk}.idx` file, +If you have an old git that does not understand the version 2 `*.idx` file, cloning or fetching over a non native protocol (e.g. "http" and "rsync") -that will copy both `{asterisk}.pack` file and corresponding `{asterisk}.idx` file from the +that will copy both `*.pack` file and corresponding `*.idx` file from the other side may give you a repository that cannot be accessed with your -older version of git. If the `{asterisk}.pack` file is smaller than 2 GB, however, +older version of git. If the `*.pack` file is smaller than 2 GB, however, you can use linkgit:git-index-pack[1] on the *.pack file to regenerate -the `{asterisk}.idx` file. +the `*.idx` file. pack.packSizeLimit:: The maximum size of a pack. This setting only affects packing to a file when repacking, i.e. the git:// protocol - is unaffected. It can be overridden by the `\--max-pack-size` + is unaffected. It can be overridden by the `--max-pack-size` option of linkgit:git-repack[1]. The minimum size allowed is limited to 1 MiB. The default is unlimited. Common unit suffixes of 'k', 'm', or 'g' are @@ -1626,8 +1626,8 @@ pager.:: If the value is boolean, turns on or off pagination of the output of a particular git subcommand when writing to a tty. Otherwise, turns on pagination for the subcommand using the - pager specified by the value of `pager.`. If `\--paginate` - or `\--no-pager` is specified on the command line, it takes + pager specified by the value of `pager.`. If `--paginate` + or `--no-pager` is specified on the command line, it takes precedence over this option. To disable pagination for all commands, set `core.pager` or `GIT_PAGER` to `cat`. @@ -1635,9 +1635,9 @@ pretty.:: Alias for a --pretty= format string, as specified in linkgit:git-log[1]. Any aliases defined here can be used just as the built-in pretty formats could. For example, - running `git config pretty.changelog "format:{asterisk} %H %s"` + running `git config pretty.changelog "format:* %H %s"` would cause the invocation `git log --pretty=changelog` - to be equivalent to running `git log "--pretty=format:{asterisk} %H %s"`. + to be equivalent to running `git log "--pretty=format:* %H %s"`. Note that an alias with the same name as a built-in format will be silently ignored. @@ -1750,7 +1750,7 @@ remote..push:: remote..mirror:: If true, pushing to this remote will automatically behave - as if the `\--mirror` option was given on the command line. + as if the `--mirror` option was given on the command line. remote..skipDefaultUpdate:: If true, this remote will be skipped by default when updating -- cgit v1.2.3