Sublime Forum

Better help integration and other ideas

#1

Hi All

The first idea is related to context help for particular languages and comes from Scite “must have” functionality :wink:
Scite already has built-in support for help for particular extensions.
It works in the following way - current selection or the nearest word is passed to help.
Depending on the help system we can use built-in support for Windows HTML Help (selected word or sentence is passes as a topic to find inside CHM file) or call browser window with given context.
Examples from Scite configuration file:

command.help.$(file.patterns.python)=$(CurrentWord)!c:\Python25\Doc\Python25.chm command.help.subsystem.$(file.patterns.python)=4
or

command.help.*.css="http://www.w3.org/TR/REC-CSS1#$(CurrentWord)" command.help.subsystem.*.css=2

The second example can be done using Sublime functionality but the main problem is related to HTMLHelp file.
To call HTMLHelp WinAPI function we have to call function HtmlHelpA or HtmlHelpW with HH_AKLINK structure which describe help topic as a fourth parameter.
Becasue this function requires casting HH_AKLINK structure to DWORD type - there a lot of problems when I’m gonna call it using ctypes.
The second problem is related to HTMLHelp instance - if you run HTMLHelp from python script it will close on script exit. To avoid this you have to add pause command inside plugin but the result is uggly because black, blank window is visible until HTML is opened.
I think that Sublime should have built-in support for above functionality.
These functionality allow the user to integrate help system for particular languages in easy way.
Calling Windows HTMLHelp function from C/C++ code is simple (this raw code comes from Scite sources):

[code]void SciTEWin::ExecuteHelp(const char *cmd) {
if (!hHH)
hHH = ::LoadLibrary(“HHCTRL.OCX”);

if (hHH) {
	char *topic = StringDup(cmd);
	char *path = strchr(topic, '!');
	if (topic && path) {
		*path = '\0';
		path++;	// After the !
		typedef HWND (WINAPI *HelpFn) (HWND, const char *, UINT, DWORD);
		HelpFn fnHHA = (HelpFn)::GetProcAddress(hHH, "HtmlHelpA");
		if (fnHHA) {
			HH_AKLINK ak;
			ak.cbStruct = sizeof(ak);
			ak.fReserved = FALSE;
			ak.pszKeywords = topic;
			ak.pszUrl = NULL;
			ak.pszMsgText = NULL;
			ak.pszMsgTitle = NULL;
			ak.pszWindow = NULL;
			ak.fIndexOnFail = TRUE;
			fnHHA(NULL,
			      path,
			      0x000d,          	// HH_KEYWORD_LOOKUP
			      reinterpret_cast<DWORD>(&ak)
			     );
		}
	}
	delete ]topic;
}

}[/code]

Opening new browser window isn’t too much complicated as well.

The second idea is related to snippets.
If you are going to create small snippet e.g. for border in HTML file you can do it in the following way:

<snippet> <content><![CDATA[border: 1px gray ${1:solid}]]></content> </snippet>
When snippet is inserting user is able to change value $1.
But it would be nice to allow the user to select this value from list of predefined values, e.g. solid, dotted, double, etc… using up and down cursor keys.
Snippet syntax can be extended as in following example:

<snippet> <content><![CDATA[border: 1px gray ${1:solid}]]></content> <mapping> <param1> <item>none</item> <item>hidden</item> <item>hidden</item> <item>dashed</item> <item>solid</item> <item>double</item> <item>groove</item> <item>ridge</item> <item>inset</item> <item>outset</item> </param1> </mapping> </snippet>

${1:solid} is a default value.

regards
Artur

0 Likes

Better help again :)
#2

re: help, I think the idea of a per-language help lookup facility is excellent: I just added it to the todo list.

re: snippets. I also like this. I do think it makes sense to hook it into auto complete, ideally with the auto complete menu coming up automatically when you tab into the target field (preferable combined with a less modal auto complete menu).

More generally, I’d like to see some closer ties between python and snippets, as sublimator mentioned. I need to put some thought into this.

0 Likes

#3

I was going to request that feature for snippets too :smile:
+1 for this feature! it would be VERY nice to have

0 Likes