diff mbox series

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

Message ID 9a949d98a3ec8b7730b5a6b66e8ef8bb62cd06aa.1710097830.git.gitgitgadget@gmail.com (mailing list archive)
State Accepted
Commit 45d5ed3e50375a4b1c5d1bf49128aec975b0546d
Headers show
Series doc: rework doc files for git-init and git-clone | expand

Commit Message

Jean-Noël AVILA March 10, 2024, 7:10 p.m. UTC
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(-)

Comments

Junio C Hamano March 11, 2024, 5:05 p.m. UTC | #1
"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.
Jean-Noël AVILA March 11, 2024, 9:43 p.m. UTC | #2
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.
diff mbox series

Patch

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.