{"thread":{"id":"61086","subject":"[PATCH 0/6] doc: rework doc files for git-init and git-clone","startedAt":"2024-03-10T19:10:33Z","lastAt":"2024-03-11T21:43:11Z","messageCount":9,"participants":["Jean-Noël Avila via GitGitGadget","Junio C Hamano","Jean-Noël Avila"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"490338","messageId":"pull.1687.git.1710097830.gitgitgadget@gmail.com","threadId":"61086","inReplyTo":null,"subject":"[PATCH 0/6] doc: rework doc files for git-init and git-clone","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-03-10T19:10:24Z","receivedAt":"2024-03-10T19:10:33Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Following the new formatting rules that were added, I reworked the two first\nmanpages of the series on git-scm.com.\n\nThis mainly entails applying placeholder and verbatim markup when it\napplies. Other changes are added; if it makes sense, they can be turned into\ngeneral rules.\n\nJean-Noël Avila (6):\n doc: git-init: format verbatim parts\n doc: git-init: format placeholders\n doc: git-init: rework definition lists\n doc: git-init: rework config item init.templateDir\n doc: git-clone: format verbatim words\n doc: git-clone: format placeholders\n\n Documentation/config/init.txt | 9 ++++--\n Documentation/git-clone.txt | 30 +++++++++----------\n Documentation/git-init.txt | 54 +++++++++++++++++++----------------\n Documentation/urls.txt | 12 ++++----\n 4 files changed, 57 insertions(+), 48 deletions(-)\n\n\nbase-commit: e09f1254c54329773904fe25d7c545a1fb4fa920\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1687%2Fjnavila%2Fdoc_git_clone-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1687/jnavila/doc_git_clone-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1687\n-- \ngitgitgadget\n"},{"id":"490339","messageId":"908b45b8a4c3ac7e1846e9cf323bb4ace7140dc1.1710097830.git.gitgitgadget@gmail.com","threadId":"61086","inReplyTo":"pull.1687.git.1710097830.gitgitgadget@gmail.com","subject":"[PATCH 1/6] doc: git-init: format verbatim parts","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-03-10T19:10:25Z","receivedAt":"2024-03-10T19:10:34Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nVerbatim parts are all formatted as `fixed font`.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-init.txt | 32 ++++++++++++++++----------------\n 1 file changed, 16 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex e8dc645bb59..7ff7d8e7ee0 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -33,10 +33,10 @@ If the object storage directory is specified via the\n are created underneath; otherwise, the default `$GIT_DIR/objects`\n directory is used.\n \n-Running 'git init' in an existing repository is safe. It will not\n+Running `git init` in an existing repository is safe. It will not\n overwrite things that are already there. The primary reason for\n-rerunning 'git init' is to pick up newly added templates (or to move\n-the repository to another place if --separate-git-dir is given).\n+rerunning `git init` is to pick up newly added templates (or to move\n+the repository to another place if `--separate-git-dir` is given).\n \n OPTIONS\n -------\n@@ -53,8 +53,8 @@ current working directory.\n \n --object-format=::\n \n-Specify the given object format (hash algorithm) for the repository. The valid\n-values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default.\n+Specify the given object __ (hash algorithm) for the repository. The valid\n+values are `sha1` and (if enabled) `sha256`. `sha1` is the default.\n +\n include::object-format-disclaimer.txt[]\n \n@@ -90,12 +90,12 @@ customized via the `init.defaultBranch` configuration variable).\n \n Specify that the Git repository is to be shared amongst several users. This\n allows users belonging to the same group to push into that\n-repository. When specified, the config variable \"core.sharedRepository\" is\n+repository. When specified, the config variable `core.sharedRepository` is\n set so that files and directories under `$GIT_DIR` are created with the\n requested permissions. When not specified, Git will use permissions reported\n-by umask(2).\n+by `umask(2)`.\n +\n-The option can have the following values, defaulting to 'group' if no value\n+The option can have the following values, defaulting to `group` if no value\n is given:\n +\n --\n@@ -109,21 +109,21 @@ specified.\n Make the repository group-writable, (and g+sx, since the git group may not be\n the primary group of all users). This is used to loosen the permissions of an\n otherwise safe umask(2) value. Note that the umask still applies to the other\n-permission bits (e.g. if umask is '0022', using 'group' will not remove read\n-privileges from other (non-group) users). See '0xxx' for how to exactly specify\n+permission bits (e.g. if umask is `0022`, using `group` will not remove read\n+privileges from other (non-group) users). See `0xxx` for how to exactly specify\n the repository permissions.\n \n 'all' (or 'world' or 'everybody')::\n \n-Same as 'group', but make the repository readable by all users.\n+Same as `group`, but make the repository readable by all users.\n \n ''::\n \n '' is a 3-digit octal number prefixed with `0` and each file\n-will have mode ''. '' will override users' umask(2)\n-value (and not only loosen permissions as 'group' and 'all'\n-do). '0640' will create a repository which is group-readable, but\n-not group-writable or accessible to others. '0660' will create a repo\n+will have mode ''. '' will override users'`umask(2)`\n+value (and not only loosen permissions as `group` and `all`\n+do). `0640` will create a repository which is group-readable, but\n+not group-writable or accessible to others. `0660` will create a repo\n that is readable and writable to the current user and group, but\n inaccessible to others (directories and executable files get their\n `x` bit from the `r` bit for corresponding classes of users).\n@@ -172,7 +172,7 @@ $ git add . <2>\n $ git commit <3>\n ----------------\n +\n-<1> Create a /path/to/my/codebase/.git directory.\n+<1> Create a `/path/to/my/codebase/.git` directory.\n <2> Add all existing files to the index.\n <3> Record the pristine state as the first commit in the history.\n \n-- \ngitgitgadget\n\n"},{"id":"490340","messageId":"df95ca4b720a86ad5c80e1a8a8cefe9abd0275b2.1710097830.git.gitgitgadget@gmail.com","threadId":"61086","inReplyTo":"pull.1687.git.1710097830.gitgitgadget@gmail.com","subject":"[PATCH 2/6] doc: git-init: format placeholders","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-03-10T19:10:26Z","receivedAt":"2024-03-10T19:10:35Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nWith the new doc format conventions, we use __.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-init.txt | 10 +++++-----\n 1 file changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 7ff7d8e7ee0..e8fe72861dc 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -60,7 +60,7 @@ include::object-format-disclaimer.txt[]\n \n --ref-format=::\n \n-Specify the given ref storage format for the repository. The valid values are:\n+Specify the given ref storage __ for the repository. The valid values are:\n +\n include::ref-storage-format.txt[]\n \n@@ -81,7 +81,7 @@ If this is a reinitialization, the repository will be moved to the specified pat\n -b ::\n --initial-branch=::\n \n-Use the specified name for the initial branch in the newly created\n+Use __ for the initial branch in the newly created\n repository. If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n@@ -119,8 +119,8 @@ Same as `group`, but make the repository readable by all users.\n \n ''::\n \n-'' is a 3-digit octal number prefixed with `0` and each file\n-will have mode ''. '' will override users'`umask(2)`\n+__ is a 3-digit octal number prefixed with `0` and each file\n+will have mode __. __ will override users'`umask(2)`\n value (and not only loosen permissions as `group` and `all`\n do). `0640` will create a repository which is group-readable, but\n not group-writable or accessible to others. `0660` will create a repo\n@@ -133,7 +133,7 @@ By default, the configuration flag `receive.denyNonFastForwards` is enabled\n in shared repositories, so that you cannot force a non fast-forwarding push\n into it.\n \n-If you provide a 'directory', the command is run inside it. If this directory\n+If you provide a __, the command is run inside it. If this directory\n does not exist, it will be created.\n \n TEMPLATE DIRECTORY\n-- \ngitgitgadget\n\n"},{"id":"490341","messageId":"4140c44a34e8c05581de14c2074945d74ecea1d4.1710097830.git.gitgitgadget@gmail.com","threadId":"61086","inReplyTo":"pull.1687.git.1710097830.gitgitgadget@gmail.com","subject":"[PATCH 3/6] doc: git-init: rework definition lists","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-03-10T19:10:27Z","receivedAt":"2024-03-10T19:10:36Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nIn all cases of option description, each option is in its own\nterm. Use the same format here.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-init.txt | 12 ++++++++----\n 1 file changed, 8 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex e8fe72861dc..5fce39040f2 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -99,12 +99,14 @@ The option can have the following values, defaulting to `group` if no value\n is given:\n +\n --\n-'umask' (or 'false')::\n+umask::\n+false::\n \n Use permissions reported by umask(2). The default, when `--shared` is not\n specified.\n \n-'group' (or 'true')::\n+group::\n+true::\n \n Make the repository group-writable, (and g+sx, since the git group may not be\n the primary group of all users). This is used to loosen the permissions of an\n@@ -113,11 +115,13 @@ permission bits (e.g. if umask is `0022`, using `group` will not remove read\n privileges from other (non-group) users). See `0xxx` for how to exactly specify\n the repository permissions.\n \n-'all' (or 'world' or 'everybody')::\n+all::\n+world::\n+everybody::\n \n Same as `group`, but make the repository readable by all users.\n \n-''::\n+::\n \n __ is a 3-digit octal number prefixed with `0` and each file\n will have mode __. __ will override users'`umask(2)`\n-- \ngitgitgadget\n\n"},{"id":"490342","messageId":"8fda922dddf4278786acab4df8d7b31ed7605bc2.1710097830.git.gitgitgadget@gmail.com","threadId":"61086","inReplyTo":"pull.1687.git.1710097830.gitgitgadget@gmail.com","subject":"[PATCH 4/6] doc: git-init: rework config item init.templateDir","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-03-10T19:10:28Z","receivedAt":"2024-03-10T19:10:37Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nWhen included into a the manpage of git-init, the param section must\nnot refer to the manpage.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/init.txt | 9 ++++++---\n Documentation/git-init.txt | 2 ++\n 2 files changed, 8 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/init.txt b/Documentation/config/init.txt\nindex 79c79d66174..dd1d8332737 100644\n--- a/Documentation/config/init.txt\n+++ b/Documentation/config/init.txt\n@@ -1,7 +1,10 @@\n-init.templateDir::\n-\tSpecify the directory from which templates will be copied.\n-\t(See the \"TEMPLATE DIRECTORY\" section of linkgit:git-init[1].)\n+:see-git-init:\n+ifndef::git-init[]\n+:see-git-init: (See the \"TEMPLATE DIRECTORY\" section of linkgit:git-init[1].)\n+endif::[]\n \n+init.templateDir::\n+\tSpecify the directory from which templates will be copied. {see-git-init}\n init.defaultBranch::\n \tAllows overriding the default branch name e.g. when initializing\n \ta new repository.\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 5fce39040f2..2f864e11ed9 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -185,6 +185,8 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.txt[]\n \n+:git-init:\n+\n include::config/init.txt[]\n \n GIT\n-- \ngitgitgadget\n\n"},{"id":"490343","messageId":"54e5d8735c4351e5041f777f8d9da0fcadfcfef6.1710097830.git.gitgitgadget@gmail.com","threadId":"61086","inReplyTo":"pull.1687.git.1710097830.gitgitgadget@gmail.com","subject":"[PATCH 5/6] doc: git-clone: format verbatim words","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-03-10T19:10:29Z","receivedAt":"2024-03-10T19:10:38Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nWe also apply the formatting to urls.txt which is included.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-clone.txt | 4 ++--\n Documentation/urls.txt | 8 ++++----\n 2 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 0c07720c6f4..6bad5641151 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -156,7 +156,7 @@ objects from the source repository into a pack in the cloned repository.\n \n --[no-]reject-shallow::\n \tFail if the source repository is a shallow repository.\n-\tThe 'clone.rejectShallow' configuration variable can be used to\n+\tThe `clone.rejectShallow` configuration variable can be used to\n \tspecify the default.\n \n --bare::\n@@ -263,7 +263,7 @@ corresponding `--mirror` and `--no-tags` options instead.\n \tbranch remote's `HEAD` points at.\n \tFurther fetches into the resulting repository will only update the\n \tremote-tracking branch for the branch this option was used for the\n-\tinitial cloning. If the HEAD at the remote did not point at any\n+\tinitial cloning. If the `HEAD` at the remote did not point at any\n \tbranch when `--single-branch` clone was made, no remote-tracking\n \tbranch is created.\n \ndiff --git a/Documentation/urls.txt b/Documentation/urls.txt\nindex ce671f812d4..9af19be2075 100644\n--- a/Documentation/urls.txt\n+++ b/Documentation/urls.txt\n@@ -44,20 +44,20 @@ syntaxes may be used:\n \n ifndef::git-clone[]\n These two syntaxes are mostly equivalent, except when cloning, when\n-the former implies --local option. See linkgit:git-clone[1] for\n+the former implies `--local` option. See linkgit:git-clone[1] for\n details.\n endif::git-clone[]\n \n ifdef::git-clone[]\n These two syntaxes are mostly equivalent, except the former implies\n---local option.\n+`--local` option.\n endif::git-clone[]\n \n-'git clone', 'git fetch' and 'git pull', but not 'git push', will also\n+`git clone`, `git fetch` and `git pull`, but not `git push`, will also\n accept a suitable bundle file. See linkgit:git-bundle[1].\n \n When Git doesn't know how to handle a certain transport protocol, it\n-attempts to use the 'remote-' remote helper, if one\n+attempts to use the `remote-` remote helper, if one\n exists. To explicitly request a remote helper, the following syntax\n may be used:\n \n-- \ngitgitgadget\n\n"},{"id":"490344","messageId":"9a949d98a3ec8b7730b5a6b66e8ef8bb62cd06aa.1710097830.git.gitgitgadget@gmail.com","threadId":"61086","inReplyTo":"pull.1687.git.1710097830.gitgitgadget@gmail.com","subject":"[PATCH 6/6] doc: git-clone: format placeholders","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-03-10T19:10:30Z","receivedAt":"2024-03-10T19:10:39Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nWith the new formatting rules, we use __.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-clone.txt | 26 +++++++++++++-------------\n Documentation/urls.txt | 4 ++--\n 2 files changed, 15 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 6bad5641151..f90977a8519 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -102,9 +102,9 @@ its source repository, you can simply run `git repack -a` to copy all\n objects from the source repository into a pack in the cloned repository.\n \n --reference[-if-able] ::\n-\tIf the reference repository is on the local machine,\n+\tIf the reference __ is on the local machine,\n \tautomatically setup `.git/objects/info/alternates` to\n-\tobtain objects from the reference repository. Using\n+\tobtain objects from the reference __. Using\n \tan already existing repository as an alternate will\n \trequire fewer objects to be copied from the repository\n \tbeing cloned, reducing network and local storage costs.\n@@ -161,8 +161,8 @@ objects from the source repository into a pack in the cloned repository.\n \n --bare::\n \tMake a 'bare' Git repository. That is, instead of\n-\tcreating `` and placing the administrative\n-\tfiles in `/.git`, make the ``\n+\tcreating __ and placing the administrative\n+\tfiles in `/.git`, make the __\n \titself the `$GIT_DIR`. This obviously implies the `--no-checkout`\n \tbecause there is nowhere to check out the working tree.\n \tAlso the branch heads at the remote are copied directly\n@@ -180,11 +180,11 @@ objects from the source repository into a pack in the cloned repository.\n --filter=::\n \tUse the partial clone feature and request that the server sends\n \ta subset of reachable objects according to a given object filter.\n-\tWhen using `--filter`, the supplied `` is used for\n+\tWhen using `--filter`, the supplied __ is used for\n \tthe partial clone filter. For example, `--filter=blob:none` will\n \tfilter out all blobs (file contents) until needed by Git. Also,\n \t`--filter=blob:limit=` will filter out all blobs of size\n-\tat least ``. For more details on filter specifications, see\n+\tat least __. For more details on filter specifications, see\n \tthe `--filter` option in linkgit:git-rev-list[1].\n \n --also-filter-submodules::\n@@ -203,13 +203,13 @@ objects from the source repository into a pack in the cloned repository.\n -o ::\n --origin ::\n \tInstead of using the remote name `origin` to keep track of the upstream\n-\trepository, use ``. Overrides `clone.defaultRemoteName` from the\n+\trepository, use __. Overrides `clone.defaultRemoteName` from the\n \tconfig.\n \n -b ::\n --branch ::\n \tInstead of pointing the newly created HEAD to the branch pointed\n-\tto by the cloned repository's HEAD, point to `` branch\n+\tto by the cloned repository's HEAD, point to __ branch\n \tinstead. In a non-bare repository, this is the branch that will\n \tbe checked out.\n \t`--branch` can also take tags and detaches the HEAD at that commit\n@@ -230,7 +230,7 @@ objects from the source repository into a pack in the cloned repository.\n \tSet a configuration variable in the newly-created repository;\n \tthis takes effect immediately after the repository is\n \tinitialized, but before the remote history is fetched or any\n-\tfiles checked out. The key is in the same format as expected by\n+\tfiles checked out. The __ is in the same format as expected by\n \tlinkgit:git-config[1] (e.g., `core.eol=true`). If multiple\n \tvalues are given for the same key, each value will be written to\n \tthe config file. This makes it safe, for example, to add\n@@ -281,7 +281,7 @@ branch of some repository for search indexing.\n \n --recurse-submodules[=]::\n \tAfter the clone is created, initialize and clone submodules\n-\twithin based on the provided pathspec. If no pathspec is\n+\twithin based on the provided __. If no _=_ is\n \tprovided, all submodules are initialized and cloned.\n \tThis option can be given multiple times for pathspecs consisting\n \tof multiple entries. The resulting clone has `submodule.active` set to\n@@ -323,20 +323,20 @@ include::ref-storage-format.txt[]\n \tDefaults to the `submodule.fetchJobs` option.\n \n ::\n-\tThe (possibly remote) repository to clone from. See the\n+\tThe (possibly remote) __ to clone from. See the\n \t<> section below for more information on specifying\n \trepositories.\n \n ::\n \tThe name of a new directory to clone into. The \"humanish\"\n-\tpart of the source repository is used if no directory is\n+\tpart of the source repository is used if no __ is\n \texplicitly given (`repo` for `/path/to/repo.git` and `foo`\n \tfor `host.xz:foo/.git`). Cloning into an existing directory\n \tis only allowed if the directory is empty.\n \n --bundle-uri=::\n \tBefore fetching from the remote, fetch a bundle from the given\n-\t`` and unbundle the data into the local repository. The refs\n+\t__ and unbundle the data into the local repository. The refs\n \tin the bundle will be stored under the hidden `refs/bundle/*`\n \tnamespace. This option is incompatible with `--depth`,\n \t`--shallow-since`, and `--shallow-exclude`.\ndiff --git a/Documentation/urls.txt b/Documentation/urls.txt\nindex 9af19be2075..0b9e0c4302d 100644\n--- a/Documentation/urls.txt\n+++ b/Documentation/urls.txt\n@@ -61,9 +61,9 @@ attempts to use the `remote-` remote helper, if one\n exists. To explicitly request a remote helper, the following syntax\n may be used:\n \n-- ::
\n+- __::_
_\n \n-where
may be a path, a server and path, or an arbitrary\n+where _
_ may be a path, a server and path, or an arbitrary\n URL-like string recognized by the specific remote helper being\n invoked. See linkgit:gitremote-helpers[7] for details.\n \n-- \ngitgitgadget\n"},{"id":"490367","messageId":"xmqqbk7ku2ak.fsf@gitster.g","threadId":"61086","inReplyTo":"9a949d98a3ec8b7730b5a6b66e8ef8bb62cd06aa.1710097830.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 6/6] doc: git-clone: format placeholders","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-03-11T17:05:39Z","receivedAt":"2024-03-11T17:05:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" writes:\n\n> --bare::\n> \tMake a 'bare' Git repository. That is, instead of\n> -\tcreating `` and placing the administrative\n> -\tfiles in `/.git`, make the ``\n> +\tcreating __ and placing the administrative\n> +\tfiles in `/.git`, make the __\n\nIt is hard to decide what the right thing to do is to the earlier\none on this line, isn't it? It is not fully verbatim, even though\nits \"/.git\" part is.\n\nEverything else in this entire series looked good to my cursory\nread, but I'd appreciate extra sets of eyes, of course.\n\nThanks for working on this topic.\n\n"},{"id":"490406","messageId":"3c98b049-4eb8-4441-aae7-4789a8f74d9b@gmail.com","threadId":"61086","inReplyTo":"xmqqbk7ku2ak.fsf@gitster.g","subject":"Re: [PATCH 6/6] doc: git-clone: format placeholders","fromName":"Jean-Noël Avila","fromEmail":"avila.jn@gmail.com","sentAt":"2024-03-11T21:43:06Z","receivedAt":"2024-03-11T21:43:11Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 11/03/2024 à 18:05, Junio C Hamano a écrit :\n> \"Jean-Noël Avila via GitGitGadget\" writes:\n> \n>> --bare::\n>> \tMake a 'bare' Git repository. That is, instead of\n>> -\tcreating `` and placing the administrative\n>> -\tfiles in `/.git`, make the ``\n>> +\tcreating __ and placing the administrative\n>> +\tfiles in `/.git`, make the __\n> \n> It is hard to decide what the right thing to do is to the earlier\n> one on this line, isn't it? It is not fully verbatim, even though\n> its \"/.git\" part is.\n> \n\nLike the synopsys of the manpages, if there is a \"constant\" part in the\nword, it is deemed to be verbatim. Only when the placeholder is standing\nalone (usually the sentence is about it) must the placeholder be marked\nup as emphasized.\n\nAlso, headers of description list needn't be marked up.\n\nMaybe worth some additional rules in the guidelines...\n\n> Everything else in this entire series looked good to my cursory\n> read, but I'd appreciate extra sets of eyes, of course.\n> \n> Thanks for working on this topic.\n\nThere are manpages that are really inconsistant, and even malformed\n(such as gitremote-helpers), but the order of fixing will be to focus on\nthe most often viewed ones first.\n\n"}]}