From 9e092cc19d369028b91c33e932778a1480d97a2d Mon Sep 17 00:00:00 2001 From: Manuel Schneider Date: Thu, 7 Nov 2024 22:52:41 +0100 Subject: [PATCH] update --- Dockerfile | 2 + Doxyfile | 33 +++- Makefile | 6 +- docker-compose.yml | 5 +- src/_sass/custom/custom.scss | 14 +- src/gettingstarted/concepts.md | 51 ------ src/gettingstarted/extension/index.md | 4 +- src/gettingstarted/install/index.md | 10 ++ .../install/linux.md} | 41 +---- src/gettingstarted/install/macos.md | 32 ++++ src/gettingstarted/install/source.md | 20 +++ src/gettingstarted/usage.md | 157 ++++++++++++------ src/index.md | 2 +- 13 files changed, 227 insertions(+), 150 deletions(-) create mode 100644 src/gettingstarted/install/index.md rename src/{installation.md => gettingstarted/install/linux.md} (60%) create mode 100644 src/gettingstarted/install/macos.md create mode 100644 src/gettingstarted/install/source.md diff --git a/Dockerfile b/Dockerfile index bd15f56..01a85f0 100644 --- a/Dockerfile +++ b/Dockerfile @@ -6,9 +6,11 @@ EXPOSE 4000 ARG DEBIAN_FRONTEND=noninteractive RUN apt-get update \ + && ls \ && apt-get -y install build-essential \ && bundle install \ && apt-get -y clean \ && apt-get -y purge build-essential \ && apt-get -y autoremove \ && rm -rf /var/lib/apt/lists/* + diff --git a/Doxyfile b/Doxyfile index 2fdc2f4..e8ce8da 100644 --- a/Doxyfile +++ b/Doxyfile @@ -4,18 +4,28 @@ #EXTRACT_LOCAL_CLASSES = YES #EXTRACT_PRIVATE = NO #EXTRACT_STATIC = YES -#GENERATE_DOCSET = YES +GENERATE_DOCSET = YES #MACRO_EXPANSION = NO #SKIP_FUNCTION_MACROS = NO - -COLLABORATION_GRAPH = NO DOT_IMAGE_FORMAT = svg DOXYFILE_ENCODING = UTF-8 EXTRACT_ALL = YES GENERATE_LATEX = NO -INPUT = albert/include -STRIP_FROM_INC_PATH = albert/include +#INPUT = albert/include +INPUT = ../include +STRIP_FROM_INC_PATH = albert/include # relative include paths + + +FULL_PATH_NAMES = YES # Relative paths in include graph +STRIP_FROM_PATH = .. + +HAVE_DOT = YES +# hide undoc stuff +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = YES +HIDE_IN_BODY_DOCS = YES JAVADOC_AUTOBRIEF = YES LAYOUT_FILE = DoxygenLayout.xml @@ -48,3 +58,16 @@ HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css doxygen-awesome HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 HTML_OUTPUT = src/reference + +#OUTPUT_DIRECTORY = doxy_out +#COLLABORATION_GRAPH = NO +#CLASS_GRAPH = YES + +# Class diagram +#INPUT = ../include ../src +#HIDE_UNDOC_RELATIONS = NO +#UML_LOOK = YES +#CALL_GRAPH = YES +#CALLER_GRAPH = YES + + diff --git a/Makefile b/Makefile index be953ef..dcac316 100644 --- a/Makefile +++ b/Makefile @@ -1,13 +1,17 @@ info: less Makefile +clean: + rm src/Gemfile.lock + docker container rm jekyll + doxygen: rm -rf albert src/reference git clone --depth 1 https://github.com/albertlauncher/albert.git doxygen build: - docker-compose up jekyll-build + docker-compose up --build jekyll-build serve: docker-compose up jekyll-serve diff --git a/docker-compose.yml b/docker-compose.yml index f67c18b..e865781 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,5 +1,3 @@ -version: "3.5" - services: jekyll: &jekyll @@ -16,16 +14,19 @@ services: jekyll-build: <<: *jekyll command: build + container_name: jekyll-build jekyll-serve: <<: *jekyll ports: - 4000:4000 command: serve --host 0.0.0.0 --trace + container_name: jekyll-serve html-proofer: image: klakegg/html-proofer:3.17.0 volumes: - ./src/_site:/src command: --allow-hash-href --check-html --empty-alt-ignore + container_name: html-proofer diff --git a/src/_sass/custom/custom.scss b/src/_sass/custom/custom.scss index 91619d8..541bbea 100644 --- a/src/_sass/custom/custom.scss +++ b/src/_sass/custom/custom.scss @@ -13,4 +13,16 @@ body { //font-size: 1.6em; //font-weight: 300; //text-shadow: 0 1px 3px rgba(0,0,0,0.05); -} \ No newline at end of file +} + +kbd { + border: .5px solid gray; + border-radius: 4px; + box-shadow: 0px 2px 4px gray; + display: inline-block; + font-size: .9em; + padding: 0.1em .5em 0em .5em; + margin: 0em .3em; + color: gray; + white-space: nowrap; +} diff --git a/src/gettingstarted/concepts.md b/src/gettingstarted/concepts.md index 93df486..e69de29 100644 --- a/src/gettingstarted/concepts.md +++ b/src/gettingstarted/concepts.md @@ -1,51 +0,0 @@ ---- -title: Concepts -parent: Getting started -nav_order: 0 ---- - -# {{ page.title }} -{: .no_toc } - -- TOC -{:toc} - -A list of core concepts that help you to grasp things faster. - -## Plugins - -A plugin is a module that can be loaded/unloaded while the launcher is running. -They could be native plugins (shared libraries) or provided by plugin providers, such as Python modules from the Python plugin provider. -Nested plugins are only accessible if their provider is loaded. - -Users can enable/disable or load/unload plugins via the Plugins tab in settings or using the built-in plugin query handler. -Enabled plugins load automatically at launch. -Plugins with graphical interfaces for configuration can be accessed via the Plugins tab. -Some plugins offer more detailed usage information there. - -## Extensions - -Each plugin can provide various extensions, like frontends, plugin providers, fallback providers or query handlers. -While frontends and plugin providers are advanced topics, fallback providers, global- and triggered query handlers are central to the app's functionality. - -## Queries - -The core of the app is the query engine which parses user input and decides the mode of a query. -If the query is prefixed by a trigger defined by any of the trigger query handlers the coresponding handler will handle the query exclusively. -This allows the handler to display matches as soon as they are available. -Queries without triggers are delegated to all global query handlers (multithreaded). -As soon as the handlers finished the matches are sorted by match score and usage history and displayed. -Additionally, fallback handlers offer a separate set of results: the fallback items. - -## TODO -{: .no_toc } - - -- Results - - Matches - - Fallbacks -- Items -- Actions -- Extension interfaces (Concept and builtins) - -If you are missing something here post an issue. \ No newline at end of file diff --git a/src/gettingstarted/extension/index.md b/src/gettingstarted/extension/index.md index 5457540..f6f71f0 100644 --- a/src/gettingstarted/extension/index.md +++ b/src/gettingstarted/extension/index.md @@ -24,14 +24,14 @@ A quick comparison: ## General considerations and best practices -### How to version plugins +### Semantic versioning If it has a public API `major.minor.patch` else `minor.patch`. Increase major if the API breaks. Increase minor if the API got some backward compatible additions or the user experiences noticeable changes. In all other cases increase patch. -### Avoiding name conflicts of extension identifiers +### Avoid extension identifier conflicts If your plugin provides multiple extensions it's a good idea to prepend the plugin id to the extension id to avoid name conflicts of extensions, e.g. `files.root_browser`. The root extension is fine to match the plugin id. diff --git a/src/gettingstarted/install/index.md b/src/gettingstarted/install/index.md new file mode 100644 index 0000000..64ee84d --- /dev/null +++ b/src/gettingstarted/install/index.md @@ -0,0 +1,10 @@ +--- +title: Install +parent: Getting started +nav_order: 0 +has_children: true +--- + +# {{ page.title }} + +Prebuilt packages are available for Linux and macOS. Windows is not supported yet. \ No newline at end of file diff --git a/src/installation.md b/src/gettingstarted/install/linux.md similarity index 60% rename from src/installation.md rename to src/gettingstarted/install/linux.md index 5c57442..dfd4316 100644 --- a/src/installation.md +++ b/src/gettingstarted/install/linux.md @@ -1,22 +1,13 @@ --- -title: Installation +title: Linux +parent: Install +grand_parent: Getting started nav_order: 1 --- -# {{ page.title }} -{: .no_toc } +# Linux -- TOC -{:toc} - -{: .warning } -Unofficial packages may contain malicious code! -Please make sure to use official or trusted repositories. - -## Official packages - -Official packages are built and hosted at [Open Build Service](https://build.opensuse.org/package/show/home:manuelschneid3r/albert). -Downloads and installation instructions for the base distributions can be found in the OBS software center. +Supported distributions, downloads and installation instructions for the base distributions can be found in the Open Build Service software center. [Visit OBS software center](https://software.opensuse.org/download/package.iframe?project=home:manuelschneid3r&package=albert&acolor=00cccc&hcolor=00aaaa){: .btn .fs-5} @@ -34,28 +25,14 @@ Several other distributions are supported when used with the correct package bas | PopOS! 22.04 | Ubuntu 22.04 [ℹī¸](https://en.wikipedia.org/wiki/Pop!_OS#Release_table) | | PopOS! 20.04 | Ubuntu 20.04 [ℹī¸](https://en.wikipedia.org/wiki/Pop!_OS#Release_table) | -{: .note } Feel free to add missing mappings to this table. +The packages are [built](https://build.opensuse.org/package/show/home:manuelschneid3r/albert) and +[hosted](http://download.opensuse.org/repositories/home:/manuelschneid3r/) at Open Build Service. ## Unofficial packages +Feel free to add repositories to this list. + - [ArchLinux AUR](https://aur.archlinux.org/packages/albert) - [nixOS](https://search.nixos.org/packages?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=albert) - -{: .note } -Feel free to add trusted repositories to this list. - -## From source - -Building and installing from sources is the least convenient, but most flexible way. -This way is usually for developers only. -The build process is trivial, but you have to manage the dependencies on your own. -See the [OBS package specs](https://build.opensuse.org/package/show/home:manuelschneid3r/albert) for up to date build and runtime dependencies. - -```bash -git clone --recursive https://github.com/albertlauncher/albert.git -cmake -B build -S albert -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug -cmake --build build -cmake --install build -``` diff --git a/src/gettingstarted/install/macos.md b/src/gettingstarted/install/macos.md new file mode 100644 index 0000000..d7d69b1 --- /dev/null +++ b/src/gettingstarted/install/macos.md @@ -0,0 +1,32 @@ +--- +title: macOS +parent: Install +grand_parent: Getting started +nav_order: 0 +--- + +# macOS + +{: .note } +The macOS version is experimental 🚧 + +Albert is available via [homebrew](https://brew.sh/) tap. +The package is [built](https://github.com/albertlauncher/albert/actions/workflows/ci.yml) +and [hosted](https://github.com/albertlauncher/albert/releases) on GitHub. +The [homebrew tap](https://github.com/albertlauncher/homebrew-albert) +provides a [cask](https://github.com/albertlauncher/homebrew-albert/blob/main/Casks/albert.rb) for Albert. +To install Albert via homebrew run the following commands: + +```bash +brew tap albertlauncher/albert +brew update +brew install albert +``` + +`brew update` and `brew upgrade` will keep the app up to date. + +Note that the packaged app is *not signed*. +Read the caveats section of `brew install`. +For convenience the cask creates an ad-hoc signature and disables Gatekeeper for the app. +See the postflight section of the cask. + \ No newline at end of file diff --git a/src/gettingstarted/install/source.md b/src/gettingstarted/install/source.md new file mode 100644 index 0000000..875dc44 --- /dev/null +++ b/src/gettingstarted/install/source.md @@ -0,0 +1,20 @@ +--- +title: From source +parent: Install +grand_parent: Getting started +nav_order: 2 +--- + +# From source + +Building and installing from sources is the least convenient, but most flexible way. +This way is usually for developers only. +The build process is trivial, but you have to manage the dependencies on your own. +See the [OBS package specs](https://build.opensuse.org/package/show/home:manuelschneid3r/albert) for up to date build and runtime dependencies. + +```bash +git clone --recursive https://github.com/albertlauncher/albert.git +cmake -B build -S albert -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug +cmake --build build +cmake --install build +``` diff --git a/src/gettingstarted/usage.md b/src/gettingstarted/usage.md index f73a0e8..c19c529 100644 --- a/src/gettingstarted/usage.md +++ b/src/gettingstarted/usage.md @@ -10,65 +10,112 @@ nav_order: 1 - TOC {:toc} -There are currently two official interfaces: -The 'Widgets Box Modeland the 'QML Box Model'. -The former uses the Qt Widgets Toolkit, prioritizing resource efficiency and low-latency UIs but has limitations considering customization. -The latter, built on QML, provides rich customization features, but suffers glitches on some systems. -Since both interfaces have the same design concept this guide applies to both of them (Please report a bug if not). - -## Input line - -Besides its primary function, the input line provides an input hint and contains the settings button. -The input hint, displayed after the entered text, varies based on the context. -For empty triggered queries, it shows the query handler's synopsis, if available, otherwhise it shows the input action text of the selected item, if available, or is empty. -The settings button, located in the top right corner, appears on hover or when the current query is processing. - -## Input history search - -The content entered into the input line is stored in the input history when the window is hidden. -This input history can be used to search former queries. -When the input has been manually altered, it functions as a pattern for substring matching within the history entries. -The empty pattern matches any entry (browsing instead of search). -When the results list is hidden or the first item is selected âŦ† searches the input history. -When holding Shift this condition is not required and âŦ‡ can be used too for bidirectional iteration. - -## Results list - -The results list displays results of a query. -Each item has an icon, a title and a description. -Almost all items have at least one action associated, which can be directly activated. -Most items provide several actions that can be activated using the action list. -Items may also provide an input action text that can be used to replace the input text. -Its semantic is loosely defined. +## User interface + +Note: The following uses [Qt terminology](https://doc.qt.io/qt-6/qt.html#KeyboardModifier-enum) for modifier key names. +The following table shows the mapping of modifier keys on different keyboards: + +| Qt | Linux/Win | MacOS | +|-----------------|-----------------|------------------------------------| +| Ctrl | Ctrl | command /⌘ | +| Meta | Win | control /⌃ | +| Alt | Alt | option /âŒĨ | + + + + +### Input line + +Besides its primary function, the input line provides an *input hint* and contains the *settings button*. + +The **input hint**, displayed after the entered text, varies based on the context. +For empty triggered queries, it shows the query handler's *synopsis*, if available, otherwise it shows the *input action text* of the selected item, if available, or is empty. + +The **settings button** is located in the top right corner of the input line. +It appears on mouse hover and also serves as **busy indicator** e.g. when the current query is processing. +On click it opens the **settings window**. + +The manually entered text of the input line is stored in the **input history** when the window is hidden. +This input history can be used to search and browse your past input. +When the results list is hidden or the first item is selected âŦ† iterates the input history in reverse order. + +Holding Shift enables the **input history navigation** mode. +In this mode the mentioned conditions for âŦ† to iterate the history are not required. +and âŦ‡ can be used for bidirectional iteration as well. + +If enabled, the (manually set) input text is used for **input history search**. +Input history navigation then only shows input history entries matching the input text. + + +### Results list + +The results list displays results items of a query. +Hold and release Meta to switch between **match items** and **fallback items**. + +Items can provide an **input action text** which is used to replace the input text on pressing Tab. +Its semantic is loosely defined. It may be a completion but also an evaluation or something else. -The results list has three states: Hidden, show matches and show fallbacks. -If a query yields matches it shows the matches. -If a global query yields no matches it shows the fallbacks. -If a triggered query yields no matches it stays hidden. -The fallbacks state can also be activated explicitly. -## Key map +### Actions list + +Result items can have multiple associated *actions*. +The **default action** of an item is activated by pressing Return or Enter. +To display and navigate the list of **alternative actions** of an item hold Alt . + + +### Key map As a reference the following table lists the keys you can use to control Albert: -Key | Action -------------- | ------------- -Esc | Hide Albert. -Hold Alt/âŒĨ
Ctrl/⌘+⏎ | Activate action mode. -Hold Meta/⌃ | Activate Fallback mode. -Hold Shift | Activate history search mode. -Tab | Activate input action of the selected item (evaluation, completion, etc). -⏎
Enter
⌘+O | Activate item. -Ctrl/⌘+, | Open settings window. -âŦ†,âŦ‡,
PgUp,PgDn | Navigation in item lists. -⌘+Q
Alt+F4 | Quit Albert (Depends on settings). -Ctrl/⌘+H
Ctrl/⌘+J
Ctrl/⌘+K
Ctrl/⌘+L | Vim bindings. Synthesize to arrows. -Ctrl/⌘+N
Ctrl/⌘+P | Emacs bindings. Synthesize to arrows. - -## TODO -{: .no_toc } +| Key | Action | +|---------------------------------------------------------------------|----------------------------------------------------------------------------| +| Esc | Hide Albert. | +| Alt (Hold) | Activate action mode. | +| Meta (Hold) | Activate fallback mode. | +| Shift (Hold) | Activate history search mode. | +| Tab | Activate input action of the selected item (evaluation, completion, etc). | +| Return,Enter | Activate item. | +| Ctrl+, | Open settings window. | +| âŦ†,âŦ‡,
PgUp,PgDn | Navigation in item lists. | +| Alt+F4,⌘+Q | Quit Albert (Depends on settings). | +| Ctrl+H/J/K/L | Vim bindings. Synthesize to arrows. | +| Ctrl+N/P | Emacs bindings. Synthesize to arrows. | + + +## Plugins and extensions + +A **plugin** is a physical module that can be loaded/unloaded at runtime. +It could be native or provided by plugin provider plugins. +Nested plugins are accessible when their provider is loaded. + +Users can **enable**/**disable** or **load**/**unload** plugins via the plugins tab in the settings +or using the built-in plugin query handler. +Enabled plugins load automatically at launch. +Plugins with graphical interfaces for configuration can be accessed via the plugins tab in the settings. + +An **extensions** is a logical module that can be provided by a plugin to add functionality. +Each plugin can provide multiple extensions. +While query and fallback handlers are central to the app's functionality, +there are other extension interfaces that plugins can provide. +More on this topic can be found in the [Extension](/gettingstarted/extension/) section. + + +## Queries + +The core of the app is the query engine which parses user input and determines the **mode of a query**. + +If the input starts with a trigger of a **trigger query handler**, the query engine instantiates a +**trigger query** execution that is exclusively handled by the corresponding handler. +This allows the handler to *asynchronously* add matches and as such define their *order*. + +If the user input does *not* start with a trigger of a trigger query handler, the query engine +instantiates a **global query** execution that executes the enabled **global query handlers** *in parallel* +and eventually gathers and *sorts* their matches. + +Both query executions eventually yield a set of **query matches** which may be empty. + +The **fallback handlers** of a query provide a separate set of result items, the **query fallbacks**, +which can handle any string. +They are displayed when no matches were found or when the user explicitly requests them. -- Input action (completion, evaluation, â€Ļ) -- Items and actions -- Fallbacks diff --git a/src/index.md b/src/index.md index 69665d3..b249112 100644 --- a/src/index.md +++ b/src/index.md @@ -14,7 +14,7 @@ And let Albert take care of the noise.
- +