msysgit, help: teach git help to open html from /doc/git/html/

msysgit, help: teach git help to open html from /doc/git/html/

[Steffen Prohaska]

I pushed the following patch to 4msysgit.git's mob branch

[ I finally found the mob branch at
ssh://mob@repo.or.cz/srv/git/git/mingw/4msysgit.git
which apparently was one git too much for my brain. ]


commit a9a42a347894edfbca33e48bed0fcd38ec334a35

     help (msysgit): teach git help to open html from /doc/git/html/

     Html pages will be opened using the default Windows application
     configured for html. This code path is taken for msysgit (mingw).

     It is assumed that html pages are installed at /doc/git/html.
     This needs to be ensured by the msysgit superproject to make this
     patch useful. html pages should be cloned from git.git's main
     repo. This is the easiest way to get up-to-date documentation,
     without requiring the complete tool chain to generate them
     locally.

     If html pages are not yet there, you can use the following
     commands to get them:

         mkdir -p /doc/git/html
         cd /doc/git/html/
         git init
         git config remote.origin.url git://git.kernel.org/pub/scm/ 
git/git.git
         git config remote.origin.fetch refs/heads/html:refs/remotes/ 
origin/html
         git fetch
         git checkout --track -b html origin/html

     and update the html documentation with

         git pull

The superproject should be setup in /share/GitMe/setup-msysgit.sh to
fetch the html pages as a submodule. But I don't understanding
submodules good enough to do so.

If you then type 'git help <command>' Firefox or Explorer or whatever
you configured as your default html viewer will show you the git help.
I think this is a good idea for Windows users.


Junio,
are you interested in such patches at this time. The patch doesn't
interfere with the existing code, but clutters it with ifdefs.

	Steffen

Re: msysgit, help: teach git help to open html from /doc/git/html/

[Junio C Hamano]

Steffen Prohaska <prohaska@zib.de> writes:

> Junio,
> are you interested in such patches at this time. The patch doesn't
> interfere with the existing code, but clutters it with ifdefs.

Actually "showing HTML pages upon 'git help' request" makes
sense even on Unixen.  I think a patch to help.c::cmd_help()
that allows the user to specify alternate action before going to
the codepath to call show_man_page(help_cmd) would make sense,
like the attached patch.

Having said that, a patch that makes the build procedure depend
on the presense of the html branch is unacceptable, as that
branch does not even exist in my private build repository.  If
you are building html pages from the source, it surely would
make sense.

---
 cache.h       |    3 +++
 config.c      |    5 +++++
 environment.c |    1 +
 help.c        |    3 ++-
 4 files changed, 11 insertions(+), 1 deletions(-)

diff --git a/cache.h b/cache.h
index 4507404..d7aeaaf 100644
--- a/cache.h
+++ b/cache.h
@@ -597,4 +597,7 @@ extern void *convert_sha1_file(const char *path, const unsigned char *sha1, unsi
 /* match-trees.c */
 void shift_tree(const unsigned char *, const unsigned char *, unsigned char *, int);
 
+/* help.c - show manual page for the named command */
+extern char *custom_help_cmd;
+
 #endif /* CACHE_H */
diff --git a/config.c b/config.c
index dc3148d..8a9d0b7 100644
--- a/config.c
+++ b/config.c
@@ -431,6 +431,11 @@ int git_default_config(const char *var, const char *value)
 		return 0;
 	}
 
+	if (!strcmp(var, "core.helpcmd")) {
+		custom_help_cmd = xstrdup(value);
+		return 0;
+	}
+
 	/* Add other config variables here and to Documentation/config.txt. */
 	return 0;
 }
diff --git a/environment.c b/environment.c
index b5a6c69..05c4ba5 100644
--- a/environment.c
+++ b/environment.c
@@ -34,6 +34,7 @@ char *pager_program;
 int pager_in_use;
 int pager_use_color = 1;
 char *editor_program;
+char *custom_help_cmd;
 int auto_crlf = 0;	/* 1: both ways, -1: only when adding git objects */
 
 /* This is set by setup_git_dir_gently() and/or git_default_config() */
diff --git a/help.c b/help.c
index 1cd33ec..49db50d 100644
--- a/help.c
+++ b/help.c
@@ -168,6 +168,7 @@ static void list_common_cmds_help(void)
 static void show_man_page(const char *git_cmd)
 {
 	const char *page;
+	const char *help = custom_help_cmd ? custom_help_cmd : "man";
 
 	if (!prefixcmp(git_cmd, "git"))
 		page = git_cmd;
@@ -180,7 +181,7 @@ static void show_man_page(const char *git_cmd)
 		page = p;
 	}
 
-	execlp("man", "man", page, NULL);
+	execlp(help, help, page, NULL);
 }
 
 void help_unknown_cmd(const char *cmd)

Re: msysgit, help: teach git help to open html from /doc/git/html/

[Steffen Prohaska]

On Aug 11, 2007, at 11:43 PM, Junio C Hamano wrote:

> Steffen Prohaska <prohaska@zib.de> writes:
>
>> Junio,
>> are you interested in such patches at this time. The patch doesn't
>> interfere with the existing code, but clutters it with ifdefs.
>
> Actually "showing HTML pages upon 'git help' request" makes
> sense even on Unixen.  I think a patch to help.c::cmd_help()
> that allows the user to specify alternate action before going to
> the codepath to call show_man_page(help_cmd) would make sense,
> like the attached patch.

So the custom command needs to have the knowledge how to find
the page (as 'man' has), based on the string 'git-<command>'.

Makes sense to me to build only the generic mechanism into
help.c and delegate the rest to core.helpcmd.


> Having said that, a patch that makes the build procedure depend
> on the presense of the html branch is unacceptable, as that
> branch does not even exist in my private build repository.

Sure, the build procedure doesn't depend on it. The executable
wouldn't do anything useful if no html is present.


> If you are building html pages from the source, it surely would
> make sense.

I'd prefer to fetch pages from your repo, at least for msysgit.
Building them requires tools that are, to my knowledge, not
present in msysgit.

	Steffen

Re: msysgit, help: teach git help to open html from /doc/git/html/

[Nguyen Thai Ngoc Duy]

This reminds me a patch I made before:

http://thread.gmane.org/gmane.comp.version-control.git/49217/focus=49575

With a little modification you can use ShellExecute to open html if
there is no suitable program to open it. The last commit on
mingw.git's mob branch does that (not based on my mentioned patch
though).

On 8/11/07, Steffen Prohaska <prohaska@zib.de> wrote:
> I pushed the following patch to 4msysgit.git's mob branch
>
> [ I finally found the mob branch at
> ssh://mob@repo.or.cz/srv/git/git/mingw/4msysgit.git
> which apparently was one git too much for my brain. ]
>
>
> commit a9a42a347894edfbca33e48bed0fcd38ec334a35
>
>      help (msysgit): teach git help to open html from /doc/git/html/
>
>      Html pages will be opened using the default Windows application
>      configured for html. This code path is taken for msysgit (mingw).
>
>      It is assumed that html pages are installed at /doc/git/html.
>      This needs to be ensured by the msysgit superproject to make this
>      patch useful. html pages should be cloned from git.git's main
>      repo. This is the easiest way to get up-to-date documentation,
>      without requiring the complete tool chain to generate them
>      locally.
>
>      If html pages are not yet there, you can use the following
>      commands to get them:
>
>          mkdir -p /doc/git/html
>          cd /doc/git/html/
>          git init
>          git config remote.origin.url git://git.kernel.org/pub/scm/
> git/git.git
>          git config remote.origin.fetch refs/heads/html:refs/remotes/
> origin/html
>          git fetch
>          git checkout --track -b html origin/html
>
>      and update the html documentation with
>
>          git pull
>
> The superproject should be setup in /share/GitMe/setup-msysgit.sh to
> fetch the html pages as a submodule. But I don't understanding
> submodules good enough to do so.
>
> If you then type 'git help <command>' Firefox or Explorer or whatever
> you configured as your default html viewer will show you the git help.
> I think this is a good idea for Windows users.
>
>
> Junio,
> are you interested in such patches at this time. The patch doesn't
> interfere with the existing code, but clutters it with ifdefs.
>
>         Steffen
> -
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>


-- 
Duy

Re: msysgit, help: teach git help to open html from /doc/git/html/

[Nguyen Thai Ngoc Duy]

On 8/11/07, Nguyen Thai Ngoc Duy <pclouds@gmail.com> wrote:
> This reminds me a patch I made before:
>
> http://thread.gmane.org/gmane.comp.version-control.git/49217/focus=49575

And the second patch:

http://article.gmane.org/gmane.comp.version-control.git/49216

> With a little modification you can use ShellExecute to open html if
> there is no suitable program to open it. The last commit on
> mingw.git's mob branch does that (not based on my mentioned patch
> though).
-- 
Duy

Re: msysgit, help: teach git help to open html from /doc/git/html/

[Steffen Prohaska]

On Aug 12, 2007, at 2:16 AM, Nguyen Thai Ngoc Duy wrote:

> On 8/11/07, Nguyen Thai Ngoc Duy <pclouds@gmail.com> wrote:
>> This reminds me a patch I made before:
>>
>> http://thread.gmane.org/gmane.comp.version-control.git/49217/ 
>> focus=49575
>
> And the second patch:
>
> http://article.gmane.org/gmane.comp.version-control.git/49216
>
>> With a little modification you can use ShellExecute to open html if
>> there is no suitable program to open it. The last commit on
>> mingw.git's mob branch does that (not based on my mentioned patch
>> though).

So we have three approached now:

1) Nguyen's approach using '--html'/core.help=html to explicitly
choose html as the format of choice. The core.htmlprogram is used
and a printf style format string can be used to specify required
command line parameters.

2) Junio's light-weight core.helpcmd, which gets passed the string
that would normally be passed to 'man'. Helpcmd needs to figure
out how to do the right thing. Most likely helpcmd would be a
small shell script that does the mapping to a file or url for
displaying the help. But it can also be a more complex thing,
for example load a Windows chm file and jump to a specific anchor,
or whatsoever.

3) Steffen's msysgit specific code path to display always locally
installed html pages on Windows, and never display 'man' pages.


 From my perspective, (3) would be the fastest way to get a useful
git help in msysgit. It only needs to be applied and shipped. But
it provides no benefit for git.git on other architectures.

(2) is a very light-weight extension to core git, yet capable of
providing everything we need, or can think of in the future. It
makes sense to me to delegate the details how to find the help,
based on the git command, to an external helper.

Maybe I work a bit more on Junio's approach later the day. I would
like to see a useful help system in msysgit before advertising it
to a larger audience that has no git experience.

	Steffen