Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation

["Julia Evans" <julia@jvns.ca>]

>> What is definitely the case is that there is no hyphen between `git` and
>> the first word, maybe in order to distinguish section 1 commands) and
>> section 5 and 7 manpages.
>
> Thanks, I'll change the naming, I didn't realize that. For some reason I felt
> sure it was the other way. Maybe we should rename `gitmergeconflicts`
> to `gitmerge-conflicts` in the other patch series too.
>
> My best guess is that I made that mistake because I (maybe idiosyncratically)
> always use `man <page>`  to access the Git man pages, and typing
> `man gitdetached-head` feels awkward to me. 
> But of course we're recommending that folks use `git help detached-head`,
> and `git help detached-head` is much nicer than `git help detachedhead`.

Reflecting on this a little more, I think there's a bit of a disconnect between
how we recommend users use the Git help system (via `git help config`)
and how we refer to other man pages in the man pages, which is like this:

> (see git-fetch(1), git-config(1) and gitmodules(5))

If a user sees a reference like `git-config(1)` or `gitmodules(5)`,
the most obvious way to look it up is to type `man git-config`, or
`man gitmodules` and not to deduce that you can run
`git help config` or `git help modules`: Especially because sometimes
you need to remove a `git-` from the beginning and sometimes just
`git`. I'm don't think the `git-help` man page even explains how those
prefixes work.

So at some point if we want to really encourage people to use
`git help` instead of `man` we might want to revisit how we present
the internal references in the man pages.

Obviously not something to solve right now, and I don't know
what a good solution would be.