1<%-- 2CDDL HEADER START 3 4The contents of this file are subject to the terms of the 5Common Development and Distribution License (the "License"). 6You may not use this file except in compliance with the License. 7 8See LICENSE.txt included in this distribution for the specific 9language governing permissions and limitations under the License. 10 11When distributing Covered Code, include this CDDL HEADER in each 12file and include the License file at LICENSE.txt. 13If applicable, add the following below this CDDL HEADER, with the 14fields enclosed by brackets "[]" replaced with your own identifying 15information: Portions Copyright [yyyy] [name of copyright owner] 16 17CDDL HEADER END 18 19Copyright (c) 2005, 2021, Oracle and/or its affiliates. All rights reserved. 20Portions Copyright 2011 Jens Elkner. 21Portions Copyright (c) 2018, 2020, Chris Fraire <cfraire@me.com>. 22Portions Copyright (c) 2022, Krystof Tulinger <k.tulinger@seznam.cz>. 23--%> 24<%@page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%> 25<%@page session="false" errorPage="error.jsp" import=" 26org.opengrok.indexer.search.SearchEngine, 27org.opengrok.web.PageConfig, 28org.opengrok.indexer.web.QueryParameters" 29%> 30<% 31/* ---------------------- help.jsp start --------------------- */ 32{ 33 PageConfig cfg = PageConfig.get(request); 34 cfg.checkSourceRootExistence(); 35 cfg.setTitle("OpenGrok Help"); 36} 37%><%@ 38 39include file="httpheader.jspf" 40 41%> 42<body> 43 <div id="page"> 44 <header id="whole_header"> 45 <%@include file="pageheader.jspf" %> 46 <div id="Masthead">Help page</div> 47 </header> 48 <div id="sbar"> 49 <div id="menu"><%@ 50 51include file="menu.jspf" 52 53%> 54 </div> 55 </div> 56 <div id="help"> 57 58<h4>Examples:</h4> 59<pre class="example"> 60 61To find where setResourceMonitors is defined: 62<a href="search?<%= QueryParameters.FULL_SEARCH_PARAM_EQ %>& 63<%= QueryParameters.DEFS_SEARCH_PARAM_EQ %>setResourceMonitors"> 64 <%= QueryBuilder.DEFS %>:setResourceMonitors</a> 65 66To find files that use sprintf in usr/src/cmd/cmd-inet/usr.sbin/: 67<a href="search?<%= QueryParameters.REFS_SEARCH_PARAM_EQ %>sprintf& 68<%= QueryParameters.PATH_SEARCH_PARAM_EQ %>usr%2Fsrc%2Fcmd%2Fcmd-inet%2Fusr.sbin%2F" 69><%= QueryBuilder.REFS %>:sprintf <%= QueryBuilder.PATH %>:usr/src/cmd/cmd-inet/usr.sbin</a> 70 71To find assignments to variable foo: 72<a href="search?<%= QueryParameters.FULL_SEARCH_PARAM_EQ %>%22foo+%3D%22">"foo ="</a> 73 74 To find Makefiles where the <code>pstack</code> binary is being built: 75<a href="search?<%= QueryParameters.FULL_SEARCH_PARAM_EQ %>pstack& 76<%= QueryParameters.PATH_SEARCH_PARAM_EQ %>Makefile">pstack <%= QueryBuilder.PATH %>:Makefile</a> 77 78to search for phrase "Bill Joy": 79<a href="search?<%= QueryParameters.FULL_SEARCH_PARAM_EQ %>%22Bill+Joy%22">"Bill Joy"</a> 80 81To find perl files that do not use /usr/bin/perl but something else: 82<a href="search?<%= QueryParameters.FULL_SEARCH_PARAM_EQ %>-%22%2Fusr%2Fbin%2Fperl%22+%2B%22%2Fbin%2Fperl%22" 83>-"/usr/bin/perl" +"/bin/perl"</a> 84 85To find all strings beginning with foo use the wildcard: 86<a href="search?<%= QueryParameters.FULL_SEARCH_PARAM_EQ %>foo*">foo*</a> 87 88To find all files which have . c in their name (dot is a token!): 89<a href="search?<%= QueryParameters.PATH_SEARCH_PARAM_EQ %>%22. c%22">". c"</a> 90 91To find all files which start with "ma" and then have only alphabet characters do: 92<a href="search?<%= QueryParameters.PATH_SEARCH_PARAM_EQ %>/ma[a-zA-Z]*/"> 93 <%= QueryBuilder.PATH %>:/ma[a-zA-Z]*/</a> 94 95To find all main methods in all files analyzed by C analyzer (so .c, .h, ...) do: 96<a href="search?<%= QueryParameters.FULL_SEARCH_PARAM_EQ %>main& 97<%= QueryParameters.TYPE_SEARCH_PARAM_EQ %>c">main <%= QueryBuilder.TYPE %>:c</a> 98</pre> 99 100<h4>More info:</h4> 101A <dfn>Query</dfn> is a series of clauses. A clause may be prefixed by: 102<ul> 103 <li>a plus "<code>+</code>" or a minus "<code>-</code>" sign, indicating that the clause 104 is required or prohibited respectively; or</li> 105 <li>a <dfn>term</dfn> followed by a colon "<code>:</code>", indicating the 106 <dfn>field</dfn> to be searched. This enables one to construct queries 107 which search multiple <dfn>fields</dfn>.</li> 108</ul> 109<p>A <dfn>clause</dfn> may be either:</p> 110<ul> 111 <li>a <dfn>term</dfn>, indicating all the documents that contain this term; 112 or</li> 113 <li>a <dfn>phrase</dfn> - group of words surrounded by double quotes 114 <code>" "</code>, e.g. "hello dolly" </li> 115 <li>a nested query, enclosed in parentheses "<code>(</code>" "<code>)</code>" (also 116 called query/field <dfn>grouping</dfn>) . Note that this may be used 117 with a +/- prefix to require any of a set of terms. </li> 118 <li>boolean <dfn>operators</dfn> which allow terms to be combined through 119 logic operators. Supported are <code>AND</code>(<code>&&</code>), "<code>+</code>", 120 <code>OR</code>(<code>||</code>), <code>NOT</code>(<code>!</code>) and "<code>-</code>" (Note: they 121 must be ALL CAPS).</li> 122</ul> 123<p>Regular Expression, Wildcard, Fuzzy, Proximity and Range Searches:</p> 124<ul> 125 <li>to perform a regular expression search use the "<code>/</code>" enclosure, 126 e.g. /[mb]an/ - will search for man or for ban;<br/> 127 NOTE: path field search escapes "/" by default, so it only supports 128 regexps when the search string <u>starts and ends</u> with "/".<br/> 129 More info can be found on <a href="https://lucene.apache.org/core/<%=SearchEngine.LUCENE_VERSION_HELP%>/core/org/apache/lucene/util/automaton/RegExp.html?is-external=true">Lucene regexp page</a>. 130 </li> 131 <li>to perform a single character wildcard search use the "<code>?</code>" symbol, 132 e.g. <code>te?t</code></li> 133 <li>to perform a multiple character wildcard search use the "<code>*</code>" 134 symbol, e.g. <code>test*</code> or <code>te*t</code></li> 135 <li>you can use a * or ? symbol as the first character of a search 136 (unless not enabled using indexer option -a).</li> 137 <li>to do a fuzzy search (find words similar in spelling, based on the 138 Levenshtein Distance, or Edit Distance algorithm) use the tilde, 139 "<code>~</code>", e.g. rcs~ </li> 140 <li>to do a proximity search use the tilde, "~", symbol at the end of a 141 Phrase. For example to search for a "opengrok" and "help" within 10 142 words of each other enter: "opengrok help"~10 </li> 143 <li>range queries allow one to match documents whose field(s) values are 144 between the lower and upper bound specified by the Range Query. Range 145 Queries can be inclusive or exclusive of the upper and lower bounds. 146 Sorting is done lexicographically. Inclusive queries are denoted by 147 square brackets <code>[ ]</code> , exclusive by curly brackets <code>{ }</code>. 148 For example: title:{Aida TO Carmen} - will find all documents between 149 Aida to Carmen, exclusive of Aida and Carmen. </li> 150</ul> 151 152<a id="escaping"><dfn>Escaping special characters:</dfn></a> 153<p> 154 Opengrok supports escaping special characters that are part of the query 155 syntax. Current special characters are:<br/> 156 <code>+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ / </code><br/> 157 To escape these character use the \ before the character. For example to 158 search for <code>(1+1):2</code> use the query: <code>\(1\+1\)\:2</code> 159</p> 160<p> 161 NOTE on analyzers: Indexed words are made up of Alpha-Numeric and Underscore 162 characters. One letter words are usually not indexed as symbols!<br/> 163 Most other characters (including single and double quotes) are treated as 164 "spaces/whitespace" (so even if you escape them, they will not be found, since 165 most analyzers ignore them). <br/> 166 The exceptions are: <code>@ $ % ^ & = ? . :</code> which are mostly indexed as 167 separate words.<br/> 168 Because some of them are part of the query syntax, they must be escaped with a 169 reverse slash as noted above.<br/> 170 So searching for <code>\+1</code> or <code>\+ 1</code> will both find <code>+1</code> and <code>+ 1</code>. 171</p> 172 173<p>Valid <dfn>FIELDs</dfn> are</p> 174<dl class="fields"> 175 <dt>full</dt> 176 <dd>Search through all text tokens (words,strings,identifiers,numbers) in index.</dd> 177 178 <dt>defs</dt> 179 <dd>Only finds symbol definitions (where e.g. a variable (function, ...) is defined).</dd> 180 181 <dt>refs</dt> 182 <dd>Only finds symbols (e.g. methods, classes, functions, variables).</dd> 183 184 <dt>path</dt> 185 <dd>path of the source file (no need to use dividers, or if, then use "/" - Windows users, "\" is an escape key in Lucene query syntax! <br/>Please don't use "\", or replace it with "/").<br/>Also note that if you want just exact path, enclose it in "", e.g. "src/mypath", otherwise dividers will be removed and you get more hits.</dd> 186 187 <% 188 if (PageConfig.get(request).getEnv().isHistoryEnabled()) { 189 %> 190 <dt>hist</dt> 191 <dd>History log comments.</dd> 192 <% 193 } 194 %> 195 196 <dt>type</dt> 197 <dd>Type of analyzer used to scope down to certain file types (e.g. just C sources).<br/>Current mappings: <%=SearchHelper.getFileTypeDescriptions().toString()%></dd> 198</dl> 199 200<p> 201 The term (phrases) can be boosted (making it more relevant) using a caret 202 <code>^</code> , e.g. help^4 opengrok - will make term help boosted 203</p> 204 205<p>Opengrok search is powered by <a href="https://lucene.apache.org/">Lucene</a>, 206for more detail on query syntax refer to <a href="https://lucene.apache.org/core/<%=SearchEngine.LUCENE_VERSION_HELP%>/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package.description">Lucene docs</a>. 207</p> 208 209<h4>Intelligence Window</h4> 210<p> 211Key "1" toggles <dfn>Intelligence Window</dfn>. It gives the user many helper actions on the last symbol pointed by the mouse cursor. 212</p> 213<img src="<%= PageConfig.get(request).getCssDir() %>/img/intelli-window.png" alt="Intelligence window screenshot"/> 214 215<h5>Symbol Highlighting</h5> 216<p> 217Keys "2", "3", ..., "7" toggles highlighting of the last symbol pointed by the mouse cursor. This functionality is also accessible via the <dfn>Intelligence Window</dfn>. 218</p> 219<p> 220Key "8" toggles un-highlighting all symbols. This functionality is also accessible via the <dfn>Intelligence Window</dfn>. 221</p> 222<img src="<%= PageConfig.get(request).getCssDir() %>/img/symbol-highlighting.png" alt="symbol highlighting screenshot"/> 223 224<p> 225 You can close the intelligence window either by mouse in the right upper corner or by keyboard with "Esc" key. 226</p> 227 228<h5>Symbol jumping</h5> 229<p> 230By 'n' for next and 'b' for back you can jump between the symbols easily only with keyboard. When there is no symbol highlighted then the jump 231is made to the next symbol in the file from the current one. If you have highlighted a specific symbol then the jump is done only among the highlighted symbols regardless the color of the symbol. 232</p> 233 234<h4>Diff jumper</h4> 235 236<p> 237The OpenGrok also provides an easy way how to jump through the large diffs finding the interesting pieces of code. In the diff mode you can enable diff jumper by hitting the "jumper" button. 238</p> 239<img src="<%= PageConfig.get(request).getCssDir() %>/img/diff-jumper.png" alt="diff jumper screenshot"/> 240 241<h5>Mouse and keyboard navigation</h5> 242<p> 243You can then use your mouse to intuitively navigate yourself through the diff. Also there is a convenient shortcut for moving on your keyboard, 244you can use 'n' for next and 'b' for back to jump over to the next chunk. This is available even when the jumper window is not opened. 245</p> 246<img src="<%= PageConfig.get(request).getCssDir() %>/img/diff-jumping.png" alt="screenshot of diff jumper in action"/> 247 248 </div> 249<% 250/* ---------------------- help.jsp end --------------------- */ 251%><%@ 252 253include file="foot.jspf" 254 255%> 256
