Subject: Re: [PATCH 1/4] doc: git-push: update intro

From: "Kristoffer Haugsbakk" <[email-masked]>
Date: Fri, 29 Aug 2025 09:20:14 +0200

On Thu, Aug 28, 2025, at 18:18, Junio C Hamano wrote:
> "D. Ben Knoble" <[email-masked]> writes:
>
>>> +Updates one or more branches, tags, or other references in a remote
>>> +repository from your local repository.
>>
>> Considering the glossary entry[1] is for "ref", not "reference", what about
>>
>> (a) linking to the glossary (is this possible?), and/or
>> (b) saying something like
>>
>>     Updates one or more branches, tags, or other references (called "refs")…
>>
>> ?
>>
>> [1]: "git help glossary", or
>> https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-ref
>
> Both sound good ideas.  We should make sure that readers are aware
> of the glossary by linking into it from more places.

I wonder if the essential commands that everyone is likely to use ought
to have footnotes which point to the glossary for all the jargon.  That
way people can skim past them if they don’t care, especially if there is
(say) at most one footnote after every sentence.

I imagine you could get a lot of parentheticals without this approach.

-- 
Kristoffer Haugsbakk