Improve 'git help' with basic user guide linkss

> My real question is on the right approach to generating a list of
> guides and including them into the git help options. I'm planning on
> extending the command-list.txt file to include 'guides' and then
> extending the generate-cmdlist.sh to generate a guides array in
> common-cmds.h.

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> I'm looking at extending the 'git help' to include some information
>> for the basic user who isn't ready for the extensive man page
>> documentation for the various commands.
>
> We have pointers at the beginning of "git(1)" for that exact reason.
> I am not saying the documents pointed at from there are perfect, but
> shouldn't that approach work?

>
>> My real question is on the right approach to generating a list of
>> guides and including them into the git help options. I'm planning on
>> extending the command-list.txt file to include 'guides' and then
>> extending the generate-cmdlist.sh to generate a guides array in
>> common-cmds.h.
>
> Having a catalog of guide documents in help.o sounds like a good way
> to go, but I doubt "command-list" is a good place to store it.  It
> is about git subcommands, "git help -a" uses it to show the list of
> them, and the bash completion support uses the list via "git help -a".
>
> The common-cmds.h does not have to be the only avenue to add your
> catalog of guide documents to help.o. As a part of the build
> procedure, you can list Documentation/guides/ and generate an array
> definition into "guides.h", and add #include "guides.h" in help.c,
> for example.

>
>> I'm thinking of adding -g --guides and -c --commands options to
>> complement the existing -a --all (becomes both commands and guides)
>
> Complement is fine.  Contaminating -a with guides is probably not.

>
>> I was expecting to update the user-manual. to become
>> gituser-manual.txt so that the existing 'git help user-manual' scheme
>> would discover it. The Tutorial and the User manual obviously(?)
>> being
>> the first port of call for the confused user.
>
> Again, we do have pointer to tutorial fairly prominently at the
> beginning of "git(1)".  Perhaps we want index.html that redirects to
> git.html or something?

> My initial https://github.com/PhilipOakley/git/commit/e6217d simply
> updates
> -  N_("See 'git help <command>' for more information on a specific
> command.");
> +  N_("See 'git help <command>' for more information on a specific
> command.\n"
> +     "Or 'git help <guide>', such as 'tutorial' for an introduction
> to Git.");
> as a starter for the new users.

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> My initial https://github.com/PhilipOakley/git/commit/e6217d simply
>> updates
>> -  N_("See 'git help <command>' for more information on a specific
>> command.");
>> +  N_("See 'git help <command>' for more information on a specific
>> command.\n"
>> +     "Or 'git help <guide>', such as 'tutorial' for an introduction
>> to Git.");
>> as a starter for the new users.
>
> Yeah, that would be a good change to make to "git help<RETURN>"
> output.

>
>> My view is that help --all (-a) is essentially incomplete as it
>> currently doesn't provide all the help.
>
> It has always been about "tell me all subcommands", not about "give
> me all the help you could give me".  You are not adding a "help"
> subcommand to a system you wrote last week.  Changing the semantics
> this late feels, eh, too late.

> From: "Junio C Hamano" <gitster@pobox.com>
> Sent: Friday, February 08, 2013 10:54 PM
>> "Philip Oakley" <philipoakley@iee.org> writes:
>>
>>> My initial https://github.com/PhilipOakley/git/commit/e6217d simply
>>> updates
>>> -  N_("See 'git help <command>' for more information on a specific
>>> command.");
>>> +  N_("See 'git help <command>' for more information on a specific
>>> command.\n"
>>> +     "Or 'git help <guide>', such as 'tutorial' for an introduction
>>> to Git.");
>>> as a starter for the new users.
>>
>> Yeah, that would be a good change to make to "git help<RETURN>"
>> output.
>
> I'll sort some patches early next week (the weekend's committed 
> elsewhere)
>
>>
>>> My view is that help --all (-a) is essentially incomplete as it
>>> currently doesn't provide all the help.
>>
>> It has always been about "tell me all subcommands", not about "give
>> me all the help you could give me".  You are not adding a "help"
>> subcommand to a system you wrote last week.  Changing the semantics
>> this late feels, eh, too late.
>
> OK, I'll limit the the follow-ons to just an extra --guides option 
> (probably just a list of the common guides initially), and 
> leave --all(-a) for just the commands.
>

> Obviously (?) this is generated from the command-list.txt file, though I 
> don't see a shell script that would generate the 
> 'cmds-mainporcelain.txt' (etc.) files 
> (//github.com/gitster/git-htmldocs). They are also part of the msysgit 
> install.
> 
> Where should I be looking to see how they are generated?

> On Tue, Feb 12, 2013 at 11:11:17AM -0000, Philip Oakley wrote:
>> Obviously (?) this is generated from the command-list.txt file, 
>> though I
>> don't see a shell script that would generate the
>> 'cmds-mainporcelain.txt' (etc.) files
>> (//github.com/gitster/git-htmldocs). They are also part of the 
>> msysgit
>> install.
>>
>> Where should I be looking to see how they are generated?
>
> Documentation/cmd-list.perl
>
> If you look in Documentation/Makefile, cmds-mainporcelain.txt is a
> member of cmds_txt, which depends on cmd-list.made, which is a stamp
> file created after invoking cmd-list.perl.
>
>
> John