Re: suggestions for gitweb

[Jakub Narebski <jnareb@gmail.com>]

On Sun, 13 May 2007, Michael Niedermayer wrote:
> On Sat, May 12, 2007 at 03:39:25PM -0700, Junio C Hamano wrote:
>> Michael Niedermayer <michaelni@gmx.at> writes:
>> 
>>> * gitweb uses many terms which are new to a non git user, 
>>>   [...] so i belive  
>>>   a small help text linked to from all pages which contains a short
>>>   definition of all the git(web) specific terms would be very helpfull
>>>   something like
>>>     blob        - file      at a specific revision/date
>>>     tree        - directory at a specific revision/date
>>>     (short) log - project wide commit log
>>>     history     - short log equivalent for a file or directory
>> 
>> Coming fron non-CVS camp, I think changing this to non-git terms
>> is very harmful than educating users who are migrating from
>> other systems.
> 
> You must have misunderstand me :(
> I want to educate them, but I cannot as I am not speaking about ffmpeg
> developers/contributors but rather random people who are curious and 
> want to take a look at the ffmpeg source
> 
> For them a simple help link similar to "ViewVC Help" which ViewVC has
> on the bottom right of its pages would be great IMHO
> also the text above is a pure random suggestion by a svn user and was
> not intended to redefine any git terms

Back in the times where there was no git homepage, the git logo at
top right corner of gitweb page was link to git documentation
  http://www.kernel.org/pub/software/scm/git/docs/
(with the title of "git documentation"), or to be more exact to HTML
version of git(7) man page. This page has link to git glossary, where
you can find explanation of this terms. Now it is link to git homepage;
I'm not sure where / if there is here link to git glossary.

It is very easy to change URL where git logo points to; either via
setting appropriate variables when running make to get gitweb.cgi out
of gitweb.perl, or via configuration file for gitweb. You can point
git logo to lead to your documentation of gitweb terms.

But gitweb was primarly meant for developers which works which git,
and have knowledge of git terms (and gitweb terms, as gitweb uses them).

Adding some gitweb-help.html page, linked somewhere from within gitweb
pages (I think it shouldn't be embedded in gitweb, like help for search
options is), certainly is possible. And perhaps we should do that, now
that gitweb is more widely deployed, and used by "accidental" users
(developers) with no knowledge of git, and perhaps even without
knowledge of SCM [terms].

By the way, I think only "blob" and perhaps "tree" terms really needs
explanation...


Sidenote: we used to have some links to 'blob_plain' action, which
returns exact contents of file at given revision to the browser
(trying to set appropriate mime type), named "plain" and some named
"raw". This ambiguity was resolved in favor of "raw". Is it better?
I'm not sure...

> [...]
>>> * on the history page there are "blob", "commitdiff" and "diff to current"
>>>   the obvious missing one is "diff to previous" which would be the diff to
>>>   the previous blob of this file
>> 
>> Isn't that commitdiff, or commitdiff on that page does not limit
>> the diff to the blob?
> 
> commitdiff doesn't limit it to the blob ...

It should be fairly easy to add "diff to prev" link, but is it really
needed? It would be yet another link. Diff to previous version of blob
is contained in "commitdiff" and is easy to find and go to... well,
unless you are used to make large commits...

-- 
Jakub Narebski
Poland