diff --git a/src/applications/typeahead/controller/PhabricatorTypeaheadFunctionHelpController.php b/src/applications/typeahead/controller/PhabricatorTypeaheadFunctionHelpController.php --- a/src/applications/typeahead/controller/PhabricatorTypeaheadFunctionHelpController.php +++ b/src/applications/typeahead/controller/PhabricatorTypeaheadFunctionHelpController.php @@ -46,10 +46,14 @@ 'more powerful queries. This document explains functions available '. 'for the selected control.'. "\n\n". + 'For general help with search, see the [[ %s | Search User Guide ]] in '. + 'the documentation.'. + "\n\n". 'Note that different controls support //different// functions '. '(depending on what the control is doing), so these specific functions '. 'may not work everywhere. You can always check the help for a control '. - 'to review which functions are available for that control.'); + 'to review which functions are available for that control.', + PhabricatorEnv::getDoclink('Search User Guide')); $table = array(); diff --git a/src/docs/user/userguide/jump.diviner b/src/docs/user/userguide/jump.diviner --- a/src/docs/user/userguide/jump.diviner +++ b/src/docs/user/userguide/jump.diviner @@ -1,14 +1,20 @@ -@title Jump Nav User Guide +@title Search User Guide: Shortcuts @group userguide -Command reference for the jump nav. +Command reference for global search shorcuts. -= Overview = +Overview +======== -The jump nav provides a quick way to navigate to tools and objects: just type -a navigational command into the box and press return. +Phabricator's global search bar automatically interprets certain commands as +shortcuts to make it easy to navigate to specific places. -= Supported Commands = +To use these shortcuts, just type them into the global search bar in the main +menu and press return. For example, enter `T123` to jump to the corresponding +task quickly. + +Supported Commands +======== - **T** - Jump to Maniphest. - **T123** - Jump to Maniphest Task 123. @@ -25,3 +31,10 @@ - **s SymbolName** - Jump to Symbol SymbolName - **task: (new title)** - Jumps to Task Creation Page with pre-filled title. - **(default)** - Search for input. + +Next Steps +========== + +Continue by: + + - returning to the @{article:Search User Guide}. diff --git a/src/docs/user/userguide/search.diviner b/src/docs/user/userguide/search.diviner new file mode 100644 --- /dev/null +++ b/src/docs/user/userguide/search.diviner @@ -0,0 +1,125 @@ +@title Search User Guide +@group userguide + +Introduction to searching for documents in Phabricator. + +Overview +======== + +Phabricator has two major ways to search for documents and objects (like tasks, +code reviews, users, wiki documents, and so on): **global search** and +**application search**. + +**Global search** allows you to search across multiple document types at once, +but has fewer options for refining a search. It's a good general-purpose +search, and helpful if you're searching for a text string. + +**Application search** allows you to search within an application (like +Maniphest) for documents of a specific type. Because application search is only +searching one type of object, it can provide more powerful options for +filtering, ordering, and displaying the results. + +Both types of search share many of the same features. This document walks +through how to use search and how to take advantage of some of the advanced +options. + + +Global Search +============= + +Global search allows you to search across multiple document types at once. +You can access global search by entering a search query in the main menu bar. + +By default, global search queries search all document types: for example, they +will find matching tasks, commits, wiki documents, users, etc. You can use the +dropdown to the left of the search box to select a different search scope. + +If you choose the **Current Application** scope, Phabricator will search for +open documents in the current application. For example, if you're in Maniphest +and run a search, you'll get matching tasks. If you're in Phriction and run a +search, you'll get matching wiki documents. + +Some pages (like the 404 page) don't belong to an application, or belong to an +application which doesn't have any searchable documents. In these cases, +Phabricator will search all documents. + +To quickly **jump to an object** like a task, enter the object's ID in the +global search box and search for it. For example, you can enter `T123` or +`D456` to quickly jump to the corresponding task or code review, or enter a Git +commit hash to jump to the corresponding commit. For a complete list of +supported commands, see @{article:Search User Guide: Shortcuts}. + +After running a search, you can scroll up to add filters and refine the result +set. You can also select **Advanced Search** from the dropdown menu to jump +here immediately, or press return in the search box without entering a query. + +This interface supports standard Phabricator search and filtering features, +like **saved queries** and **typeaheads**. See below for more details on using +these features. + + +Application Search +================== + +Application search gives you a more powerful way to search one type of document, +like tasks. Most applications provide application search interfaces for the +documents or objects they let you create: these pages have queries in the left +menu, show objects or documents in the main content area, and have controls +for refining the results. + +These interfaces support **saved queries** and **typeaheads**. + + +Saving and Sharing Queries +============= + +If you have a query which you run often, you can save it for easy access. +To do this, click "Save Custom Query..." on the result screen. Choose a name +for your query and it will be saved in the left nav so you can run it again +with one click. + +You can use "Edit Queries..." to reorder queries or remove saved queries you +don't use anymore. + +If you drag a query to the top of the list, it will execute by default when +you load the relevant search interface. You can use this to make your default +view show the results you most often want. + +You can share queries with other users by sending them the URL. This will run +the same query for them with all the parameters you've set (they may see +different results than you do, because they may not have the same permisions). + + +Typeaheads +========== + +Typeaheads are text inputs which suggest options as you type. Typeaheads make +it easy to select users, projects, document types, and other kinds of objects +without typing their full names. + +For example, if you want to find tasks that a specific user created, you can +use the "Authors:" filter in Maniphest. The filter uses a typeahead control +to let you enter authors who you want to search for. + +To use a typeahead, enter the first few letters of the thing you want to +select. It will appear in a dropdown under your cursor, and you can select it +by clicking it (or using the arrow keys to highlight it, then pressing return). + +If you aren't sure about the exact name of what you're looking for, click the +browse button ({nav icon=search}) to the right of the input. This will let you +browse through valid results for the control. You can filter the results from +within the browse dialog to narrow them down. + +Some typeaheads support advanced selection functions which can let you build +more powerful queries. If a control supports functions, the "Browse" dialog +will show that advanced functions are available and give you a link to details +on which functions you can use. + +For example, the `members()` function lets you automatically select all of the +members of a project. You could use this with the "Authors" filter to find +tasks created by anyone on a certain team. + +Another useful function is the `viewer()` function, which works as though you'd +typed your own username when you run the query. However, if you send the query +to someone else, it will show results for //their// username when they run it. +This can be particularly useful when creating dashboard panels. diff --git a/src/view/page/menu/PhabricatorMainMenuSearchView.php b/src/view/page/menu/PhabricatorMainMenuSearchView.php --- a/src/view/page/menu/PhabricatorMainMenuSearchView.php +++ b/src/view/page/menu/PhabricatorMainMenuSearchView.php @@ -163,13 +163,11 @@ 'href' => '/search/query/advanced/', ); - /* TODO: Write this. $items[] = array( 'icon' => 'fa-book', 'name' => pht('User Guide: Search'), - 'href' => PhabricatorEnv::getDoclink('User Guide: Search'), + 'href' => PhabricatorEnv::getDoclink('Search User Guide'), ); - */ $scope_key = PhabricatorUserPreferences::PREFERENCE_SEARCH_SCOPE; $current_value = $viewer->loadPreferences()->getPreference(