CYBERDEViL
/
searx-qt


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068
							<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.16: http://docutils.sourceforge.net/" />
<title>Searx-Qt documentation</title>
<style type="text/css">

/*
:Author: CYBERDEViL
:Contact: cyberdevilnl at protonmail d0t com
:Copyright: This stylesheet has been placed in the public domain.

Stylesheet for use with Docutils.

https://docutils.sourceforge.io/docs/howto/html-stylesheets.html
*/

/*@import url(html4css1.css);*/

body {
	max-width: 800px;
	background-color: #161616;
	color: #bcb;
}

a {
  color: #11aa11;
}

table {
	border: none;
	background-color: #191919;
}

tr {
	border: none;
}

th {
	border: none;
	text-align: left;
}

td {
	border: none;
	border-bottom: 1px solid #114411;
	text-align: left;
}


/*indent sections a little*/
.section {
	margin-left: 12px;
}

/*indent section contents a little*/
p, pre, table {
  margin-left: 12px;
}

pre {
	font-family: monospace;
	background-color: #222;
	border: 1px solid #111;
	padding: 5px;
}

h1 {
	background-color: #222;
	padding: 6px;
}

h1 a {
	color: #fff;
	text-decoration: none;
}

h1 a:hover {
	text-decoration: underline;
}

img.header {
	max-width: 800px;
	height: auto;
	width: 100%;
}

img.align-right {
	clear: right;
	float: right;
	margin-left: 1em
}

</style>
</head>
<body>
<div class="document">


<div class="section" id="searx-qt">
<h1>Searx-Qt</h1>
<div class="section" id="lightweight-desktop-application-for-searx">
<h2>Lightweight desktop application for Searx</h2>
<p>This is documentation for Searx-Qt version 0.3</p>
<img alt="Searx-Qt v0.3 screenshot." class="header" src="images/screenshot_0_3.png" />
</div>
</div>
<div class="section" id="id1">
<span id="index"></span><h1>Index</h1>
<ul class="simple">
<li><a class="reference internal" href="#index">Index</a></li>
<li><a class="reference internal" href="#about">About</a></li>
<li><ul class="first">
<li><a class="reference internal" href="#about-summary">Summary</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#about-source">Source</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#about-license">License</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#about-dependencies">Dependencies</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#about-translations">Translations</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#about-contact">Contact</a></li>
</ul>
</li>
<li><a class="reference internal" href="#getting-started">Getting started</a></li>
<li><ul class="first">
<li><a class="reference internal" href="#getting-started-install-dependencies">Install dependencies</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#getting-started-installation">Installation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#usage">Usage</a></li>
<li><ul class="first">
<li><a class="reference internal" href="#usage-profiles">Profiles</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#usage-settings">Settings</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#usage-instances">Instances</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#usage-search">Search</a></li>
</ul>
</li>
<li><a class="reference internal" href="#development">Development</a></li>
<li><ul class="first">
<li><a class="reference internal" href="#development-themes">Themes</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#development-translations">Translations</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="id2">
<span id="about"></span><h1><a class="reference internal" href="#about">About</a></h1>
<div class="section" id="summary">
<span id="about-summary"></span><h2><a class="reference internal" href="#about-summary">Summary</a></h2>
<p>Searx-Qt is a lightweight desktop application that lets you search on
public Searx instances listed on <cite>https://searx.space</cite>.</p>
<p>Technically Searx-Qt is a client application that does magic with the Searx
API and Searx-Stats2 it's instances.json.</p>
<p>Since version <cite>0.2</cite> it is also possible to manage your own (private?)
instances with the use of a 'user' profile.</p>
<div class="section" id="searx">
<h3>Searx</h3>
<p>Actual search requests will be made to a server running Searx software,
there are many public available. We call such servers 'Searx instances'
or in this document we may refer to just 'instance(s)'.</p>
<p>If you are not familiar with the Searx project; you can checkout their page
here: <a class="reference external" href="https://searx.github.io/searx/">https://searx.github.io/searx/</a> or <a class="reference external" href="https://searx.me/">https://searx.me/</a></p>
<ul class="simple">
<li>API Docs: <a class="reference external" href="https://searx.github.io/searx/dev/search_api.html">https://searx.github.io/searx/dev/search_api.html</a></li>
<li>Source: <a class="reference external" href="https://github.com/searx/searx">https://github.com/searx/searx</a></li>
<li>License: GPL3</li>
</ul>
</div>
<div class="section" id="searx-stats2">
<h3>Searx-Stats2</h3>
<p>The Searx-Stats2 project lists public Searx instances with statistics. The
original Searx-Stats2 instance is running at <a class="reference external" href="https://searx.space/">https://searx.space/</a>. This is
where Searx-Qt will request a list with instances when the update button
is pressed.</p>
<ul class="simple">
<li>Source: <a class="reference external" href="https://github.com/searxng/searx-space">https://github.com/searxng/searx-space</a></li>
<li>License: GPL3</li>
</ul>
</div>
</div>
<div class="section" id="source">
<span id="about-source"></span><h2><a class="reference internal" href="#about-source">Source</a></h2>
<p><a class="reference external" href="https://notabug.org/CYBERDEViL/searx-qt">https://notabug.org/CYBERDEViL/searx-qt</a></p>
</div>
<div class="section" id="license">
<span id="about-license"></span><h2><a class="reference internal" href="#about-license">License</a></h2>
<ul class="simple">
<li>GPL3 <a class="reference external" href="https://www.gnu.org/licenses/gpl-3.0.en.html">https://www.gnu.org/licenses/gpl-3.0.en.html</a></li>
</ul>
</div>
<div class="section" id="dependencies">
<span id="about-dependencies"></span><h2><a class="reference internal" href="#about-dependencies">Dependencies</a></h2>
<table border="1" class="docutils">
<colgroup>
<col width="10%" />
<col width="11%" />
<col width="11%" />
<col width="68%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">version</th>
<th class="head">license</th>
<th class="head">URL</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>python</td>
<td>3</td>
<td>PSFL</td>
<td><a class="reference external" href="https://docs.python.org/3/license.html">https://docs.python.org/3/license.html</a></td>
</tr>
<tr><td>requests</td>
<td><ul class="first last simple">
<li></li>
</ul>
</td>
<td>Apache 2</td>
<td><a class="reference external" href="http://docs.python-requests.org/en/master/">http://docs.python-requests.org/en/master/</a></td>
</tr>
<tr><td>PyQt5</td>
<td><ul class="first last simple">
<li></li>
</ul>
</td>
<td>GPL3</td>
<td><a class="reference external" href="https://www.riverbankcomputing.com/software/pyqt/intro">https://www.riverbankcomputing.com/software/pyqt/intro</a></td>
</tr>
<tr><td>urllib3</td>
<td><ul class="first last simple">
<li></li>
</ul>
</td>
<td>MIT</td>
<td><a class="reference external" href="https://urllib3.readthedocs.io/">https://urllib3.readthedocs.io/</a></td>
</tr>
</tbody>
</table>
<p><strong>Optional for socks proxy support</strong>:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="14%" />
<col width="15%" />
<col width="15%" />
<col width="56%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">version</th>
<th class="head">license</th>
<th class="head">URL</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>pysocks</td>
<td><ul class="first last simple">
<li></li>
</ul>
</td>
<td>BSD</td>
<td><a class="reference external" href="https://github.com/Anorov/PySocks">https://github.com/Anorov/PySocks</a></td>
</tr>
</tbody>
</table>
</blockquote>
<p><strong>Building</strong>:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="11%" />
<col width="11%" />
<col width="11%" />
<col width="67%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">version</th>
<th class="head">license</th>
<th class="head">URL</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>gettext</td>
<td><ul class="first last simple">
<li></li>
</ul>
</td>
<td>GPL</td>
<td><a class="reference external" href="https://www.gnu.org/software/gettext/">https://www.gnu.org/software/gettext/</a></td>
</tr>
<tr><td>PyQt5-dev</td>
<td>Qt5</td>
<td>GPL3</td>
<td><a class="reference external" href="https://www.riverbankcomputing.com/software/pyqt/intro">https://www.riverbankcomputing.com/software/pyqt/intro</a></td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="translations">
<span id="about-translations"></span><h2><a class="reference internal" href="#about-translations">Translations</a></h2>
<p>The default language is English.</p>
<p>Since version <cite>0.2</cite> Searx-Qt is able (application-wise, not search results) to
be fully translated with the use of gettext and <cite>.po .pot</cite> files. However the
only translation available currently is for the Dutch language. If you like to
translate Searx-Qt in your language then you can find a example of how to do
that in the <a class="reference internal" href="#development">development section</a>. Please consider opening a
PR on <tt class="docutils literal"><span class="pre">https://notabug.org/CYBERDEViL/searx-qt</span></tt> after your translation has
finished.</p>
</div>
<div class="section" id="contact">
<span id="about-contact"></span><h2><a class="reference internal" href="#about-contact">Contact</a></h2>
<p>Please open a issue on <tt class="docutils literal"><span class="pre">https://notabug.org/cyberdevil/searx-qt</span></tt>.</p>
</div>
</div>
<div class="section" id="id3">
<span id="getting-started"></span><h1><a class="reference internal" href="#getting-started">Getting started</a></h1>
<div class="section" id="install-dependencies">
<span id="getting-started-install-dependencies"></span><h2><a class="reference internal" href="#getting-started-install-dependencies">Install dependencies</a></h2>
<p><strong>Note:</strong> <tt class="docutils literal"><span class="pre">python-requests</span></tt> is also dependent on <tt class="docutils literal"><span class="pre">python-urllib3</span></tt> ;
so <tt class="docutils literal"><span class="pre">python-urllib3</span></tt> will be installed with <tt class="docutils literal"><span class="pre">python-requests</span></tt>
(No need to do a explicit install).</p>
<div class="section" id="debian-ubuntu-based">
<h3>Debian / Ubuntu based</h3>
<p>Install required dependencies:</p>
<pre class="literal-block">
# apt update
# apt upgrade
# apt install python3 python3-requests python3-pyqt5 gettext pyqt5-dev-tools
</pre>
<p><strong>Optional</strong> for socks proxy support:</p>
<pre class="literal-block">
# apt install python3-socks
</pre>
</div>
<div class="section" id="arch-based">
<h3>Arch based</h3>
<p>Install required dependencies:</p>
<pre class="literal-block">
# pacman -Syu python python-requests python-pyqt5 gettext qt5-tools
</pre>
<p><strong>Optional</strong> for socks proxy support:</p>
<pre class="literal-block">
# pacman -S python-pysocks
</pre>
</div>
</div>
<div class="section" id="installation">
<span id="getting-started-installation"></span><h2><a class="reference internal" href="#getting-started-installation">Installation</a></h2>
<p>It is always recommended to let the package-manager of your system
do the installing of software, so your package-manager will keep
track of files installed. Only use <tt class="docutils literal">setup.py</tt> directly if you
know what you are doing.</p>
<p>Since Searx-Qt isn't available in any GNU/Linux distribution (yet?); the
best option is to create a package for your distribution yourself from the
latest release. This will also mean that you have to manually update
Searx-Qt if there is a new version available.</p>
<p><strong>Note:</strong> <a class="reference external" href="https://notabug.org/CYBERDEViL/searx-qt/releases">https://notabug.org/CYBERDEViL/searx-qt/releases</a></p>
<p><strong>Note:</strong> noticed the <tt class="docutils literal">#</tt> or <tt class="docutils literal">$</tt> before every command? When there is a
<tt class="docutils literal">$</tt> before the command, it should be run as a regular user. <tt class="docutils literal">#</tt> as root.</p>
<div class="section" id="debian-based">
<h3>Debian based</h3>
<p>The steps below describe how to get a specific version of Searx-Qt; then
package and install it. This method is available from version
<tt class="docutils literal"><span class="pre">0.1-beta2</span></tt> and up.</p>
<ol class="arabic">
<li><p class="first">Make sure you have <tt class="docutils literal"><span class="pre">python3-stdeb</span></tt> and <tt class="docutils literal">git</tt> installed:</p>
<pre class="literal-block">
# apt install python3-stdeb git
</pre>
</li>
<li><p class="first">Creating a working directory and <tt class="docutils literal">cd</tt> in to it, you may
change this to your own preference:</p>
<pre class="literal-block">
$ mkdir ~/git
$ cd ~/git
</pre>
</li>
<li><p class="first">Cloning the repository and <tt class="docutils literal">cd</tt> in to it:</p>
<pre class="literal-block">
$ git clone &quot;https://notabug.org/CYBERDEViL/searx-qt.git&quot; &quot;searx-qt&quot;
$ cd searx-qt
</pre>
</li>
<li><p class="first">Checkout a specific version:</p>
</li>
</ol>
<blockquote>
<p><strong>Note:</strong> get a list with available tags (versions) with the
<tt class="docutils literal">git tag</tt> command.</p>
<p>Below is a example to checkout version <tt class="docutils literal"><span class="pre">0.3-beta1</span></tt>:</p>
<pre class="literal-block">
$ git checkout 0.3-beta1
</pre>
</blockquote>
<ol class="arabic" start="5">
<li><p class="first">Create .deb:</p>
<pre class="literal-block">
$ ./utils/gen_deb.sh
</pre>
</li>
<li><p class="first">Install the created package:</p>
<pre class="literal-block">
# dpkg -i ./deb_dist/python3-searx-qt_0.3-beta1-1_all.deb
</pre>
</li>
</ol>
</div>
<div class="section" id="id4">
<h3>Arch based</h3>
<p>For Arch based distributions there is a package available in the AUR;
<a class="reference external" href="https://aur.archlinux.org/packages/searx-qt/">https://aur.archlinux.org/packages/searx-qt/</a></p>
<ol class="arabic">
<li><p class="first">Make sure you have <tt class="docutils literal">git</tt> installed:</p>
<pre class="literal-block">
# pacman -S git
</pre>
</li>
<li><p class="first">Creating a working directory and <tt class="docutils literal">cd</tt> in to it, you may change this
to your own preference:</p>
<pre class="literal-block">
$ mkdir ~/pkg
$ cd ~/pkg
</pre>
</li>
<li><p class="first">Getting the <tt class="docutils literal">PKGBUILD</tt> from Arch AUR:</p>
<pre class="literal-block">
$ git clone https://aur.archlinux.org/searx-qt.git
$ cd searx-qt
</pre>
</li>
<li><p class="first">Build and install Searx-Qt package:</p>
<pre class="literal-block">
$ makepkg -si
</pre>
</li>
</ol>
</div>
</div>
</div>
<div class="section" id="id5">
<span id="usage"></span><h1><a class="reference internal" href="#usage">Usage</a></h1>
<div class="section" id="profiles">
<span id="usage-profiles"></span><h2><a class="reference internal" href="#usage-profiles">Profiles</a></h2>
<img alt="Profiles window" class="align-right" src="images/profiles_window.png" />
<p>Profiles are useful when you want to have different settings and/or data without
to having to set it manually every-time. For example you can create a profile
named <cite>Tor</cite> which has different proxy and stats2 settings then you normal
profile.</p>
<dl class="docutils">
<dt>There are two types of profiles:</dt>
<dd><ul class="first last simple">
<li><cite>Stats2</cite> profile</li>
<li><cite>User</cite> profile</li>
</ul>
</dd>
</dl>
<p>The profile type names maybe changed to something better, suggestions are
welcome.</p>
<p>Create a <cite>Stats2</cite> profile if you wish to get/update a list of Searx-instances
from a <cite>Searx-Stats2</cite> instance. For example the default <cite>https://searx.space</cite>.</p>
<p>Create a <cite>User</cite> profile if you wish to add/remove/update your own list with
Searx-instances.</p>
<blockquote>
<div class="line-block">
<div class="line"><strong>NOTE</strong>: Profile types cannot be changed after the creation of the profile,</div>
<div class="line-block">
<div class="line">but you can add multiple profiles of both types.</div>
</div>
</div>
</blockquote>
<div class="section" id="creating-new-profile">
<h3>Creating new profile</h3>
<p>On first usage of <cite>Searx-Qt</cite> you will need to create a new profile. The <cite>Add</cite>
button (of the &quot;Profile select&quot; window) will open a dialog to do so.</p>
<p>There are profile settings presets (Web, Tor, i2p) which you can choose from.
The Tor preset sets the proxy to <tt class="docutils literal">127.0.0.1:9050</tt> and
changes the Searx-Stats2 instance url to the onion address. The i2p preset
sets the proxy to <tt class="docutils literal">127.0.0.1:4444</tt>, it also adds some known
i2p instances of Searx.</p>
<blockquote>
<img alt="Create new profile dialog" src="images/profiles_new.png" />
</blockquote>
</div>
<div class="section" id="deleting-a-profile">
<h3>Deleting a profile</h3>
<p>I hope that it is self explanatory that the <cite>Delete</cite> button of the
&quot;Profile select&quot; window deletes the currently selected profile, it will ask
for confirmation before doing so.</p>
<p>It is not possible to delete a active profile (at-least it shouldn't ;-)).</p>
</div>
</div>
<div class="section" id="settings">
<span id="usage-settings"></span><h2><a class="reference internal" href="#usage-settings">Settings</a></h2>
<div class="section" id="general">
<h3>General</h3>
<img alt="images/settings_general.png" class="align-right" src="images/settings_general.png" />
<div class="section" id="theme">
<h4>Theme</h4>
<p>A <tt class="docutils literal">Theme</tt> is a Searx-Qt specific <tt class="docutils literal">stylesheet</tt> and the <tt class="docutils literal">Base style</tt> is a
Qt theme/style.</p>
<p>The Searx-Qt specific <tt class="docutils literal">Theme</tt> does override the <tt class="docutils literal">Base style</tt>.</p>
</div>
<div class="section" id="cli-output-level">
<h4>CLI output level</h4>
<p>The amount of CLI spam can be set here.</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal">Info</tt> does print to <tt class="docutils literal">stdout</tt>.</li>
<li><tt class="docutils literal">Warning</tt> does print to <tt class="docutils literal">stderr</tt>.</li>
<li><tt class="docutils literal">Debug</tt> does print to <tt class="docutils literal">stderr</tt>.</li>
<li><tt class="docutils literal">Errror</tt> does print to <tt class="docutils literal">stderr</tt>.</li>
</ul>
</blockquote>
</div>
</div>
<div class="section" id="connection">
<h3>Connection</h3>
<img alt="images/settings_connection.png" class="align-right" src="images/settings_connection.png" />
<div class="section" id="verify-ssl">
<h4>Verify (SSL)</h4>
<p>Request will fail on a invalid SSL/TLS certificate.</p>
<p>Leave checked if unsure.</p>
<p>See
<a class="reference external" href="https://requests.readthedocs.io/en/master/user/advanced/#ssl-cert-verification">https://requests.readthedocs.io/en/master/user/advanced/#ssl-cert-verification</a>
for a more technical description.</p>
</div>
<div class="section" id="timeout">
<h4>Timeout</h4>
<p>Timeout in seconds for a single request.</p>
<p>Leave it at the default value of 10 seconds if unsure.</p>
<p>See <a class="reference external" href="https://requests.readthedocs.io/en/master/user/advanced/#timeouts">https://requests.readthedocs.io/en/master/user/advanced/#timeouts</a> for a
more technical description.</p>
</div>
<div class="section" id="proxy">
<h4>Proxy</h4>
<p>Here you can set a proxy that will be used for every connection Searx-Qt
makes. Leave the input field blank to use no proxy.</p>
<p>The 'Http' section can be used to proxy plain <a class="reference external" href="http://">http://</a> requests to for
example instances without a certificate. The 'Https' section can be used
to proxy all <a class="reference external" href="https://">https://</a> requests to instances (including fetching the
instances list data from <a class="reference external" href="https://searx.space">https://searx.space</a>) with a certificate. So you
can use a separate proxy for both protocols.</p>
<p>If you use a socks4 or socks5 proxy you probably want to make sure the
'Proxy DNS' checkbox is checked so DNS requests will also go through the
proxy. DNS proxy is not available for a http proxy type.</p>
</div>
<div class="section" id="user-agents">
<h4>User-agents</h4>
<p>What user-agent string should Searx-Qt send?</p>
<p>After pressing the <cite>Edit</cite> button it will change to a <cite>Save</cite> button, you will
be able to edit the user-agent ?string(s) Searx-Qt will send. Some notes:</p>
<ul class="simple">
<li>One user-agent string per line.</li>
<li>Set total blank to not send any user-agent string.</li>
</ul>
<p>When the <cite>Random</cite> checkbox is checked and there are multiple user-agent
strings set then Searx-Qt will pick a random user-agent string from the list
for every request.</p>
</div>
</div>
<div class="section" id="id6">
<h3>Searx-Stats2</h3>
<p>Here you can change the URL of the Searx-Stats2 instance you like to use
for fetching the instances data.</p>
<blockquote>
<div class="line-block">
<div class="line"><strong>NOTE</strong>: This is only available for a <cite>Stats2</cite> profile type.</div>
</div>
</blockquote>
</div>
<div class="section" id="guard">
<span id="usage-instances"></span><h3>Guard</h3>
<p>Guard can put instances on a timeout or the blacklist when they are failing.</p>
<p>When the Guard rules are set properly, searches will be quicker over time
since failing instances are not used anymore. This reduces the chance of
requesting a search query to a instance that probably will fail again. Also
some instances block our request for whatever reason they have, and there is
no standard response so they all may (and many will) respond diffrently (Thus
we can not properly detect when we may use the API and when not).</p>
<blockquote>
<ul class="simple">
<li>It should be obvious that when <tt class="docutils literal">Enable guard</tt> is checked that Guard is enabled, when not checked Guard is disabled.</li>
<li>When Guard is enabled it is advised to also enable the <tt class="docutils literal">Store log</tt> option so that old failures can be evaluated against new failures after Searx-Qt has been restarted.</li>
<li>Below the <tt class="docutils literal">Store log</tt> option is a spinbox that defines for how long log entries will be stored (in days).</li>
<li>A rule defines what a fail is and what should happen with the failing instance.</li>
</ul>
</blockquote>
<img alt="images/settings_guard.png" class="align-right" src="images/settings_guard.png" />
<div class="section" id="rules">
<h4>Rules</h4>
<p>A rule has the following variables:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal">Error Type</tt>, the type of error.</li>
<li><tt class="docutils literal">Amount</tt> of fails.</li>
<li><tt class="docutils literal">Timeframe</tt> in which the <tt class="docutils literal">Amount</tt> of fails have to occur.</li>
<li><tt class="docutils literal">Status</tt>, the HTTP response code. (Only used for the <tt class="docutils literal">WrongStatus</tt> <tt class="docutils literal">Error type</tt>).</li>
<li><tt class="docutils literal">Destination</tt>, what should happen to the instance? Should Guard put it on
the blacklist or on a timeout?</li>
<li><tt class="docutils literal">Duration</tt> in minutes of the timeout. (Only used when <tt class="docutils literal">Destionation</tt> is set to <tt class="docutils literal">Timeout</tt>). When <tt class="docutils literal">Timeout</tt> is used as <tt class="docutils literal">Destination</tt> and this is set to <tt class="docutils literal">0</tt> minutes the instance will be on timeout until Searx-Qt
has been restarted.</li>
</ul>
</blockquote>
<p>When <tt class="docutils literal">Error type</tt>, <tt class="docutils literal">Amount</tt>, <tt class="docutils literal">Timeframe</tt> and <tt class="docutils literal">Status</tt> are met the rule
will be triggered and the instance will be put on the <tt class="docutils literal">Destination</tt> for
<tt class="docutils literal">Duration</tt> amount of time in minutes.</p>
</div>
<div class="section" id="log">
<h4>Log</h4>
<p>Here you can see failed search requests. Failed search requests will only
be logged when Guard is enabled.</p>
<p>It logs as little as possible. The following is logged:</p>
<blockquote>
<ul class="simple">
<li>Date and time.</li>
<li>Instance url.</li>
<li>Error Type.</li>
<li>HTTP status code.</li>
<li>HTTP content/Error message (for debugging, may contain error message)</li>
</ul>
</blockquote>
</div>
</div>
</div>
<div class="section" id="instances">
<h2><a class="reference internal" href="#usage-instances">Instances</a></h2>
<img alt="images/instances.png" class="align-right" src="images/instances.png" />
<p>A Searx instance is a server running the Searx project. Since we want to
preform searches to Searx instance(s) we need addresses of those
instance(s).</p>
<p>The interface to manage instances is on the right.</p>
<div class="section" id="with-stats2-profile-type">
<h3>With <cite>Stats2</cite> profile type</h3>
<p>When your profile is a <cite>Stats2</cite> type, the Searx-instances will be fetched
from <tt class="docutils literal"><span class="pre">https://searx.space/data/instances.json</span></tt> (or any other set in the
settings by your preference). The <tt class="docutils literal">instances.json</tt> from <tt class="docutils literal">search.space</tt>
also contains a lot of other data about the instances it lists (which we can
use to filter instances based on our preferences).</p>
<p>When Searx-Qt is used for the first time you will need to update the
instances table. There is a 'Update' button between the Filter and the
Table that can be used for this. Searx-Qt will not update this automatically!</p>
<p>It maybe useful to update the instances data so now and then since public
instances appear, disappear and their stats change over time.</p>
</div>
<div class="section" id="with-user-profile-type">
<h3>With <cite>User</cite> profile type</h3>
<p>If your profile is a <cite>User</cite> type you will have to add addresses of instances
manually.</p>
<p>This can be done by pressing the <cite>Add instance</cite> button right above
the instances table, a dialog will pop-up asking for the address to add
(without scheme).</p>
<p>The scheme (<a class="reference external" href="http://">http://</a> or <a class="reference external" href="https://">https://</a>) can be selected from the combobox.</p>
<p>There is also a &quot;Update data on add&quot; checkbox, when this is checked
and <cite>Add</cite> is pressed it will automatically download data from
<cite>http(s)://your-address/config</cite>. Downloading/updating this data may also be
done later by right clicking on a (or multiple) Searx-instances in the table
and pressing <cite>Update selected</cite>.</p>
</div>
<div class="section" id="instances-table">
<span id="usage-instances-table"></span><h3>Instances table</h3>
<p>The instances table can be used to browse instances with their data that
remain after all filters. The table is also used to set the current
instance by left-clicking on one.</p>
<p>The currently used instance should also be visible bottom right in the
application it's status-bar.</p>
<p>Right-clicking in the table opens a context-menu from where you can do
the following:</p>
<ul class="simple">
<li>Whitelist/blacklist selected instance(s).</li>
<li>Temporary blacklist.</li>
<li>Copy selected instance(s) it's/their URL(s).</li>
<li>Select All instances (CTRL+A should do the same).</li>
<li>Hide or show columns.</li>
</ul>
<p>If your profile is a <cite>User</cite> profile the context-menu will have the
following extra actions:</p>
<ul class="simple">
<li>Remove selected instance(s).</li>
<li>Update selected instance(s).</li>
</ul>
</div>
<div class="section" id="filter-instances">
<h3>Filter instances</h3>
<p>When a filter is enabled and the instance it's value that is being
matched is unknown then it is excluded by default!</p>
<div class="section" id="network">
<h4>Network</h4>
<p>Filter instances on network type. Only instances that match one of the
checked network types remain.</p>
</div>
<div class="section" id="require-asn-privacy">
<h4>Require ASN privacy</h4>
<p>Excludes instances that run their server at a known malicious network.
Like for example CloudFlare, Google, Akamai etc..</p>
<p>This does not give any guarantee, it only filters <strong>known</strong> privacy
violators!</p>
<p>For a full list of known malicious networks (technical):
<a class="reference external" href="https://github.com/dalf/searx-stats2/blob/master/searxstats/data/asn.py">https://github.com/dalf/searx-stats2/blob/master/searxstats/data/asn.py</a></p>
</div>
<div class="section" id="require-ipv6">
<h4>Require IPv6</h4>
<p>Exclude instances that don't have at least one IPv6 address.</p>
</div>
<div class="section" id="min-version">
<h4>Min version</h4>
<p>When a minimum version is set only instances that have the minimum set
or higher -version are included.</p>
<blockquote>
<ul class="simple">
<li>When <tt class="docutils literal">Development</tt> is checked it will also include git versions.</li>
<li>When <tt class="docutils literal">Unknown suffix</tt> is checked it will also include git versions with a
unknown commit hash</li>
</ul>
</blockquote>
</div>
<div class="section" id="blacklist">
<h4>Blacklist</h4>
<p>Here are the URLs of the instances that have been blacklisted, either manually
or automatically by Guard (when enabled).</p>
<p>There is a button right to each blacklist item to remove it from the
blacklist.</p>
<p>Hovering the remove button or the url of a blacklist item will show a tooltip
with some more info.</p>
<p>You can manually blacklist a instance by right clicking on a instance in
the instances table and click 'Add to blacklist'; multiple instances can
be blacklisted at once.</p>
<p>Blacklisted instances will be excluded from the table by default.</p>
</div>
<div class="section" id="whitelist">
<h4>Whitelist</h4>
<p>Here are the URLs of the instances that have been manually whitelisted.
There is a button right to each whitelist item to remove it from the
whitelist.</p>
<p>You can manually whitelist a instance by right clicking on a instance in
the instances table and click 'Add to whitelist'; multiple instances can
be whitelisted at once.</p>
<p>Whitelisted instances will be in the table by default except when they are on
the timeout list.</p>
</div>
<div class="section" id="id7">
<h4>Timeout</h4>
<p>This is a temporary blacklist. Instances manually put on a timeout will stay
here until Searx-Qt is restarted. When Guard is enabled it also may put
instances here depending on the set rules, those may persist after Searx-Qt is
restarted depending on the rule(s).</p>
<p>Hovering the remove button or the url of a timeout item will show a tooltip
with some more info.</p>
</div>
</div>
</div>
<div class="section" id="search">
<span id="usage-search"></span><h2><a class="reference internal" href="#usage-search">Search</a></h2>
<div class="section" id="search-bar">
<span id="usage-search-bar"></span><h3>Search bar</h3>
<img alt="images/search_bar.png" src="images/search_bar.png" />
<div class="section" id="fallback">
<span id="usage-search-bar-fallback"></span><h4>Fallback</h4>
<p>When checked it will pick a random instance from the instances table if a
search request fails one way or another and re-try the same request with
the freshly picked instance. There is a maximum amount of 10 tries (10
different instances to try the same request on).</p>
<p>What is fail?</p>
<ul class="simple">
<li>Connection errors including timeout.</li>
<li>Wrong status code (not 200).</li>
<li>No or malformed results returned.</li>
</ul>
</div>
<div class="section" id="random-every">
<span id="usage-search-random-every"></span><h4>Random every</h4>
<p>When checked it will automatically pick a random instance on a search request,
it will also hide the 'Random search button' because it makes it obsolete.</p>
<p>When not checked it will do search requests on the same instance unless the
request fails somehow and 'Fallback' is checked. Exception is when the
'Random search button' is used for the search request.</p>
</div>
<div class="section" id="random-search-button">
<span id="usage-search-bar-random-search-button"></span><h4>Random search button</h4>
<p>When pressed it will pick a random instance from the list and preform the
search request.</p>
</div>
<div class="section" id="reload-button">
<span id="usage-search-bar-reload-button"></span><h4>Reload button</h4>
<p>When pressed it basically preforms a search request without 'Fallback'
whenever it is enabled or not, it also doesn't reset the page number. So
it can act as a reload button thus it's name, but it does more.</p>
<p>Note: When a search argument like the search query, instance URL,
categories/engines etc. has changed by user interaction it will do the
request with those changes, that isn't a real reload of the previous
request.</p>
<p>Dev-note: Probably this behavior should change or the name/icon should
change to something more fitting.</p>
</div>
<div class="section" id="search-button">
<span id="usage-search-bar-search-button"></span><h4>Search button</h4>
<p>Preform a search request on the currently selected instance.</p>
<p>Page number is reset, 'Fallback' and 'Random Every' options are honored.</p>
</div>
<div class="section" id="search-query-input">
<span id="usage-search-bar-search-query-input"></span><h4>Search query input</h4>
<p>The query you like to search for.</p>
<p>See <a class="reference external" href="https://searx.github.io/searx/user/search_syntax.html">https://searx.github.io/searx/user/search_syntax.html</a> for what is
possible.</p>
<p>It will do a search request on <tt class="docutils literal">enter</tt> key pressed, same behavior as
when the 'Search button' has been pressed.</p>
</div>
</div>
<div class="section" id="search-options">
<span id="usage-search-options"></span><h3>Search options</h3>
<img alt="Search options bar" src="images/search_options.png" />
<p><strong>NOTE</strong>: Right clicking in (on the picture above) the dark area opens a
context-menu where you can manage what options you want to be visible or
not as shown in the image below.</p>
<img alt="Search options context menu" class="align-right" src="images/search_options_rmb.png" />
<p><strong>NOTE</strong>: Left-click (mouse) on the <tt class="docutils literal">Categories</tt> or <tt class="docutils literal">Engines</tt> label will
toggle the label collapsed/expanded state, to be able to reduce the height
when multiple options are selected.</p>
<p><strong>NOTE</strong>: Right-click (mouse) on <tt class="docutils literal">Categories</tt> or <tt class="docutils literal">Engines</tt> label will open
a context menu with a option to uncheck all for convenience.</p>
<div class="section" id="categories">
<span id="usage-search-options-categories"></span><h4>Categories</h4>
<img alt="Categories menu" class="align-right" src="images/categories_menu.png" />
<p>A category is basically a collection of engines. When a category gets checked
then all the engines it represents will also be checked which in turn will
filter out all Searx-instances that don't have at least one of the checked
engines enabled.</p>
<p>Multiple categories may be selected.</p>
<p>The default (non-editable) categories will be compiled from categories listed
in engines. Besides default categories there is also a option to create custom
categories.</p>
<img alt="Custom categories window" src="images/custom_categories.png" />
</div>
<div class="section" id="engines">
<span id="usage-search-options-engines"></span><h4>Engines</h4>
<p>Here you can toggle what search engines should be enabled. It will
automatically filter out all instances from the instances table that doesn't
have at least one of the checked engines enabled. The checked engines will
be send with a search request to a Searx instance with the <cite>enabled_engines</cite>
param. You should only get results from engines that are checked.</p>
<p>If no engine is checked it means that it may return results of any engine
in the list.</p>
<p>The list with engines is created with data from the
<a class="reference internal" href="#usage-instances-table">instances table</a>, so only engines are listed that
are available from the instances table.</p>
</div>
<div class="section" id="period">
<span id="usage-search-options-period"></span><h4>Period</h4>
<p>Search period you like results from. Options are <tt class="docutils literal">Last day</tt>,
<tt class="docutils literal">Last week</tt>, <tt class="docutils literal">Last month</tt> or <tt class="docutils literal">Last year</tt>.</p>
</div>
<div class="section" id="language">
<span id="usage-search-options-language"></span><h4>Language</h4>
<p>If you want results in a specific language than you can select one here. The
set language will persist on restart.</p>
<p>Since Searx-Qt 0.3 there is a option to mark languages a favorites. Favorites
will appear on the top of the combobox list so you won't have to scroll.</p>
<p>Adding a language to favorite can be done by hovering the language and
pressing the spacebar on your keyboard. Removing a favorite works the same,
hover the favorite language and press the spacebar on your keyboard.</p>
<blockquote>
<div class="line-block">
<div class="line"><strong>NOTE</strong>: Not all engines have language support and not all engines </div>
<div class="line-block">
<div class="line">honor the requested language. Searx-qt does not (yet?) act on </div>
<div class="line">this.</div>
</div>
</div>
<div class="line-block">
<div class="line"><strong>NOTE</strong>: When <tt class="docutils literal">Default language</tt> is set that means the default language</div>
<div class="line-block">
<div class="line">of the instance.</div>
</div>
</div>
</blockquote>
</div>
</div>
<div class="section" id="search-results">
<h3>Search results</h3>
<div class="section" id="find-text-in-results">
<h4>Find text in results</h4>
<p>The find widget to search text inside the results can be opened/focused by the
keyboard shortcut <tt class="docutils literal">Ctrl + F</tt>.</p>
<p>Shortcuts that may be used while the find text input is activated:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal">Return</tt> to find the next match.</li>
<li><tt class="docutils literal">Shift + Return</tt> to find the previous match.</li>
<li><tt class="docutils literal">Escape</tt> to close.</li>
</ul>
</blockquote>
</div>
</div>
</div>
</div>
<div class="section" id="id8">
<span id="development"></span><h1><a class="reference internal" href="#development">Development</a></h1>
<p><strong>NOTE</strong>: Make sure you are in the Searx-Qt source root (where utils/,
locales/, searxqt/ etc.. are).</p>
<p><strong>NOTE</strong>: To run Searx-Qt without need to install:</p>
<pre class="literal-block">
# Copy the executable from ./bin to cwd (searx-qt source root)
cp bin/searx-qt ./

# Start
./searx-qt
</pre>
<div class="section" id="themes">
<span id="development-themes"></span><h2><a class="reference internal" href="#development-themes">Themes</a></h2>
<div class="section" id="create-new-theme">
<h3>Create new theme</h3>
<p>A theme consists of icons, application css and search result/fail css.</p>
<p>Simple example to create a new theme from the default theme:</p>
<p><strong>NOTE</strong>: Replace <tt class="docutils literal">your_theme</tt> with the name of your new theme.</p>
<p><strong>NOTE</strong>: For this example you should know basic CSS.</p>
<ol class="arabic">
<li><p class="first">Setup structure for new theme.</p>
<blockquote>
<pre class="code literal-block">
cp -r ./themes/default/ ./themes/your_theme/
</pre>
</blockquote>
</li>
<li><p class="first">Edit the application style <tt class="docutils literal">./themes/your_theme/style.css</tt>.</p>
</li>
<li><p class="first">Edit the css used for failed search result message <tt class="docutils literal">./themes/your_theme/html_fail.css</tt>.</p>
</li>
<li><p class="first">Edit the css used for search results <tt class="docutils literal">./themes/your_theme/html_results.css</tt></p>
</li>
<li><p class="first">Edit the icons (don't change their size) <tt class="docutils literal"><span class="pre">./themes/your_theme/icons/*.png</span></tt></p>
</li>
<li><p class="first">Open <tt class="docutils literal">./themes/your_theme/manifest.json</tt> and change the <tt class="docutils literal">name</tt> variable to the pretty name of your new theme.</p>
</li>
<li><p class="first">See if your theme is listed, when not there is a error:</p>
<pre class="literal-block">
python ./utils/themes_tool.py list
</pre>
</li>
<li><p class="first">Compile the theme:</p>
<pre class="literal-block">
python ./utils/themes_tool.py make your_theme
</pre>
</li>
<li><p class="first">Open Searx-Qt, go to settings, change to your new theme (it should be listed, else there is an error) and test it:</p>
<pre class="literal-block">
./searx-qt
</pre>
</li>
<li><p class="first">Done? :-)</p>
</li>
</ol>
</div>
</div>
<div class="section" id="id9">
<span id="development-translations"></span><h2><a class="reference internal" href="#development-translations">Translations</a></h2>
<p>Searx-Qt will try to find a translation for your system locale and use that
when found.</p>
<p>To test translations the system locale should be installed for that language,
it doesn't have to be set for testing since we can easly override the <tt class="docutils literal">LANG</tt>
environment variable before executing Searx-Qt.</p>
<p><strong>NOTE</strong>: The examples below are for a Dutch language translation, you
should replace <tt class="docutils literal">nl_NL</tt> with the i18n locale ID of the language you whish to
translate.</p>
<div class="section" id="create-new-translation">
<h3>Create new translation</h3>
<ol class="arabic">
<li><p class="first">Setup structure for new language:</p>
<pre class="literal-block">
# Update the searx-qt.pot template file.
./utils/locale_tool.sh -c

# Create directory structure.
mkdir -p ./locales/nl_NL/LC_MESSAGES/

# Copy the template file to our new directory.
cp ./locales/searx-qt.pot ./locales/nl_NL/LC_MESSAGES/searx-qt.po

# Check if our new language is found. It should be listed.
./utils/locale_tool.sh --list
</pre>
</li>
<li><p class="first">Start working on the translation.</p>
<p>You can edit the <tt class="docutils literal"><span class="pre">./locales/nl_NL/LC_MESSAGES/searx-qt.po</span></tt> file with a
text editor or a special editor for translations (that can handle <tt class="docutils literal">.po</tt>
files like for example Poedit).</p>
</li>
<li><p class="first">Compile the translation:</p>
<pre class="literal-block">
./utils/locale_tool.sh -m nl_NL
</pre>
</li>
<li><p class="first">Test the translation:</p>
<pre class="literal-block">
# Note: overriding XDG_DATA_HOME only for debugging translations! Themes
#       will not work.
XDG_DATA_HOME=&quot;$(pwd -P)/&quot; LANG=nl_NL.UTF-8 ./searx-qt
</pre>
</li>
</ol>
</div>
<div class="section" id="update-existing-translation">
<h3>Update existing translation</h3>
<ol class="arabic">
<li><p class="first">Update files:</p>
<pre class="literal-block">
# Update the .pot template file.
./utils/locale_tool.sh -c

# Update the translation it's .po file
./utils/locale_tool.sh -u nl_NL
</pre>
</li>
<li><p class="first">Edit the translation:</p>
<p>You can edit the <tt class="docutils literal"><span class="pre">./locales/nl_NL/LC_MESSAGES/searx-qt.po</span></tt> file with a
text editor or a special editor for translations (that can handle <tt class="docutils literal">.po</tt>
files like for example Poedit).</p>
</li>
<li><p class="first">Compile the translation:</p>
<pre class="literal-block">
./utils/locale_tool.sh -m nl_NL
</pre>
</li>
<li><p class="first">Test the translation:</p>
<pre class="literal-block">
# Note: overriding XDG_DATA_HOME only for debugging translations! Themes
#       will not work.
XDG_DATA_HOME=&quot;$(pwd -P)/&quot; LANG=nl_NL.UTF-8 ./searx-qt
</pre>
</li>
</ol>
</div>
</div>
</div>
</div>
</body>
</html>