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

From: Philip Oakley <philipoakley@iee.org>
Date: Feb 26, 2013, 20:24 UTC
Message-ID: <512D1A0D.7020203@iee.org>
In-Reply-To: <7va9qsndnn.fsf@alter.siamese.dyndns.org>

On 26/02/13 00:04, Junio C Hamano wrote:

Show 16 quoted lines

> 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.

Show 5 quoted lines

>   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 ;-)

Show 9 quoted lines

>
> 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