doc/index.docbook

   1 <?xml version="1.0" ?>
   2
   3 <!--
   4   Copyright 2023 Soren Stoutner <soren@stoutner.com>.
   5
   6   This file is part of Privacy Browser PC <https://www.stoutner.com/privacy-browser-pc>.
   7
   8   Permission is granted to copy, distribute and/or modify this document
   9   under the terms of the GNU Free Documentation License, Version 1.3
  10   or any later version published by the Free Software Foundation;
  11   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
  12
  13   You should have received a copy of the GNU Free Documentation License
  14   along with Privacy Browser PC.  If not, see <http://www.gnu.org/licenses/>. -->
  15
  16 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
  17   <!-- Privacy Browser’s name -->
  18   <!ENTITY privacybrowser "<application>Privacy Browser</application>">
  19
  20   <!-- People. -->
  21   <!ENTITY Soren.Stoutner "<personname><firstname>Soren</firstname><surname>Stoutner</surname></personname>">
  22   <!ENTITY Soren.Stoutner.mail "<email>soren@stoutner.com</email>">
  23
  24   <!-- Set the language of this documentation. -->
  25   <!ENTITY % English "INCLUDE">
  26
  27   <!-- Default entries.  May not be needed. -->
  28   <!ENTITY i18n-translatable-entity "<application>Translatable Entity</application>">
  29   <!ENTITY % addindex "IGNORE">
  30 ]>
  31
  32 <book id="privacybrowser" lang="&language;">
  33   <bookinfo>
  34     <title>The &privacybrowser; Handbook</title>
  35
  36     <authorgroup>
  37       <author>&Soren.Stoutner; &Soren.Stoutner.mail;</author>
  38
  39       <!-- Add translators here.  TRANS:ROLES_OF_TRANSLATORS -->
  40     </authorgroup>
  41
  42     <copyright>
  43       <year>2016-2017, 2021-2023</year>
  44       <holder>&Soren.Stoutner;</holder>
  45     </copyright>
  46
  47     <!-- Documentation license. -->
  48     <legalnotice>&FDLNotice;</legalnotice>
  49
  50     <!-- Last update. -->
  51     <date>2023-02-22</date>
  52
  53     <!-- The version of Privacy Browser this documentation is written for. -->
  54     <releaseinfo>&privacybrowser; version 0.1</releaseinfo>
  55
  56
  57     <!-- Abstract about this handbook -->
  58     <abstract>
  59       <para>
  60         &privacybrowser; is a web browser that respects your privacy.
  61       </para>
  62     </abstract>
  63
  64     <!-- This is a set of Keywords for indexing by search engines. -->
  65     <keywordset>
  66       <keyword>KDE</keyword>
  67       <keyword>privacy</keyword>
  68       <keyword>browser</keyword>
  69     </keywordset>
  70   </bookinfo>
  71
  72   <!-- Introduction. -->
  73   <chapter id="introduction">
  74     <title>Introduction</title>
  75
  76     <para>
  77       &privacybrowser; is currently in an early alpha state.
  78       Most of the features are not yet implemented, but I thought it would be useful to publish it so that users can track the progress and submit feedback.
  79     </para>
  80
  81     <para>
  82       To distinguish between the Android and the PC version, the website, issue tracker,
  83       and code base refer to this version as <ulink url="https://www.stoutner.com/privacy-browser-pc/">Privacy Browser PC</ulink>.
  84     </para>
  85
  86     <para>
  87       The best place to discuss the development of Privacy Browser is <ulink url="https://redmine.stoutner.com/projects/privacy-browser-pc/boards">on the forum</ulink>.
  88       I also frequently post on my <ulink url="https://fosstodon.org/@privacybrowser">Mastodon account</ulink> regarding the development status.
  89     </para>
  90
  91     <!-- Qt WebEngine. -->
  92     <sect1 id="qt-webengine">
  93       <title>Qt WebEngine</title>
  94
  95       <para>
  96         Privacy Browser uses <ulink url="https://doc.qt.io/qt-5/qtwebengine-index.html">Qt WebEngine</ulink> to render websites.
  97         Qt WebEngine is based on the <ulink url="https://www.chromium.org/blink/">Chromium Blink</ulink> source code.
  98         Because Privacy Browser is built on the <ulink url="https://api.kde.org/frameworks/index.html">KDE Framework</ulink>,
  99         it currently uses the <ulink url="https://community.kde.org/Schedules/Plasma_6">Qt 5</ulink> packages.
 100       </para>
 101
 102       <para>
 103         The current Qt 5 packages are in long-term support mode.
 104         Qt WebEngine 5.15.x is based on <ulink url="https://wiki.qt.io/QtWebEngine/ChromiumVersions">Chromium 87.0.4280.144</ulink> from a feature perspective.
 105         Security fixes are backported with <ulink url="https://wiki.qt.io/Qt_5.15_Release#Release_Plan">each release</ulink> every couple of months.
 106       </para>
 107     </sect1>
 108
 109     <!-- Bugs and missing features. -->
 110     <sect1 id="bugs-and-missing-features">
 111       <title>Bugs and Missing Features</title>
 112
 113       <para>
 114         There is a list of feature requests and known bugs at <ulink url="https://redmine.stoutner.com/projects/privacy-browser-pc/issues">redmine.stoutner.com</ulink>.
 115         Users should anticipate that all the current features of <ulink url="https://www.stoutner.com/privacy-browser-android/">Privacy Browser Android</ulink>
 116         will also be implemented in Privacy Browser PC.
 117         There is no need at this point to create features requests for these as they will be added as I start working on each feature and have a better idea of how they will be implemented.
 118         However, each feature that has already been implemented should be bug free.
 119         If you discover a bug that is not already documented at <ulink url="https://redmine.stoutner.com/projects/privacy-browser-pc/issues">redmine.stoutner.com</ulink> please add it.
 120       </para>
 121
 122       <para>
 123         Below is a list of known prominent bugs or missing features in this alpha release.
 124       </para>
 125
 126       <itemizedlist>
 127         <listitem><para>The page zoom is <ulink url="https://redmine.stoutner.com/issues/799">momentarily reset</ulink> every time a new URL is loaded.</para></listitem>
 128         <listitem><para>If domain settings change the user agent, loading of the new URL is interrupted and the
 129           <ulink url="https://redmine.stoutner.com/issues/821">previous site is reloaded</ulink>.</para></listitem>
 130         <listitem><para>Browser <ulink url="https://redmine.stoutner.com/issues/831">error messages are not displayed</ulink> unless JavaScript is enabled.</para></listitem>
 131         <listitem><para>Bookmarks are <ulink url="https://redmine.stoutner.com/issues/968">not yet implemented</ulink>.</para></listitem>
 132         <listitem><para>Blocklists are <ulink url="https://redmine.stoutner.com/issues/969">not yet implemented</ulink>.</para></listitem>
 133       </itemizedlist>
 134     </sect1>
 135   </chapter>
 136
 137   <!-- Using Privacy Browser. -->
 138   <chapter id="using-privacy-browser">
 139     <title>Using &privacybrowser;</title>
 140
 141     <para>
 142       <mediaobject>
 143         <imageobject>
 144           <imagedata fileref="privacybrowser.png" format="PNG"/>
 145         </imageobject>
 146         <textobject>
 147           <phrase>Screenshot</phrase>
 148         </textobject>
 149       </mediaobject>
 150     </para>
 151
 152     <!-- JavaScript. -->
 153     <sect1 id="javascript">
 154       <title>JavaScript</title>
 155
 156       <para>
 157         JavaScript allows web pages to run scripts (programs) on your device. It allows web pages to function more like apps, but it also allows web pages to spy on you.
 158         Most of the tracking on the internet does not work when JavaScript is disabled.
 159         JavaScript can be toggled by clicking on the privacy shield, which is blue if JavaScript is disabled and red when it is enabled.
 160         <inlinemediaobject>
 161           <imageobject>
 162             <imagedata fileref="javascript.png" format="PNG"/>
 163           </imageobject>
 164           <textobject>
 165             <phrase>JavaScript</phrase>
 166           </textobject>
 167         </inlinemediaobject>
 168       </para>
 169     </sect1>
 170
 171     <!-- Local Storage. -->
 172     <sect1 id="local-storage">
 173       <title>Local Storage</title>
 174
 175       <para>
 176         <ulink url="https://doc.qt.io/qt-5/qwebenginecookiestore.html#setCookieFilter">Local storage</ulink>
 177         in Privacy Browser encompasses cookies, DOM storage, IndexedDB, service workers, and the filesystem API.
 178         Local storage can be toggled through an action on the toolbar.
 179       </para>
 180
 181       <!-- Cookies. -->
 182       <sect2 id="cookies">
 183         <title>Cookies</title>
 184
 185         <para>
 186           <mediaobject>
 187             <imageobject>
 188               <imagedata fileref="cookies.png" format="PNG"/>
 189             </imageobject>
 190             <textobject>
 191               <phrase>Cookies</phrase>
 192             </textobject>
 193           </mediaobject>
 194         </para>
 195
 196         <para>
 197           <ulink url="https://en.wikipedia.org/wiki/HTTP_cookie">Cookies</ulink>
 198           allow websites to store small pieces of information for a specific host that are sent in the HTTP header every time the browser connects to that host.
 199           Privacy Browser allows a maximum of <ulink url="http://browsercookielimits.iain.guru/">180 cookies with a maximum size of 4096 bytes per cookie</ulink> to be set per domain.
 200           Cookies are often used to track users across the web, particularly third-party cookies (which are completely blocked in Privacy Browser).
 201           They are also used as a security mechanism on websites where you log in to identify it is you as you browse from page to page on a site.
 202         </para>
 203
 204         <para>
 205           Durable cookies are shared with all tabs that are opened after they are made durable and are preserved even when Privacy Browser is restarted.
 206           This allows users to stay logged in to sites of their choosing. No cookies are durable by default. Making a cookie durable requires specific user interaction.
 207         </para>
 208
 209         <para>
 210           All other cookies are specific to the tab where they are created and are destroyed when the tab is closed.
 211         </para>
 212       </sect2>
 213
 214       <!-- DOM storage. -->
 215       <sect2 id="dom-storage">
 216         <title>DOM storage</title>
 217
 218         <para>
 219           <ulink url="https://en.wikipedia.org/wiki/Web_storage">DOM (Document Object Model) storage</ulink>, also knows as web storage, allows web pages to store information on a client device.
 220           The storage capacity is larger than for cookies and the data is not automatically sent in the headers with every HTTP request.
 221           In Privacy Browser, each website is allowed to store a <ulink url="https://arty.name/localstorage.html">5 MB of data</ulink> in DOM storage.
 222           DOM storage requires JavaScript to function, and, in addition, requires an extra toggle to be enabled.
 223           In Privacy Browser, DOM storage is limited to the tab where it is created and is destroyed when the tab is closed.
 224         </para>
 225       </sect2>
 226
 227       <!-- IndexedDB. -->
 228       <sect2 id="indexeddb">
 229         <title>IndexedDB</title>
 230
 231         <para>
 232           <ulink url="https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API">IndexedDB</ulink>
 233           provides web pages with a local database where they can store “significant amounts of structured data”.
 234           There is disagreement on the internet about the maximum size of an IndexedDB database, probably because the various rendering engines keep changing their mind.
 235           But it is usually listed at somewhere between 20% and 80% of <emphasis>your entire hard drive</emphasis> with each individual domain limited to some segment of that.
 236           IndexedDB requires JavaScript to function.
 237           In Privacy Browser, this database is limited to the tab where it is created and is destroyed when the tab is closed.
 238         </para>
 239       </sect2>
 240
 241       <!-- Service Workers. -->
 242       <sect2 id="service-workers">
 243         <title>Service Workers</title>
 244
 245         <para>
 246           <ulink url="https://developer.chrome.com/docs/workbox/service-worker-overview/">Service workers</ulink> are offline JavaScript proxies of a website. They have their own cache that is usually hidden and hard to clear.
 247           They were designed by people who want the web browser to become the operating system and run full “apps”.
 248           In Privacy Browser, service workers are limited to the tab where they are created and are destroyed when the tab is closed.
 249         </para>
 250       </sect2>
 251
 252       <!-- Filesystem API. -->
 253       <sect2 id="filesystem-api">
 254         <title>Filesystem API</title>
 255
 256         <para>
 257           The <ulink url="https://developer.chrome.com/articles/file-system-access/">filesystem API</ulink> grants the browser direct access to the files on your system.
 258           Like service workers, the filesystem API is a summarily bad idea thought up by those who want the browser to become an operating system.
 259           Even when JavaScript and local storage are enabled, the filesystem API does not work in Privacy Browser.
 260         </para>
 261       </sect2>
 262     </sect1>
 263
 264     <!-- User Agent. -->
 265     <sect1 id="user-agent">
 266       <title>User Agent</title>
 267
 268       <para>
 269         The user agent is a text string that is sent as part of every HTTP header that identifies the browser to the web server.
 270         Privacy Browser's default user agent is <code>PrivacyBrowser/1.0</code>.
 271         Qt WebEngine 5.15.12’s default user agent is <code>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) QtWebEngine/5.15.12 Chrome/87.0.4280.144 Safari/537.36</code>.
 272       </para>
 273
 274       <para>
 275         Over the years user agents have become quite lengthy,
 276         partially because they tend to include a <ulink url="https://webaim.org/blog/user-agent-string-history/">brief history of the internet</ulink>.
 277         In the modern world they serve almost no good purpose, but some web developers still think they need them so they can send different version of their website to different browsers.
 278         Some servers <ulink url="https://www.stoutner.com/user-agent-problems/">refuse to function correctly</ulink> if they don't like the user agent that is sent.
 279       </para>
 280
 281       <para>
 282         At some point in the future Privacy Browser will send no user agent by default.
 283         Not only is that currently impossible because the Qt WebEngine doesn't allow you to not send a user agent (I will probably have to fork it to enable that functionality),
 284         but even web servers that don't care what the user agent is often refuse to send an answer if there is no user agent at all.
 285         Getting rid of this relic of the internet is going to take some time and a retraining of common expectations.
 286       </para>
 287     </sect1>
 288
 289     <!-- Domain Settings. -->
 290     <sect1 id="domain-settings">
 291       <title>Domain Settings</title>
 292
 293       <para>
 294         Domain setting make it easy to automatically change JavaScript, local storage, user agent, and other settings when the domain changes.
 295         Domain settings for the current domain can be accessed through the domain settings button at the far right of the URL line edit.
 296         Domain settings for all domains can be accessed through the settings menu. When domain settings are active, the URL line edit will have a green background.
 297       </para>
 298     </sect1>
 299   </chapter>
 300
 301   <!-- Commands. -->
 302   <chapter id="commands">
 303     <title>Command Reference</title>
 304
 305     <!-- Main Window. -->
 306     <sect1 id="main-window">
 307       <title>The main &privacybrowser; window</title>
 308
 309       <!-- File Menu. -->
 310       <sect2>
 311         <title>The File Menu</title>
 312
 313         <para>
 314           <variablelist>
 315             <!-- File > New Tab. -->
 316             <varlistentry id="file-new-tab">
 317               <term>
 318                 <menuchoice>
 319                   <shortcut>
 320                     <keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo>
 321                   </shortcut>
 322                   <guimenu>File</guimenu>
 323                   <guimenuitem>New Tab</guimenuitem>
 324                 </menuchoice>
 325               </term>
 326
 327               <listitem>
 328                 <para>
 329                   <action>Create a new tab.</action>
 330                 </para>
 331               </listitem>
 332             </varlistentry>
 333
 334             <!-- File > New Window. -->
 335             <varlistentry id="file-new-window">
 336               <term>
 337                 <menuchoice>
 338                   <shortcut>
 339                     <keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
 340                   </shortcut>
 341                   <guimenu>File</guimenu>
 342                   <guimenuitem>New Window</guimenuitem>
 343                 </menuchoice>
 344               </term>
 345
 346               <listitem>
 347                 <para>
 348                   <action>Create a new window.</action>
 349                 </para>
 350               </listitem>
 351             </varlistentry>
 352
 353             <varlistentry  id="file-save">
 354               <term>
 355                 <menuchoice>
 356                   <shortcut>
 357                     <keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
 358                   </shortcut>
 359                   <guimenu>File</guimenu>
 360                   <guimenuitem>Save</guimenuitem>
 361                 </menuchoice>
 362               </term>
 363
 364               <listitem>
 365                 <para>
 366                   <action>Saves the document</action>
 367                 </para>
 368               </listitem>
 369             </varlistentry>
 370
 371             <varlistentry  id="file-quit">
 372               <term>
 373                 <menuchoice>
 374                   <shortcut>
 375                     <keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
 376                   </shortcut>
 377                   <guimenu>File</guimenu>
 378                   <guimenuitem>Quit</guimenuitem>
 379                 </menuchoice>
 380               </term>
 381
 382               <listitem>
 383                 <para>
 384                   <action>Quits</action> &privacybrowser;
 385                 </para>
 386               </listitem>
 387             </varlistentry>
 388           </variablelist>
 389         </para>
 390       </sect2>
 391
 392       <!-- Examples how to use the common menus Settings and Help -->
 393       <sect2 id="settings-help-menu">
 394         <title>The Settings and Help Menu</title>
 395
 396         <para>
 397           &privacybrowser; has the common &kde; <guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
 398           menu items, for more information read the sections about the <ulink url="help:/fundamentals/ui.html#menus-settings"
 399           >Settings Menu</ulink> and <ulink url="help:/fundamentals/ui.html#menus-help">Help Menu</ulink>
 400           of the &kde; Fundamentals.
 401         </para>
 402       </sect2>
 403
 404       <sect2 id="help-menu1">
 405         <title>The Help Menu</title>
 406
 407         <para>
 408           &privacybrowser; has the common &kde; <guimenu>Help</guimenu> menu item, for more information read the section
 409           about the <ulink url="help:/fundamentals/ui.html#menus-help">Help Menu</ulink> of the &kde; Fundamentals.
 410         </para>
 411       </sect2>
 412
 413       <sect2 id="menu-commands">
 414         <title>Menu Items</title>
 415
 416         <para>
 417           Apart from the common &kde; menus described in the <ulink url="help:/fundamentals/ui.html#menus">Menu</ulink>
 418           chapter of the &kde; Fundamentals documentation &privacybrowser; has these application specific menu entries:
 419         </para>
 420       </sect2>
 421
 422       <sect2 id="help-menu2">
 423         <title>The Help Menu</title>
 424
 425         <para>
 426           &privacybrowser; has a default &kde; <guimenu>Help</guimenu> menu as described in the
 427           <ulink url="help:/fundamentals/ui.html#menus-help">&kde; Fundamentals</ulink>
 428           with two additional entries:
 429         </para>
 430       </sect2>
 431     </sect1>
 432   </chapter>
 433
 434   <!-- FAQ. -->
 435   <chapter id="faq">
 436     <title>Questions and Answers</title>
 437
 438     <!-- (OPTIONAL but recommended) This chapter should include all of the silly
 439     (and not-so-silly) newbie questions that fill up your mailbox. This chapter
 440     should be reserved for BRIEF questions and answers! If one question uses more
 441     than a page or so then it should probably be part of the
 442     "Using this Application" chapter instead. You should use links to
 443     cross-reference questions to the parts of your documentation that answer them.
 444     This is also a great place to provide pointers to other FAQ's if your users
 445     must do some complicated configuration on other programs in order for your
 446     application work. -->
 447
 448     <qandaset id="faqlist">
 449       <qandaentry>
 450         <question>
 451           <para>My Mouse doesn't work. How do I quit &privacybrowser;?</para>
 452         </question>
 453
 454         <answer>
 455           <para>You silly goose! Check out the <link linkend="commands">Commands Section</link> for the answer.</para>
 456         </answer>
 457       </qandaentry>
 458
 459       <qandaentry>
 460         <question>
 461           <para>Why can I not twiddle my documents?</para>
 462         </question>
 463
 464         <answer>
 465           <para>
 466             You can only twiddle your documents if you have the foobar.lib installed.
 467           </para>
 468         </answer>
 469       </qandaentry>
 470     </qandaset>
 471   </chapter>
 472
 473   <!-- Credits. -->
 474   <chapter id="credits">
 475     <title>Credits and License</title>
 476
 477     <para>
 478       Program copyright 2016-2017,2021-2023 Soren Stoutner <ulink url="mailto:soren@stoutner.com">soren@stoutner.com</ulink>.
 479     </para>
 480
 481     <para>
 482       Translators:
 483       <itemizedlist>
 484         <listitem><para>Translations will be added in a future release.</para></listitem>
 485       </itemizedlist>
 486     </para>
 487
 488     <!-- The program license. -->
 489     &underGPL;
 490
 491     <para>
 492       Documentation copyright 2023 Soren Stoutner <ulink url="mailto:soren@stoutner.com">soren@stoutner.com</ulink>.
 493     </para>
 494
 495     <!-- The documentation license. -->
 496     &underFDL;
 497   </chapter>
 498 </book>