aboutsummaryrefslogtreecommitdiff
path: root/docs/manual
diff options
context:
space:
mode:
Diffstat (limited to 'docs/manual')
-rw-r--r--docs/manual/Building.Compiling.md44
-rw-r--r--docs/manual/Building.Dependencies.md15
-rw-r--r--docs/manual/Building.Packaging.md16
-rw-r--r--docs/manual/Building.md26
-rw-r--r--docs/manual/Contributing.Bugs.md20
-rw-r--r--docs/manual/Contributing.Code.md35
-rw-r--r--docs/manual/Contributing.Style.md70
-rw-r--r--docs/manual/Contributing.md1
-rw-r--r--docs/manual/Features.1.0.md82
-rw-r--r--docs/manual/Features.md1
-rw-r--r--docs/manual/Introduction.md1
-rw-r--r--docs/manual/Quickstart.md4
-rw-r--r--docs/manual/SUMMARY.md14
13 files changed, 329 insertions, 0 deletions
diff --git a/docs/manual/Building.Compiling.md b/docs/manual/Building.Compiling.md
new file mode 100644
index 0000000..bf6637e
--- /dev/null
+++ b/docs/manual/Building.Compiling.md
@@ -0,0 +1,44 @@
+# Compiling
+
+## Creating qbs configuration
+Before you can build anything with qbs, you need to set up the compiler
+toolchain as well as Qt.
+
+```
+qbs setup-toolchains --detect
+qbs setup-qt /usr/bin/qmake-qt5 qt5
+```
+
+
+## Compiling
+
+* Create a build folder
+```
+[smolbote repo]$ mkdir ../build
+```
+
+* Run qbs
+```
+[smolbote repo]$ qbs build -d ../build profile:qt5 release
+```
+This installs the files to ../build/release/install-root.
+
+* Run
+```
+[smolbote repo]$ qbs run -d ../build -p poi profile:qt5 release
+```
+
+## mach
+mach is a helper script that can build and run smolbote.
+
+#### setup
+./mach setup creates a qbs configuration in :settingsDir,
+by default ../build/config.
+
+You can edit this using qbs-config-ui --settings-dir ../build/config.
+
+#### run
+
+#### clean
+
+#### build
diff --git a/docs/manual/Building.Dependencies.md b/docs/manual/Building.Dependencies.md
new file mode 100644
index 0000000..a506958
--- /dev/null
+++ b/docs/manual/Building.Dependencies.md
@@ -0,0 +1,15 @@
+# Dependencies
+
+### Libraries
+- [Qt](https://www.qt.io/)
+ - at least 5.9
+ - core, widgets
+ - webengine, webenginewidgets
+- [libconfig](http://hyperrealm.com/libconfig/libconfig.html)
+
+### Tools
+* A working compiler
+ - gcc or clang on Linux
+ - msvc on Windows due to QtWebEngine
+* qbs
+ - minimal version 1.8.0
diff --git a/docs/manual/Building.Packaging.md b/docs/manual/Building.Packaging.md
new file mode 100644
index 0000000..c88eab0
--- /dev/null
+++ b/docs/manual/Building.Packaging.md
@@ -0,0 +1,16 @@
+# Packaging
+
+## Source Tarball
+
+1. Get source code from the repository
+> git archive --format=tar HEAD > head.tar
+
+2. Compress with lzip
+> lzip -9 --force --output=head.tar.lz head.tar
+
+3. Generate checksum
+> sha512sum --binary head.tar.lz > head.tar.lz.sha512
+
+## makepkg
+
+A PKGBUILD is provided in linux/makepkg/PKGBUILD.
diff --git a/docs/manual/Building.md b/docs/manual/Building.md
new file mode 100644
index 0000000..aa5c1f4
--- /dev/null
+++ b/docs/manual/Building.md
@@ -0,0 +1,26 @@
+# Building
+
+### Notes (TODO: move)
+* Windows: MSVC compiler is required because of QtWebEngine dependency
+* Windows: Passing the -v or -h parameters creates a dialog box instead of
+writing the output to stdout. This is Qt behaviour.
+* Windows: Use windeployqt.exe to collect the libraries
+```
+QT_DIR\QT_VER\msvc2015_64\windeployqt.exe build-PROFILE\release\qtbrowser.exe
+```
+* grsecurity: You may need to exception qbs.
+
+An optional system proxy should be picked up automatically. However, for proxies
+that require a username or password, you need to connect to
+QWebEnginePage::proxyAuthenticationRequired.
+
+Qt WebEngine Widgets uses the Qt Quick Scene Graph to compose the page.
+Therefore, OpenGL support is required.
+And that's also why QML is a dependancy.
+
+To use clang with QtCreator, you need to change the compiler in
+Build & Run » Kits, not the qbs profile.
+
+
+
+[1]: https://doc.qt.io/qbs/index.html
diff --git a/docs/manual/Contributing.Bugs.md b/docs/manual/Contributing.Bugs.md
new file mode 100644
index 0000000..9904273
--- /dev/null
+++ b/docs/manual/Contributing.Bugs.md
@@ -0,0 +1,20 @@
+# Reporting bugs
+
+Please include the following when reporting bugs:
+* Operating system used
+* Version of Qt used
+* Detailed explanation of the bug:
+ * what was done
+ * what was expected
+ * what happened
+
+An example of a bad bug report is:
+> Something happened, and what I pressed the button it broke.
+
+An exmaple of a good bug report is:
+> When I opened the Page menu and pressed Print to PDF, nothing happened.
+
+You can fill out this template when submitting a bug report
+> I'm using (Windows? Linux?)
+>
+> The smolbote version is (0.1? 0.2? 1.0?)
diff --git a/docs/manual/Contributing.Code.md b/docs/manual/Contributing.Code.md
new file mode 100644
index 0000000..419a08c
--- /dev/null
+++ b/docs/manual/Contributing.Code.md
@@ -0,0 +1,35 @@
+# Before you submit
+
+## Licensing
+Smolbote is licensed under GPLv3. Your code needs to be compatible with it, and
+have a license header.
+
+A sample GPLv3 header is included in docs/header-gpl3.txt
+
+The provided pre-commit hook uses the following regular expression to check for
+a license:
+```ruby
+/Copyright\s\(C\)\s(\d{4}\s*-\s*){0,1}(#{Time.now.year})/
+```
+
+## Style
+Please use the [One True Brace style](https://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS_.28OTBS.29).
+Tabs are 4 spaces.
+
+For ease of use, you can set the following astyle configuration:
+```
+--style=otbs
+--attach-namespaces
+--attach-inlines
+--indent=spaces=4
+```
+
+## Format patch for email
+```sh
+git format-patch hash
+```
+where _hash_ is the commit immediately prior to the commit or series of commits
+you want to submit.
+
+Attach the patch file and email it to _aqua at iserlohn-fortress.net_. If
+possible, GPG sign the email.
diff --git a/docs/manual/Contributing.Style.md b/docs/manual/Contributing.Style.md
new file mode 100644
index 0000000..1ab6b17
--- /dev/null
+++ b/docs/manual/Contributing.Style.md
@@ -0,0 +1,70 @@
+# Code style
+
+## Guidelines
+* Use generic formats
+* Where possible, use QVector over QList:
+http://lists.qt-project.org/pipermail/development/2017-March/029040.html
+
+## Versioning
+
+#### Major version
+Changed infrequently and almost entirely out of foppery and whim.
+
+#### Minor version
+Milestone of multiple features.
+
+#### Revision
+Major bugfixes and each new feature should get a revision.
+
+### Branching
+* master - main branch, should be kept up-to-date, and have only working code
+* next - next stable release preparation, mostly for bugfixes
+* development - development branch, anything goes there
+
+### Folder structure
+
+ folder | description
+ ------ | -----------
+/src | source code
+/src/widgets | subclassed Qt widgets
+/src/formats | file format parsing (toml, xbel)
+/src/forms | Qt UI forms and classes
+/src/webengine | QWebEngine subclasses
+/test | test run location, mainly for QtCreator
+
+
+## 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_
+
+This will update the qbs profile that QtCreator uses.
+
+### Reducing clazy noise
+If you want to suppress warnings from headers of Qt or 3rd party code, include
+them with -isystem instead of -I. To do this, you have to
+[modify your Qt profile](clazy-sysincludes) like this:
+
+Find the profile's search path:
+```sh
+$ qbs config --list profiles.qt562.preferences
+profiles.qt562.preferences.qbsSearchPaths: "/home/someone/.config/QtProject/qbs/1.9.0/profiles/qt562"
+```
+
+Replace cpp.includePaths with cpp.systemIncludePaths in the Qt modules of that
+profile:
+
+```sh
+$ find /home/someone/.config/QtProject/qbs/1.9.0/profiles/qt562/modules/Qt/ -name '*.qbs' | xargs -n1 sed -i s/cpp\.includePaths/cpp.systemIncludePaths/
+```
+
+[clazy-sysincludes]: http://lists.qt-project.org/pipermail/qbs/2017-April/001709.html
+
diff --git a/docs/manual/Contributing.md b/docs/manual/Contributing.md
new file mode 100644
index 0000000..854139a
--- /dev/null
+++ b/docs/manual/Contributing.md
@@ -0,0 +1 @@
+# Contributing
diff --git a/docs/manual/Features.1.0.md b/docs/manual/Features.1.0.md
new file mode 100644
index 0000000..31ad978
--- /dev/null
+++ b/docs/manual/Features.1.0.md
@@ -0,0 +1,82 @@
+# Version 1.0
+* Profiles
+ - Application-level profile manager
+ - System-level and user-level profile config, with per-profile overrides [todo]
+* Configuration
+ - Default system-level config and user-level overrides [todo]
+* Cookies
+ - Filter list similar to the URL filter list [todo]
+* Tabs
+ - Moving tabs between windows [todo]
+ - Tab context menu [todo]
+* Page actions
+ - Search [todo]
+ - Zoom [todo]
+ - Print [todo]
+* Navigation toolbar
+ - Back and Forward history [todo]
+
+## Overall design of smolbote
+
+The aim of smolbote is to be a lightweight and fast, to the point web browser.
+
+### How smolbote works [TODO]
+
+0. Launch
+1. Check for other instance, unless otherwise specified
+ - If other instance is found, pass the parameters to it and quit
+ - Else, create a new instance
+2. Create application object
+ - Read configuration
+ _ Create profiles
+3. Pass parameters to application object
+ - Create main window if there isn't one
+ - open URLs
+
+### main() and smolmain() [TODO]
+
+The main() function should contain all code to start up, check for another
+running instance, and if necessary pass the parameters to the other instance.
+
+The smolmain() function should contain code to create a new instance based on
+the parameters passed.
+
+IPC should be done with QLocalSocket.
+
+### Dockable windows
+
+### Folder structure
+
+- data/ - Any resource files (defaults, icons, etc)
+- docs/ - Where all the documentation lives
+- src/ - Source code
+- test/ - Testing grounds
+- tools/ - Hooks, qbs helpers, updater
+
+### Libraries used
+All 3rd-party libraries should be placed in src/3rd-party/library-name, together
+with their corresponding license file. The license file should start with the
+library name and repository location.
+
+- tinytoml
+
+## Components
+Components should, when possible, be split off into self-contained static
+libraries. This is to reduce recompile times.
+
+### Navigation
+Includes the Address bar (URLLineEdit).
+
+### Bookmarks [TODO]
+
+- [TODO] Bookmark location should be read from profile, with a default in the config
+- [TODO] Split off xbel implementation into a library
+- [TODO] BookmarksLibrary API
+
+### History
+
+History is managed by QtWebEngine.
+
+### Cookies
+
+Cookies are managed by QtWebEngine.
diff --git a/docs/manual/Features.md b/docs/manual/Features.md
new file mode 100644
index 0000000..ead0223
--- /dev/null
+++ b/docs/manual/Features.md
@@ -0,0 +1 @@
+# Features
diff --git a/docs/manual/Introduction.md b/docs/manual/Introduction.md
new file mode 100644
index 0000000..e10b99d
--- /dev/null
+++ b/docs/manual/Introduction.md
@@ -0,0 +1 @@
+# Introduction
diff --git a/docs/manual/Quickstart.md b/docs/manual/Quickstart.md
new file mode 100644
index 0000000..9cbcda0
--- /dev/null
+++ b/docs/manual/Quickstart.md
@@ -0,0 +1,4 @@
+# Getting started
+
+- Installing and running smolbote
+- Configuration files
diff --git a/docs/manual/SUMMARY.md b/docs/manual/SUMMARY.md
new file mode 100644
index 0000000..5362502
--- /dev/null
+++ b/docs/manual/SUMMARY.md
@@ -0,0 +1,14 @@
+# Summary
+
+- [Introduction](./Introduction.md)
+- [Getting started](./Quickstart.md)
+- [Features](./Features.md)
+ - [1.0](./Features.1.0.md)
+- [Building](./Building.md)
+ - [Dependencies](./Building.Dependencies.md)
+ - [Compiling](./Building.Compiling.md)
+ - [Packaging](./Building.Packaging.md)
+- [Contributing](./Contributing.md)
+ - [Reporting bugs](./Contributing.Bugs.md)
+ - [Code style](./Contributing.Style.md)
+ - [Before you submit](./Contributing.Code.md)