From 7a9b29dc1167367e3d601cf2e73c6e43904f6b42 Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Thu, 5 Mar 2026 20:55:56 +0200 Subject: [PATCH 01/10] Add AI Bible Study Assistant documentation Comprehensive user documentation for the AI/LLM feature covering: - Provider setup (10 providers) and API key configuration - Built-in prompts (translate, explain, summary, Strong's, word study) - AI tools (10 read, 9 write) and permission system - Custom prompt creation and CSV sharing - Cache management and cost tracking - Cloud sync behavior for AI data --- docs/source/ai.rst | 460 +++++++++++++++++++++++++++++++++++++ docs/source/cloud_sync.rst | 9 +- docs/source/index.rst | 1 + 3 files changed, 468 insertions(+), 2 deletions(-) create mode 100644 docs/source/ai.rst diff --git a/docs/source/ai.rst b/docs/source/ai.rst new file mode 100644 index 0000000..7caad38 --- /dev/null +++ b/docs/source/ai.rst @@ -0,0 +1,460 @@ +AI Bible Study Assistant +======================== + +|app| includes a built-in AI assistant that can translate, explain, summarize, +annotate, and perform word studies on Bible text. It works by sending selected +text to an external AI provider and displaying the result directly in the app. + +.. note:: + + The AI assistant requires an internet connection and an API key from a + supported provider. Usage may incur costs depending on your chosen provider + and model. + +.. warning:: + + When you use an AI prompt, the selected text is sent to your chosen external + AI provider for processing. Do not use this feature with content you wish to + keep private. + + +Getting Started +--------------- + +Choosing a Provider +^^^^^^^^^^^^^^^^^^^ + +|app| supports the following AI providers: + +.. list-table:: + :header-rows: 1 + :widths: 20 50 30 + + * - Provider + - Description + - Notes + * - **Google Gemini** + - Google's AI models. Good starting point with a generous free tier. + - Recommended for beginners + * - **OpenAI (ChatGPT)** + - The company behind ChatGPT. + - + * - **Anthropic (Claude)** + - Maker of the Claude family of models. + - + * - **xAI (Grok)** + - AI models from xAI. + - + * - **Mistral** + - European AI provider with efficient models. + - + * - **DeepSeek** + - Cost-effective models with strong multilingual capabilities. + - + * - **Groq** + - Extremely fast inference with open-source models. + - + * - **Alibaba Cloud (Qwen)** + - Chinese AI provider with multilingual models. + - + * - **OpenRouter** + - Aggregator that provides access to models from many providers through a + single API key. + - Convenient for trying different models + * - **Custom** + - Connect to any OpenAI- or Anthropic-compatible API endpoint. + - For self-hosted or other providers + +If you are new to AI services, **Google Gemini** is a good starting point +because it offers a free usage tier that is sufficient for casual use. + +Getting an API Key +^^^^^^^^^^^^^^^^^^ + +To use the AI assistant, you need an API key from your chosen provider: + +#. Visit the provider's API key console (|app| provides direct links in the + setup screen). +#. Create an account if you don't have one. +#. Generate a new API key. +#. Copy the key -- you will paste it into |app|. + +.. note:: + + API keys are stored securely on your device. They are **never** included + in backups or synchronized to the cloud. + +Adding a Provider +^^^^^^^^^^^^^^^^^ + +#. Open the top left main menu (|hamburger|). +#. Tap ``AI Settings``. +#. Tap ``Configure Connection``. +#. Tap ``Add provider``. +#. Select your provider from the list. +#. Paste your API key. +#. Choose a model (a sensible default is pre-selected). +#. Tap ``Save``. + +The first provider you add becomes the default. You can change this later. + +Multiple Providers +^^^^^^^^^^^^^^^^^^ + +You can configure multiple providers simultaneously. This is useful if you +want to use a cheaper model for simple tasks (like translation) and a more +capable model for complex tasks (like word studies). + +The first provider is used by default. Individual prompts can be configured to +use a specific provider, overriding the default. + + +Using AI Prompts +---------------- + +Prompts are instructions that tell the AI what to do with your selected text. +|app| comes with several built-in prompts and allows you to create your own. + +Built-in Prompts +^^^^^^^^^^^^^^^^ + +|app| includes six built-in prompts: + +**Translate to [UI language]** + Translates Bible text into the language your app interface is set to. If a + translation in that language is already installed, it can use it directly + instead of generating a new translation. + +**Translate to English** + Translates Bible text into English. Like the above, it can use an installed + English Bible when available. + +**Summary** + Creates a concise summary of the selected passage with theological focus. + +**Explain Verses** + Explains the meaning, context, and theological significance of selected + verses in depth. + +**Strong's Annotation** + Adds Strong's concordance numbers to Bible text by comparing it with a + reference translation (KJV). Useful for translations that lack Strong's + numbers. + +**Word Study** + Analyzes the original Hebrew or Greek words in the selected text, providing + definitions, usage patterns, and links to dictionary entries. + +Where Prompts Appear +^^^^^^^^^^^^^^^^^^^^ + +AI prompts are available in several places throughout the app. Each prompt is +configured to appear in the contexts where it is most useful: + +**LLM Mode (document display)** + Process an entire chapter or document through AI. Enable by selecting an + LLM Mode prompt in the window's text display settings. The result replaces + the document view. + +**Verse selection** + When you tap a verse and the verse action dialog appears, available AI + prompts are shown as action buttons. + +**Text selection** + When you select text by long-pressing and dragging, AI prompts appear in the + context menu. + +**Window menu** + Some prompts are accessible from the window's popup menu (long-press the + window button at the bottom of the screen). + +**Workspace menu** + Some prompts appear in the workspace toolbar's three-dot menu. + +**Note editor** + When editing a bookmark note, AI prompts can assist with writing. + +Running a Prompt +^^^^^^^^^^^^^^^^ + +**Example: Explaining a verse** + +#. Tap a verse to open the verse action dialog. +#. Tap the ``Explain Verses`` button. +#. The AI processes your request and displays the result. + +**Example: Using LLM Mode for a whole chapter** + +#. Long-press the window button at the bottom of the screen. +#. Tap ``Text Options``, then ``All Text Options``. +#. Under the LLM Mode section, select a prompt (e.g. ``Translate``). +#. The entire chapter is processed through the selected prompt. + +**Example: Word study on selected text** + +#. Long-press a word in the Bible text to start a text selection. +#. Extend the selection if needed. +#. Tap ``Word Study`` from the context menu. + +The Agent Log +^^^^^^^^^^^^^ + +When an AI prompt runs, a log panel shows the progress in real time. You can +see: + +* Which tools the AI is calling (e.g. reading verses, looking up dictionaries) +* Permission requests for write operations +* Token usage and estimated cost + +You can cancel a running prompt at any time by tapping the cancel button. + + +AI Tools +-------- + +AI prompts can use *tools* -- specialized functions that let the AI read data +from your app or make changes. This is what allows the AI to look up cross- +references, search your Bible, read your bookmarks, and more. + +Read Tools +^^^^^^^^^^ + +Read tools retrieve information without making any changes. They do not require +permission. + +* **Read verse content** -- Retrieve the text of any verse or chapter from any + installed Bible translation. +* **Search Bible** -- Search for verses containing specific keywords. +* **Read commentaries** -- Look up commentary on specific verses from installed + commentary modules. +* **Look up dictionary entry** -- Look up entries in installed dictionaries and + lexicons (e.g. Strong's, Robinson's). +* **Get bookmarks for verse** -- Retrieve your bookmarks at a specific verse. +* **Get bookmarks with label** -- Get all bookmarks assigned to a specific label. +* **List all labels** -- Get a list of all your labels. +* **Read study pad content** -- Read entries from a study pad. +* **Search study pads** -- Search study pad entries by keyword. +* **List installed documents** -- Get a list of installed Bibles, commentaries, + and dictionaries. + +Write Tools +^^^^^^^^^^^ + +Write tools can create or modify data in your app. They are subject to the +:ref:`ai:Permissions` system. + +* **Create bookmark** -- Create a new bookmark at a verse, optionally with a + note. +* **Add bookmark note** -- Add a note to an existing bookmark. +* **Update bookmark note** -- Modify an existing bookmark's note. +* **Create label** -- Create a new label for organizing bookmarks and study pads. +* **Add label to bookmark** -- Assign a label to a bookmark. +* **Add study pad entry** -- Add a text entry to a study pad. +* **Set document title** -- Set the title for an AI-generated document. +* **Open study pad** -- Complete the task and open a specified study pad. +* **Finish without document** -- End the task without producing a document + (for action-only prompts that create bookmarks, etc.). + + +Permissions +----------- + +Write tools require your permission before the AI can use them. This ensures +the AI cannot modify your data without your knowledge. + +.. note:: + + Read tools never require permission. Only write tools (creating bookmarks, + adding notes, etc.) are gated by the permission system. + +Permission Modes +^^^^^^^^^^^^^^^^ + +There are four permission modes: + +**Always ask** (default) + The AI asks for your permission every time it wants to use a write tool. + A dialog shows what the tool will do and lets you approve or deny. + +**Ask once per run** + The AI asks permission the first time it uses a write tool during a prompt + run. After you approve, subsequent write operations in the same run proceed + without asking. + +**Allow all** + All write operations are allowed automatically without asking. Use this only + if you fully trust the prompt. + +**Deny all** + All write operations are denied automatically. The AI can only read data. + +Setting Permissions +^^^^^^^^^^^^^^^^^^^ + +Permissions can be configured at three levels: + +#. **Global default** -- In ``AI Settings`` > ``Configure Connection`` > + ``Manage tool permissions``. This sets the default behavior for all prompts. +#. **Per-prompt** -- When editing a custom prompt, you can set a permission mode + that overrides the global default for that prompt. +#. **Per-tool** -- In the global tool permissions dialog, you can set individual + tools to "Always allow" or "Always deny", overriding the mode-based + behavior. + + +Custom Prompts +-------------- + +Creating a Custom Prompt +^^^^^^^^^^^^^^^^^^^^^^^^ + +You can create your own prompts for specialized tasks: + +#. Open the top left main menu (|hamburger|). +#. Tap ``AI Settings``. +#. Tap the ``+`` button. +#. Fill in the prompt details: + + * **Name** -- A short name shown in menus. + * **Description** -- What the prompt does (shown in the prompt list). + * **Template** -- The instructions sent to the AI. This is the core of your + prompt. + * **Contexts** -- Where this prompt should appear (verse selection, text + selection, window menu, etc.). + * **Provider and model** -- Optionally override which provider and model to + use for this prompt. + +#. Tap ``Save``. + +Editing Built-in Prompts +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Built-in prompts cannot be modified directly. To customize one: + +#. Open the built-in prompt you want to modify. +#. Use the ``Copy to customize`` option. +#. Edit the copy as needed and save. + +Prompt Template Tips +^^^^^^^^^^^^^^^^^^^^ + +* **Be specific** -- Clearly describe what you want the AI to do and what + format the output should be in. +* **Mention tools** -- If you want the AI to look up commentaries or + dictionaries, mention it in the prompt. For example: "Look up relevant + commentary entries to support your explanation." +* **Define the output format** -- Specify whether you want bullet points, + paragraphs, a table, or other formats. +* **Set the language** -- If you want output in a specific language, say so + explicitly. + +Sharing Prompts (CSV) +^^^^^^^^^^^^^^^^^^^^^ + +Custom prompts can be exported and imported as CSV files, making it easy to +share your prompts with other |app| users: + +* **Export** -- From the prompt list, use the export option to save your custom + prompts to a CSV file. +* **Import** -- Use the import option to load prompts from a CSV file. + + +Cache and Cost Management +------------------------- + +Cache +^^^^^ + +AI results are cached locally so that the same request does not consume +additional API tokens. For example, if you translate Genesis 1 and then +navigate away and come back, the cached result is displayed instantly. + +The cache can be managed in ``AI Settings`` > ``Configure Connection`` > +``Cache``: + +* **Browse** cached entries with details (document, verse, prompt type, model, + date, size). +* **Filter** by document, processing type, or model. +* **Delete** entries individually, by filter, by age (older than 7, 30, or 90 + days), or all at once. + +.. note:: + + The cache is stored only on the device and is not synchronized to the cloud. + +Cost Tracking +^^^^^^^^^^^^^ + +|app| tracks token usage and provides estimated costs for each provider: + +* **Token counts** -- Input tokens (text sent to the AI), output tokens + (text received), and cache tokens are tracked separately. +* **Estimated cost** -- Calculated based on each model's published pricing. +* **Per-provider breakdown** -- Each configured provider shows its own usage + and cost. +* **Reset** -- You can reset the usage counters at any time. + +View cost tracking in ``AI Settings`` > ``Configure Connection`` under the +Usage section. + +.. note:: + + Cost estimates are approximate. Always check your provider's billing + dashboard for actual charges. + + +Cloud Sync +---------- + +When :doc:`cloud_sync` is enabled, the following AI data is synchronized: + +* **Synced:** Custom prompts and provider configurations (provider type, + model selection, endpoint settings). +* **Not synced:** API keys, cache, and usage/cost data. + +API keys remain on each device for security. You need to enter your API key +separately on each device. + + +Tips and Troubleshooting +------------------------- + +Recommended Setup for Beginners +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Start with **Google Gemini** -- it has a free tier that is sufficient for + trying out the AI features. +#. Try the **Explain Verses** prompt first -- tap a verse and select it from + the verse action dialog. +#. Keep the permission mode set to **Always ask** until you are comfortable + with how the AI uses tools. + +Reducing Costs +^^^^^^^^^^^^^^ + +* Use a smaller, cheaper model for simple tasks like translation. +* Use a more capable (and expensive) model only for complex tasks like word + studies. +* Configure multiple providers and assign them to specific prompts. +* The cache prevents duplicate API calls -- avoid clearing it unnecessarily. + +Common Issues +^^^^^^^^^^^^^ + +**"API key invalid" or authentication errors** + Double-check that your API key is entered correctly. Visit your provider's + console to verify the key is active. + +**Slow responses or timeouts** + AI responses can take several seconds, especially for longer passages or + complex prompts. Check your internet connection if responses consistently + fail. + +**Unexpected or low-quality results** + Try a more capable model, or refine your prompt to be more specific about + what you want. Different models have different strengths. + +**Higher costs than expected** + Check which model you are using -- larger models cost significantly more. + Review the cost tracking in AI Settings to identify which prompts consume + the most tokens. Consider switching to a smaller model for routine tasks. diff --git a/docs/source/cloud_sync.rst b/docs/source/cloud_sync.rst index 0c24814..5938edb 100644 --- a/docs/source/cloud_sync.rst +++ b/docs/source/cloud_sync.rst @@ -63,10 +63,15 @@ What Gets Synced **Workspaces** (toggle: Workspaces) Workspace configurations, window layouts, and current document positions. +**AI settings** (synced with Workspaces) + Custom AI prompts and provider configurations (provider type, model, + endpoint). API keys, cache, and usage data are **not** synced -- you need + to enter your API key on each device separately. See :doc:`ai` for details. + **Not synced:** Bible and commentary modules themselves are not synced. - Download your modules separately on each device. App settings and preferences - are also not synced. + Download your modules separately on each device. App settings, preferences, + AI API keys, and AI cache are also not synced. How Sync Works -------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 9a4d0f2..7c5fe75 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,6 +20,7 @@ Contents :caption: Contents: getting_started + ai backup_restore bible_links bookmarks From 406ac3ebf7f1e62e740132d2436da7bc4c362fe1 Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Fri, 6 Mar 2026 18:29:00 +0200 Subject: [PATCH 02/10] Add My Documents and Markdown editor documentation - New page: my_documents.rst covering document/page management, content formats, and cloud sync - Updated notes.rst with editor format setting, HTML editor section, and new Markdown editor section --- docs/source/index.rst | 1 + docs/source/my_documents.rst | 63 ++++++++++++++++++++++++++++++++++++ docs/source/notes.rst | 51 +++++++++++++++++++++++++++-- 3 files changed, 113 insertions(+), 2 deletions(-) create mode 100644 docs/source/my_documents.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 7c5fe75..bb60977 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -33,6 +33,7 @@ Contents labels look_and_feel memorize + my_documents navigation notes reading_plans diff --git a/docs/source/my_documents.rst b/docs/source/my_documents.rst new file mode 100644 index 0000000..727c764 --- /dev/null +++ b/docs/source/my_documents.rst @@ -0,0 +1,63 @@ +My Documents +============ + +|app| allows you to create your own custom documents, such as personal study +guides, sermon outlines, or reference notes. These documents appear alongside +Bibles and commentaries in the document library and can be opened in any window. + +Creating a Document +------------------- + +#. From the top left main menu (|hamburger|), click ``My Documents``. +#. Click the ``+`` button to create a new document. +#. Enter a name for your document and click ``OK``. + +Managing Documents +------------------ + +From the My Documents screen you can: + +- **Reorder** documents by dragging them up or down. +- **Rename** a document via the popup menu (long-press or three-dot menu). +- **Edit description** to add a short summary of the document's contents. +- **Delete** a document via the popup menu (requires confirmation). + +Managing Pages +-------------- + +Each document contains one or more pages. Click a document to open its page +list. + +- **Add a page** by clicking the ``+`` button. +- **Reorder** pages by dragging. +- **Rename** or **delete** a page via its popup menu. +- **Click a page** to open it in a document window for viewing. + +Content Formats +--------------- + +My Document pages support three content formats: + +- **Markdown** (default) -- Write using Markdown syntax. See + :doc:`notes` for more about the Markdown editor. +- **HTML** -- Raw HTML content. +- **OSIS** -- Bible markup format for advanced use cases. + +The content format for each page is shown in the page list. + +Opening Documents +----------------- + +My Documents are available in the document library alongside other book types. +To open a document in a window: + +#. Open the document library (click and hold the document name in the top menu + bar, or use the main menu). +#. Find your document under the ``Generic Books`` section. +#. Click the document to open it. + +Cloud Sync +---------- + +My Documents are included in :doc:`cloud sync `, so your documents +and their contents are synchronized across devices. diff --git a/docs/source/notes.rst b/docs/source/notes.rst index a6e561b..44dd248 100644 --- a/docs/source/notes.rst +++ b/docs/source/notes.rst @@ -110,7 +110,31 @@ Editing a note To edit a note, simply :ref:`view a note` and click into the note to start editing. When editing a note, changes are saved automatically. -Notes support rich formatting similar to word processing applications. +Notes support rich formatting. |app| offers two editor types: an **HTML editor** +and a **Markdown editor**. You can choose which editor is used for new notes in +the settings. + +.. _notes-editor-setting: + +Choosing the Editor Format +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. From the top left main menu (|hamburger|), click ``Settings``. +#. Under the notes settings, find ``Format for new bookmark notes``. +#. Select either **HTML** or **Markdown**. + +This setting applies to newly created notes and study pad entries. Existing +notes keep the format they were created with. + +HTML Editor +^^^^^^^^^^^ + +The HTML editor provides a toolbar with standard formatting options: + +- **Bold**, **Italic**, **Underline** +- Ordered and unordered **lists** +- **Indentation** (increase / decrease) +- **Bible reference link** insertion To add a Bible reference link: @@ -120,4 +144,27 @@ To add a Bible reference link: .. image:: ./images/note_editing.png :align: left - :scale: 60% \ No newline at end of file + :scale: 60% + +Markdown Editor +^^^^^^^^^^^^^^^ + +The Markdown editor lets you write notes using Markdown syntax. It provides a +formatting toolbar and a live text editing area. + +The toolbar includes: + +- **Heading** selector (H1--H3) +- **Bold**, **Italic**, **Underline** +- Ordered and unordered **lists** +- **Indentation** (increase / decrease) +- **Undo / Redo** +- **Bible reference link** insertion + +The editor also supports these conveniences: + +- **Auto-list continuation**: pressing Enter on a list item creates the next + item automatically. +- **Auto-save**: changes are saved automatically after a short delay. +- **Keyboard shortcuts**: Ctrl+Z for undo, Ctrl+Y (or Ctrl+Shift+Z) for redo, + Escape to close the editor. \ No newline at end of file From 84f52abaebee477f273f3c5f1fdf19564dc335f2 Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Fri, 6 Mar 2026 18:47:31 +0200 Subject: [PATCH 03/10] Add gestures and shortcuts section to navigation docs Covers swipe behavior configuration, double-tap fullscreen, fullscreen by scrolling, volume keys scrolling, and long-press actions. --- docs/source/navigation.rst | 54 +++++++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/docs/source/navigation.rst b/docs/source/navigation.rst index 95ac84c..02fec95 100644 --- a/docs/source/navigation.rst +++ b/docs/source/navigation.rst @@ -138,4 +138,56 @@ on the book reference section of the top main toolbar: :alt: Open the workspaces dialog :height: 400 -For more information about managing workspaces, see :doc:`Workspaces`. \ No newline at end of file +For more information about managing workspaces, see :doc:`Workspaces`. + +Gestures and Shortcuts +---------------------- + +|app| supports a variety of gestures and shortcuts for efficient navigation. + +Swipe Left/Right on Bible Text +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can swipe left or right on the Bible text to navigate. The behavior can be +configured in ``Settings`` > ``Application behavior`` > ``Action for swipe +left/right gesture``: + +- **Chapter** (default) -- Navigate to the next or previous chapter. +- **Page** -- Scroll by one page (like tapping the margin). +- **Disabled** -- Swiping has no effect on the Bible text. + +Double-Tap to Fullscreen +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Double-tap the Bible text to enter fullscreen mode, which hides the toolbar and +status bar for distraction-free reading. Double-tap again to exit fullscreen. + +This feature is enabled by default and can be toggled in ``Settings`` > +``Application behavior`` > ``Double-tap to fullscreen``. + +Fullscreen by Scrolling +^^^^^^^^^^^^^^^^^^^^^^^ + +When enabled, the app automatically enters fullscreen mode when you start +scrolling the text, and exits fullscreen when you scroll back to the top. + +To enable: ``Settings`` > ``Application behavior`` > ``Fullscreen by +scrolling``. + +Volume Keys Scrolling +^^^^^^^^^^^^^^^^^^^^^ + +By default, the device volume buttons scroll the Bible text up and down instead +of adjusting the system volume. This is useful for hands-free reading. + +To disable: ``Settings`` > ``Application behavior`` > ``Volume keys scroll``. + +Long-Press Actions +^^^^^^^^^^^^^^^^^^ + +Several buttons support long-press for quick access to additional features: + +- **Back button** -- Open the navigation history list. +- **Speak toolbar button** -- Open speak settings directly. +- **Window button** (in the bottom bar) -- Minimize the window instantly. +- **Verse location title** (top of screen) -- Jump to the document selector. \ No newline at end of file From c55b6d3c4a11b52483dd4d94bfca73e036d82fca Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Fri, 6 Mar 2026 18:48:20 +0200 Subject: [PATCH 04/10] Expand look and feel documentation - Reorganize application settings into subsections (general, e-ink, font, fullscreen, one-tap actions, study pad) - Add night mode, note editor format, study pad click-to-edit docs - Expand workspace text display settings with detailed descriptions for all formatting and appearance options --- docs/source/look_and_feel.rst | 159 ++++++++++++++++++++++++---------- 1 file changed, 115 insertions(+), 44 deletions(-) diff --git a/docs/source/look_and_feel.rst b/docs/source/look_and_feel.rst index b2d9c1a..40bf243 100644 --- a/docs/source/look_and_feel.rst +++ b/docs/source/look_and_feel.rst @@ -9,34 +9,76 @@ Application To configure application-wide look and feel settings (which are not synced to other devices), navigate to the top left main menu (|hamburger|) and click -`Application preferences`. Some options that you can use to customize the look -and feel of the application are: - - - **Application language:** Choose the language you would like the application - to use in dialogs, settings, etc. - - **Black & white mode:** Enabling this setting reduces the use of colors. - This is useful for e-ink displays. - - **Disable animations:** Enabling this setting will reduce animations that - may not work well on e-ink or very old devices. - - **Font size multiplier:** Changing this setting will scale document text - sizes. It can be useful for devices with larger screens. Since application - settings are not synced, this can be configured per-device. This setting will - multiply the workspace and/or window font size settings (which are synced). - - **Hide window button bar in fullscreen:** Enabling this setting will hide - the bottom window buttons when in fullscreen mode - giving you a distraction-free - fullscreen view. - - **Hide window buttons:** Enabling this setting will hide the menu buttons - that are displayed at the top right of each window. You can long-click the - buttons in the window button bar at the bottom of the screen to access the - menu for each window. - - **Hide Bible reference overlay:** Enabling this setting will hide the Bible - reference overlay that would otherwise be displayed near the bottom of the - screen when in fullscreen mode. - - **Show active window indicator:** Enabling this setting will highlight window - corners of the active window in the reading pane. This makes it easier to see - which window is the active window. - - **One-tap actions (Bibles/Other):** You can configure what context menu items - are visible when selecting text in Bibles or other documents. +``Settings``. These settings apply to the local device only. + +General +^^^^^^^ + +- **Application language:** Choose the language for the application interface + (dialogs, menus, settings). +- **Night mode:** Control when the dark theme is used: + + - *Manual* (default) -- toggle dark mode from the three-dot menu. + - *Automatic* -- switch based on time of day. + - *System* -- follow the Android system dark mode setting (Android 10+). + +- **Format for new bookmark notes:** Choose whether new :doc:`notes ` + are created with the **HTML** editor or the **Markdown** editor. Existing + notes keep the format they were created with. + +E-Ink Displays +^^^^^^^^^^^^^^ + +- **Black & white mode:** Reduces the use of colors throughout the application. + Recommended for e-ink displays where color rendering is limited. +- **Disable animations:** Turns off smooth scrolling and transition animations. + Improves responsiveness on e-ink screens and very old devices. + +These two settings work well together for an optimal e-ink reading experience. + +Font and Text +^^^^^^^^^^^^^ + +- **Font size multiplier:** A global scaling factor (10%--500%) applied to all + document text. Useful when you synchronize workspaces across devices with + different screen sizes -- the workspace font size is synced, but the + multiplier is per-device. For example, setting 150% on a small phone while + leaving 100% on a tablet keeps text proportional. + +Fullscreen and Window Display +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- **Hide window button bar in fullscreen:** Hides the bottom window buttons + when in fullscreen mode for a distraction-free view. +- **Hide window buttons:** Hides the menu buttons at the top right of each + window. You can still access the window menu by long-pressing the buttons in + the bottom window bar. +- **Hide Bible reference overlay:** Hides the semi-transparent Bible reference + indicator that normally appears near the bottom of the screen in fullscreen + mode. +- **Show active window indicator:** Highlights the corners of the active window + with a colored border. Makes it easier to see which window is currently + active when using multiple windows side by side. + +One-Tap Actions +^^^^^^^^^^^^^^^ + +When you tap on a verse or text, a quick action bar appears. You can customize +which buttons are shown in this bar: + +- **One-tap actions (Bibles):** Configure which actions appear when tapping + text in Bible documents. Available actions include: Bookmark, Bookmark with + note, My Notes, Share, Compare, Speak, and Memorize. +- **One-tap actions (Other documents):** Configure which actions appear for + non-Bible documents (commentaries, books, etc.). Available actions include: + Bookmark, Bookmark with note, and Speak. + +Study Pad +^^^^^^^^^ + +- **Disable Study Pad click-to-edit:** When enabled, notes in Study Pads can + only be edited by tapping the edit button, not by clicking on the note text + directly. This prevents accidental edits while reading. .. image:: ./images/application_look_and_feel.png :align: center @@ -48,22 +90,51 @@ Workspace To configure the look and feel of individual workspaces, click on the three dot kebab menu on the top right of your workspace. From there click on `All Text Options`. -Various appearance options can be changed: - - - Color Settings - - Workspace color - - Text color - - Background color & Background noise - - Font size - - Font family - - Margin size - - Top margin - - Line spacing - - Red Letter - - One verse per Line - - Justify-align text - - Hyphenation - - Relative page number +Various appearance options can be changed. These settings are synced across +devices. + +Formatting +"""""""""" + +- **Section titles:** Show non-canonical section titles added by translators. +- **Title scroll button:** Show a small button next to section titles that + scrolls to the top of the section when tapped. +- **Verse numbers:** Show or hide chapter and verse numbers. +- **Footnotes:** Show footnotes if available in the document. Optionally + display them inline rather than in a popup. +- **Cross references:** Show cross-reference markers. Optionally expand them + inline to see referenced text directly. +- **Strong's numbers:** Show links to Greek and Hebrew dictionary definitions. +- **Morphological codes:** Show Robinson's Greek morphology codes. +- **Italicize added words:** Italicize words that do not have Strong's numbers + associated with them. Useful for translations like KJV where added words are + traditionally shown in italics. +- **Infinite scroll:** Automatically load more content when you scroll to the + end of a chapter. + +Text Appearance +""""""""""""""" + +- **Colors:** Adjust text color, background color, and background noise + (a subtle texture overlay on the background). +- **Font size:** Set the base text size in points. +- **Font family:** Change the typeface. Additional fonts can be installed via + font add-on modules. +- **Margin size:** Set the left and right margins independently, measured in + millimeters. You can also set a maximum text width to prevent lines from + becoming too long on wide screens. +- **Top margin:** Add a margin at the top of the window (in millimeters). The + reading position starts below this margin. +- **Line spacing:** Adjust the space between lines (multiplier from 1.0x to + 2.0x). +- **Paragraph spacing:** Adjust the space between paragraphs (in millimeters). +- **Red letter:** Show the words of Christ in red. +- **One verse per line:** Display each verse on a separate line. +- **Justify text:** Align text to both left and right margins. +- **Hyphenation:** Automatically hyphenate words at line breaks (if supported + by the language). +- **Relative page number:** Show a page number overlay indicating your position + relative to where you started reading. .. image:: ./images/workspace_appearance.png :align: center From 8f24764013c6e549bae4480d1a9cd2ee736403dc Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Fri, 6 Mar 2026 18:48:37 +0200 Subject: [PATCH 05/10] Add earcon sounds, sleep timer, and Bluetooth sections to speak docs --- docs/source/speak.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/source/speak.rst b/docs/source/speak.rst index 5fc0d23..8f0f163 100644 --- a/docs/source/speak.rst +++ b/docs/source/speak.rst @@ -48,3 +48,30 @@ How to speak a range of verses :align: center :alt: Speak Settings +Earcon Sounds +------------- + +Earcon sounds are short audio cues that play during speech to indicate +transitions in the text. The speak settings let you enable or disable earcon +sounds for: + +- **Chapter changes** -- a sound plays when a new chapter begins. +- **Titles** -- section titles added by translators are read aloud. +- **Footnotes** -- footnotes included in the Bible text are read aloud. + +Sleep Timer +----------- + +The sleep timer automatically stops playback after the specified number of +minutes. This is useful when listening to the Bible before falling asleep. Set +the timer in the Speak settings dialog by entering the number of minutes. + +Bluetooth Media Buttons +----------------------- + +|app| can respond to Bluetooth media buttons (play/pause on headsets, +car audio systems, etc.) to start and stop text-to-speech playback. + +This feature is enabled by default. To disable it, go to ``Settings`` > +``Advanced`` > ``Enable Bluetooth media buttons``. + From dfb3104dfe341ab70f6a930fe81a35297f2af52f Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Fri, 6 Mar 2026 18:48:51 +0200 Subject: [PATCH 06/10] Add Bible links section to sharing docs Cross-references bible_links.rst for deep link sharing. --- docs/source/share.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/source/share.rst b/docs/source/share.rst index 0044d9e..17b689e 100644 --- a/docs/source/share.rst +++ b/docs/source/share.rst @@ -53,4 +53,13 @@ Sharing Bibles/Documents It is also possible to share other |app| documents. See :doc:`/backup_restore` for details on backing up documents that can then be shared with other -|app| users. \ No newline at end of file +|app| users. + +Sharing Bible Links +------------------- + +You can share a direct link to a specific Bible passage using the +``https://read.andbible.org/`` URL format. When another |app| user opens the +link, it opens the passage directly in the app. + +For more details on the link format and options, see :doc:`/bible_links`. \ No newline at end of file From f141b1e259161c793bf2dd8d59619babc84e309e Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Fri, 6 Mar 2026 20:27:17 +0200 Subject: [PATCH 07/10] Add experimental features documentation --- docs/source/experimental_features.rst | 70 +++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 71 insertions(+) create mode 100644 docs/source/experimental_features.rst diff --git a/docs/source/experimental_features.rst b/docs/source/experimental_features.rst new file mode 100644 index 0000000..a6427e7 --- /dev/null +++ b/docs/source/experimental_features.rst @@ -0,0 +1,70 @@ +Experimental Features +===================== + +|app| includes a number of experimental features that are still in development. +These features may change, be improved, or be removed in future versions. You +can enable or disable them individually. + +.. note:: + + Experimental features are disabled by default. Enable only the ones you want + to try -- they may have rough edges or incomplete functionality. + + +Enabling Experimental Features +------------------------------ + +#. Open the top left main menu (|hamburger|). +#. Tap ``Settings``. +#. Scroll down to ``Advanced Settings``. +#. Tap ``Experimental features``. +#. Check the features you want to enable. +#. Tap ``OK``. + + +Available Features +------------------ + +LLM Mode (AI Text Processing) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When enabled, this feature unlocks the full :doc:`AI assistant ` +functionality. You must also have a configured AI provider for AI features to +appear. + +Once enabled: + +* An **LLM Mode** prompt selector appears in the window's text display settings, + allowing you to process entire chapters through AI (e.g. translate or + annotate a whole chapter at once). +* **AI action buttons** appear in verse selection, text selection, and window + menus. + +See :doc:`ai` for full details on setting up a provider, using prompts, and +managing costs. + +.. note:: + + This feature requires both the experimental feature toggle **and** a + configured AI provider. If either is missing, AI options will not appear. + + +Add Paragraph Break Bookmark +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Adds a **Paragraph break** option to the verse context menu. When used, it +creates a special bookmark that inserts a visual paragraph break before the +selected verse. + +This is useful for adjusting the paragraph layout of Bible texts where the +original formatting does not match your reading preference. The breaks are +stored as bookmarks with a special internal label and are visible as extra +spacing between verses. + + +Bookmark Edit Actions +^^^^^^^^^^^^^^^^^^^^^ + +Adds edit action controls to bookmarks. When enabled, you can assign an +**Append** or **Prepend** action to a bookmark, which allows adding custom +content before or after the bookmarked verse in the Bible view. diff --git a/docs/source/index.rst b/docs/source/index.rst index bb60977..c9f477c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -29,6 +29,7 @@ Contents customisation/index discrete_build documents + experimental_features faq labels look_and_feel From 34efeb096c3259e41391da319a63e726cc69a155 Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Sat, 7 Mar 2026 18:50:37 +0200 Subject: [PATCH 08/10] Rename LLM Mode to AI Text Processing in documentation --- docs/source/ai.rst | 10 +++++----- docs/source/experimental_features.rst | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/ai.rst b/docs/source/ai.rst index 7caad38..8ff9eaf 100644 --- a/docs/source/ai.rst +++ b/docs/source/ai.rst @@ -151,10 +151,10 @@ Where Prompts Appear AI prompts are available in several places throughout the app. Each prompt is configured to appear in the contexts where it is most useful: -**LLM Mode (document display)** +**AI Text Processing (document display)** Process an entire chapter or document through AI. Enable by selecting an - LLM Mode prompt in the window's text display settings. The result replaces - the document view. + AI Text Processing prompt in the window's text display settings. The result + replaces the document view. **Verse selection** When you tap a verse and the verse action dialog appears, available AI @@ -183,11 +183,11 @@ Running a Prompt #. Tap the ``Explain Verses`` button. #. The AI processes your request and displays the result. -**Example: Using LLM Mode for a whole chapter** +**Example: Using AI Text Processing for a whole chapter** #. Long-press the window button at the bottom of the screen. #. Tap ``Text Options``, then ``All Text Options``. -#. Under the LLM Mode section, select a prompt (e.g. ``Translate``). +#. Under the AI Text Processing section, select a prompt (e.g. ``Translate``). #. The entire chapter is processed through the selected prompt. **Example: Word study on selected text** diff --git a/docs/source/experimental_features.rst b/docs/source/experimental_features.rst index a6427e7..2ac51d1 100644 --- a/docs/source/experimental_features.rst +++ b/docs/source/experimental_features.rst @@ -25,8 +25,8 @@ Enabling Experimental Features Available Features ------------------ -LLM Mode (AI Text Processing) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +AI Text Processing +^^^^^^^^^^^^^^^^^^^ When enabled, this feature unlocks the full :doc:`AI assistant ` functionality. You must also have a configured AI provider for AI features to @@ -34,9 +34,9 @@ appear. Once enabled: -* An **LLM Mode** prompt selector appears in the window's text display settings, - allowing you to process entire chapters through AI (e.g. translate or - annotate a whole chapter at once). +* An **AI Text Processing** prompt selector appears in the window's text display + settings, allowing you to process entire chapters through AI (e.g. translate + or annotate a whole chapter at once). * **AI action buttons** appear in verse selection, text selection, and window menus. From d0e72e5b1320b1d93e1e4e7de44d6b3af88d7d4d Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Fri, 13 Mar 2026 18:55:11 +0200 Subject: [PATCH 09/10] Add 'Available Data and Documents' section to AI documentation Explains what data the AI agent can access (installed modules, personal data) and how to write effective prompts that leverage the tools. --- docs/source/ai.rst | 85 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/docs/source/ai.rst b/docs/source/ai.rst index 8ff9eaf..a5fb442 100644 --- a/docs/source/ai.rst +++ b/docs/source/ai.rst @@ -255,6 +255,91 @@ Write tools can create or modify data in your app. They are subject to the * **Finish without document** -- End the task without producing a document (for action-only prompts that create bookmarks, etc.). +.. tip:: + + You can view all available tools and their descriptions directly in the app + by opening the **Available tools** menu item in the prompt editor. + + +Available Data and Documents +---------------------------- + +The AI agent can access a wide range of data through its tools. Understanding +what data is available helps you write more effective prompts. + +Installed Bible Modules +^^^^^^^^^^^^^^^^^^^^^^^ + +The AI has access to **all installed modules** on your device: + +* **Bible translations** -- Any installed Bible version (e.g. KJV, ESV, NIV). + The AI can read and compare text across multiple translations. +* **Commentaries** -- All installed commentary modules. The AI can look up + commentary entries for specific verses. +* **Dictionaries and lexicons** -- Including Strong's concordance, Robinson's + morphological codes, and any other installed dictionary modules. These + allow in-depth word studies. + +.. tip:: + + The more modules you have installed, the richer data the AI can work with. + Installing additional commentaries, dictionaries, and translations gives the + AI more resources for answering your questions. + +Cross-Referencing Capabilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The AI can combine information from multiple sources in a single response: + +* **Translation comparison** -- Compare how different Bible versions render + the same passage. +* **Commentary + dictionary integration** -- Read a verse, look up commentary, + then look up individual words in a lexicon -- all in one prompt. +* **Word studies** -- Follow a chain from a verse to its Strong's numbers to + dictionary definitions to find the original meaning. +* **Bible text search** -- Search for verses containing specific keywords across + installed translations. + +Your Personal Data +^^^^^^^^^^^^^^^^^^ + +The AI can also access your personal study data: + +* **Bookmarks** -- Find bookmarks at specific verses or by label. +* **Labels** -- List all your labels for organizing and filtering. +* **Notes** -- Read bookmark notes you have written. +* **Study pads** -- Read and search study pad content. + +Writing Effective Prompts +^^^^^^^^^^^^^^^^^^^^^^^^^ + +To get the most out of the AI agent, mention the specific actions you want it +to perform. The AI uses its tools based on your instructions. + +**Refer to capabilities by name:** + +* "Look up what Matthew Henry's commentary says about this verse" +* "Search for all verses mentioning 'grace' in KJV" +* "Find the Strong's dictionary entry for the main Greek word in this verse" +* "Check my bookmarks with the 'Study' label" + +**Combine multiple tools:** + +* "Compare this verse in KJV, ESV, and NIV, then look up the commentary" +* "Read this passage, look up the key Greek words in Strong's dictionary, and + summarize the findings in a study pad" + +**Specify the output format:** + +* "Create a study pad with a verse-by-verse analysis" +* "Add a bookmark note summarizing the cross-references" +* "Give a brief answer without creating any documents" + +**Ask for sources:** + +* "Include verse references for all claims" +* "Cite which commentary or dictionary you are quoting" + Permissions ----------- From 4a96810218d80b5d5180a0945d859b3e1408cf6c Mon Sep 17 00:00:00 2001 From: Tuomas Airaksinen Date: Wed, 18 Mar 2026 10:27:04 +0200 Subject: [PATCH 10/10] Document 3-level text display settings hierarchy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for the global text options level and the global → workspace → window inheritance chain. Update look_and_feel, workspaces, and windows pages with cross-references and visual indicator explanations. --- docs/source/look_and_feel.rst | 148 +++++++++++++++++++++++++++------- docs/source/windows.rst | 43 ++++++---- docs/source/workspaces.rst | 23 ++++-- 3 files changed, 164 insertions(+), 50 deletions(-) diff --git a/docs/source/look_and_feel.rst b/docs/source/look_and_feel.rst index 40bf243..28b379e 100644 --- a/docs/source/look_and_feel.rst +++ b/docs/source/look_and_feel.rst @@ -1,15 +1,66 @@ Look and Feel ============= -The look and feel of |app| can be configured for the entire application, for -specific workspaces, specific windows, or even individual modules. - -Application ------------ - -To configure application-wide look and feel settings (which are not synced to -other devices), navigate to the top left main menu (|hamburger|) and click -``Settings``. These settings apply to the local device only. +The look and feel of |app| can be configured at several levels: for the entire +application, as global defaults, for specific workspaces, for individual +windows, or even for particular modules. + +.. _settings-hierarchy: + +Text display settings hierarchy +------------------------------- + +Text display settings (formatting, fonts, colors, etc.) follow a three-level +hierarchy. Each level inherits from the one above it, so you only need to +change a setting at the level where you want it to differ. + +#. **Global defaults** -- apply to all workspaces and windows everywhere. +#. **Workspace settings** -- override global defaults for one workspace and all + its windows. +#. **Window settings** -- override the workspace setting for one specific + window. + +When you change a setting at a higher level, all lower levels that have not +been explicitly overridden will automatically follow the change. For example, +if you set the global font size to 16 pt and a workspace has no font size of +its own, it uses 16 pt. If you then change the global font size to 14 pt, that +workspace (and all its windows) will switch to 14 pt as well. + +A setting that has been explicitly set at a lower level is called an +**override**. Overrides are not affected by changes at higher levels. For +example, if you set a workspace font size to 18 pt, changing the global font +size will not affect that workspace. You can remove an override at any time to +go back to inheriting from the parent level. + +**Visual indicators** in the text options screens show where each setting comes +from: + +- |settings_gear| **Settings gear icon** -- the setting is inherited from + global defaults. +- |workspace_icon| **Gray workspace icon** -- you are editing a workspace + default (affects all its windows). +- |workspace_green| **Green workspace icon** -- the window setting is using the + workspace default. +- **No icon** -- the setting has been explicitly changed at this level + (overrides the parent). + +.. |settings_gear| unicode:: U+2699 +.. |workspace_icon| unicode:: U+25A0 +.. |workspace_green| unicode:: U+25A1 + +You can navigate between levels directly from the text options screen. At the +window level, links to the workspace and global settings are shown at the top. +At the workspace level, a link to the global settings is shown. This makes it +easy to see and adjust settings at every level without leaving the settings +screen. + +Application settings +-------------------- + +To configure application-wide settings (which are not synced to other devices), +navigate to the top left main menu (|hamburger|) and click ``Settings``. These +settings apply to the local device only and are separate from the text display +settings hierarchy described above. General ^^^^^^^ @@ -84,14 +135,44 @@ Study Pad :align: center :scale: 30% -Workspace ---------- +.. _global-text-options: + +Global text options +------------------- + +Global text options are the default text display settings for all workspaces. +Any workspace or window that has not explicitly overridden a setting will use +the global value. + +To access global text options: + +- From a **workspace** text options screen, tap the **Global text options** + link at the top. +- From a **window** text options screen, tap the **Global text options** link + at the top. + +When you change a global setting, the change is immediately reflected in every +workspace and window that is still inheriting that setting. Workspaces or +windows that have their own override are not affected. + +Global text options are synced across devices. + +The available settings are the same as those described in the `Formatting`_ and +`Text Appearance`_ sections below. -To configure the look and feel of individual workspaces, click on the three dot -kebab menu on the top right of your workspace. From there click on `All Text Options`. +.. _workspace-text-options: -Various appearance options can be changed. These settings are synced across -devices. +Workspace text options +---------------------- + +To configure the look and feel of an individual workspace, click on the three +dot kebab menu on the top right of your workspace. From there click on +``All Text Options``. + +Workspace text options override the global defaults for that workspace and all +its windows. These settings are synced across devices. + +.. _formatting-options: Formatting """""""""" @@ -112,6 +193,8 @@ Formatting - **Infinite scroll:** Automatically load more content when you scroll to the end of a chapter. +.. _text-appearance-options: + Text Appearance """"""""""""""" @@ -140,21 +223,28 @@ Text Appearance :align: center :scale: 30% -Window ------- -When using multiple windows, you can even customize the individual window text -options to override current workspace settings. To change window text options: +.. _window-text-options: + +Window text options +------------------- + +When using multiple windows, you can customize the text options of each +individual window to override the workspace settings. To change window text +options: + + #. Tap and hold the square window icon at the bottom for the window you + would like to customize. + #. Click ``Text Options``, then click ``All Text Options``. - #. Tap and hold the square window icon at the bottom for the window you would - like to customize. - #. Click `Text Options`, then click `All Text Options`. +All of the same options that you could configure at the `workspace +`_ level can be overridden for the selected window. +In the screenshot below you can see that the window color settings are +overriding the workspace color settings (indicated by the missing workspace +icon). To reset all window settings back to the workspace defaults, you can +click the circular back arrow at the top right of the window settings screen. -All of the same options that you could configure in `Workspace`_ can be overridden -for the selected window. In the screenshot below you can see that the window -`Color settings` are overriding the workspace `Color settings`. To indicate this, -there is no workspace icon on the `Color settings` icon). To reset all window -settings back to the workspace settings, you can click the circular back arrow -at the top right of the window settings screen. +From the window text options screen you can also navigate directly to the +workspace or global text options using the links at the top of the screen. .. image:: ./images/window_appearance.png :align: center @@ -162,7 +252,7 @@ at the top right of the window settings screen. Module ------ -For things that can not be changed through application, workspace, or window +For things that can not be changed through global, workspace, or window settings, like the color of certain text within a module, e.g. Headings or Strong's numbers, you can code the color in the style.css file located within the module's zip package. You can see some examples of this being implemented here: diff --git a/docs/source/windows.rst b/docs/source/windows.rst index 4a2cbac..9640eb3 100644 --- a/docs/source/windows.rst +++ b/docs/source/windows.rst @@ -42,24 +42,37 @@ Reposition the window by using the 'Move To' menu option. A window has many customisation settings. The most recently used settings appear in the pop-up menu. But you can access all window settings via the 'All-text-options' menu item. -It's important to understand the difference between workspace-settings and window-settings. These settings are nearly the same so it's easy to get them confused. - -* Workspace-settings are accessed via the dot menu at the top right of the screen. -* Workspace-settings have the gray-workspace-icon. -* Workspace-settings apply to ALL windows. - -Now for Window settings. They are accessed via the window-buttons. - -* Window-settings have either a green-workspace-icon or no icon at all. -* Window-settings will use the workspace-setting unless you have changed it to something different. - -So, if you want to change the appearance of all windows, change the workspace-setting. But if you only want one window to look different, change the window-setting. +Text display settings follow a three-level hierarchy: **global defaults → +workspace settings → window settings**. Each level inherits from the one above +it. For a full explanation of how this works, see :ref:`settings-hierarchy`. + +Here is a quick summary of the difference between the levels: + +* **Global settings** set the defaults for all workspaces and windows. Access + them via the link at the top of any workspace or window text options screen. +* **Workspace settings** override global defaults for one workspace and all its + windows. Access them via the dot menu at the top right of the screen. They + are shown with a gray workspace icon. +* **Window settings** override the workspace setting for one specific window. + Access them via the window buttons. They show either a green workspace icon + (using workspace default), a settings gear icon (inherited from global), or + no icon (explicitly changed). + +So, if you want to change the appearance of all windows everywhere, change the +global setting. If you want all windows in one workspace to look different, +change the workspace setting. If you only want one window to look different, +change the window setting. Some examples: -* I want the cross-reference window only to have a different background color. So I change the window-setting. -* I want all other windows to have a different background color. So I change the workspace-setting. This won't affect the window I just changed because setting the color at the Window-level overrides the workspace-setting. -* And finally I want all windows to have a smaller font-size. So I change the font-size workspace-setting. +* I want the cross-reference window only to have a different background color. + So I change the window setting. +* I want all other windows to have a different background color. So I change + the workspace setting. This won't affect the window I just changed because + setting the color at the window level overrides the workspace setting. +* I want all windows everywhere to have a smaller font size. So I change the + global setting. This affects every workspace and window that has not been + individually overridden. .. raw:: html diff --git a/docs/source/workspaces.rst b/docs/source/workspaces.rst index a05648d..63840d1 100644 --- a/docs/source/workspaces.rst +++ b/docs/source/workspaces.rst @@ -25,17 +25,28 @@ Access the list of workspaces via the 'dot' menu or by swiping down on the verse * create new workspaces * and delete existing ones -The Settings option allows you to edit the default settings for all windows in the workspace. +The Settings option allows you to edit the default text display settings for all +windows in the workspace. These workspace settings override the +:ref:`global defaults `, and in turn can be overridden by +individual window settings. -The **gray workspace** icon indicates you are changing a workspace default setting. +The **gray workspace** icon indicates you are changing a workspace default +setting. .. warning:: - These settings affect all windows in the workspace that are using the defaults. + These settings affect all windows in the workspace that are using the + defaults. -A **green workspace** icon indicates that this window setting *is* using the default workspace setting. +A **green workspace** icon indicates that this window setting *is* using the +default workspace setting. A **settings gear** icon indicates the setting is +inherited from global defaults. -If there is no green-workspace-icon, then the setting has been changed manually and the workspace settings won't affect it. -Restore it to the default by pushing the Reset button. +If there is no icon, then the setting has been changed manually and changes at +higher levels won't affect it. Restore it to the default by pushing the Reset +button. + +For more details on how settings are inherited, see +:ref:`settings-hierarchy`. :doc:`Easily navigate between workspaces using gestures. `