[PATCH 0/6] doc: rework doc files for git-init and git-clone

[PATCH 0/6] doc: rework doc files for git-init and git-clone

[Jean-Noël Avila via GitGitGadget]

Following the new formatting rules that were added, I reworked the two first
manpages of the series on git-scm.com.

This mainly entails applying placeholder and verbatim markup when it
applies. Other changes are added; if it makes sense, they can be turned into
general rules.

Jean-Noël Avila (6):
  doc: git-init: format verbatim parts
  doc: git-init: format placeholders
  doc: git-init: rework definition lists
  doc: git-init: rework config item init.templateDir
  doc: git-clone: format verbatim words
  doc: git-clone: format placeholders

 Documentation/config/init.txt |  9 ++++--
 Documentation/git-clone.txt   | 30 +++++++++----------
 Documentation/git-init.txt    | 54 +++++++++++++++++++----------------
 Documentation/urls.txt        | 12 ++++----
 4 files changed, 57 insertions(+), 48 deletions(-)


base-commit: e09f1254c54329773904fe25d7c545a1fb4fa920
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1687%2Fjnavila%2Fdoc_git_clone-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1687/jnavila/doc_git_clone-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1687
-- 
gitgitgadget

[PATCH 1/6] doc: git-init: format verbatim parts

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

Verbatim parts are all formatted as `fixed font`.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-init.txt | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index e8dc645bb59..7ff7d8e7ee0 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -33,10 +33,10 @@ If the object storage directory is specified via the
 are created underneath; otherwise, the default `$GIT_DIR/objects`
 directory is used.
 
-Running 'git init' in an existing repository is safe. It will not
+Running `git init` in an existing repository is safe. It will not
 overwrite things that are already there. The primary reason for
-rerunning 'git init' is to pick up newly added templates (or to move
-the repository to another place if --separate-git-dir is given).
+rerunning `git init` is to pick up newly added templates (or to move
+the repository to another place if `--separate-git-dir` is given).
 
 OPTIONS
 -------
@@ -53,8 +53,8 @@ current working directory.
 
 --object-format=<format>::
 
-Specify the given object format (hash algorithm) for the repository.  The valid
-values are 'sha1' and (if enabled) 'sha256'.  'sha1' is the default.
+Specify the given object _<format>_ (hash algorithm) for the repository.  The valid
+values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.
 +
 include::object-format-disclaimer.txt[]
 
@@ -90,12 +90,12 @@ customized via the `init.defaultBranch` configuration variable).
 
 Specify that the Git repository is to be shared amongst several users.  This
 allows users belonging to the same group to push into that
-repository.  When specified, the config variable "core.sharedRepository" is
+repository.  When specified, the config variable `core.sharedRepository` is
 set so that files and directories under `$GIT_DIR` are created with the
 requested permissions.  When not specified, Git will use permissions reported
-by umask(2).
+by `umask(2)`.
 +
-The option can have the following values, defaulting to 'group' if no value
+The option can have the following values, defaulting to `group` if no value
 is given:
 +
 --
@@ -109,21 +109,21 @@ specified.
 Make the repository group-writable, (and g+sx, since the git group may not be
 the primary group of all users). This is used to loosen the permissions of an
 otherwise safe umask(2) value. Note that the umask still applies to the other
-permission bits (e.g. if umask is '0022', using 'group' will not remove read
-privileges from other (non-group) users). See '0xxx' for how to exactly specify
+permission bits (e.g. if umask is `0022`, using `group` will not remove read
+privileges from other (non-group) users). See `0xxx` for how to exactly specify
 the repository permissions.
 
 'all' (or 'world' or 'everybody')::
 
-Same as 'group', but make the repository readable by all users.
+Same as `group`, but make the repository readable by all users.
 
 '<perm>'::
 
 '<perm>' is a 3-digit octal number prefixed with `0` and each file
-will have mode '<perm>'. '<perm>' will override users' umask(2)
-value (and not only loosen permissions as 'group' and 'all'
-do). '0640' will create a repository which is group-readable, but
-not group-writable or accessible to others. '0660' will create a repo
+will have mode '<perm>'. '<perm>' will override users'`umask(2)`
+value (and not only loosen permissions as `group` and `all`
+do). `0640` will create a repository which is group-readable, but
+not group-writable or accessible to others. `0660` will create a repo
 that is readable and writable to the current user and group, but
 inaccessible to others (directories and executable files get their
 `x` bit from the `r` bit for corresponding classes of users).
@@ -172,7 +172,7 @@ $ git add .     <2>
 $ git commit    <3>
 ----------------
 +
-<1> Create a /path/to/my/codebase/.git directory.
+<1> Create a `/path/to/my/codebase/.git` directory.
 <2> Add all existing files to the index.
 <3> Record the pristine state as the first commit in the history.
 
-- 
gitgitgadget

[PATCH 2/6] doc: git-init: format placeholders

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

With the new doc format conventions, we use _<placeholders>_.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-init.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 7ff7d8e7ee0..e8fe72861dc 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -60,7 +60,7 @@ include::object-format-disclaimer.txt[]
 
 --ref-format=<format>::
 
-Specify the given ref storage format for the repository. The valid values are:
+Specify the given ref storage _<format>_ for the repository. The valid values are:
 +
 include::ref-storage-format.txt[]
 
@@ -81,7 +81,7 @@ If this is a reinitialization, the repository will be moved to the specified pat
 -b <branch-name>::
 --initial-branch=<branch-name>::
 
-Use the specified name for the initial branch in the newly created
+Use _<branch-name>_ for the initial branch in the newly created
 repository.  If not specified, fall back to the default name (currently
 `master`, but this is subject to change in the future; the name can be
 customized via the `init.defaultBranch` configuration variable).
@@ -119,8 +119,8 @@ Same as `group`, but make the repository readable by all users.
 
 '<perm>'::
 
-'<perm>' is a 3-digit octal number prefixed with `0` and each file
-will have mode '<perm>'. '<perm>' will override users'`umask(2)`
+_<perm>_ is a 3-digit octal number prefixed with `0` and each file
+will have mode _<perm>_. _<perm>_ will override users'`umask(2)`
 value (and not only loosen permissions as `group` and `all`
 do). `0640` will create a repository which is group-readable, but
 not group-writable or accessible to others. `0660` will create a repo
@@ -133,7 +133,7 @@ By default, the configuration flag `receive.denyNonFastForwards` is enabled
 in shared repositories, so that you cannot force a non fast-forwarding push
 into it.
 
-If you provide a 'directory', the command is run inside it. If this directory
+If you provide a _<directory>_, the command is run inside it. If this directory
 does not exist, it will be created.
 
 TEMPLATE DIRECTORY
-- 
gitgitgadget

[PATCH 3/6] doc: git-init: rework definition lists

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

In all cases of option description, each option is in its own
term. Use the same format here.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-init.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index e8fe72861dc..5fce39040f2 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -99,12 +99,14 @@ The option can have the following values, defaulting to `group` if no value
 is given:
 +
 --
-'umask' (or 'false')::
+umask::
+false::
 
 Use permissions reported by umask(2). The default, when `--shared` is not
 specified.
 
-'group' (or 'true')::
+group::
+true::
 
 Make the repository group-writable, (and g+sx, since the git group may not be
 the primary group of all users). This is used to loosen the permissions of an
@@ -113,11 +115,13 @@ permission bits (e.g. if umask is `0022`, using `group` will not remove read
 privileges from other (non-group) users). See `0xxx` for how to exactly specify
 the repository permissions.
 
-'all' (or 'world' or 'everybody')::
+all::
+world::
+everybody::
 
 Same as `group`, but make the repository readable by all users.
 
-'<perm>'::
+<perm>::
 
 _<perm>_ is a 3-digit octal number prefixed with `0` and each file
 will have mode _<perm>_. _<perm>_ will override users'`umask(2)`
-- 
gitgitgadget

[PATCH 4/6] doc: git-init: rework config item init.templateDir

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

When included into a the manpage of git-init, the param section must
not refer to the manpage.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/config/init.txt | 9 ++++++---
 Documentation/git-init.txt    | 2 ++
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/init.txt b/Documentation/config/init.txt
index 79c79d66174..dd1d8332737 100644
--- a/Documentation/config/init.txt
+++ b/Documentation/config/init.txt
@@ -1,7 +1,10 @@
-init.templateDir::
-	Specify the directory from which templates will be copied.
-	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
+:see-git-init:
+ifndef::git-init[]
+:see-git-init: (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
+endif::[]
 
+init.templateDir::
+	Specify the directory from which templates will be copied. {see-git-init}
 init.defaultBranch::
 	Allows overriding the default branch name e.g. when initializing
 	a new repository.
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 5fce39040f2..2f864e11ed9 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -185,6 +185,8 @@ CONFIGURATION
 
 include::includes/cmd-config-section-all.txt[]
 
+:git-init:
+
 include::config/init.txt[]
 
 GIT
-- 
gitgitgadget

[PATCH 5/6] doc: git-clone: format verbatim words

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

We also apply the formatting to urls.txt which is included.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-clone.txt | 4 ++--
 Documentation/urls.txt      | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 0c07720c6f4..6bad5641151 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -156,7 +156,7 @@ objects from the source repository into a pack in the cloned repository.
 
 --[no-]reject-shallow::
 	Fail if the source repository is a shallow repository.
-	The 'clone.rejectShallow' configuration variable can be used to
+	The `clone.rejectShallow` configuration variable can be used to
 	specify the default.
 
 --bare::
@@ -263,7 +263,7 @@ corresponding `--mirror` and `--no-tags` options instead.
 	branch remote's `HEAD` points at.
 	Further fetches into the resulting repository will only update the
 	remote-tracking branch for the branch this option was used for the
-	initial cloning.  If the HEAD at the remote did not point at any
+	initial cloning.  If the `HEAD` at the remote did not point at any
 	branch when `--single-branch` clone was made, no remote-tracking
 	branch is created.
 
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index ce671f812d4..9af19be2075 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -44,20 +44,20 @@ syntaxes may be used:
 
 ifndef::git-clone[]
 These two syntaxes are mostly equivalent, except when cloning, when
-the former implies --local option. See linkgit:git-clone[1] for
+the former implies `--local` option. See linkgit:git-clone[1] for
 details.
 endif::git-clone[]
 
 ifdef::git-clone[]
 These two syntaxes are mostly equivalent, except the former implies
---local option.
+`--local` option.
 endif::git-clone[]
 
-'git clone', 'git fetch' and 'git pull', but not 'git push', will also
+`git clone`, `git fetch` and `git pull`, but not `git push`, will also
 accept a suitable bundle file. See linkgit:git-bundle[1].
 
 When Git doesn't know how to handle a certain transport protocol, it
-attempts to use the 'remote-<transport>' remote helper, if one
+attempts to use the `remote-<transport>` remote helper, if one
 exists. To explicitly request a remote helper, the following syntax
 may be used:
 
-- 
gitgitgadget

[PATCH 6/6] doc: git-clone: format placeholders

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

With the new formatting rules, we use _<placeholders>_.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-clone.txt | 26 +++++++++++++-------------
 Documentation/urls.txt      |  4 ++--
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 6bad5641151..f90977a8519 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -102,9 +102,9 @@ its source repository, you can simply run `git repack -a` to copy all
 objects from the source repository into a pack in the cloned repository.
 
 --reference[-if-able] <repository>::
-	If the reference repository is on the local machine,
+	If the reference _<repository>_ is on the local machine,
 	automatically setup `.git/objects/info/alternates` to
-	obtain objects from the reference repository.  Using
+	obtain objects from the reference _<repository>_.  Using
 	an already existing repository as an alternate will
 	require fewer objects to be copied from the repository
 	being cloned, reducing network and local storage costs.
@@ -161,8 +161,8 @@ objects from the source repository into a pack in the cloned repository.
 
 --bare::
 	Make a 'bare' Git repository.  That is, instead of
-	creating `<directory>` and placing the administrative
-	files in `<directory>/.git`, make the `<directory>`
+	creating _<directory>_ and placing the administrative
+	files in `<directory>/.git`, make the _<directory>_
 	itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
 	because there is nowhere to check out the working tree.
 	Also the branch heads at the remote are copied directly
@@ -180,11 +180,11 @@ objects from the source repository into a pack in the cloned repository.
 --filter=<filter-spec>::
 	Use the partial clone feature and request that the server sends
 	a subset of reachable objects according to a given object filter.
-	When using `--filter`, the supplied `<filter-spec>` is used for
+	When using `--filter`, the supplied _<filter-spec>_ is used for
 	the partial clone filter. For example, `--filter=blob:none` will
 	filter out all blobs (file contents) until needed by Git. Also,
 	`--filter=blob:limit=<size>` will filter out all blobs of size
-	at least `<size>`. For more details on filter specifications, see
+	at least _<size>_. For more details on filter specifications, see
 	the `--filter` option in linkgit:git-rev-list[1].
 
 --also-filter-submodules::
@@ -203,13 +203,13 @@ objects from the source repository into a pack in the cloned repository.
 -o <name>::
 --origin <name>::
 	Instead of using the remote name `origin` to keep track of the upstream
-	repository, use `<name>`.  Overrides `clone.defaultRemoteName` from the
+	repository, use _<name>_.  Overrides `clone.defaultRemoteName` from the
 	config.
 
 -b <name>::
 --branch <name>::
 	Instead of pointing the newly created HEAD to the branch pointed
-	to by the cloned repository's HEAD, point to `<name>` branch
+	to by the cloned repository's HEAD, point to _<name>_ branch
 	instead. In a non-bare repository, this is the branch that will
 	be checked out.
 	`--branch` can also take tags and detaches the HEAD at that commit
@@ -230,7 +230,7 @@ objects from the source repository into a pack in the cloned repository.
 	Set a configuration variable in the newly-created repository;
 	this takes effect immediately after the repository is
 	initialized, but before the remote history is fetched or any
-	files checked out.  The key is in the same format as expected by
+	files checked out.  The _<key>_ is in the same format as expected by
 	linkgit:git-config[1] (e.g., `core.eol=true`). If multiple
 	values are given for the same key, each value will be written to
 	the config file. This makes it safe, for example, to add
@@ -281,7 +281,7 @@ branch of some repository for search indexing.
 
 --recurse-submodules[=<pathspec>]::
 	After the clone is created, initialize and clone submodules
-	within based on the provided pathspec.  If no pathspec is
+	within based on the provided _<pathspec>_.  If no _=<pathspec>_ is
 	provided, all submodules are initialized and cloned.
 	This option can be given multiple times for pathspecs consisting
 	of multiple entries.  The resulting clone has `submodule.active` set to
@@ -323,20 +323,20 @@ include::ref-storage-format.txt[]
 	Defaults to the `submodule.fetchJobs` option.
 
 <repository>::
-	The (possibly remote) repository to clone from.  See the
+	The (possibly remote) _<repository>_ to clone from.  See the
 	<<URLS,GIT URLS>> section below for more information on specifying
 	repositories.
 
 <directory>::
 	The name of a new directory to clone into.  The "humanish"
-	part of the source repository is used if no directory is
+	part of the source repository is used if no _<directory>_ is
 	explicitly given (`repo` for `/path/to/repo.git` and `foo`
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
 --bundle-uri=<uri>::
 	Before fetching from the remote, fetch a bundle from the given
-	`<uri>` and unbundle the data into the local repository. The refs
+	_<uri>_ and unbundle the data into the local repository. The refs
 	in the bundle will be stored under the hidden `refs/bundle/*`
 	namespace. This option is incompatible with `--depth`,
 	`--shallow-since`, and `--shallow-exclude`.
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 9af19be2075..0b9e0c4302d 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -61,9 +61,9 @@ attempts to use the `remote-<transport>` remote helper, if one
 exists. To explicitly request a remote helper, the following syntax
 may be used:
 
-- <transport>::<address>
+- _<transport>_::_<address>_
 
-where <address> may be a path, a server and path, or an arbitrary
+where _<address>_ may be a path, a server and path, or an arbitrary
 URL-like string recognized by the specific remote helper being
 invoked. See linkgit:gitremote-helpers[7] for details.
 
-- 
gitgitgadget

Re: [PATCH 6/6] doc: git-clone: format placeholders

[Junio C Hamano]

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  --bare::
>  	Make a 'bare' Git repository.  That is, instead of
> -	creating `<directory>` and placing the administrative
> -	files in `<directory>/.git`, make the `<directory>`
> +	creating _<directory>_ and placing the administrative
> +	files in `<directory>/.git`, make the _<directory>_

It is hard to decide what the right thing to do is to the earlier
one on this line, isn't it?  It is not fully verbatim, even though
its "/.git" part is.

Everything else in this entire series looked good to my cursory
read, but I'd appreciate extra sets of eyes, of course.

Thanks for working on this topic.

Re: [PATCH 6/6] doc: git-clone: format placeholders

[Jean-Noël Avila]

Le 11/03/2024 à 18:05, Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>>  --bare::
>>  	Make a 'bare' Git repository.  That is, instead of
>> -	creating `<directory>` and placing the administrative
>> -	files in `<directory>/.git`, make the `<directory>`
>> +	creating _<directory>_ and placing the administrative
>> +	files in `<directory>/.git`, make the _<directory>_
> 
> It is hard to decide what the right thing to do is to the earlier
> one on this line, isn't it?  It is not fully verbatim, even though
> its "/.git" part is.
> 

Like the synopsys of the manpages, if there is a "constant" part in the
word, it is deemed to be verbatim. Only when the placeholder is standing
alone (usually the sentence is about it) must the placeholder be marked
up as emphasized.

Also, headers of description list needn't be marked up.

Maybe worth some additional rules in the guidelines...

> Everything else in this entire series looked good to my cursory
> read, but I'd appreciate extra sets of eyes, of course.
> 
> Thanks for working on this topic.

There are manpages that are really inconsistant, and even malformed
(such as gitremote-helpers), but the order of fixing will be to focus on
the most often viewed ones first.