Re: [PATCH] git-gui: Add hotkeys to set widget focus

From: Philip Oakley <philipoakley@iee.email>
To: Pratyush Yadav <me@yadavpratyush.com>
Cc: Birger Skogeng Pedersen <birger.sp@gmail.com>, git@vger.kernel.org
Subject: Re: [PATCH] git-gui: Add hotkeys to set widget focus
Date: Mon, 2 Sep 2019 18:23:07 +0100	[thread overview]
Message-ID: <ca5052b8-32ea-5d38-76ba-2389b5f95e45@iee.email> (raw)
In-Reply-To: <20190902122527.6cbcizo5dsewrl57@yadavpratyush.com>

On 02/09/2019 13:25, Pratyush Yadav wrote:
> On 01/09/19 11:27PM, Philip Oakley wrote:
>> Hi Pratyus,
>> On 01/09/2019 12:32, Pratyush Yadav wrote:
>>> Hi Birger,
>>>
>>> In case you haven't been following the list, Pat has been inactive
>>> recently, so I am acting as the interim maintainer of git-gui for now,
>>> because no one else stepped up and Junio would rather not maintain it.
>>>
>>> You can find my fork over athttps://github.com/prati0100/git-gui. I
>>> munged your patches to apply on my tree (which is separate from the
>>> git.git tree), but it would be great if you base them on my tree next
>>> time around.
>> Are there any plans or thoughts about creating a more inclusive man page for
>> the git-gui?
>   
> Having better documentation has been one of the things I have in my
> future plans, but I can't really say when I can get to it depending on
> my schedule and time available. I have a couple other topics active
> which I'd like to get resolved first.
>
> Of course, if someone else is willing to take the initiative, I'm happy
> to help :)

The main aspect that would help for providing a contribution would be to 
at least decide the (rough) framework/format for a full Gui 'man page'. 
The existing one 
https://github.com/git/git/blob/master/Documentation/git-gui.txt is 
rather short. (would also need the sub-tree integration to be finessed)

e.g.
1. how much should it be done via 'include' files (like the git-config 
man page now does include::config.txt[] and onwards).

2. Does it use the doc-book man-page format, or something akin to the 
former tutorial format? (everything appears to have shifted to the man 
page format, so looks like man format is the one.. [1,2,3,4]

I'm thinking that, as it is a big job, it will need the documentation to 
be split over a number of small include files so that more folk can be 
contributors.

>> Such things as the Options dialog linkages [1], and how to drive the command
>> line options are areas I've wondered about over the years.
>>
>> Not exactly sure how our plain text man pages and formatted HTML would fare
>> for describing the gui layout and where to click. One thing I am noting is
>> that these hotkey nicely have numbers so can easily be used for reference..
>   
> For the options dialog, I think a "tooltip" (something like what you get
> when you hover over a image in a browser) that describes the option is a
> better idea than having a separate man page. I don't expect the option
> descriptions to be too long or complicated. This approach has the added
> benefit of not having to maintain a separate man page. Whenever someone
> adds a new options, they have to add its description as well.
A tool tip that says 'see git help config.. ' could be done. Any 
pointers to an existing one for trying a cookie cutter approach getting 
started on those ones?
>
> I also think the "tools" feature needs some documentation, especially
> about what environment variables we export.
>
> Other than these two, I don't see many places that need too much
> documentation. Rest of the UI is pretty self-intuitive, at least to me.
>
>> Philip
>>
>> [1] https://stackoverflow.com/questions/6007823/is-there-a-help-page-for-the-git-gui-options-dialog
[1,2,3,4] 
https://github.com/git/git/blob/master/Documentation/giteveryday.txt
https://github.com/git/git/blob/master/Documentation/gittutorial.txt
https://github.com/git/git/blob/master/Documentation/gitcore-tutorial.txt
https://github.com/git/git/blob/master/Documentation/everyday.txto