mig5/bouquin
1
0
Fork 0
Code Issues Pull requests Releases 54 Wiki Activity Actions

Update Help

Miguel Jacq 2025-12-12 18:20:16 -06:00
parent 909b718725
commit fb2f92a80d
1 changed files with 4 additions and 243 deletions
Download patch file Download diff file Expand all files Collapse all files

247
Help.md

@ -1,248 +1,9 @@
# Bouquin Documentation # Bouquin Documentation
## Keyboard Shortcuts _Sidebar
Bouquin supports various keyboard shortcuts: Welcome to the Bouquin documentation!
### Actions Please use the Sidebar on the right to view specific sections of the documentation.
- **Ctrl+S**: Save the notebook If you don't see an answer to your issue, please contact mig5 using the 'Report a bug' feature in Bouquin, or on the Fediverse (https://goto.mig5.net/@mig5)
- **Ctrl+F**: Find text on the current page
- **Ctrl+Shift+H**: Open the History dialog for a given date to view versions and diff/revert
- **Ctrl+Shift+.**: Open settings
- **Ctrl+Shift+E**: Export the notebook to different formats
- **Ctrl+Shift+B**: Backup the notebook to an encrypted database (that can be loaded by Bouquin again directly)
- **Ctrl+Shift+P**: Go to previous day
- **Ctrl+Shift+N**: Go to next day
- **Ctrl+Shift+T**: Go to today
- **Ctrl+W**: Close current tab
- **Ctrl+Shift+S**: Open Statistics
- **Ctrl+Shift+D**: Open this documentation page
- **Ctrl+Shift+R**: Report a bug
- **Ctrl+Shift+L**: Lock the screen immediately
- **Ctrl+Shift+U**: Unlock the screen
- **Ctrl+Q**: Quit the application
### Styling
- **Ctrl+B**: Set selected text to bold
- **Ctrl+I**: Set selected text to italic
- **Ctrl+-**: Set selected text to strikethrough
- **Ctrl+1**: Set selected text to h1 (heading)
- **Ctrl+2**: Set selected text to h2 (heading)
- **Ctrl+3**: Set selected text to h3 (heading)
- **Ctrl+.**: Set selected text to normal size (paragraph)
- **Ctrl+Shift+-**: Decrease size of normal text
- **Ctrl+Shift++**: Increase size of normal text
- **Ctrl+`**: Set selected text to be in a ```<code>``` block
#### Code blocks
If you generate a code block, you can right-click on it to set a desired code language. This will apply some very basic syntax highlighting to the code block. Not all code language syntax is supported.
#### Checkboxes
It's possible to add checkboxes into the editor.
You can also start a line with the word TODO (in capitals) and it will automatically convert that word into a checkbox.
#### Moving unchecked checkboxes from previous days
Do you like to move any TODOs that were unfinished from yesterday to your list of today's TODOs?
There is an option for that in the settings. When turned on, any unchecked checkboxes in the last 7 day's notes will be automatically moved to the next weekday after the last day's unchecked TODO. This occurs on startup or on rollover of midnight.
## Navigating by date
You can select any date in the calendar and it will jump to that date.
The act of jumping to a new date automatically saves whatever current date you were on, so there is no need to save first.
You can also right-click on a date in the calendar and open it in a new tab. If that date is already open in a tab, it will jump to that tab instead.
## Saving, History and version control
### History and version control
Bouquin supports versioning. Every time you save a page/date, it stores a new version of that page. The previous version remains in the database.
You can click on 'View History' from the toolbar, or via the **File -> History** navigation, or via `Ctrl+Shift+H`, to open the History dialog.
This will display a list of versions for the page, with the version number, timestamp and a 'note' about the change.
On the right will be a preview pane that shows that version of the page.
There is also a 'Diff' tab which will show all the differences between the current version and the version you have selected in the left pane.
You can click on 'Revert to Selected' to revert to an older or newer version of the page. Your current version will still be in the database, so you can always revert 'back to the future' if you change your mind :)
If you wish, you can also select one or more revisions and click Delete to delete them (you cannot delete the latest revision).
### Autosave vs explicit save
Every 10 seconds, Bouquin will autosave the page if there were any unsaved changes. This will be given the note 'autosave' in the version history.
If you explicitly press `Ctrl+S` or via the **File -> Save** navigation, you will be prompted to optionally set a version note. You can either accept the default which has a reasonably meaningful message, or give it a meaningful note of your own.
## Images
You can choose the Image icon from the toolbar to insert an image into the page.
## Alarms/Reminders
You can use the alarm clock button to schedule a reminder for the day. When you do this, Bouquin will reclaim focus on your screen, with a pop-up flashing a reminder based on the text you entered.
You can configure Reminders to reoccur daily, weekly, or only on weekdays.
Use the Reminders widget in the left sidebar to view 7 days of upcoming reminders. You can click on the hamburger icon in that widget to manage old and upcoming reminders. You can also right-click on reminders from the widget to delete them.
## Searching for data
You can enter terms into the search bar in the left sidebar.
If there is a matching entry for that term in the database, a preview box will appear underneath the search bar, showing a preview of that matching term, on the respective date. The matching term will be highlighted in bold to help you notice it.
Clicking on the previewed item will jump to that date.
If there are multiple dates with a match, these will be listed underneath each other, with the date shown at the start of each matching item.
**Note:** when searching for data, only the current version of the page is searched (not previous revisions/versions).
You can also search for text on the current page by pressing **Ctrl+F** or Navigate -> Find on page. This will open a search bar at the bottom of the page. You can set it to be case sensitive (it is case-insensitive by default) and scroll through matches. The matched word will be highlighted on the page.
## Tagging
### Tag widget in the sidebar
You can add tags to a page via the collapsed 'Tags' widget in the left sidebar. If the tag already exists, it will auto-complete as you type. Each tag gets its own hex colour.
When a page is tagged, searching in the Search sidebar tool for that tag will also return the page that has that tag.
### Tag Browser
You can click on a tag to open the Tag Browser (or press **Ctrl+T**). From there, you can:
* Add new tags (without yet assigning them to a page)
* Rename tags
* Change the colour of tags
* Expand a tag to see a list of dated pages which have that tag. Double-clicking on the date will open that page.
### Disabling Tag feature
If you have no need for the Tagging feature and find it a distraction on the screen, you can disable the feature in the Settings.
## Time Log
### Projects and Activities
It is possible to record time for each day. The Time Log Manager lets you define 'Projects' and 'Activities'. An activity can be associated with any project.
Once you have projects and activities, you can record time against them. Typing in an activity will auto-complete from the known list. You can rename activities and projects.
### Editing time entries
You can click on a cell in the time table to modify its value as well. If you modify the name of the project or activity to something that didn't previously exist, that will implicitly add that as a new project or activity.
Use decimals for time entries, where '1' represents one hour. E.G, 0.25 is 15 minutes, 0.33 is 20, 0.42 is 25, 0.58 is 35, 0.83 is 50, and so on.
Once you close the time dialog, the summary of the time spent will update automatically in the sidebar with a breakdown of time per project, and a total.
### Notes
You can also leave a note when recording the time for that activity. For example, if you had an activity called 'Meetings', you could record 1 hour with a note 'Meeting with Marco'.
### Pomodoro timer
Enter some text in the editor and click on ⌛ in the toolbar to start a Pomodoro-style running timer.
Once you are finished doing your work, you can click Stop and Log. This will present the Time log screen with the text that was in your editor as the 'note' and the elapsed time. It should round the timer up to the closest 15 minutes to the hour. You can then choose the Project and Activity under which to log the elapsed time.
### Reporting and exporting timesheets
You are able to run a report of time across a date range for a specific project. It is possible to set the granularity of the report to day, week or month.
Once you have generated a report, you can export it to either CSV or PDF. The PDF export shows a graph but it is less detailed than the CSV, the latter of which also contains the notes associated with the time entries.
### Disabling Time Log feature
If you have no need for the Time Log feature and find it a distraction on the screen, you can disable the feature in the Settings.
## Settings
In the File -> Settings dialog, it is possible to:
- Configure the **theme** (dark, light or system mode)
- Configure the **font size** (this applies to all pages)
- Change the **language** (currently English, French and Italian supported). You must restart the app to load in the new selected language
- **Remember the encryption key**. Doing so means that you aren't prompted for it at startup (**WARNING**: this means the encryption key is written to the application settings on the disk! It could be exfiltrated by various means if the filesystem is accessible to an attacker. Only check this option if you are not concerned with this risk.)
- **Change the encryption key**. This will prompt for a new passphrase and will re-encrypt the database with that passphrase.
- **Configure the auto-lock timeout**. The default setting is to lock the notepad if it has been idle (no key presses) for 15 minutes, after which time you must re-enter the password. You can set to 0 (Never) to turn off the auto-lock feature.
- **Compact** the database. This runs the SQLite3 command `VACUUM` against the database, which can de-fragment it and reduce its size.
- Configure whether to **move previous unchecked TODOs to the next weekday** at startup. This means that any unchecked checkboxes from the last 7 days will be automatically *moved* to the next weekday (e.g today, or if it is the weekend, the following Monday).
## Export options
Currently, the following formats are supported for export (these are all *unencrypted* data exports!):
- JSON
- CSV
- HTML
- Markdown
- SQL (plaintext format suitable for loading with SQLite3)
Set the appropriate extension when prompted to save the exported file.
Note: only the SQL option exports the full version history. The other formats export just the current version of pages. Also note that the .sql file is not a 'flat file' plaintext backup: rather, it's am unencrypted database you can open with a regular 'sqlite3' command or DBMS.
## Backup and Restore
If you choose the **Backup** option, this will export the Bouquin database in its *encrypted* format. _This database cannot be read by native SQLite3_, only by the SQLCipher variant (which you can install on some distributions, such as Debian).
Because it is encrypted with SQLCipher, this means you can also load such a backup into Bouquin as a way of 'importing' the database. To do this, choose the backup file from Settings as the path to the database or edit the path to the database in the configuration file directly (see below).
## Location of data
### Config file
The settings typically get written to `~/.config/Bouquin/Bouquin.conf`.
### Database file
The default database for your notebook is stored in `~/.local/share/Bouquin/Bouquin/notebook.db`. This is an encrypted SQLCipher database, you can't open it with a normal `sqlite` CLI tool or other DBMS.
You can choose a different database file to open when starting the application (unless you have set Bouquin to remember the Encryption key). Bouquin remembers this path and saves it in the config file so that you don't have to keep selecting that database each time you start the application.
If you have set Bouquin to remember the Encryption key but wish to open a different database, first open Bouquin, navigate to the Settings and uncheck 'Remember Encryption key'. Next time you open the app, you'll be prompted for both the database path and the key as normal.
## Upgrading
Click on Help -> Version to use the button 'Check for Updates'.
If there is a new version available, it will offer to download the AppImage for you. (If you are using pip or poetry, you wouldn't want to use this option, you can use those tools to update your local installations).
After the AppImage is downloaded to your 'Downloads' folder, it will also verify the signature. The GPG public key is baked into the app itself, and (if you want to put it in your keychain or compare it) is the same as the one at https://mig5.net/static/mig5.asc.
## Troubleshooting
### xcb library missing
Do you get this error when trying to start Bouquin?
```
qt.qpa.plugin: From 6.5.0, xcb-cursor0 or libxcb-cursor0 is needed to load the Qt xcb platform plugin.
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.
Available platform plugins are: vnc, eglfs, offscreen, wayland-brcm, wayland-egl, wayland, minimal, linuxfb, vkkhrdisplay, minimalegl, xcb.
Aborted
```
Make sure you have `libxcb-cursor0` installed (on Debian-based distributions) or `xcb-util-cursor` (RedHat/Fedora-based distributions).