docs: remove {litdd} usage
Subsystems (2)
PATCH 1/1 docs: remove {litdd} usage
From: samonon <[email protected]>
*** Problem.
{litdd} is used as alias for -- (when not inside backticks) because -- is a reserved text in asciidoc. There is some problems with this:
- need to remember that in some cases -- should be replaced with {litdd}
- unnecessary config options when exporting adoc to other formats
- in HTML it looks like "--" instead of "--" (it works, but browser should correctly decode hex symbols in html link:
see htmldocs/git-sh-i18n.html)
*** Solution
For better readability just escape -- using \.
This is default asciidoc mechanism that don't need any configuration. Tested with "make all doc" - links inside linkgit: work.
---
docs: remove {litdd} usage
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2215%2FMuxaJIbI4%2Fremove-litdd-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2215/MuxaJIbI4/remove-litdd-v1
Pull-Request: https://github.com/git/git/pull/2215
Documentation/Makefile | 1 - Documentation/SubmittingPatches | 2 +- Documentation/asciidoc.conf.in | 1 - Documentation/config/browser.adoc | 2 +- Documentation/config/core.adoc | 2 +- Documentation/git-archimport.adoc | 6 +++--- Documentation/git-credential-cache--daemon.adoc | 6 +++--- Documentation/git-fsmonitor--daemon.adoc | 12 ++++++------ Documentation/git-help.adoc | 6 +++--- Documentation/git-instaweb.adoc | 6 +++--- Documentation/git-mergetool--lib.adoc | 10 +++++----- Documentation/git-sh-i18n--envsubst.adoc | 10 +++++----- Documentation/git-sh-i18n.adoc | 2 +- Documentation/git-update-index.adoc | 2 +- Documentation/git-web--browse.adoc | 10 +++++----- Documentation/lint-gitlink.perl | 2 +- Documentation/meson.build | 1 - contrib/subtree/Makefile | 1 - t/t0450-txt-doc-vs-help.sh | 2 +- 19 files changed, 40 insertions(+), 44 deletions(-)
Documentation/Makefile +0 -1
@@ -223,7 +223,6 @@ ASCIIDOC_HTML = xhtml5 ASCIIDOC_DOCBOOK = docbook5 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions -ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' ASCIIDOC_EXTRA += -adocinfo=shared ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS DBLATEX_COMMON =
Documentation/SubmittingPatches +1 -1
@@ -35,7 +35,7 @@ The people who may need to know are the ones who worked on the code you are touching. These people happen to be the ones who are most likely to be knowledgeable enough to help you, but they have no obligation to help you (i.e. you ask them for help, -you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would +you don't demand). +git log -p \-- _$area_you_are_modifying_+ would help you find out who they are. . You get comments and suggestions for improvements. You may even get
Documentation/asciidoc.conf.in +0 -1
@@ -20,7 +20,6 @@ backslash=\ tilde=~ apostrophe=' backtick=` -litdd=-- manmanual=Git Manual mansource=Git @GIT_VERSION@ revdate=@GIT_DATE@
Documentation/config/browser.adoc +1 -1
@@ -1,7 +1,7 @@ browser.<tool>.cmd:: Specify the command to invoke the specified browser. The specified command is evaluated in shell with the URLs passed - as arguments. (See linkgit:git-web{litdd}browse[1].) + as arguments. (See linkgit:git-web\--browse[1].) browser.<tool>.path:: Override the path for the given tool that may be used to
Documentation/config/core.adoc +1 -1
@@ -63,7 +63,7 @@ core.protectNTFS:: core.fsmonitor:: If set to true, enable the built-in file system monitor - daemon for this working directory (linkgit:git-fsmonitor{litdd}daemon[1]). + daemon for this working directory (linkgit:git-fsmonitor\--daemon[1]). + Like hook-based file system monitors, the built-in file system monitor can speed up Git commands that need to refresh the Git index
Documentation/git-archimport.adoc +3 -3
@@ -45,7 +45,7 @@ archives that it imports, it is also possible to specify Git branch names manually. To do so, write a Git branch name after each <archive>/<branch> parameter, separated by a colon. This way, you can shorten the Arch branch names and convert Arch jargon to Git jargon, for example mapping a -"PROJECT{litdd}devo{litdd}VERSION" branch to "master". +"PROJECT\--devo\--VERSION" branch to "master". Associating multiple Arch branches to one Git branch is possible; the result will make the most sense only if no commits are made to the first
@@ -86,8 +86,8 @@ OPTIONS -o:: Use this for compatibility with old-style branch names used by earlier versions of 'git archimport'. Old-style branch names - were category{litdd}branch, whereas new-style branch names are - archive,category{litdd}branch{litdd}version. In both cases, names given + were category\--branch, whereas new-style branch names are + archive,category\--branch\--version. In both cases, names given on the command-line will override the automatically-generated ones.
Documentation/git-credential-cache--daemon.adoc +3 -3
@@ -1,5 +1,5 @@ -git-credential-cache{litdd}daemon(1) -==================================== +git-credential-cache\--daemon(1) +================================ NAME ----
@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- [verse] -'git credential-cache{litdd}daemon' [--debug] <socket-path> +'git credential-cache\--daemon' [--debug] <socket-path> DESCRIPTION -----------
Documentation/git-fsmonitor--daemon.adoc +6 -6
@@ -1,5 +1,5 @@ -git-fsmonitor{litdd}daemon(1) -============================= +git-fsmonitor\--daemon(1) +========================= NAME ----
@@ -8,10 +8,10 @@ git-fsmonitor--daemon - A Built-in Filesystem Monitor SYNOPSIS -------- [verse] -'git fsmonitor{litdd}daemon' start -'git fsmonitor{litdd}daemon' run -'git fsmonitor{litdd}daemon' stop -'git fsmonitor{litdd}daemon' status +'git fsmonitor\--daemon' start +'git fsmonitor\--daemon' run +'git fsmonitor\--daemon' stop +'git fsmonitor\--daemon' status DESCRIPTION -----------
Documentation/git-help.adoc +3 -3
@@ -110,9 +110,9 @@ other display programs (see below). + The web browser can be specified using the configuration variable `help.browser`, or `web.browser` if the former is not set. If neither of -these config variables is set, the 'git web{litdd}browse' helper script +these config variables is set, the 'git web\--browse' helper script (called by 'git help') will pick a suitable default. See -linkgit:git-web{litdd}browse[1] for more information about this. +linkgit:git-web\--browse[1] for more information about this. CONFIGURATION VARIABLES -----------------------
@@ -135,7 +135,7 @@ help.browser, web.browser, and browser.<tool>.path The `help.browser`, `web.browser` and `browser.<tool>.path` will also be checked if the 'web' format is chosen (either by command-line option or configuration variable). See '-w|--web' in the OPTIONS -section above and linkgit:git-web{litdd}browse[1]. +section above and linkgit:git-web\--browse[1]. man.viewer ~~~~~~~~~~
Documentation/git-instaweb.adoc +3 -3
@@ -45,9 +45,9 @@ OPTIONS -b:: --browser:: The web browser that should be used to view the gitweb - page. This will be passed to the 'git web{litdd}browse' helper + page. This will be passed to the 'git web\--browse' helper script along with the URL of the gitweb instance. See - linkgit:git-web{litdd}browse[1] for more information about this. If + linkgit:git-web\--browse[1] for more information about this. If the script fails, the URL will be printed to stdout. start::
@@ -83,7 +83,7 @@ You may specify configuration in your .git/config If the configuration variable `instaweb.browser` is not set, `web.browser` will be used instead if it is defined. See -linkgit:git-web{litdd}browse[1] for more information about this. +linkgit:git-web\--browse[1] for more information about this. SEE ALSO --------
Documentation/git-mergetool--lib.adoc +5 -5
@@ -1,5 +1,5 @@ -git-mergetool{litdd}lib(1) -========================== +git-mergetool\--lib(1) +====================== NAME ----
@@ -8,7 +8,7 @@ git-mergetool--lib - Common Git merge tool shell scriptlets SYNOPSIS -------- [verse] -'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool{litdd}lib"' +'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool\--lib"' DESCRIPTION -----------
@@ -17,11 +17,11 @@ This is not a command the end user would want to run. Ever. This documentation is meant for people who are studying the Porcelain-ish scripts and/or are writing new ones. -The 'git-mergetool{litdd}lib' scriptlet is designed to be sourced (using +The 'git-mergetool\--lib' scriptlet is designed to be sourced (using `.`) by other shell scripts to set up functions for working with Git merge tools. -Before sourcing 'git-mergetool{litdd}lib', your script must set `TOOL_MODE` +Before sourcing 'git-mergetool\--lib', your script must set `TOOL_MODE` to define the operation mode for the functions listed below. 'diff' and 'merge' are valid values.
Documentation/git-sh-i18n--envsubst.adoc +5 -5
@@ -1,5 +1,5 @@ -git-sh-i18n{litdd}envsubst(1) -============================= +git-sh-i18n\--envsubst(1) +========================= NAME ----
@@ -10,8 +10,8 @@ SYNOPSIS [verse] eval_gettext () { printf "%s" "$1" | ( - export PATH $('git sh-i18n{litdd}envsubst' --variables "$1"); - 'git sh-i18n{litdd}envsubst' "$1" + export PATH $('git sh-i18n\--envsubst' --variables "$1"); + 'git sh-i18n\--envsubst' "$1" ) }
@@ -22,7 +22,7 @@ This is not a command the end user would want to run. Ever. This documentation is meant for people who are studying the plumbing scripts and/or are writing new ones. -'git sh-i18n{litdd}envsubst' is Git's stripped-down copy of the GNU +'git sh-i18n\--envsubst' is Git's stripped-down copy of the GNU `envsubst(1)` program that comes with the GNU gettext package. It's used internally by linkgit:git-sh-i18n[1] to interpolate the variables passed to the `eval_gettext` function.
Documentation/git-sh-i18n.adoc +1 -1
@@ -35,7 +35,7 @@ gettext:: eval_gettext:: Currently a dummy fall-through function implemented as a wrapper around `printf(1)` with variables expanded by the - linkgit:git-sh-i18n{litdd}envsubst[1] helper. Will be replaced by a + linkgit:git-sh-i18n\--envsubst[1] helper. Will be replaced by a real gettext implementation in a later version. GIT
Documentation/git-update-index.adoc +1 -1
@@ -539,7 +539,7 @@ This feature is intended to speed up git operations for repos that have large working directories. It enables git to work together with a file system monitor (see -linkgit:git-fsmonitor{litdd}daemon[1] +linkgit:git-fsmonitor\--daemon[1] and the "fsmonitor-watchman" section of linkgit:githooks[5]) that can inform it as to what files have been modified. This enables git to avoid
Documentation/git-web--browse.adoc +5 -5
@@ -1,5 +1,5 @@ -git-web{litdd}browse(1) -======================= +git-web\--browse(1) +=================== NAME ----
@@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser SYNOPSIS -------- [verse] -'git web{litdd}browse' [<options>] (<URL>|<file>)... +'git web\--browse' [<options>] (<URL>|<file>)... DESCRIPTION -----------
@@ -71,7 +71,7 @@ browser.<tool>.path You can explicitly provide a full path to your preferred browser by setting the configuration variable `browser.<tool>.path`. For example, you can configure the absolute path to firefox by setting -'browser.firefox.path'. Otherwise, 'git web{litdd}browse' assumes the tool +'browser.firefox.path'. Otherwise, 'git web\--browse' assumes the tool is available in PATH. browser.<tool>.cmd
@@ -80,7 +80,7 @@ browser.<tool>.cmd When the browser, specified by options or configuration variables, is not among the supported ones, then the corresponding `browser.<tool>.cmd` configuration variable will be looked up. If this -variable exists then 'git web{litdd}browse' will treat the specified tool +variable exists then 'git web\--browse' will treat the specified tool as a custom command and will use a shell eval to run the command with the URLs passed as arguments.
Documentation/lint-gitlink.perl +1 -1
@@ -54,7 +54,7 @@ while (<>) { my ($target, $page, $section) = ($1, $2, $3); # De-AsciiDoc - $page =~ s/{litdd}/--/g; + $page =~ s/\\--/--/g; if (!exists $TXT{$page}) { report($pos, $line, $target, "link outside of our own docs");
Documentation/meson.build +0 -1
@@ -295,7 +295,6 @@ elif docs_backend == 'asciidoctor' asciidoctor, '--attribute', 'compat-mode', '--attribute', 'tabsize=8', - '--attribute', 'litdd=--', '--attribute', 'docinfo=shared', '--attribute', 'build_dir=' + meson.current_build_dir(), '--load-path', meson.current_build_dir(),
contrib/subtree/Makefile +0 -1
@@ -33,7 +33,6 @@ ASCIIDOC_CONF = ASCIIDOC_HTML = xhtml5 ASCIIDOC_DOCBOOK = docbook ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions -ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' ASCIIDOC_DEPS = asciidoctor-extensions.rb XMLTO_EXTRA += --skip-validation endif
t/t0450-txt-doc-vs-help.sh +1 -1
@@ -58,7 +58,7 @@ adoc_to_synopsis () { -E '/^\[(verse|synopsis)\]$/,/^$/ { /^$/q; /^\[(verse|synopsis)\]$/d; - s/\{litdd\}/--/g; + s/\\--/--/g; s/'\''(git[ a-z-]*)'\''/\1/g; p;
base-commit: 7c02d39fc2ed2702223c7674f73150d9a7e61ba4
Signature · 1 line
gitgitgadget
Quoted 11 lines · Michael Ryzhikov via GitGitGadget
From: samonon <[email protected]>
*** Problem.
{litdd} is used as alias for -- (when not inside backticks) because -- is a reserved text in asciidoc. There is some problems with this:
- need to remember that in some cases -- should be replaced with {litdd}
- unnecessary config options when exporting adoc to other formats
- in HTML it looks like "--" instead of "--" (it works, but browser should correctly decode hex symbols in html link:
see htmldocs/git-sh-i18n.html)
Quoted 4 lines
*** Solution
For better readability just escape -- using \.
This is default asciidoc mechanism that don't need any configuration. Tested with "make all doc" - links inside linkgit: work.
Hmph, I do not quite see the point of this churn. We'd need to remember to do \-- instead of doing {litdd}, either way.
I do not know what you want to say with "when exporting to other formats", as we already are formatting these source files into HTML and manual pages.
Quoted 6 lines · Junio C Hamano
Hmph, I do not quite see the point of this churn. We'd need to remember to do \-- instead of doing {litdd}, either way.
I do not know what you want to say with "when exporting to other formats", as we already are formatting these source files into HTML and manual pages.
Let this e-mail be a summary post for similar suggestions.
If there is a reason to continue using legacy fix {litdd} there needs to be an example
where it breaks output with current tools/setups (or even may be future setups). If it can be replaced there needs to be a list of required tests for all setups (see 2.).
1. I searched this mailing list for 'litdd' references (links will be in the end) and understood
that it was introduced because of changes in asciidoc syntax (-- became emdash) and
bugs in asciidoc* converter more than 10 years ago. Should it be used still for legacy code support?
I tested (cygwin + asciidoc) 'make all doc' and it works correctly (but maybe it's only for me).
Since '\--' is a default asciidoc syntax for disabling text replacement it should be used
for writing docs and converters now should know about this syntax.
2. What should be tested whether replacing {litdd} with '\--' doesn't regress with current tools?
Should it work correctly (and create same textual output):
- with Win/Mac and all types of Linux/Unix/BSD?
- with all converters (including older versions): asciidoc, asciidoctor, etc...
- with all output formats (man, html, info, pdf, docbook, etc...)?
- with 'Git for Windows' repo and other forks?
Who can take their time and test all this?
Or release docs should come from a single source (like manpages and html docs at https://www.kernel.org/pub/software/scm/git)?
3. Development discussion forum.
3.1 I apologize for sending it directly to this mailing list - maybe It should have been
discussed somewhere else beforehand? For example, Discord? Mailing list is SO old school.
3.2 Maybe there should be a discord channel #docs for Git documentation development?
-----------------------------------------------------------------------------
Previous important references to {litdd} in this mailing list. My comments start with >>
https://lore.kernel.org/git/20110629053510.GC28690@elie/
[PATCH 1/2 maint] Documentation: quote double-dash for AsciiDoc Use "\--" to avoid such misformatting in sentences in which "--" represents a literal
double-minus command line argument that separates options and revs from pathspecs, and use "{litdd}" in cases where the double-dash is embedded in the command name. The latter is just for consistency with v1.7.3-rc0~13^2 (Work around em-dash handling in newer AsciiDoc, 2010-08-23).
https://lore.kernel.org/git/[email protected]/
[PATCH] docs: stop using asciidoc no-inline-literal
https://lore.kernel.org/git/[email protected]/
[PATCH 0/8] asciidoc fixups
https://lore.kernel.org/git/[email protected]/
[PATCH v3 1/2] Documentation: fix linkgit references
Quoted 1 line
Quoted 1 line
previous attempt to remove {litdd}
https://lore.kernel.org/git/[email protected]/
[PATCH 0/2] Convert SubmittingPatches to AsciiDoc
https://lore.kernel.org/git/[email protected]/
There are certainly a few that can't, though (e.g., config.txt uses linkgit:git-web{litdd}browse[1]).
I agree that "\--" is less ugly there (and seems to work on my modern asciidoc). There's some history on the litdd versus "\--" choice in 565e135a1e (Documentation:
quote double-dash for AsciiDoc, 2011-06-29). That in turn references the 2839478774
(Work around em-dash handling in newer AsciiDoc, 2010-08-23),
but I wouldn't be surprised if all of that is now obsolete with our AsciiDoc 8+ requirement.
https://lore.kernel.org/git/[email protected]/
Re: [PATCH] asciidoctor-extensions: provide <refmiscinfo/>
https://lore.kernel.org/git/[email protected]/
Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again (14.05.2021) A typesetting rule like "instead of double-dashes --, use {litdd}" is an acceptable way out.
At least that wouldn't constrain what the final product that gets delivered to the end-users can say.
https://lore.kernel.org/git/[email protected]/
[PATCH] doc: replace "--" with {litdd} in credential-cache/fsmonitor Asciidoc renders -- as em-dash. This is not appropriate for command names. It also breaks linkgit links to these commands.
Quoted 1 line
Quoted 1 line
Currently it doesn't break linkgit: (but may be only for me).