Re: [PATCH 12/13] Documentation/Makefile: update git guide links

[Philip Oakley <philipoakley@iee.org>]

On 26/02/13 00:04, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.org> writes:
>
>> On 25/02/13 05:29, Junio C Hamano wrote:
>> ...
>>> In other words, can't you change the side that launches the document
>>> viewer so that we do not have to rename anything in the first place?
>>
>> The current help code will only show either 'git-<cmd>' man pages, or
>> git<guide>' pages so the current everyday and user-manual pages aren't
>> served by the existing help code.
>
> That is exactly what I meant by "the side that launches the document
> viewer".  We obviously would not want to type
>
> 	$ git help gituser-manual
>          $ git help giteveryday
Neither do I...

>
> I was wondering if you can keep document names as-is, register these
> names without "git" prefix (i.e. "user-manual.html")

I don't register them at all. I'm simply gathering a list of common 
guides in the array so that I can show that list as a 'usage' list, in 
exactly the same manner as the common commands list is used when 'git 
help' [ no options] is typed.

>   to the list of
> guide documents you are generating and compiling into the binary,
> and let the user ask:
>
> 	$ git help everyday

This is the existing way.
'git help tutorial' will display the gittutorial.txt man page - Note the 
git prefix is required by the code.

It is interesting to note that 'git help k' and 'git help gitk' produce 
the same response, while gitk can't be a common-command because it 
doesn't have a dashed form so isn't picked up by the script ;-)

>
> which you would turn into "browser %s/%s.html" % (GIT_HTML_PATH, 'everyday'),
> after checking "everyday" is one of the guides that are available to us.
>
> If some guides are already named with git prefix, you can keep them
> in the compiled-in list with that name.  We do not have to worry
> about redirects and people's bookmarks if we can avoid renaming
> existing pages, so "because grabbing everything with git* glob was
> easier to write the generate-guidelist script" is a false economy.

I was hoping to avoid more special casing of special files for special 
purposes..
> That is the single place we can afford to spend extra effort to make
> the end result easier to use by the users, no?
It could be done.

>
> Or am I misreading the series completely?
Yes, I think so (in terms of my starting point and approach).

I was using the existing common-commands approach _just_ to display a 
'usage' string of common guides. so that new users would be informed of 
their presence, and then they would use the existing command 'git help 
<guide>' to read about it (see also patch 2/13).

It was just unfortunate that the user-manual and everyday didn't fit the 
existing naming pattern causing the writing of patch 8 & 9 et seq to 
sort the renames to fit the pattern (just like git-remote-helpers)

Also, I think it's the user-manual, one of the files doesn't fit the 
'man page' style required by the MAN7 list in Documentation/Makefile, so 
that's another potential complication I need to bottom out - most likely 
keep it 'as is' in the Makefile and check that the Help command will 
display it properly if done that way.

Philip