From cf06dcb0650f603ae3d634634d81f9ec78d21937 Mon Sep 17 00:00:00 2001 From: Aqua-sama Date: Thu, 21 Dec 2017 17:52:56 +0100 Subject: Edited documentation - Search highlighting is removed when you close the search box - Fixed PKGBUILD not working - PKGBUILD can now pick compiler and optimization --- docs/manual/Bugs.md | 17 ++++++++ docs/manual/Building.Compiling.md | 28 ------------ docs/manual/Building.Dependencies.md | 15 ------- docs/manual/Building.Packaging.md | 16 ------- docs/manual/Building.md | 60 ++++++++++++++++++------- docs/manual/Contributing.Bugs.md | 20 --------- docs/manual/Contributing.Style.md | 58 ------------------------ docs/manual/Contributing.Submitting.md | 51 ---------------------- docs/manual/Contributing.md | 80 +++++++++++++++++++++++++++++++++- docs/manual/Features.md | 3 -- docs/manual/Introduction.md | 1 - docs/manual/Quickstart.md | 17 ++++++-- docs/manual/SUMMARY.md | 14 ------ 13 files changed, 154 insertions(+), 226 deletions(-) create mode 100644 docs/manual/Bugs.md delete mode 100644 docs/manual/Building.Compiling.md delete mode 100644 docs/manual/Building.Dependencies.md delete mode 100644 docs/manual/Building.Packaging.md delete mode 100644 docs/manual/Contributing.Bugs.md delete mode 100644 docs/manual/Contributing.Style.md delete mode 100644 docs/manual/Contributing.Submitting.md delete mode 100644 docs/manual/Features.md delete mode 100644 docs/manual/Introduction.md delete mode 100644 docs/manual/SUMMARY.md (limited to 'docs') diff --git a/docs/manual/Bugs.md b/docs/manual/Bugs.md new file mode 100644 index 0000000..8d1b086 --- /dev/null +++ b/docs/manual/Bugs.md @@ -0,0 +1,17 @@ +# Reporting bugs + +Please include the following when reporting bugs: +* Operating system used +* Version of Qt used, any relevant information if you built it yourself +* 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. + +Send bug reports to _aqua at iserlohn-fortress.net_. diff --git a/docs/manual/Building.Compiling.md b/docs/manual/Building.Compiling.md deleted file mode 100644 index 7505755..0000000 --- a/docs/manual/Building.Compiling.md +++ /dev/null @@ -1,28 +0,0 @@ -# Compiling - -## Create 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 -``` - -## Compile - -1. Create a build folder -``` -[smolbote repo]$ mkdir ../build -``` - -2. Build -``` -[smolbote repo]$ qbs build -d ../build profile:qt5 release -``` -This installs the files to ../build/release/install-root. - -3. Install -``` -[smolbote repo]$ qbs install -d ../build -p poi --install-root "/install/root" profile:qt5 release -``` diff --git a/docs/manual/Building.Dependencies.md b/docs/manual/Building.Dependencies.md deleted file mode 100644 index 3b03e1b..0000000 --- a/docs/manual/Building.Dependencies.md +++ /dev/null @@ -1,15 +0,0 @@ -# Dependencies - -### Libraries -- [Qt](https://www.qt.io/) - - at least 5.9 - - core, widgets - - webengine, webenginewidgets -- [libconfig](https://hyperrealm.github.io/libconfig/) - -### 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 deleted file mode 100644 index c88eab0..0000000 --- a/docs/manual/Building.Packaging.md +++ /dev/null @@ -1,16 +0,0 @@ -# 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 index aa5c1f4..56a6646 100644 --- a/docs/manual/Building.md +++ b/docs/manual/Building.md @@ -1,26 +1,54 @@ # 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 +## Dependencies + +### Libraries +- [Qt](https://www.qt.io/) + - at least 5.9 (codebase should largely work with Qt 5.7) + - core, widgets + - webengine, webenginewidgets +- [libconfig](https://hyperrealm.github.io/libconfig/) + +### Tools +* A working compiler + - gcc or clang on Linux + - msvc on Windows due to QtWebEngine +* qbs + - minimal version 1.8.0 + +## Compiling + +### Create qbs configuration +Before you can build anything with qbs, you need to set up the compiler +toolchain. + ``` -QT_DIR\QT_VER\msvc2015_64\windeployqt.exe build-PROFILE\release\qtbrowser.exe +qbs setup-toolchains --detect +qbs setup-qt /usr/bin/qmake-qt5 qt5 ``` -* 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. +### Compiling +``` +mkdir ../build +qbs build -d ../build profile:qt5 release +``` -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. +## Packaging -To use clang with QtCreator, you need to change the compiler in -Build & Run » Kits, not the qbs profile. +### Source Tarball +``` +# Get source code from the repository +git archive --format=tar HEAD > head.tar +# Compress with lzip +lzip -9 --force --output=head.tar.lz head.tar +# Generate checksum +sha512sum --binary head.tar.lz > head.tar.lz.sha512 +``` +### makepkg +A PKGBUILD is provided in linux/makepkg/PKGBUILD. +## Troubleshooting -[1]: https://doc.qt.io/qbs/index.html +### Cannot link libconfig +You don't have pkg-config installed. diff --git a/docs/manual/Contributing.Bugs.md b/docs/manual/Contributing.Bugs.md deleted file mode 100644 index 9904273..0000000 --- a/docs/manual/Contributing.Bugs.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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.Style.md b/docs/manual/Contributing.Style.md deleted file mode 100644 index 7f3a052..0000000 --- a/docs/manual/Contributing.Style.md +++ /dev/null @@ -1,58 +0,0 @@ -# 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 - -## Qt -* Check pointers with ´´´Q_CHECK_PTR´´´ before returning them -* Avoid using connect SIGNAL and SLOT. Instead use &Class::method. This way, -connects are checked during the compile, not at runtime. - -## 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.Submitting.md b/docs/manual/Contributing.Submitting.md deleted file mode 100644 index d84e14f..0000000 --- a/docs/manual/Contributing.Submitting.md +++ /dev/null @@ -1,51 +0,0 @@ -# Before you submit - -## Licensing -Smolbote is licensed under GPLv3. Your code needs to be compatible with it, and -have a license header. - -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})/ -``` - -```c -/****************************************************************************** - ** - ** smolbote: yet another qute browser - ** - ** Copyright (C) 2017 author - ** SPDX-License-Identifier: GPL-3.0 - ** License-Filename: docs/gpl-3.0.md - ** - ******************************************************************************/ -``` - -### SPDX-License-Identifier -A full list of license identifiers can be found on [the SPDX website](https://spdx.org/licenses/). - -### License-Filename -Path to the license text, relative to the repository root. - -## 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.md b/docs/manual/Contributing.md index 854139a..ff8e2b2 100644 --- a/docs/manual/Contributing.md +++ b/docs/manual/Contributing.md @@ -1 +1,79 @@ -# Contributing +# Code style + +## Guidelines +* Use generic formats + +## 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. + +## 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_ + +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 + +# Before you submit + +## 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. + +### SPDX-License-Identifier +A full list of license identifiers can be found on [the SPDX website](https://spdx.org/licenses/). + +## 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/Features.md b/docs/manual/Features.md deleted file mode 100644 index e499fb7..0000000 --- a/docs/manual/Features.md +++ /dev/null @@ -1,3 +0,0 @@ -# Features - -The aim of smolbote is to be a lightweight and fast, to the point web browser. diff --git a/docs/manual/Introduction.md b/docs/manual/Introduction.md deleted file mode 100644 index e10b99d..0000000 --- a/docs/manual/Introduction.md +++ /dev/null @@ -1 +0,0 @@ -# Introduction diff --git a/docs/manual/Quickstart.md b/docs/manual/Quickstart.md index 9cbcda0..b8dcaa1 100644 --- a/docs/manual/Quickstart.md +++ b/docs/manual/Quickstart.md @@ -1,4 +1,15 @@ -# Getting started +# Quickstart -- Installing and running smolbote -- Configuration files +## Installing and running + +### Linux + +### Windows +Grab a package from (not yet available url). + +## Configuration files +On first run, smolbote will create its basic configuration: +- on Linux, in _~/.config/smolbote_ +- on Windows, in + +## Troubleshooting diff --git a/docs/manual/SUMMARY.md b/docs/manual/SUMMARY.md deleted file mode 100644 index ca7b072..0000000 --- a/docs/manual/SUMMARY.md +++ /dev/null @@ -1,14 +0,0 @@ -# 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) - - [Submitting](./Contributing.Submitting.md) -- cgit v1.2.1