Re: [PATCH] doc: format pathnames and URLs as monospace

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 14, 2019, 20:44 UTC
Message-ID: <xmqq4l9685ia.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20190214163043.7103-1-corentin.bompard@etu.univ-lyon1.fr>

Corentin BOMPARD <corentin.bompard@etu.univ-lyon1.fr> writes:

Show 10 quoted lines

> diff --git a/Documentation/config/checkout.txt b/Documentation/config/checkout.txt
> index c4118fa19..8ba92f274 100644
> --- a/Documentation/config/checkout.txt
> +++ b/Documentation/config/checkout.txt
> @@ -1,7 +1,7 @@
>  checkout.defaultRemote::
>  	When you run 'git checkout <something>' and only have one
>  	remote, it may implicitly fall back on checking out and
> -	tracking e.g. 'origin/<something>'. This stops working as soon
> +	tracking e.g. `origin/<something>`. This stops working as soon

Are you doing only pathnames and URLs, or are you also doing refnames?

I am not sure if "this is a pathname, or a URL or a refname, so it must be typeset with monospace" is the direction we'd want to go in in the first place. One rule we tried to follow (but with minor inconsistencies everywhere, apparently we are not doing a very good job at) is "this is a string the user would literally type or see when following this description, so it must be typeset with monospace".

From that point of view, we'd want the `git checkout <something>` we see in the introductory sentence of this paragraph also typeset in mono. In order to match (i.e. to make it clear that the <something> part came from what the user typed), the change in this hunk your patch makes does make sense.

Show 13 quoted lines

> diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
> index f98b7c6ed..6643bc39f 100644
> --- a/Documentation/git-cvsserver.txt
> +++ b/Documentation/git-cvsserver.txt
> @@ -140,7 +140,7 @@ CVS_SERVER directly in CVSROOT like
>  ------
>  cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name>
>  ------
> -This has the advantage that it will be saved in your 'CVS/Root' files and
> +This has the advantage that it will be saved in your `CVS/Root` files and
>  you don't need to worry about always setting the correct environment
>  variable.  SSH users restricted to 'git-shell' don't need to override the default
>  with CVS_SERVER (and shouldn't) as 'git-shell' understands `cvs` to mean

I am using this hunk as just an example, but "this is what the user literally sees or types" point-of-view, `CVS/Root` and `CVS_SERVER` in the hunk fall into the same category. They are both literals in the sense that you cannot say "I do not like the words Root or SERVER, so in my CVS repository I am using CVS/Leaf and CVS_HELPER instead".

Show 9 quoted lines

> @@ -179,7 +179,7 @@ allowing access over SSH.
>  ------
>  --
>  3. If you didn't specify the CVSROOT/CVS_SERVER directly in the checkout command,
> -   automatically saving it in your 'CVS/Root' files, then you need to set them
> +   automatically saving it in your `CVS/Root` files, then you need to set them
>     explicitly in your environment.  CVSROOT should be set as per normal, but the
>     directory should point at the appropriate Git repo.  As above, for SSH clients
>     _not_ restricted to 'git-shell', CVS_SERVER should be set to 'git-cvsserver'.

Even if you are doing only pathnames and URLs, `git-shell` and `git-cvsserver` would be candidates to be in monospace, as they are names in $GIT_EXEC_PATH/.

Show 13 quoted lines

> diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
> index 7a2375a55..bbc984235 100644
> --- a/Documentation/technical/pack-protocol.txt
> +++ b/Documentation/technical/pack-protocol.txt
> @@ -107,7 +107,7 @@ Initiating the upload-pack or receive-pack processes over SSH is
>  executing the binary on the server via SSH remote execution.
>  It is basically equivalent to running this:
>  
> -   $ ssh git.example.com "git-upload-pack '/project.git'"
> +   $ ssh git.example.com "git-upload-pack `/project.git`"
>  
>  For a server to support Git pushing and pulling for a given user over
>  SSH, that user needs to be able to execute one or both of those

I agree with Eric's comment. If the user types `/project.git`, it would give a funny result ;-).