Several enhancements on documentation

[hoppfrosch]

No description provided.

[aviaryan]

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]

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]

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?

• Writing them directly into language file (as for HST_m_edit)
• or having separated documentation- and shortcut-string and put both together in Sourcecode?

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]

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]

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:

• Introduce an new section on basic_help.html describing the single "Window Interfaces"?
• or introduce a section for each window interface on the shortcuts.html giving a comprehensive list of all shortcuts?

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:

• All text shown in Clipjump can be customized WITHOUT changing the sourcecode (in your suggestion this cannot be done: introducing a missing shortcut on the GUI-display would need sourcecode changes)
• repetitive texts (as for example the shortcut Alt + x) only need to be defined at one place - and a reference to this definition could be used all over the language file. A side effect is a homogenous wording ... (for example using accidentally Alt + x <-> ALT+x if you have to enter it on several places ...)
• Within your sourcecode you do not have the need to add the text and the corresponding shortcut for output (
  Menu, chOrgSubM, Add, % TXT.TIP_move " (" TXT["_!x"] ")", chOrgCut) - you simply could use Menu, chOrgSubM, Add, % TXT.TIP_move, chOrgCut instead AND you could still use TXT["_!x"] within your sourcecode (is still needed

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

[aviaryan]

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
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)

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

• 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.

[hoppfrosch]

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:

• have a section Global bindings for windows interfaces which list all bindings which are valid for all windows interfaces (for example F5 - Refresh which is valid for HistoryTool and ChannelOrganizer ...)
• 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?)
• those sections refer to each other via links

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]

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]

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]

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

[aviaryan]

Thanks @hoppfrosch. I will merge it soon.

[aviaryan]

Merged !