From ae2a713f26fd58f397aaf93242f24c85dee98a2b Mon Sep 17 00:00:00 2001 From: Aqua-sama Date: Wed, 3 Oct 2018 16:48:26 +0200 Subject: Convert documentation into asciidoc from markdown --- BUGS.md | 54 ---------------- BUILDING.md | 81 ------------------------ QUICKSTART.md | 59 ------------------ README.md | 31 ---------- Readme.asciidoc | 48 +++++++++++++++ doc/Breakpad.md | 14 ----- doc/Bugs.asciidoc | 54 ++++++++++++++++ doc/Building.asciidoc | 81 ++++++++++++++++++++++++ doc/Building/Breakpad.asciidoc | 20 ++++++ doc/Building/QtWebEngine.md | 7 --- doc/Building/Windows.asciidoc | 26 ++++++++ doc/Building/smolbote.md | 30 --------- doc/Development.asciidoc | 42 +++++++++++++ doc/Development/ManPage.asciidoc | 7 +++ doc/Development/RepositoryCommands.asciidoc | 6 ++ doc/Development/Translating.asciidoc | 16 +++++ doc/Development/Updater.asciidoc | 25 ++++++++ doc/ManPage.md | 15 ----- doc/RepositoryCommands.md | 16 ----- doc/Translating.md | 24 -------- doc/Updater.md | 25 -------- doc/UrlFilter.md | 95 ----------------------------- doc/Usage.asciidoc | 21 +++++++ doc/Usage/CommandLine.asciidoc | 8 +++ doc/Usage/CommandLine.md | 12 ---- doc/Usage/Configuration.asciidoc | 56 +++++++++++++++++ doc/Usage/Configuration.md | 53 ---------------- doc/Usage/Profile.asciidoc | 31 ++++++++++ doc/Usage/Profile.md | 17 ------ doc/Usage/Session.md | 30 --------- doc/smolbote.7.asciidoc | 35 +++++++++++ linux/makepkg/PKGBUILD | 21 +++---- linux/man/smolbote.md | 75 ----------------------- 33 files changed, 486 insertions(+), 649 deletions(-) delete mode 100644 BUGS.md delete mode 100644 BUILDING.md delete mode 100644 QUICKSTART.md delete mode 100644 README.md create mode 100644 Readme.asciidoc delete mode 100644 doc/Breakpad.md create mode 100644 doc/Bugs.asciidoc create mode 100644 doc/Building.asciidoc create mode 100644 doc/Building/Breakpad.asciidoc delete mode 100644 doc/Building/QtWebEngine.md create mode 100644 doc/Building/Windows.asciidoc delete mode 100644 doc/Building/smolbote.md create mode 100644 doc/Development.asciidoc create mode 100644 doc/Development/ManPage.asciidoc create mode 100644 doc/Development/RepositoryCommands.asciidoc create mode 100644 doc/Development/Translating.asciidoc create mode 100644 doc/Development/Updater.asciidoc delete mode 100644 doc/ManPage.md delete mode 100644 doc/RepositoryCommands.md delete mode 100644 doc/Translating.md delete mode 100644 doc/Updater.md delete mode 100644 doc/UrlFilter.md create mode 100644 doc/Usage.asciidoc create mode 100644 doc/Usage/CommandLine.asciidoc delete mode 100644 doc/Usage/CommandLine.md create mode 100644 doc/Usage/Configuration.asciidoc delete mode 100644 doc/Usage/Configuration.md create mode 100644 doc/Usage/Profile.asciidoc delete mode 100644 doc/Usage/Profile.md delete mode 100644 doc/Usage/Session.md create mode 100644 doc/smolbote.7.asciidoc delete mode 100644 linux/man/smolbote.md diff --git a/BUGS.md b/BUGS.md deleted file mode 100644 index a3a5153..0000000 --- a/BUGS.md +++ /dev/null @@ -1,54 +0,0 @@ -## Reporting bugs - -### What to include -A bug report should contain these 4 things: - -#### Environment -This includes program version; operating system used; version of Qt or other -libraries; any relevant information if you built from source. - -#### Steps to reproduce -Give detailed steps on how to reproduce the problem. Start from the beginning, -mention the actions involved, and be verbose. - -#### Expected result -It's important to include the result you were expecting, as it might differ -from the way the program was designed to work. - -#### Actual result -It is also important to include a good description of the buggy behaviour -itself as well, because it's possible that following your steps on a different -system doesn't reproduce the issue. - -Send bug reports to _aqua at iserlohn dash fortress dot net_. - -_Adapted from the guide in the texmate repository._ - -## Known bugs - -#### databases-incognito in home -https://bugreports.qt.io/browse/QTBUG-62957 - -#### loadFinished is not always emitted when loading is finished -https://bugreports.qt.io/browse/QTBUG-65223 - -#### QWebEngineView setUrl()/load() methods in some case divide page in two parts -https://bugreports.qt.io/browse/QTBUG-68224 - -Only affects Qt 5.11.0. Set __QTBUG_68224_WORKAROUND__. - -### Wayland bugs - -#### mainwindow.maximized doesn't work -setWindowState(Qt::WindowMaximized) has no effect on KDE/Wayland: -https://community.kde.org/Plasma/Wayland_Showstoppers - -### Windows bugs - -#### stdout and stderr -Starting the application with some command-line options (like --version, ---help, etc) causes the application to 'stall' on exit. - -Starting the application from the command prompt returns after launch, but -continues outputting stdout and stderr to it. - diff --git a/BUILDING.md b/BUILDING.md deleted file mode 100644 index 105e7b4..0000000 --- a/BUILDING.md +++ /dev/null @@ -1,81 +0,0 @@ -## Requirements - -### [Qt](https://www.qt.io/) - - Version 5.11 - -Even though most of the browser might work with the last LTS Qt release, always -use an up-to-date version of QtWebEngine. Security fixes to Blink do _not_ get -backported. QtWebEngine can be built with older versions of Qt, if upgrading Qt -is not a possibility. - -### [boost](http://www.boost.org/) - - Version 1.66 - - Components: program_options - -### cmake - - Version 3.10 - -### Compiler - - C++17 support - - gcc 7+; clang 4+ - - Windows: only MSVC is supported due to QtWebEngine - -## Basic Installation -In short, the generic cmake build loop of 'cmake, make, make install' will -generate a makefile, build the program and install it. - -~~~ sh -# clone the repository -git clone https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git - -# generate makefile -mkdir build && cd build -cmake -DCMAKE_BUILD_TYPE=Release ../smolbote - -# make && make install -make -j4 -make install -~~~ - -## Configuring - -### vendor.cmake -vendor.cmake contains all settings but the build type. It can be used to easily -create a build profile. - -When changing vendor.cmake, make sure to have all values defined in the preset. - -### Compiler flags -cmake does not set any C++ flags by default, including no optimization flags. -You need to set these yourself if your build system doesn't set any either. - -On gcc/clang, no optimize flags are set by default, resulting in rather bloated -code being generated. Recommend setting at least -O2. MSVC has optimze flags -set by default. - -You can set the compiler using -DCMAKE_CXX_COMPILER=/path/to/c++. -You can set additional compiler flags using -DCMAKE_CXX_FLAGS. - -### Build type -Install paths are only set on Release builds. - -~~~sh --DCMAKE_BUILD_TYPE=Debug|Release -~~~ - -### Install prefix -Sets the install location prefix. -win32: Binary is written to bin/, and plugins to bin/plugins. -others: Binary will be written to bin/, and plugins to lib/smolbote/. - -~~~sh --DCMAKE_INSTALL_PREFIX=/usr/local -~~~ - -### Using libc++ -You can use libc++ over stdlibc++ by setting UseLibCpp to On. Requires clang. - -~~~ sh --DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DUseLibCpp=On -~~~ - diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index 0f65115..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,59 +0,0 @@ -## Principles - -### Simplicity -This should be a simple browser that only does its browsing job with as little -fuss as possible. This is not a platform. - -### Customizability -This browser should be usable with minimal configuration necessary. At the same -time, all functionality should be user-customizable. It is the user's -responsibility to ensure a stable working state when changing settings. - -This browser should be kept as platform-agnostic as possible, while learning -from and implementing the UNIX philosophy as applicable. - -### Pragmatic Freedom -Free software should serve the user, not impose unbreakable barriers for -ideological reasons. - -QtWebEngine allows the usage of third-party non-free codecs and non-free -plugins. This browser does not prevent you from doing so. It's up to you how -you exercise your freedom. - -## Keyboard shortcuts -- F4 to focus the address bar and type an address; F2 show its menu -- Ctrl + Left/Right - go back/forward -- Ctrl + T - new tab -- Ctrl + X - close tab -- Ctrl + O/P - previous tab/next tab -- Ctrl + Shift + O/P - move tab left/right -- Ctrl + B - show/hide bookmarks -- Ctrl + D - show/hide downloads - -## Subwindows -A subwindow is a multiple document interface window that contains a collection -of tabs and has a default profile. It can be minimized, resized, moved, -maximized, tiled (F9) and cascaded (F10) within the main window. - -- Ctrl + G - new subwindow -- Ctrl + W - close subwindow - -## Profiles -A Profile is a collection of settings, policies, scripts, cookies, cache and -history. Profiles can be used to isolate pages from each other. - -Each window has a default profile it uses when opening new tabs. This can be -changed from the window's menu. Additionally, tabs can have their profiles -individually changed from their context menu. - -Because profiles store all their data separately, you can log in into the same -site with a different account from each profile. However, links opened into new -tabs will still use the subwindow's default profile. For example, you can set a -profile to hold login information for a site, but all new tabs opened from that -site would still be using the default off-the-record profile. - -## Configuration files -Configuration is saved in: - -- on Linux, _~/.config/smolbote/_ - diff --git a/README.md b/README.md deleted file mode 100644 index ac735d1..0000000 --- a/README.md +++ /dev/null @@ -1,31 +0,0 @@ -## *smolbote?* -_It's yet another no-frills browser, poi!_ - -### What is this and why should I care? -smolbote is a [keep-it-simple][kiss-principle] free software web browser based -on Qt and QtWebEngine. - -This program is free software. You can use it as you see fit, study and modify -it, and share the program with or without modification, but providing the same -terms. - -For more information, and a list of dependancies, see [LICENSE.md][repo-license]. - -### What's up with the name?! -It's a small boat. It says poi. - -### Sounds dumb, how do I use it? -You make it yourself. - -It's a cmake-based project that depends on Qt and Boost, so cmake && make alone -should be sufficient to build from source. Some basic package scripts are -provided in the repository. - -Detailed [build instructions](/smolbote/building.html) also included. - -### It doesn't work, what now? -Drop me an email at _aqua at iserlohn dash fortress dot net_. - -[kiss-principle]: https://en.wikipedia.org/wiki/KISS_principle -[repo-license]: https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote/src/branch/master/LICENSE.md - diff --git a/Readme.asciidoc b/Readme.asciidoc new file mode 100644 index 0000000..2434561 --- /dev/null +++ b/Readme.asciidoc @@ -0,0 +1,48 @@ +== *smolbote?* +_It's yet another no-frills browser, poi!_ + +=== What is this and why should I care? +smolbote is a link:https://en.wikipedia.org/wiki/KISS_principle[keep-it-simple] +free software web browser based on Qt and QtWebEngine. + +==== Simplicity +This should be a simple browser that only does its browsing job with as little +fuss as possible. This is not a platform. + +==== Customizability +This browser should be usable with minimal configuration necessary. At the same +time, all functionality should be user-customizable. It is the user's +responsibility to ensure a stable working state when changing settings. + +This browser should be kept as platform-agnostic as possible, while learning +from and implementing the UNIX philosophy as applicable. + +==== Pragmatic Freedom +Free software should serve the user, not impose unbreakable barriers for +ideological reasons. + +QtWebEngine allows the usage of third-party non-free codecs and non-free +plugins. This browser does not prevent you from doing so. It's up to you how +you exercise your freedom. + +This program is free software. You can use it as you see fit, study and modify +it, and share the program with or without modification, but providing the same +terms. + +For more information, and a list of dependancies, see the license information +included in the repository. + +=== What's up with the name?! +It's a small boat. It says poi. + +=== Sounds dumb, how do I use it? +You make it yourself. + +It's a cmake-based project that depends on Qt and Boost, so cmake && make alone +should be sufficient to build from source. Some basic package scripts are +provided in the repository. + +Detailed link:/smolbote/building.html[build instructions] also included. + +=== It doesn't work, what now? +Drop me an email at _aqua at iserlohn dash fortress dot net_. diff --git a/doc/Breakpad.md b/doc/Breakpad.md deleted file mode 100644 index d1056a5..0000000 --- a/doc/Breakpad.md +++ /dev/null @@ -1,14 +0,0 @@ -## Producing symbols - -~~~sh -tools/linux/dump_syms/dump_syms ./poi > poi.sym -head -n1 poi.sym -mkdir -p ./symbols/poi/ -mv poi.sym ./symbols/poi/ -~~~ - -## Processing minidump - -~~~sh -processor/minidump_stackwalk minidump.dmp ./symbols -~~~ diff --git a/doc/Bugs.asciidoc b/doc/Bugs.asciidoc new file mode 100644 index 0000000..057fae9 --- /dev/null +++ b/doc/Bugs.asciidoc @@ -0,0 +1,54 @@ +== Reporting bugs + +=== What to include +A bug report should contain these 4 things: + +==== Environment +This includes program version; operating system used; version of Qt or other +libraries; any relevant information if you built from source. + +==== Steps to reproduce +Give detailed steps on how to reproduce the problem. Start from the beginning, +mention the actions involved, and be verbose. + +==== Expected result +It's important to include the result you were expecting, as it might differ +from the way the program was designed to work. + +==== Actual result +It is also important to include a good description of the buggy behaviour +itself as well, because it's possible that following your steps on a different +system doesn't reproduce the issue. + +Send bug reports to _aqua at iserlohn dash fortress dot net_. + +_Adapted from the guide in the texmate repository._ + +== Known bugs + +=== databases-incognito in home +https://bugreports.qt.io/browse/QTBUG-62957 + +=== loadFinished is not always emitted when loading is finished +https://bugreports.qt.io/browse/QTBUG-65223 + +=== QWebEngineView setUrl()/load() methods in some case divide page in two parts +https://bugreports.qt.io/browse/QTBUG-68224 + +Only affects Qt 5.11.0. Set __QTBUG_68224_WORKAROUND__. + +=== Wayland bugs + +=== mainwindow.maximized doesn't work +setWindowState(Qt::WindowMaximized) has no effect on KDE/Wayland: +https://community.kde.org/Plasma/Wayland_Showstoppers + +=== Windows bugs + +=== stdout and stderr +Starting the application with some command-line options (like --version, +--help, etc) causes the application to 'stall' on exit. + +Starting the application from the command prompt returns after launch, but +continues outputting stdout and stderr to it. + diff --git a/doc/Building.asciidoc b/doc/Building.asciidoc new file mode 100644 index 0000000..47eb0bb --- /dev/null +++ b/doc/Building.asciidoc @@ -0,0 +1,81 @@ +== Requirements + +[cols="1,1,3"] +|=== +|Name |Version |Notes + +| link:https://www.qt.io/[Qt] +| 5.11.1 or later +| QtWebEngine should be buildable with older versions of Qt. Please use the + latest version. + +| link:http://www.boost.org/[boost] +| Version 1.66 +| Components: program_options + +| cmake +| Version 3.10 +| Anything supporting modern cmake + +| Compiler +| C++17 support +| gcc 7+; clang 4+; on Windows only MSVC is supported due to QtWebEngine + +| asciidoc +| +| Only for building manpage + +|=== + +== Building from source +In short, the generic cmake build loop of 'cmake, make, make install' will +generate a makefile, build the program and install it. + +[source, sh] +---- +# clone the repository +git clone https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git smolbote.git +cd smolbote.git +git submodule init +git submodule update 3rd-party/SingleApplication/SingleApplication.git + + +# generate makefile +mkdir build && cd build +cmake -DCMAKE_BUILD_TYPE=Release .. + +# make && make install +make -j4 +make install +---- + +=== vendor.cmake +vendor.cmake contains various settings to customize the way in which the program +functions. The available options and their values may change with revisions. +When changing vendor.cmake, make sure to have all values defined in the preset. + + -DVENDOR=path/to/custom-vendor.cmake + +=== Compiler flags +cmake does not set any C++ flags by default, including no optimization flags. +You need to set these yourself if your build system doesn't set any either. + +- On gcc/clang, no optimize flags are set by default, setting at least -O2 is +recommended; check vendor.cmake. + +=== Install prefix (`-DCMAKE_INSTALL_PREFIX`) +Sets the install location prefix. Install targets are only set on Release builds. + +- windows: Binary is written to bin/, and plugins to bin/plugins. +- others: Binary will be written to bin/, and plugins to lib/smolbote/. + +=== Using libc++ +You can use libc++ over stdlibc++ by setting UseLibCpp to On. Requires clang. + + -DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DUseLibCpp=On + +// Additional items + +include::Building/Breakpad.asciidoc[] + +include::Building/Windows.asciidoc[] diff --git a/doc/Building/Breakpad.asciidoc b/doc/Building/Breakpad.asciidoc new file mode 100644 index 0000000..9cc561e --- /dev/null +++ b/doc/Building/Breakpad.asciidoc @@ -0,0 +1,20 @@ +== Breakpad + +=== Enabling breakpad +Use `-DBreakpad=On` cmake option. This requires either Breakpad be installed as +a package, or that it is already built. Check 3rd-party/breakpad/CMakeLists.txt. + +=== Producing symbols +[source, sh] +---- +tools/linux/dump_syms/dump_syms ./poi > poi.sym +head -n1 poi.sym +mkdir -p ./symbols/poi/ +mv poi.sym ./symbols/poi/ +---- + +=== Processing minidump +[source, sh] +---- +processor/minidump_stackwalk minidump.dmp ./symbols +---- diff --git a/doc/Building/QtWebEngine.md b/doc/Building/QtWebEngine.md deleted file mode 100644 index 7d72dd6..0000000 --- a/doc/Building/QtWebEngine.md +++ /dev/null @@ -1,7 +0,0 @@ -- download qtwebengine - -~~~sh -mkdir build && cd build -qmake ../qtwebengine-version-source/qtwebengine.pro -make -~~~ diff --git a/doc/Building/Windows.asciidoc b/doc/Building/Windows.asciidoc new file mode 100644 index 0000000..4c1fc20 --- /dev/null +++ b/doc/Building/Windows.asciidoc @@ -0,0 +1,26 @@ +== Building on Windows +[source, bat] +---- +set INSTALL_DIR="C:\projects\smolbote-install" +mkdir %INSTALL_DIR% + +mkdir C:\projects\smolbote-build +cd C:\projects\smolbote-build + +set QT="C:\Qt\5.11\msvc2017_64" +set BOOST_ROOT="C:\Libraries\boost_1_66_0" +set BOOST_LIBDIR="C:\Libraries\boost_1_66_0\lib64-msvc-14.1" + +cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_BUILD_TYPE=Release + -DCMAKE_INSTALL_PREFIX=%INSTALL_DIR% + -DCMAKE_PREFIX_PATH=%QT%;%BOOST_ROOT% + -DBOOST_ROOT=%BOOST_ROOT% -DBOOST_LIBRARYDIR=%BOOST_LIBDIR% -DBoost_USE_STATIC_LIBS=On + C:\projects\smolbote + +cmake --build . --target poi --config Release +cmake --build . --target install --config Release +cd %INSTALL_DIR% +C:\Qt\5.11\msvc2017_64\bin\windeployqt.exe bin\poi.exe + +7z a C:\projects\smolbote\build.7z %INSTALL_DIR% +---- diff --git a/doc/Building/smolbote.md b/doc/Building/smolbote.md deleted file mode 100644 index e40132c..0000000 --- a/doc/Building/smolbote.md +++ /dev/null @@ -1,30 +0,0 @@ -## Customizing -Set through vendor.cmake. - -### Configuration defaults - -### Version information -Building without git metadata requires the version be set in vendor.cmake. - - -## Building on Windows - -~~~sh -set INSTALL_DIR="C:\projects\smolbote-install" -mkdir %INSTALL_DIR% - -mkdir C:\projects\smolbote-build -cd C:\projects\smolbote-build - -set QT="C:\Qt\5.11.0\msvc2017_64" -set BOOST_ROOT="C:\Libraries\boost_1_66_0" -set BOOST_LIBDIR="C:\Libraries\boost_1_66_0\lib64-msvc-14.1" -cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=%INSTALL_DIR% -DCMAKE_PREFIX_PATH=%QT%;%BOOST_ROOT% -DBOOST_ROOT=%BOOST_ROOT% -DBOOST_LIBRARYDIR=%BOOST_LIBDIR% -DBoost_USE_STATIC_LIBS=On C:\projects\smolbote-hg -cmake --build . --target poi --config Release -cmake --build . --target install --config Release -cd %INSTALL_DIR% -C:\Qt\5.10.1\msvc2017_64\bin\windeployqt.exe bin\poi.exe - -7z a C:\projects\smolbote-hg\smolbote.7z %INSTALL_DIR% -~~~ - diff --git a/doc/Development.asciidoc b/doc/Development.asciidoc new file mode 100644 index 0000000..41c832d --- /dev/null +++ b/doc/Development.asciidoc @@ -0,0 +1,42 @@ +== Guidelines + +=== Qt +* Check pointers with Q_CHECK_PTR before using or returning them. +* Avoid using connect SIGNAL and SLOT. Instead use &Class::method. This way, connects are checked during the compile, + not at runtime. +* Where possible, use QVector over QList: http://lists.qt-project.org/pipermail/development/2017-March/029040.html + +=== clazy +You can use [clazy](https://github.com/KDE/clazy) to check Qt semantics. +Requires clang. + +To set check levels, set the CLAZY_CHECKS environment variable to 'level0,level1', etc. + +==== Setting up in QtCreator +The simplest way to set it up is to use _clazy_ instead of _clang_. + +1. Go to Tools » Options » Build & Run » Compilers +2. Clone the clang compiler of your choice +3. Set _Compiler path_ to _/usr/bin/clazy_ + +== Licensing +Smolbote is licensed under GPLv3 _only_. Your code needs to be compatible with it, and have a license header in the +style used by the project. + +- No self-updating "-or-later" licensing. + +=== SPDX-License-Identifier +A full list of license identifiers can be found on [the SPDX website](https://spdx.org/licenses/). + +== Style +There is a clang-format style in .clang-format. + +== Format patch for email + +~~~ sh +hg export -r startcommit[:endcommit] -o patchname.txt +~~~ + +to export the from _startcommit_ until tip or optionally _endcommit_. + +Email the patch file to _aqua at iserlohn dash fortress dot net_. diff --git a/doc/Development/ManPage.asciidoc b/doc/Development/ManPage.asciidoc new file mode 100644 index 0000000..4d8c015 --- /dev/null +++ b/doc/Development/ManPage.asciidoc @@ -0,0 +1,7 @@ +== manpage + +=== Generating manpage +[code, sh] +---- +a2x --format=manpage doc/smolbote.7.asciidoc +---- diff --git a/doc/Development/RepositoryCommands.asciidoc b/doc/Development/RepositoryCommands.asciidoc new file mode 100644 index 0000000..13e2f8e --- /dev/null +++ b/doc/Development/RepositoryCommands.asciidoc @@ -0,0 +1,6 @@ +== Repository commands +[code, sh] +---- +# listing branches +curl --request GET --url https://neueland.iserlohn-fortress.net/gitea/api/v1/repos/aqua/smolbote/branches +---- diff --git a/doc/Development/Translating.asciidoc b/doc/Development/Translating.asciidoc new file mode 100644 index 0000000..f79fa56 --- /dev/null +++ b/doc/Development/Translating.asciidoc @@ -0,0 +1,16 @@ +== Translating +[code, sh] +---- +# generating translations +lupdate src/ lib/ -ts lang/.ts + +# updating translations +lupdate src/ lib/ -no-obsolete -ts lang/.ts + +# generate lang/.qm +lrelease lang/.ts +---- + +=== Using translations + --browser.locale # set Qt translation; ex. de + --browser.translation # set translation file; ex. /home/user/.config/smolbote/lang/custom-translate.qm diff --git a/doc/Development/Updater.asciidoc b/doc/Development/Updater.asciidoc new file mode 100644 index 0000000..a039318 --- /dev/null +++ b/doc/Development/Updater.asciidoc @@ -0,0 +1,25 @@ +== Updater + +=== Creating manifest +[code, sh] +---- +find windows/ -type f | xargs sha512sum | sed 's/windows\///' > windows-sha512.txt +find windows/ -type d -exec chmod 755 {} + +---- + +=== Building + +You can build for the current system using: +[code, sh] +---- +go build +# remove debug information +strip updater +---- + +You can also cross-compile for other systems by setting GOOS and GOARCH. For a +list of supported platforms, use `go tool dist list`. +[code, sh] +---- +GOOS=windows GOARCH=amd64 go build +---- diff --git a/doc/ManPage.md b/doc/ManPage.md deleted file mode 100644 index d3f7c74..0000000 --- a/doc/ManPage.md +++ /dev/null @@ -1,15 +0,0 @@ -The manpage format is ridiculous, so they get generated from markdown (which is more sane in comparison) - -### with ronn -~~~sh -## install -gem install --user-install ronn -## generate -ronn smolbote.7.ronn -~~~ - -### with go-md2man -~~~sh -go-md2man -in smolbote.md -out smolbote.7 -~~~ - diff --git a/doc/RepositoryCommands.md b/doc/RepositoryCommands.md deleted file mode 100644 index 3725b6e..0000000 --- a/doc/RepositoryCommands.md +++ /dev/null @@ -1,16 +0,0 @@ -## git commit template -You can set the commit template with: - -~~~sh -git config commit.template=.git-commit-template -~~~ - -## gitea api -A full list of the api can be found on https://try.gitea.io/api/swagger. - -## Listing branches - -~~~sh -curl --request GET --url https://neueland.iserlohn-fortress.net/gitea/api/v1/repos/aqua/smolbote/branches -~~~ - diff --git a/doc/Translating.md b/doc/Translating.md deleted file mode 100644 index fc7bad3..0000000 --- a/doc/Translating.md +++ /dev/null @@ -1,24 +0,0 @@ -## Generating translations - -~~~sh -lupdate src/ lib/ -ts lang/.ts -~~~ - -### Updating translations -~~~sh -lupdate src/ lib/ -no-obsolete -ts lang/.ts -~~~ - -## Baking translation -This generates lang/.qm - -~~~sh -lrelease lang/.ts -~~~ - -## Using translations - -~~~sh ---browser.locale # set Qt translation; ex. de ---browser.translation # set translation file; ex. /home/user/.config/smolbote/lang/custom-translate.qm -~~~ diff --git a/doc/Updater.md b/doc/Updater.md deleted file mode 100644 index 899240f..0000000 --- a/doc/Updater.md +++ /dev/null @@ -1,25 +0,0 @@ -## Updater - -### Manifest -~~~sh -find windows/ -type f | xargs sha512sum | sed 's/windows\///' > windows-sha512.txt -find windows/ -type d -exec chmod 755 {} + -~~~ - -### Building - -You can build for the current system using: -~~~sh -go build -~~~ - -You can also cross-compile for other systems by setting GOOS and GOARCH. For a -list of supported platforms, use `go tool dist list`. -~~~sh -GOOS=windows GOARCH=amd64 go build -~~~ - -#### Removing debug information -~~~sh -strip updater -~~~ diff --git a/doc/UrlFilter.md b/doc/UrlFilter.md deleted file mode 100644 index b521228..0000000 --- a/doc/UrlFilter.md +++ /dev/null @@ -1,95 +0,0 @@ -## FilterDomain -Filter Domains are groups of domains that can point to one or more filter -rules. - -### Types -There are 4 Filter Domain types: -- AllowOnDomains - only match specified domains -- BlockOnDomains - match all but specified domains -- AllowOnAllDomains - match all domains -- BlockOnAllDomains - match no domains - -### JSON - { - "type" : "AllowOnDomains", - "domains" : [ "example.com", "test.example.com" ], - "rules" : [] - } - -## FilterRule -Filter rules contain information on how a request should be modified. - -### Action -- Whitelist - allow this request -- Blacklist - block this request -- Redirect - redirect this request -- SetHeader - apply a list of headers - -### Match Type -- "regexp" -- "contains" -- "endswith" -- if none is specified, all URLs are matched - -### JSON -Allow all URLs that contain "waifu.png" - { - "action" : "Whitelist" - "contains" : "waifu.png" - } - -Block specific URL - { - "action" : "Blacklist" - "equals" : "example.com/annoying-ad/masquerade/waifu.png" - } - -Block all URLs that contain "banner.gif" - { - "action" : "Blacklist", - "contains" : "banner.gif" - } - -Redirect URLs containing "ads/annoying-spam.gif" to "waifu.tld/waifu.gif" - { - "action" : "Redirect" - "contains" : "ads/annoying-spam.gif" - "url" : "waifu.tld/waifu.gif" - } - -Set some headers - { - "action" : "SetHeader" - "headers" : [ "DNT:1" ] - } - -## QWebEngineUrlRequestInterceptor - -All network requests pass through the request interceptor. It gives the -following information: - -- firstPartyUrl - the page on which the request is made -- requestUrl - the url of the request -- requestMethod -- resourceType -- navigationType - -And provides the following methods: - -- block (bool shouldBlock) - can block the request -- redirect (const QUrl) - can redirect the requestUrl -- setHttpHeader - can set HTTP headers (such as user agent and do not track) - -### Example -This is a sample request made when loading DuckDuckGo: - - firstPartyUrl=https://duckduckgo.com/ - requestUrl=https://duckduckgo.com/o1635.css - -## How the filter works -When a requst comes in, the interceptor extracts the host of the request and -matches it against the list of FilterDomains. - - firstPartyHost=duckduckgo.com - requestHost=duckduckgo.com - diff --git a/doc/Usage.asciidoc b/doc/Usage.asciidoc new file mode 100644 index 0000000..ee2cc20 --- /dev/null +++ b/doc/Usage.asciidoc @@ -0,0 +1,21 @@ +== Keyboard shortcuts +- F4 to focus the address bar and type an address; F2 show its menu +- Ctrl + Left/Right - go back/forward +- Ctrl + T - new tab +- Ctrl + X - close tab +- Ctrl + O/P - previous tab/next tab +- Ctrl + Shift + O/P - move tab left/right +- Ctrl + B - show/hide bookmarks +- Ctrl + D - show/hide downloads + +== Subwindows +A subwindow is a multiple document interface window that contains a collection +of tabs and has a default profile. It can be minimized, resized, moved, +maximized, tiled (F9) and cascaded (F10) within the main window. + +- Ctrl + G - new subwindow +- Ctrl + W - close subwindow + +include::Usage/Profile.asciidoc[] + +include::Usage/Configuration.asciidoc[] diff --git a/doc/Usage/CommandLine.asciidoc b/doc/Usage/CommandLine.asciidoc new file mode 100644 index 0000000..a21b7c2 --- /dev/null +++ b/doc/Usage/CommandLine.asciidoc @@ -0,0 +1,8 @@ +== Command-line Options + +=== General +* `-h`, `--help`: Display this help. +* `-v`, `--version`: Display version information. +* `--build`: Display build branch and commit. +* `-c`, `--config`: Set configuration file. +* `--no-remote`: Don't check for other instances when starting. diff --git a/doc/Usage/CommandLine.md b/doc/Usage/CommandLine.md deleted file mode 100644 index 1c532ce..0000000 --- a/doc/Usage/CommandLine.md +++ /dev/null @@ -1,12 +0,0 @@ -## Command-line options - -### General -* `-h`, `--help`: Display this help. -* `-v`, `--version`: Display version information. -* `--build`: Display build branch and commit. -* `-c`, `--config`: Set configuration file. -* `--no-remote`: Don't check for other instances when starting. - -### Tweaking configuration -You can overwrite options at runtime using the option path as a command line -parameter. diff --git a/doc/Usage/Configuration.asciidoc b/doc/Usage/Configuration.asciidoc new file mode 100644 index 0000000..44e6b92 --- /dev/null +++ b/doc/Usage/Configuration.asciidoc @@ -0,0 +1,56 @@ +== Configuration + +The Configuration is loaded from .config/smolbote/smolbote.cfg. Most +settings are only loaded on launch. + +For a full list of settings, check '--help'. + +You can overwrite options at runtime using the option path as a command line +parameter. + +- Browser (group: browser) + +- Main Window (group: mainwindow) +A main window contains one or more subwindows. + +- Subwindow (group: window) +A subwindow contains multiple tabs and functions similarly to a tab group. + +- Navigation bar (group: navigation) +The navigation bar is the toolbar that holds the history, reload and home +buttons, as well as the address bar. It can be made movable through the +navigation.movable option. + +- Address bar (group: addressbar) + +- Filter (group: filter) + +- Plugins (group: plugins) +Plugins a way of extending smolbote's functionality using the Qt plugin system. +They are not to be confused with NPAPI/PPAPI or WebExtension plugins. + +To enable a plugin either copy it or symlink it in the plugins.path location, +or set its absolute path as the plugins.path. + +- Profiles (group: profile) +A Profile is a collection of settings, policies, scripts, cookies, cache and +history. Profiles can be used to isolate pages from each other. + +Each window has a default profile it uses when opening new tabs. This can be +set by the profile.default option, and can be changed from the window's menu. +Additionally, tabs can have their profiles individually changed from their page +menu. + +Because profiles store all their data separately, you can log in into the same +site with a different account from each profile. However, links opened into new +tabs will still use the subwindow's default profile. For example, you can set a +profile to hold login information for a site, but all new tabs opened from that +site would still be using the default off-the-record profile. + +Profile definitions are stored in the profiles.path location. To create a new +profile, create a profile-id.profile file in that location. + +- Bookmarks (group: bookmarks) + +- Downloads (group: downloads) + diff --git a/doc/Usage/Configuration.md b/doc/Usage/Configuration.md deleted file mode 100644 index 3bf55b9..0000000 --- a/doc/Usage/Configuration.md +++ /dev/null @@ -1,53 +0,0 @@ -## Configuration - -The Configuration is loaded from _~/.config/smolbote/smolbote.cfg_. Most -settings are only loaded on launch. - -For a full list of settings, check `--help`. - -### Browser (group: browser) - -### Main Window (group: mainwindow) -A main window contains one or more subwindows. - -### Subwindow (group: window) -A subwindow contains multiple tabs and functions similarly to a tab group. - -### Navigation bar (group: navigation) -The navigation bar is the toolbar that holds the history, reload and home -buttons, as well as the address bar. It can be made movable through the -navigation.movable option. - -### Address bar (group: addressbar) - -### Filter (group: filter) - -### Plugins (group: plugins) -Plugins a way of extending smolbote's functionality using the Qt plugin system. -They are not to be confused with NPAPI/PPAPI or WebExtension plugins. - -To enable a plugin either copy it or symlink it in the plugins.path location, -or set its absolute path as the plugins.path. - -### Profiles (group: profile) -A Profile is a collection of settings, policies, scripts, cookies, cache and -history. Profiles can be used to isolate pages from each other. - -Each window has a default profile it uses when opening new tabs. This can be -set by the profile.default option, and can be changed from the window's menu. -Additionally, tabs can have their profiles individually changed from their page -menu. - -Because profiles store all their data separately, you can log in into the same -site with a different account from each profile. However, links opened into new -tabs will still use the subwindow's default profile. For example, you can set a -profile to hold login information for a site, but all new tabs opened from that -site would still be using the default off-the-record profile. - -Profile definitions are stored in the profiles.path location. To create a new -profile, create a profile-id.profile file in that location. - -### Bookmarks (group: bookmarks) - -### Downloads (group: downloads) - diff --git a/doc/Usage/Profile.asciidoc b/doc/Usage/Profile.asciidoc new file mode 100644 index 0000000..9b00dbc --- /dev/null +++ b/doc/Usage/Profile.asciidoc @@ -0,0 +1,31 @@ +== Profiles +A Profile is a collection of settings, policies, scripts, cookies, cache and +history. Profiles can be used to isolate pages from each other. + +Each window has a default profile it uses when opening new tabs. This can be +changed from the window's menu. Additionally, tabs can have their profiles +individually changed from their context menu. + +Because profiles store all their data separately, you can log in into the same +site with a different account from each profile. However, links opened into new +tabs will still use the subwindow's default profile. For example, you can set a +profile to hold login information for a site, but all new tabs opened from that +site would still be using the default off-the-record profile. + +Profiles are read from profile.path + +Settings + +- otr (defaults to true) - is this profile off-the-record +- name (defaults to the configuration file name) +- search (defaults to profile.search) - search engine url +- homepage (defaults to profile.homepage) +- newtab (defaults to profile.newtab) + +Properties +Key is property name; value is property value + +Attributes +see QWebEngineSetting::WebAttribute for list of IDs. +Key is attribute id; value is attribute value (true/false) + diff --git a/doc/Usage/Profile.md b/doc/Usage/Profile.md deleted file mode 100644 index d205a86..0000000 --- a/doc/Usage/Profile.md +++ /dev/null @@ -1,17 +0,0 @@ -Profiles are read from profile.path - -## Settings - -- otr (defaults to true) - is this profile off-the-record -- name (defaults to the configuration file name) -- search (defaults to profile.search) - search engine url -- homepage (defaults to profile.homepage) -- newtab (defaults to profile.newtab) - -### Properties -Key is property name; value is property value - -### Attributes -see QWebEngineSetting::WebAttribute for list of IDs. -Key is attribute id; value is attribute value (true/false) - diff --git a/doc/Usage/Session.md b/doc/Usage/Session.md deleted file mode 100644 index 3018253..0000000 --- a/doc/Usage/Session.md +++ /dev/null @@ -1,30 +0,0 @@ -## Session format -A session is a single window, which contains a list of subwindows. - -Each subwindow has a profile (profile id), and a list of tabs. - -Each tab has a profile (profile id) and url. - -~~~json -{ - "subwindows": [ - { - "profile": "", - "tabs": [ - { - "profile": "", - "url": "" - }, - { - ... - } - ] - } - ] -} - -~~~ - -## --session -This command-line option causes the browser to load the specified json file. - diff --git a/doc/smolbote.7.asciidoc b/doc/smolbote.7.asciidoc new file mode 100644 index 0000000..ec1150f --- /dev/null +++ b/doc/smolbote.7.asciidoc @@ -0,0 +1,35 @@ += smolbote(7) +:doctype: manpage +:man source: smolbote +:man manual: smolbote manpage +:toc: +:homepage: https://neueland.iserlohn-fortress.net/smolbote/ + +== Name +smolbote - yet another no-frills web browser + +== Synopsis +*poi* ['-OPTION' ['...']] ['COMMAND'] ['URL' ['...']] + +== Description +smolbote is a cross-platform keep-it-simple free software web browser based on +Qt and QtWebEngine. + +include::Usage/CommandLine.asciidoc[] + +include::Usage/Configuration.asciidoc[] + +include::Usage/Profile.asciidoc[] + +== Copyright +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License version 3 as +published by the Free Software Foundation. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . diff --git a/linux/makepkg/PKGBUILD b/linux/makepkg/PKGBUILD index 2e0e755..4bb7571 100644 --- a/linux/makepkg/PKGBUILD +++ b/linux/makepkg/PKGBUILD @@ -17,7 +17,7 @@ license=('GPL3') depends=('qt5-webengine>=5.11.0' 'boost-libs>=1.66.0') optdepends=('firejail: launch a sandboxed instance') -makedepends=('git' 'cmake' 'pkg-config' 'go-md2man') +makedepends=('git' 'cmake' 'pkg-config' 'asciidoc') # this is the central repository source=("git+https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git" @@ -66,7 +66,6 @@ build() { -DVerDescribe=$_describe \ -DVerCommit=$_commit \ -DVerBranch=$_branch \ - -DBreakpad=On \ $srcdir/smolbote # Build @@ -77,16 +76,16 @@ package() { # Install make install - # icon and .desktop - install -Dm644 "${srcdir}/smolbote/data/poi.svg" "${pkgdir}/usr/share/icons/hicolor/scalable/apps/poi.svg" - install -Dm644 "${srcdir}/smolbote/linux/poi.desktop" "${pkgdir}/usr/share/applications/poi.desktop" + msg2 "Installing icon and .desktop" + install -Dm644 $srcdir/smolbote/data/poi.svg $pkgdir/usr/share/icons/hicolor/scalable/apps/poi.svg + install -Dm644 $srcdir/smolbote/linux/poi.desktop $pkgdir/usr/share/applications/poi.desktop - # firejail profile - install -Dm644 "${srcdir}/smolbote/data/poi.profile" "${pkgdir}/usr/local/lib/smolbote/poi.profile" + msg2 "Installing firejail profile" + install -Dm644 $srcdir/smolbote/data/poi.profile $pkgdir/usr/local/lib/smolbote/poi.profile - msg2 "Install manpage" - go-md2man -in $srcdir/smolbote/linux/man/smolbote.md -out smolbote.7 - gzip smolbote.7 - install -Dm644 smolbote.7.gz $pkgdir/usr/local/man/man7/smolbote.7.gz + msg2 "Installing manpage" + a2x --format=manpage $srcdir/doc/smolbote.7.asciidoc + gzip $srcdir/doc/smolbote.7 + install -Dm644 $srcdir/doc/smolbote.7.gz $pkgdir/usr/local/man/man7/smolbote.7.gz } diff --git a/linux/man/smolbote.md b/linux/man/smolbote.md deleted file mode 100644 index b9ea181..0000000 --- a/linux/man/smolbote.md +++ /dev/null @@ -1,75 +0,0 @@ -smolbote(7) -=== - -## NAME -smolbote - yet another no-frills web browser - -## SYNOPSIS -`poi` [...] URL(s) - -## DESCRIPTION -smolbote is a cross-platform keep-it-simple free software web browser based on -Qt and QtWebEngine. - -## COMMAND-LINE OPTIONS - -### General -* `-h`, `--help`: Display this help. -* `-v`, `--version`: Display version information. -* `--build`: Display build branch and commit. -* `-c`, `--config`: Set configuration file. -* `--no-remote`: Don't check for other instances when starting. - -## CONFIGURATION - -The Configuration is loaded from _~/.config/smolbote/smolbote.cfg_. Most -settings are only loaded on launch. - -For a full list of settings, check `--help`. - -### Browser (group: browser) - -### Main Window (group: mainwindow) -A main window contains one or more subwindows. - -### Subwindow (group: window) -A subwindow contains multiple tabs and functions similarly to a tab group. - -### Navigation bar (group: navigation) -The navigation bar is the toolbar that holds the history, reload and home -buttons, as well as the address bar. It can be made movable through the -navigation.movable option. - -### Address bar (group: addressbar) - -### Filter (group: filter) - -### Plugins (group: plugins) -Plugins a way of extending smolbote's functionality using the Qt plugin system. -They are not to be confused with NPAPI/PPAPI or WebExtension plugins. - -To enable a plugin either copy it or symlink it in the plugins.path location, -or set its absolute path as the plugins.path. - -### Profiles (group: profile) -A Profile is a collection of settings, policies, scripts, cookies, cache and -history. Profiles can be used to isolate pages from each other. - -Each window has a default profile it uses when opening new tabs. This can be -set by the profile.default option, and can be changed from the window's menu. -Additionally, tabs can have their profiles individually changed from their page -menu. - -Because profiles store all their data separately, you can log in into the same -site with a different account from each profile. However, links opened into new -tabs will still use the subwindow's default profile. For example, you can set a -profile to hold login information for a site, but all new tabs opened from that -site would still be using the default off-the-record profile. - -Profile definitions are stored in the profiles.path location. To create a new -profile, create a profile-id.profile file in that location. - -### Bookmarks (group: bookmarks) - -### Downloads (group: downloads) - -- cgit v1.2.1