diff --git a/docs/source/ai.rst b/docs/source/ai.rst new file mode 100644 index 0000000..a5fb442 --- /dev/null +++ b/docs/source/ai.rst @@ -0,0 +1,545 @@ +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: + +**AI Text Processing (document display)** + Process an entire chapter or document through AI. Enable by selecting an + 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 + 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 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 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** + +#. 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.). + +.. 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 +----------- + +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/experimental_features.rst b/docs/source/experimental_features.rst new file mode 100644 index 0000000..2ac51d1 --- /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 +------------------ + +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 **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. + +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 9a4d0f2..c9f477c 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 @@ -28,10 +29,12 @@ Contents customisation/index discrete_build documents + experimental_features faq labels look_and_feel memorize + my_documents navigation notes reading_plans diff --git a/docs/source/look_and_feel.rst b/docs/source/look_and_feel.rst index b2d9c1a..28b379e 100644 --- a/docs/source/look_and_feel.rst +++ b/docs/source/look_and_feel.rst @@ -1,89 +1,250 @@ 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 -`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. +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 +^^^^^^^ + +- **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 :scale: 30% -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 +.. _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. + +.. _workspace-text-options: + +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 +"""""""""" + +- **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-options: + +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 :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 @@ -91,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/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/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 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 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 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``. + 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. `