Re: What's cooking in git.git (Mar 2014, #03; Fri, 14)

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 17, 2014, 17:21 UTC
Message-ID: <xmqqd2hkg2qw.fsf@gitster.dls.corp.google.com>
In-Reply-To: <EA1EF5746EA7414CAE1320AA61100178@PhilipOakley>

"Philip Oakley" <philipoakley@iee.org> writes:

Show 7 quoted lines

>> * po/git-help-user-manual (2014-02-18) 1 commit
>> - Provide a 'git help user-manual' route to the docbook
>>
>> I am not sure if this is even needed.
>
> My rhetorical question would be "what should 'git help user-manual'
> do?" for the beginner, ...

Why would any _beginner_ even be expected to ask "git help" everything, including "user-manual", in the first place? Wouldn't things like /usr/share/doc/git-doc/ be the place to help them in a consistent manner across different programs instead?

> ... do we have a sort of policy on ensuring
> that the majority of user documentation should be available (or at
> least referenced) via the 'git help' mechanism?

I doubt that there should be such a policy.

"git help" is primarily to show the manual pages, and some technical details docs that are referenced from manpages may need to be reachable from it. The user manual, on the other hand, may reference individual manpages but because it is primarily a document that shows the overall flow to employ different commands, individual manpages referring to the user manual feels entirely the other way around.