Re: [PATCH 2/2] gittutorial: wrap literal examples in backticks

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 20, 2023, 21:33 UTC
Message-ID: <xmqqedoexmqr.fsf@gitster.g>
In-Reply-To: <280c7d18b99e7cfc882d0dad0de536d4f40d4338.1681579244.git.martin.agren@gmail.com>

Martin Ågren <martin.agren@gmail.com> writes:

> Our coding guidelines prefer literal examples to be wrapped in
> `backticks` to typeset them in monospace.

True.

Everything I saw in this patch looked reasonable. Except for one minor thing that I found a bit iffy.

Show 13 quoted lines

>  ------------------------------------------------
>  alice$ cd /home/alice/project
>  alice$ git pull /home/bob/myrepo master
>  ------------------------------------------------
>  
> -This merges the changes from Bob's "master" branch into Alice's
> +This merges the changes from Bob's `master` branch into Alice's
>  current branch.  If Alice has made her own changes in the meantime,
>  then she may need to manually fix any conflicts.
>  
> -The "pull" command thus performs two operations: it fetches changes
> +The `pull` command thus performs two operations: it fetches changes
>  from a remote branch, then merges them into the current branch.

We use the name of an operation (e.g. "pull", "fetch", ...) to refer to a specific command name and also as a general concept. The former should be in `pair of backticks`, but not the latter. Unfortunately, there is no bright line between the two.

It is OK to say that this "pull" refers to the command line we see above, i.e. "git pull", but ...

>  Note that in general, Alice would want her local changes committed before
> -initiating this "pull".  If Bob's work conflicts with what Alice did since
> +initiating this `pull`.  If Bob's work conflicts with what Alice did since

... it is unclear if this one should be taken as a "literal example". It may flow more naturally if we take it as the name of general concept of one operation, as ...

>  their histories forked, Alice will use her working tree and the index to
>  resolve conflicts, and existing local changes will interfere with the
>  conflict resolution process (Git will still perform the fetch but will
>  refuse to merge -- Alice will have to get rid of her local changes in

... it contrasts with the "fetch" operation and the "merge" operation referred to here a bit better, it seems. The same for the reference of `fetch` in the next paragraph.

Show 8 quoted lines

>  some way and pull again when this happens).
>  
> -Alice can peek at what Bob did without merging first, using the "fetch"
> +Alice can peek at what Bob did without merging first, using the `fetch`
>  command; this allows Alice to inspect what Bob did, using a special
> -symbol "FETCH_HEAD", in order to determine if he has anything worth
> +symbol `FETCH_HEAD`, in order to determine if he has anything worth
>  pulling, like this:

But as I said, it is quite minor and I am not even convinced it is wrong, so let's take the whole thing as is and merge it down.

Thanks.