diff options
Diffstat (limited to 'doc')
| -rwxr-xr-x | doc/man/genroff.sh | 4 | ||||
| -rw-r--r-- | doc/man/smolbote-profile.5.scd | 80 | ||||
| -rw-r--r-- | doc/man/smolbote.1.scd | 47 | ||||
| -rw-r--r-- | doc/man/smolbote.5.scd | 106 | ||||
| -rw-r--r-- | doc/man/smolboterc.5.scd | 21 | ||||
| -rw-r--r-- | doc/meson.build | 41 |
6 files changed, 122 insertions, 177 deletions
diff --git a/doc/man/genroff.sh b/doc/man/genroff.sh new file mode 100755 index 0000000..1d513f4 --- /dev/null +++ b/doc/man/genroff.sh @@ -0,0 +1,4 @@ +#/usr/bin/env sh + +scdoc < $1 + diff --git a/doc/man/smolbote-profile.5.scd b/doc/man/smolbote-profile.5.scd new file mode 100644 index 0000000..115e6ed --- /dev/null +++ b/doc/man/smolbote-profile.5.scd @@ -0,0 +1,80 @@ +smolbote(5) "smolbote profile configuration" + +# NAME + +smolbote profile format + +# DESCRIPTION + +A profile is a collection of settings, policies, scripts, cookies, cache and +history. They store their data separately, and can be used to isolate pages from +each other. + +Off-the-record profiles only use in-memory cache and don't keep cookies or +history between sessions. They are useful as a private browsing mode. + +Each subwindow has a default profile it uses when opening new tabs. This can be +changed from the _Subwindow_ menu. Additionally, tabs can have their profiles +individually changed from the _Page_ menu. + +Profiles can be either temporary or permanent. Temporary profiles expire when +the application is closed, whereas permanent profiles are kept between runs. + +The browser will save changes made to profiles automatically. If you want to +prevent modifications, set the corresponding .profile to read-only. + +# SECTIONS + +Profiles are defined in an INI format file with a `.profile` extension. The file +name is used as the profile's ID. +If no value is specified, the default value is used instead. + +## General +- `name`: Name (Default: same as the ID) +- `otr`: Off-the-record toggle, true or false (Default: true) +- `search`: The search engine URL, with the following format: + https://engine.url/q=%1, where %1 will be substituted by the search term. +- `homepage`: The homepage URL. (Default: about:blank) +- `newtab`: The URL that should be loaded by default when opening a new tab with + this profile. (Default: about:blank) + +## properties +- `cachePath` +- `persistentStoragePath` +- `persistentCookiesPolicy` +- `httpAcceptLanguage` +- `httpCacheMaximumSize` +- `httpCacheType` +- `httpUserAgent` +- `spellCheckEnabled` + +See the QtWebEngine documentation[0] for more information. + +## attributes +QWebEngineSettings::WebAttribute, see the QtWebEngine documentation[1] for more +information. + +## headers +HTTP headers that should be enforced by the profile. + +# EXAMPLES +To check where profiles are read from, you can use: + $ poi configuration --dump | grep profile.path + +Creating a `otr.profile` file in that location will create a permanent +off-the-record profile with an ID of `otr`. You can customize it further: + +``` +[General] +name=off-the-record + +[headers] +Dnt=1 +``` + +This will name the profile `off-the-record` in menus, and cause it to send out a +Dnt (Do not track) header. + +# SEE ALSO +0: https://doc.qt.io/qt-5/qwebengineprofile.html++ +1: https://doc.qt.io/qt-5/qwebenginesettings.html diff --git a/doc/man/smolbote.1.scd b/doc/man/smolbote.1.scd index 4ca55b7..758fda3 100644 --- a/doc/man/smolbote.1.scd +++ b/doc/man/smolbote.1.scd @@ -10,66 +10,29 @@ smolbote - yet another no-frills web browser # DESCRIPTION -smolbote is a cross-platform keep-it-simple free software web browser that -uses Qt and QtWebEngine. +smolbote is a cross-platform keep-it-simple free software web browser that uses Qt and QtWebEngine. # USAGE ## Command-line options - `-h`, `--help`: Display command-line options list. - `-v`, `--version`: Display version information. -- `--build`: Display build commit. +- `-b`, `--build`: Display build commit. - `-c`, `--config`: Set configuration file. - `--no-remote`: Don't check for other instances when starting. - `-s, --session`: Open the selected session. - `--pick-session`: Open all available sessions and select which one to open. -## Profiles -A Profile is a collection of settings, policies, scripts, cookies, cache and -history. Profiles can be used to isolate pages from each other. - -Off-the-record profiles only use in-memory cache and save no files to disk. - -Profiles can be either temporary or permanent. Temporary profiles expire when -the application is closed, whereas permanent profiles are kept between runs. - -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. - -## 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. - -## Filters -smolbote has a singular URL request filter that is installed onto all profiles. -Any setting applied to it will be applied to all profiles. - -filter.header: A list of header-value pairs, separated by a colon (':'). - -You can specify multiple headers by using --filter.header multiple times: -``` -poi --filter.header "Dnt:1" --filter.header "Accept:text/html" -``` - # SEE ALSO -*smolbote*(5) - configuration file and options +*smolboterc*(5) - configuration file and options++ +*smolbote-profile*(5) - profiles and how to use them # AUTHORS Maintained by <aqua@iserlohn-fortress.net>. -Up-to-date sources can be found at https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote +Up-to-date sources can be found at https://neueland.iserlohn-fortress.net/cgit/smolbote Bug reports and patches can be submitted by email to <aqua@iserlohn-fortress.net>. diff --git a/doc/man/smolbote.5.scd b/doc/man/smolbote.5.scd deleted file mode 100644 index 063a050..0000000 --- a/doc/man/smolbote.5.scd +++ /dev/null @@ -1,106 +0,0 @@ -smolbote(5) "smolbote configuration" - -# NAME - -smolbote - configuration file and options description - -# DESCRIPTION - -The smolbote configuration is loaded at startup, and is not reloaded when -changed. By default (without any plugins), the browser does not change its -configuration or overwrite this file. Thus, it can be made read-only. - -The settings in this file change your preferences and keybindings. - -Lines starting with *#* are considered comments and ignored. - -Options taking multiple values (list options) can have multiple values set by -using the same option name multiple times. - -# SECTIONS - -## Browser Options - -*browser.stylesheet* (arg):: TODO - -*browser.iconTheme* (arg):: -Set arg as icon theme. - -*browser.locale* (arg):: -Set Qt localization. This will translate Qt strings, such as the dialog buttons. -For possible values see `/usr/share/qt/translations`. - -*browser.translation* (arg):: -Set browser localization. This will translate the rest of the browser. For -possible values, see `install-root/share/smolbote/lang`. - -*browser.session.path* (arg=~/.config/smolbote/session.d):: -Location where browser sessions should be saved and loaded from by default. - -*plugins.path* (arg=~/.config/smolbote/plugins.d):: -Location where plugins should be loaded from. - -*bookmarks.path* (arg=~/.config/smolbote/bookmarks.xbel):: -Default bookmarks location. -*bookmarks.shortcut* (arg=Ctrl+B):: -Show/Hide bookmakrs widget shortcut. - -*downloads.path* (arg=~/Downloads):: -Default downloads location. -*downloads.shortcut* (arg=Ctrl+D):: -Show/Hide downloads widget shortcut. - -## UI Options - -*mainwindow.height* (arg=720) -*mainwindow.width* (arg=1280) -*mainwindow.maximized* (arg=1):: Default window size and maximize toggle. - -*mainwindow.title* (arg=smolbote):: Default window title. - -*mainwindow.shortcuts.saveSession* (arg=Ctrl+S,S):: Save Session shortcut -*mainwindow.shortcuts.openSession* (arg=Ctrl+S,O):: Open Session shortcut -*mainwindow.shortcuts.newGroup* (arg=Ctrl+G):: New Group shortcut (subwindow) -*mainwindow.shortcuts.newWindow* (arg=Ctrl+N):: New Window shortcut -*mainwindow.shortcuts.about* (arg=F1):: About dialog shortcut -*mainwindow.shortcuts.quit* (arg=Ctrl+Q):: Quit shortcut -*mainwindow.shortcuts.search* (arg=F3):: Search in page shortcut -*mainwindow.shortcuts.tileWindows* (arg=F9):: Tile subwindows shortcut -*mainwindow.shortcuts.cascadeWindows* (arg=F10):: Cascade subwindows shortcut - -*navigation.movable* (arg=0):: Make navigation bar movable -*navigation.shortcuts.back* (arg=Ctrl+Left):: Back shortcut -*navigation.shortcuts.backMenu* (arg=Ctrl+Down):: Back menu shortcut -*navigation.shortcuts.forward* (arg=Ctrl+Right):: Forward shortcut -*navigation.shortcuts.forwardMenu* (arg=Ctrl+Up):: Forward menu shortcut -*navigation.shortcuts.refresh* (arg=F5):: Refresh shortcut -*navigation.shortcuts.reload* (arg=Ctrl+F5):: Reload shortcut -*navigation.shortcuts.home* (arg=Ctrl+Home):: Home shortcut - -*addressbar.shortcuts.focus* (arg=F4):: Focus on the address -*addressbar.shortcuts.menu* (arg=F2):: Show addressbar menu - -*subwindow.shortcuts.menu* (arg=Ctrl+M):: Show subwindow menu -*subwindow.shortcuts.new* (arg=Ctrl+T):: Create new tab shortcut -*subwindow.shortcuts.close* (arg=Ctrl+X):: Close tab shortcut -*subwindow.shortcuts.restoreTab* (arg=Ctrl+Shift+T):: Restore last closed tab -*subwindow.shortcuts.left* (arg=Ctrl+O):: Move to tab on the left -*subwindow.shortcuts.moveLeft* (arg=Ctrl+Shift+O):: Move tab to the left -*subwindow.shortcuts.right* (arg=Ctrl+P):: Move to tab on the right -*subwindow.shortcuts.moveRight* (arg=Ctrl+Shift+P):: Move tab to the right -*subwindow.shortcuts.fullscreen* (arg=F11):: Show page fullscreen - -## Security Options - -*filter.hosts* (arg=~/.config/smolbote/hosts.d):: Hostlist -*filter.adblock* arg:: TODO -*filter.header* (list):: -A list of HTTP headers to set. Each header should be given as a colon-separated -name:value pair. - -*profile.default* (arg):: Default browser profile -*profile.path* (arg=~/.config/smolbote/profiles.d):: Profile location -*profile.search* (arg=`https://duckduckgo.com/?q=%1&ia=web`):: -Default search engine. %1 is replaced by the search term. -*profile.homepage* (arg=`about:blank`):: Default homepage -*profile.newtab* (arg=`about:blank`):: Default new tab page diff --git a/doc/man/smolboterc.5.scd b/doc/man/smolboterc.5.scd new file mode 100644 index 0000000..f340c01 --- /dev/null +++ b/doc/man/smolboterc.5.scd @@ -0,0 +1,21 @@ +smolbote(5) "smolbote configuration" + +# NAME + +smolbote - configuration file and options description + +# DESCRIPTION + +The smolbote configuration is loaded at startup, and is not reloaded when +changed. By default (without any plugins), the browser does not change its +configuration or overwrite this file. Thus, it can be made read-only. + +The settings in this file change your preferences and keybindings. + +Lines starting with *#* are considered comments and ignored. + +Options taking multiple values (list options) can have multiple values set by +using the same option name multiple times. + +# SECTIONS + diff --git a/doc/meson.build b/doc/meson.build index 26e5d6c..6490969 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -1,33 +1,16 @@ -scdoc = find_program('scdoc', required: get_option('manpage'), disabler: true) -if scdoc.found() +if not get_option('manpage') + subdir_done() +endif sh = find_program('sh', required: true, native: true, disabler: true) -man_files = ['man/smolbote.1.scd', 'man/smolbote.5.scd'] - -foreach input : man_files - topic = input.split('/')[-1].split('.')[-3] - section = input.split('.')[-2] - output = '@0@.@1@'.format(topic, section) - - message('creating manpage target ' + output) - custom_target(output, - build_by_default: true, - - input: input, - output: output, - - # scdoc takes input from stdin, and prints its output to stdout - # meson uses 'capture' to store stdout to output, but there is no stdin toggle - #command: [scdoc], - #capture: true, - - # workaround using sh - command: [sh, '-c', '@0@ < @INPUT0@ > @OUTPUT0@'.format(scdoc.path())], - - install: true, - install_dir: '@0@/man@1@'.format(get_option('mandir'), section) - ) +foreach f : [ 'smolbote.1', 'smolboterc.5', 'smolbote-profile.5' ] +manpage = custom_target(f, + input: 'man'/f+'.scd', + output: '@BASENAME@', + capture: true, + command: [ sh, meson.current_source_dir()/'man/genroff.sh', '@INPUT@' ], + install: true, + install_dir: get_option('mandir') +) endforeach - -endif # manpage |