From: Philip Oakley <philipoakley@iee.org>
To: Junio C Hamano <gitster@pobox.com>
Cc: GitList <git@vger.kernel.org>
Subject: Re: [PATCH 12/13] Documentation/Makefile: update git guide links
Date: Tue, 26 Feb 2013 20:24:45 +0000 [thread overview]
Message-ID: <512D1A0D.7020203@iee.org> (raw)
In-Reply-To: <7va9qsndnn.fsf@alter.siamese.dyndns.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
next prev parent reply other threads:[~2013-02-26 20:25 UTC|newest]
Thread overview: 37+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-02-23 23:05 [PATCH 00/13] Git help option to list user guides Philip Oakley
2013-02-23 23:05 ` [PATCH 01/13] Use 'Git' in help messages Philip Oakley
2013-02-23 23:41 ` David Aguilar
2013-02-23 23:54 ` Philip Oakley
2013-02-24 8:59 ` Junio C Hamano
2013-02-24 21:50 ` Philip Oakley
2013-02-24 22:11 ` David Aguilar
2013-02-23 23:05 ` [PATCH 02/13] Show 'git help <guide>' usage, with examples Philip Oakley
2013-02-24 14:39 ` W. Trevor King
2013-02-24 22:05 ` Philip Oakley
2013-02-23 23:05 ` [PATCH 03/13] Help.c use OPT_COUNTUP Philip Oakley
2013-02-23 23:05 ` [PATCH 04/13] Help.c add --guide option Philip Oakley
2013-02-23 23:05 ` [PATCH 05/13] Help.c: add list_common_guides_help() function Philip Oakley
2013-02-24 9:01 ` Junio C Hamano
2013-02-24 21:51 ` Philip Oakley
2013-02-25 5:24 ` Junio C Hamano
2013-02-25 23:43 ` Philip Oakley
2013-02-25 23:55 ` Junio C Hamano
2013-02-23 23:05 ` [PATCH 06/13] Add guide-list.txt and extraction shell Philip Oakley
2013-02-24 14:51 ` W. Trevor King
2013-02-24 22:12 ` Philip Oakley
2013-02-23 23:05 ` [PATCH 07/13] Extend name string for longer names Philip Oakley
2013-02-23 23:05 ` [PATCH 09/13] Rename everyday to giteveryday Philip Oakley
2013-02-24 14:55 ` W. Trevor King
2013-02-24 22:16 ` Philip Oakley
2013-02-23 23:05 ` [PATCH 10/13] Update Git(1) links to guides Philip Oakley
2013-02-23 23:05 ` [PATCH 11/13] Add missing guides to list and regenerate Philip Oakley
2013-02-23 23:06 ` [PATCH 12/13] Documentation/Makefile: update git guide links Philip Oakley
2013-02-24 14:58 ` W. Trevor King
2013-02-24 22:31 ` Philip Oakley
2013-02-25 5:29 ` Junio C Hamano
2013-02-25 23:43 ` Philip Oakley
2013-02-26 0:04 ` Junio C Hamano
2013-02-26 20:24 ` Philip Oakley [this message]
2013-02-23 23:06 ` [PATCH 13/13] Fixup! doc: giteveryday and user-manual man format Philip Oakley
2013-02-24 15:01 ` W. Trevor King
2013-02-24 22:32 ` Philip Oakley
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=512D1A0D.7020203@iee.org \
--to=philipoakley@iee.org \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).