Hi, Following from an different email thread earlier this year. Link: http://www.nabble.com/Searching-for-Objective-C-documentation-td16722396.htm...
As some of you know, Textmate has this very good script for performing correctly the searches on Apple Docset with the /Developer/usr/bin/ docsetutil tool.
The command is bound to Ctrl - h, and will also search the unix man (3) pages. Offers a multiple - selection popup.
To access this feature you must type in and select the word into your document before proceeding. However it strikes me that adding an alternative method to use the script (probably a Search box) could be useful.
There;s nothing wrong with the Ctrl - h shortcut just that its rather cumbersome if you are searching speculatively for a series of related classes. For that we really can prefer an open Search box where the choices are typed in, without affecting / editing the current open document.
Basically any improvement of the current functionality thats going to let me stay inside TextMate and not lead me to an external program or tool such as AppKiDo. Actually there also used to be QuickSilver + Developer Documentation Plugin, but that was broken since the Docset format came in.
Perhaps something like the "Select Bundle Item" window (Ctrl-Cmd-T), which can be toggled visible / invisible and left open for multiple searches would be the best way to go.
My ruby is - 0/0 unfortunately so cannot put up any code myself for what i am trying to propose here. But anyway the relevant place to go is file docset_query.rb
There could be an obstacle because how should we handle multiple results? Of course already there is a place already in the Ctrl-H cmd where the mini selection list pop-up is shown.
http://svn.textmate.org/trunk/Bundles/Objective-C.tmbundle/Support/lib/docse... Function "def show_document (results, query)"
If we write a new command in this file and choose not to call this above function, then its going to mean that we can use other existing function definition in the ruby script and we can bypass the showing of the results mini- pop-up window, right ?
Or perhaps we will need some kind of re-write because there another place at the beginning of the file where "the selected word" is used for input? Would we want a different input going into a new ruby function. The user input is probably going to be from a search box. And later we must print any multiple search results (called 'results' array). Printed back into e.g. an NSTableview of the bottom half of our search box.
I cannot find any existing feature improvement / request for this yet, but still looking.
Cheers Gulliver
dreamcat7 dreamcat7@googlemail.com
On 1 Jan 2009, at 14:56, dreamcat7 wrote:
[...] searches on Apple Docset [...] To access this feature you must type in and select the word into your document before proceeding.
You needn’t select it, just have the caret “on it”.
However it strikes me that adding an alternative method to use the script (probably a Search box) could be useful.
Great idea. I often type in keywords followed by ⌃H, but we could make ⌃H popup a dialog when there is no current word (or word is not found), we do that for ⌃H in HTML mode (and maybe a few others).
We can’t really do a list of terms (to filter) though since there are thousands of terms and we don’t really know them beforehand.
Or perhaps we will need some kind of re-write because there another place at the beginning of the file where "the selected word" is used for input?
Yeah, I don’t think it is an easy change, also because we have different doc commands depending on context in Objective-C. The stuff is long overdue for refactoring though.
On 6 Jan 2009, at 03:15, Allan Odgaard wrote:
On 1 Jan 2009, at 14:56, dreamcat7 wrote:
[...] searches on Apple Docset [...] To access this feature you must type in and select the word into your document before proceeding.
You needn’t select it, just have the caret “on it”.
However it strikes me that adding an alternative method to use the script (probably a Search box) could be useful.
Great idea. I often type in keywords followed by ⌃H, but we could make ⌃H popup a dialog when there is no current word (or word is not found), we do that for ⌃H in HTML mode (and maybe a few others).
We can’t really do a list of terms (to filter) though since there are thousands of terms and we don’t really know them beforehand.
Or perhaps we will need some kind of re-write because there another place at the beginning of the file where "the selected word" is used for input?
So we can keep the selected word as the initial input , check if selected word is an empty string right? If there is no selected word *then* add a routine to open the search box. - great!
I dont know any ruby but will try something this week to get the interest going. (No bell or whistles, probably very rudimentary)
Yeah, I don’t think it is an easy change, also because we have different doc commands depending on context in Objective-C. The stuff is long overdue for refactoring though.
textmate mailing list textmate@lists.macromates.com http://lists.macromates.com/listinfo/textmate
Done - patch available. Hope they're in the right format, etc.
dreamcat4: patch-1 (trunk/support) http://pastie.org/354995
dreamcat4: patch-2 (trunk/Bundles/Objective-C.tmbundle) http://pastie.org/355007
On 6 Jan 2009, at 03:15, Allan Odgaard wrote:
On 1 Jan 2009, at 14:56, dreamcat7 wrote:
[...] searches on Apple Docset [...] To access this feature you must type in and select the word into your document before proceeding.
You needn’t select it, just have the caret “on it”.
However it strikes me that adding an alternative method to use the script (probably a Search box) could be useful.
Great idea. I often type in keywords followed by ⌃H, but we could make ⌃H popup a dialog when there is no current word (or word is not found), we do that for ⌃H in HTML mode (and maybe a few others).
We can’t really do a list of terms (to filter) though since there are thousands of terms and we don’t really know them beforehand.
Or perhaps we will need some kind of re-write because there another place at the beginning of the file where "the selected word" is used for input?
Yeah, I don’t think it is an easy change, also because we have different doc commands depending on context in Objective-C. The stuff is long overdue for refactoring though.
textmate mailing list textmate@lists.macromates.com http://lists.macromates.com/listinfo/textmate
Hi, Actually thinking about it there are some more things we could really to with do here. Here are the change up-to now.
1) We chopped the input into only one word so the script can handle it better and not throw to the tooltip a big error. I put this stripping / to the query string, however it really should move to the search_docs(query) command, where we are executing the search. Sorry but I did add to there and break the ruby code.
Ctrl-H --> documentation_for_word() --> search_docs_all(query) --> search_docs(query)** --> docsetutil Ctrl-H --> documentation_for_word() --> search_docs_all(query) --> man_page(query)** --> man
2) If we keep the full string in query variable, then when we print the tooltip, we can show the full text back to the user. As it stands we show back the doctored text, i.e. the first word or line of the selected text.
3) With the latest (above) the command it still may not execute right for conditions where there are spaces, tabs, or newline characters etc before the text point. So cleaning up the input should be tested and tweaked some more.
4) If the word is wrapped in square brackets. e.g. [NSArray] - then TM_SELECTED_TEXT will not work but TM_CURRENT_WORD will. Again, a better place to sanitize this input may be either search_docs(query) or search_docs_all(query)
5) If we have just run the command (Ctrl-H) then we have opened a Web- window and not a text window. Can we press Ctrl-H here (in the html window) to bring up the dialog again to perform another search?
This would be much more convenient when we are engaged in the activity only for searching, and reading documentation. Not to need to switch back to the working document, to run this command ?
6) As Allan wants we will show the search box only conditionally, when there isnt a current word on the caret. However it would be a nice option to have for those who always want to show it. This may sound like a personal request, however i would be very grateful because pressing Ctrl-W is very much more difficult with RSI than to press enter key with the dialog. So to check on TM_DOC_SEARCH_BOX_ALWAYS or a defaulted argument will allow the user to customise :)
def documentation_for_word( show_always = FALSE ) ?
dreamcat7 dreamcat7@googlemail.com
On 7 Jan 2009, at 21:15, dreamcat7 wrote:
Done - patch available. Hope they're in the right format, etc.
dreamcat4: patch-1 (trunk/support) http://pastie.org/354995
<dreamcat7-searchbox.patch>
<SearchBox.nib>
dreamcat4: patch-2 (trunk/Bundles/Objective-C.tmbundle) http://pastie.org/355007
<dreamcat7-objc_docset_query.patch>
On 6 Jan 2009, at 03:15, Allan Odgaard wrote:
On 1 Jan 2009, at 14:56, dreamcat7 wrote:
[...] searches on Apple Docset [...] To access this feature you must type in and select the word into your document before proceeding.
You needn’t select it, just have the caret “on it”.
However it strikes me that adding an alternative method to use the script (probably a Search box) could be useful.
Great idea. I often type in keywords followed by ⌃H, but we could make ⌃H popup a dialog when there is no current word (or word is not found), we do that for ⌃H in HTML mode (and maybe a few others).
We can’t really do a list of terms (to filter) though since there are thousands of terms and we don’t really know them beforehand.
Or perhaps we will need some kind of re-write because there another place at the beginning of the file where "the selected word" is used for input?
Yeah, I don’t think it is an easy change, also because we have different doc commands depending on context in Objective-C. The stuff is long overdue for refactoring though.
textmate mailing list textmate@lists.macromates.com http://lists.macromates.com/listinfo/textmate
On 9 Jan 2009, at 14:23, dreamcat7 wrote:
- We chopped the input into only one word so the script can handle
it better and not throw to the tooltip a big error. I put this stripping / to the query string, however it really should move to the search_docs(query) command, where we are executing the search. Sorry but I did add to there and break the ruby code.
Ctrl-H --> documentation_for_word() --> search_docs_all(query) --> search_docs(query)** --> docsetutil Ctrl-H --> documentation_for_word() --> search_docs_all(query) --> man_page(query)** --> man
- If we keep the full string in query variable, then when we print
the tooltip, we can show the full text back to the user. As it stands we show back the doctored text, i.e. the first word or line of the selected text.
I think the user should see the term that was actually searched for, rather than the full (selected) text.
There is however a minor gotcha when presenting the dialog, here it has the doctored text, which might not make it very clear from where the text comes from (since only the first word is shown).
- With the latest (above) the command it still may not execute
right for conditions where there are spaces, tabs, or newline characters etc before the text point. So cleaning up the input should be tested and tweaked some more.
I believe I fixed that in the version I committed (I did make a few changes compared to your latest version).
- If the word is wrapped in square brackets. e.g. [NSArray] - then
TM_SELECTED_TEXT will not work but TM_CURRENT_WORD will. Again, a better place to sanitize this input may be either search_docs(query) or search_docs_all(query)
I think this is actually because the scope of this selection has it call a different documentation lookup function (the one for selectors).
- If we have just run the command (Ctrl-H) then we have opened a
Web-window and not a text window. Can we press Ctrl-H here (in the html window) to bring up the dialog again to perform another search?
In theory, yes. But it would require doctoring the presented page (to handle a key down event on ⌃H and use TextMate.system() to open the dialog etc.) — it might be better to leave it be and wait for a more general re-run ability for commands with HTML output.
- As Allan wants we will show the search box only conditionally,
when there isnt a current word on the caret. However it would be a nice option to have for those who always want to show it. This may sound like a personal request, however i would be very grateful because pressing Ctrl-W is very much more difficult with RSI than to press enter key with the dialog [...]
Why do you need to press ⌃W?
On 14 Jan 2009, at 07:42, Allan Odgaard wrote:
On 9 Jan 2009, at 14:23, dreamcat7 wrote:
- We chopped the input into only one word so the script can handle
it better and not throw to the tooltip a big error. I put this stripping / to the query string, however it really should move to the search_docs(query) command, where we are executing the search. Sorry but I did add to there and break the ruby code.
Ctrl-H --> documentation_for_word() --> search_docs_all(query) --> search_docs(query)** --> docsetutil Ctrl-H --> documentation_for_word() --> search_docs_all(query) --> man_page(query)** --> man
- If we keep the full string in query variable, then when we print
the tooltip, we can show the full text back to the user. As it stands we show back the doctored text, i.e. the first word or line of the selected text.
I think the user should see the term that was actually searched for, rather than the full (selected) text.
There is however a minor gotcha when presenting the dialog, here it has the doctored text, which might not make it very clear from where the text comes from (since only the first word is shown).
Probably the way other cocoa apps handle this is to display either the first or last line (as the dialogue can visibly accomodate a single line of text). However other Cocoa apps often don't have the limitation for searching a single word as the search term.
- With the latest (above) the command it still may not execute
right for conditions where there are spaces, tabs, or newline characters etc before the text point. So cleaning up the input should be tested and tweaked some more.
I believe I fixed that in the version I committed (I did make a few changes compared to your latest version).
- If the word is wrapped in square brackets. e.g. [NSArray] - then
TM_SELECTED_TEXT will not work but TM_CURRENT_WORD will. Again, a better place to sanitize this input may be either search_docs(query) or search_docs_all(query)
I think this is actually because the scope of this selection has it call a different documentation lookup function (the one for selectors).
- If we have just run the command (Ctrl-H) then we have opened a
Web-window and not a text window. Can we press Ctrl-H here (in the html window) to bring up the dialog again to perform another search?
In theory, yes. But it would require doctoring the presented page (to handle a key down event on ⌃H and use TextMate.system() to open the dialog etc.) — it might be better to leave it be and wait for a more general re-run ability for commands with HTML output.
- As Allan wants we will show the search box only conditionally,
when there isnt a current word on the caret. However it would be a nice option to have for those who always want to show it. This may sound like a personal request, however i would be very grateful because pressing Ctrl-W is very much more difficult with RSI than to press enter key with the dialog [...]
Why do you need to press ⌃W?
Ctrl-W - "select current word" afterwards to delete the search term just typed in order to search on? Hey, I think I was a little unclear to begin with so i must apologise.
My point was to request some a configurability on this command, which is frequently used. Otherwise any change i do will be a hack and therefore outdated in future revisions.
This suggestion is not meant to affect the default behaviour of TexMate. I Won't feel hurt if you decide not to add it Allan, if its a little inconvenient.
def documentation_for_word( request_string_always = FALSE ) query = ENV['TM_SELECTED_TEXT'] || ENV['TM_CURRENT_WORD'] query = $& if query.to_s =~ /\w*/
if query.to_s.empty? || request_string_always query = %x{ __CF_USER_TEXT_ENCODING=$UID:0x8000100:0x8000100 /usr/ bin/pbpaste -pboard find } query = $& if query =~ /\w+/ query = TextMate::UI.request_string :title => "Documentation Search", :default => query, :prompt => "Search documentation for word" abort if query.nil? end
results = search_docs_all(query) if results.nil? || results.empty? TextMate.exit_show_tool_tip "Cannot find documentation for: #{query}" else show_document(results, query) end end
dreamcat7 dreamcat7@googlemail.com
textmate mailing list textmate@lists.macromates.com http://lists.macromates.com/listinfo/textmate
On 14 Jan 2009, at 17:27, dreamcat7 wrote:
- As Allan wants we will show the search box only conditionally,
when there isnt a current word on the caret. However it would be a nice option to have for those who always want to show it. This may sound like a personal request, however i would be very grateful because pressing Ctrl-W is very much more difficult with RSI than to press enter key with the dialog [...]
Why do you need to press ⌃W?
Ctrl-W - "select current word" afterwards to delete the search term just typed in order to search on? Hey, I think I was a little unclear to begin with so i must apologise.
My point was to request some a configurability on this command, which is frequently used. Otherwise any change i do will be a hack and therefore outdated in future revisions.
What I don’t understand is the way you work. I.e. you would not type the word into the document, you just move to whitespace, press ⌃H and then enter the search term.
-
Allan Odgaard -
dreamcat7