search

aviaryan / Clipjump

:clipboard: Clipboard Manager for Windows, built in AutoHotkey
http://clipjump.sourceforge.net/
384 stars 62 forks source link

Several enhancements on documentation #42

Closed hoppfrosch closed 10 years ago

aviaryan commented 10 years ago

Commit 8 not needed. All the custom shortcuts are already given in the context menu. The common ones (Ctrl+F for find...) are already known to the users. If you provide gui accessibility keys of Channel organizer, it will become necessary to provide keys for History GUI and then Plugin Gui and more.. This is not necessary as Clipjump menus are plain, not nested and not large. You don't have to dig to find the needed feature and its shortcut.

aviaryan commented 10 years ago

I found a problem with your shortcuts.html

see [Paste Mode] - almost all [Paste Mode] shortcuts work in [Search Mode] as well

Maybe in the wrong place. Also it should "press Ctrl + paste mode key to execute a paste mode feature when search is active."

Also there is a typo in that page toogles (not because of these commits)

hoppfrosch commented 10 years ago

Concerning Commit 8 (e191860): I consider the shortcuts page as a comprehensive list (reference) of the most hotkeys available in Clipjump. Some of the shortcuts are not mentioned within the documentation (for example "Refresh" - (F5) (History GUI, Channel Organizer) - and on the Context-Menus do not show the shortcut for Refresh ...) This might be mentionend anywhere within the documentation - but I cannot remember to have it seen yet.

The above (missing shortcuts on context menus) is even more confusing as some of the menu entries don't have a shortcut at all (for example right clicking on the channel list in channel organizer - "New" does not have any shortcut)

On the other hand: as most keyboards offer a special key to open the context menu, each command on the context menu has an implicit shortcut via the "context menu" button and the up/down arrows - so why special shortcuts at all? Shortcut should be - as the name says - SHORTCUTS and offer almost direct access to the features - without pressing a complex key-sequence. The documentation of those shortcuts should be easy accessible as well (and not via digging deep in the documentation or opening the context menu ...)

So I thought it might be a good idea to have a comprehensive list of all supported shortcuts. This would include for sure documentation of shortcuts of History GUI, Plugin Gui and more

Concerning: Method to document shortcuts within language files?

There are two methods within language files to document shortcuts.

For example in language file:

_!x = Alt+X
_!c = Alt+C
...
TIP_copy = Copy current Clip
TIP_move = Move current Clip
...
HST_m_edit = Edit Clip      (Ctrl+H)

Within channelOrganizer.ahk:

Menu, chOrgLVMenu, Add, % TXT.HST_m_prev, chOrg_preview
...
Menu, chOrgLVMenu, Add, % TXT.ORG_m_openPst, chOrg_openPasteMode
    ...
    Menu, chOrgSubM, Add, % TXT.TIP_move "    (" TXT["_!x"] ")", chOrgCut
    Menu, chOrgSubM, Add, % TXT.TIP_copy "    (" TXT["_!c"] ")" , chOrgCopy

What's the expected way to document shortcuts?

I think the second one is more error prune (needs more editing ...)

Which way would you recommend?

Concerning: [Search Mode] or [Search-Paste Mode]?

What name to use for [Search-Paste Mode]? [Search-Paste Mode] might be a good choice, since the corresponding functions in the API are prefixed spm - on the other hand Cancel-, Delete-, Copy-, Move- and Delete All- Mode are not called for example Move-Paste Mode (unless they are as well sub-modes of the [Paste-Mode])

I found a problem with your shortcuts.html

Will fix it

"press Ctrl + paste mode key to execute a paste mode feature when search is active."

will add it

Also there is a typo in that page toogles

will fix it

aviaryan commented 10 years ago

Sorry for such a late response. I completely forgot about this active issue.

Some of the shortcuts are not mentioned within the documentation (for example "Refresh" - (F5) (History GUI, Channel Organizer) - and on the Context-Menus do not show the shortcut for Refresh ...) This might be mentionend anywhere within the documentation - but I cannot remember to have it seen yet.

The main reason of not mentioning them is because they are common. But I feel your perspective is right here. Will you create a new group on the introduction as "Window Interfaces" and then add things like Organizer, History and more in it.

or having separated documentation- and shortcut-string and put both together in Sourcecode?

This one. I would like to do this way in the future and have no plans to correct the past keys because of the reason you already gave. !! NO RISK !!

What name to use for [Search-Paste Mode]?

[Search-paste mode] or when writing it in language - "search in paste mode".

hoppfrosch commented 10 years ago

Sorry for the late respnse - I've been quite busy the last days (and the next days as well ...)

Will you create a new group on the introduction as "Window Interfaces" and then add things like Organizer, History and more in it.

I'll try to do this - but it's not completely clear to me what you mean here:

I'm not quite sure as most of the window interfaces already have their own separate pages (organizer.html, history.html) ..

I would like to do this way in the future and have no plans to correct the past keys because of the reason you already gave. !! NO RISK !!

I see the risk - but in terms of maintainability it might make more sense to have only one method documenting hotkeys. Therefore it might be a goal in longer terms to homogenize this ... (for example: on the context menus certain hotkeys are missing (there is a menu entry for "Refresh" - but "F5" is missing) If I want to correct this, it's difficult for anybody else than you to distinguish in language-file whether TXT["F5"] is empty or missing - or the HST_m_ref = &Refresh should simply be HST_m_ref = &Refresh F5) This makes translation quite complicated - since you cannot be sure whether the Shortcut should be added in translation file (since some commands do have shortcuts and others not ...) or is already added in Sourcecode.

What I would suggest is a third method, a combination of both:

Allow "variables" within language files and before using the language file preprocess it:

    _!x = Alt+X
    TIP_move = Move current Clip  ([% _!x %])`

During preprocess step all entities [% VAR %] are replaced by the value of VAR, so that using TXT:TIP_move in the source inserts Move current Clip (Alt + X)

Doing so, I see several advantages:

I think my suggestion makes maintaining languages files easier and your sourcecode more fail-safe (missing or using wrong shortcuts ...)

aviaryan commented 10 years ago

I'm not quite sure as most of the window interfaces already have their own separate pages

That's true. I am also confused as to what should be done. I think we should drop this idea for the time being and only add something like "Important bindings" section at the end of history.html, organizer.html which will only have (important & un-documented) or global combinations.

Allow "variables" within language files and before using the language file preprocess it: _!x = Alt+X TIPmove = Move current Clip ([% !x %])` During preprocess step all entities [% VAR %] are replaced by the value of VAR, so that using TXT:TIP_move in the source inserts Move current Clip (Alt + X)

That's a good idea. One problem in this method is values of all hotkey variables (like _!x) will be needed to be defined before other keys who ask for them so that the variable is active when needed.

Both of the above things, I am not sure with. It would be better to wait till better ideas (or time) come.

Other suggestions

hoppfrosch commented 10 years ago

That's true. I am also confused as to what should be done.

I would prefer to have a own page for each major window interface with detailed information. On the basic_help.html I would only give an short overview on each window interface and link to the detailled information ... (BTW: that's something I already tried to discuss on #25)

I think we should drop this idea for the time being and only add something like "Important bindings" section at the end of history.html, organizer.html which will only have (important & un-documented) or global combinations.

I would suggest on shortcuts.html:

I agree to postpone this until you/we have a clearer vision ...

One problem in this method is values of all hotkey variables (like _!x) will be needed to be defined before other keys who ask for them so that the variable is active when needed.

This might be solved by n-iterations on the replacement step (running it several times to resolve all templates ([% VAR %] is what I would call a template). This should solve the problem you see. Also the problem of having nested templates like

_!x = Alt+X
TIP_move = Move current Clip  ([% _!x %])`
FANTASY_key = [% TIP_move %] to a new channel

could be solved via iterations ...

Please use just <br> instead of </br> and <br/> or other variants ... It adds to extra diff and then again more extra diffs. HTML 5 says <br> is the way to go.

OK. I'm more a X...-Person - prefering XHTML style. I personally find it much clearer to see where any tag ends if there is a closing tag available and automated parsing and validation is much easier as well if the text is encapsulated by opening and closing tags instead of relying on implicit rules. Beneath this it's more consistent and easier to remember having all tags properly closed (as some tags explicitly need a closing tag (i.e. <a>...</a>) whilst others don't (i.e <br> or <li>) - at least for me.

aviaryan commented 10 years ago

I would prefer to have a own page for each major window interface with detailed information. On the basic_help.html I would only give an short overview on each window interface and link to the detailled information ... (BTW: that's something I already tried to discuss on #25)

Yes. It would be better to add shortcuts for window interfaces in their respective pages. That being said a page OR section in plugins\index.html file for plugin manager should be created.

having a section on each page (History.html, Organizer.html) with the special keys listed (if there are any) (or is it better to have it on shortcuts page in sake of completeness?)

No. have them in their pages.

This might be solved by n-iterations on the replacement step (running it several times to resolve all templates ([% VAR %] is what I would call a template).

hoppfrosch commented 10 years ago

I consider this pull request as ready for pull - I'd prefer having this pull request merged before starting on new issues (esp. #50 & #51) to avoid additional working overhead

The other topics discussed here will be parts of separate issues. (and separate pull requests as well)

aviaryan commented 10 years ago

Please solve the <br> inconsistency in this pull. I will have it merged then.

aviaryan commented 10 years ago

Thanks @hoppfrosch. I will merge it soon.

aviaryan commented 10 years ago

Merged !