doc: adds upgrade instructions (#198).

Author: HugoFara

docs-src/.vitepress/config.ts

@@ -54,6 +54,7 @@ export default defineConfig({
           items: [
             { text: 'Introduction', link: '/guide/getting-started' },
             { text: 'Installation', link: '/guide/installation' },
+            { text: 'Upgrading', link: '/guide/upgrade' },
             { text: 'Post-Installation', link: '/guide/post-installation' }
           ]
         },

docs-src/changelog.md

@@ -14,6 +14,10 @@ ones are marked like "v1.0.0-fork".
 
 ### Added
 
+* **Notes Field for Terms** ([#128](https://github.com/HugoFara/lwt/issues/128)):
+  Added a dedicated "Notes" field to terms/words, allowing users to add personal
+  notes separate from translations. Includes database migration, updated entity
+  classes, service layer, UI forms, and API endpoints.
 * Official support for PHP 8.3 and 8.4.
 * **Multi-user support** ([#221](https://github.com/HugoFara/lwt/issues/221)):
   Users are now stored in a dedicated `users` table with proper foreign key
@@ -69,9 +73,28 @@ ones are marked like "v1.0.0-fork".
 * **TTS Settings Storage** ([#186](https://github.com/HugoFara/lwt/issues/186)):
   Text-to-Speech language settings (voice, rate, pitch) now use browser localStorage
   instead of cookies. Includes automatic migration from old cookie format.
+* **Removed SYSTEM_VARIABLES_ADMIN Privilege Requirement**
+  ([#167](https://github.com/HugoFara/lwt/issues/167)): LWT no longer requires
+  elevated database privileges for word imports. The `SET GLOBAL max_heap_table_size`
+  call has been removed and replaced with chunked batch inserts (500 rows per batch)
+  that stream files line-by-line, reducing memory usage for large imports.
 
 ### Fixed
 
+* **Tag Duplicate Key Error** ([#120](https://github.com/HugoFara/lwt/issues/120)):
+  Fixed rare error when updating a word with tags. When the session cache was
+  stale, saving a word with an existing tag would fail with "Duplicate entry
+  for key 'TgText'" and remove the tag from the word. Changed tag insertion
+  to use `INSERT IGNORE` to handle race conditions and stale cache gracefully.
+* **Japanese Annotations** ([#101](https://github.com/HugoFara/lwt/issues/101)):
+  Fixed annotations not displaying correctly in Japanese texts. The
+  `annotationToJson()` function was using an off-by-one index that didn't
+  match the `Ti2Order` values used by the frontend, causing approximately
+  50% of annotations to fail to display.
+* **Text Parsing** ([#114](https://github.com/HugoFara/lwt/issues/114)): Fixed
+  last word of text not being recognized when text ends without punctuation.
+  Words at the end of a text are now correctly identified regardless of trailing
+  punctuation.
 * **PHP 8.3 Compatibility**: Fixed deprecation warnings in `langFromDict()` and
   `targetLangFromDict()` - both functions now check for null query strings before
   calling `parse_str()`.
@@ -81,6 +104,10 @@ ones are marked like "v1.0.0-fork".
 * **SQL Prefix Queries**: Fixed `prefixQuery()` in database migrations:
   * Now handles `DROP TABLE IF EXISTS` syntax (previously only `IF NOT EXISTS`).
   * Now case-insensitive for SQL keywords (CREATE, DROP, ALTER, INSERT).
+* **Punctuation Formatting** ([#125](https://github.com/HugoFara/lwt/issues/125)):
+  Fixed punctuation marks (periods, commas, quotation marks) breaking away from
+  adjacent words onto separate lines. Punctuation now stays "stuck" to the word
+  it belongs to by wrapping word+punctuation pairs in non-breaking groups.
 
 ### Security
 
@@ -103,6 +130,24 @@ ones are marked like "v1.0.0-fork".
   user-based multi-tenancy. Existing prefixed tables will be migrated to the
   new system automatically.
 
+### Removed
+
+* **Orphaned Frame Settings** ([#116](https://github.com/HugoFara/lwt/issues/116)):
+  Removed all legacy frame-related settings from the admin settings page:
+  * `set-text-h-frameheight-no-audio` - Frame height without audio
+  * `set-text-h-frameheight-with-audio` - Frame height with audio
+  * `set-text-l-framewidth-percent` - Width of left frames (text)
+  * `set-text-r-frameheight-percent` - Height of right frame (text)
+  * `set-test-h-frameheight` - Frame height (test)
+  * `set-test-l-framewidth-percent` - Width of left frames (test)
+  * `set-test-r-frameheight-percent` - Height of right frame (test)
+
+  These settings controlled frame dimensions in the text reading and test
+  interfaces, but became non-functional after the iframe-based layout was
+  replaced with Alpine.js components ([#166](https://github.com/HugoFara/lwt/issues/166)).
+  Also removed the dead `initFrameResizable()` function from TypeScript.
+  Closes #116.
+
 ## 2.10.0-fork (April 1 2024)
 
 ### Added in 2.10.0-fork

docs-src/guide/installation.md

@@ -229,17 +229,12 @@ The official repository is at <https://packagist.org/packages/hugofara/lwt>.
 
 ## Upgrade LWT
 
-1. Backup the LWT directory. Backup your database (within LWT).
+Already have LWT installed? See the [Upgrading Guide](./upgrade.md) for detailed instructions on how to safely upgrade to a newer version, including:
 
-2. Get the [latest GitHub release](https://github.com/HugoFara/lwt/releases).
-
-   You can also try to download the [latest stable version](https://github.com/HugoFara/lwt/archive/refs/heads/main.zip) if you want the cutting-edge updates (that may include some bugs)
-
-3. Unzip it.
-
-4. Copy the following (if not already at its place and OK) from your LWT backup into the LWT directory: ".env" and the whole "media" sub-directory (if you created one; contains your MP3 audio files).
-
-5. Clear the web browser cache and open LWT as usual.
+- Backup procedures
+- Automatic database migrations
+- Upgrading from very old versions
+- Troubleshooting common issues
 
 ## Something Went Wrong
 

docs-src/guide/upgrade.md

@@ -0,0 +1,169 @@
+# Upgrading LWT
+
+This guide covers how to upgrade Learning with Texts to a newer version safely.
+
+## How Upgrades Work
+
+LWT uses an **automatic database migration system**. When you start LWT after updating the files, it automatically:
+
+1. Detects your current database version
+2. Runs any pending migrations to update the database schema
+3. Updates the `dbversion` setting to match the current version
+
+This means most upgrades are seamless - just replace the files and open LWT.
+
+## Standard Upgrade Process
+
+### Step 1: Backup Your Data
+
+Before any upgrade, create backups:
+
+**Database backup (recommended):**
+
+1. Open LWT in your browser
+2. Go to **Settings** (gear icon)
+3. Click **Backup/Restore/Empty Database**
+4. Click **Backup ENTIRE Database** to download a backup file
+
+**File backup:**
+
+Copy your entire LWT directory to a safe location. Important files include:
+
+- `.env` - Your database configuration
+- `media/` - Your audio files (if you created this folder)
+
+### Step 2: Download the New Version
+
+Get the latest release:
+
+- **Stable releases**: [GitHub Releases](https://github.com/HugoFara/lwt/releases)
+- **Latest development**: [Download main branch](https://github.com/HugoFara/lwt/archive/refs/heads/main.zip)
+
+### Step 3: Replace Files
+
+1. Extract the new version
+2. Copy your `.env` file from the backup into the new LWT directory
+3. Copy your `media/` folder (if it exists) into the new directory
+4. Replace the old LWT directory with the new one
+
+### Step 4: Clear Browser Cache
+
+Clear your browser cache to ensure you're loading the new JavaScript and CSS files. You can also try:
+
+- Hard refresh: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
+- Or open LWT in a private/incognito window
+
+### Step 5: Open LWT
+
+Open LWT in your browser as usual. The database will be automatically updated if needed.
+
+## Docker Upgrades
+
+If you're using Docker:
+
+```bash
+# Stop the current container
+docker compose down
+
+# Pull the latest image (if using pre-built images)
+docker compose pull
+
+# Or rebuild from source
+docker compose build --no-cache
+
+# Start the updated container
+docker compose up -d
+```
+
+Your data persists in Docker volumes, so it will be preserved across upgrades.
+
+## Upgrading from Very Old Versions
+
+If you're upgrading from a version older than 2.7.0 (released before 2022), special considerations apply:
+
+### Database Schema Changes
+
+Older versions used a different database structure. The migration system will attempt to convert your data, but for very old versions:
+
+1. **Export your data first**: Use LWT's export features to save your terms and texts
+2. **Consider a fresh install**: Create a new database, then import your exported data
+3. **Test thoroughly**: After upgrading, verify your terms and texts are intact
+
+### Configuration File Changes
+
+- Versions before 3.0 used `connect.inc.php` instead of `.env`
+- If upgrading from these versions, create a new `.env` file based on `.env.example`
+- Copy your database credentials from `connect.inc.php` to `.env`
+
+### PHP Version Requirements
+
+Modern LWT requires **PHP 8.1 or higher**. If your server runs an older PHP version, you'll need to upgrade PHP first.
+
+| LWT Version | Minimum PHP |
+|-------------|-------------|
+| 3.0+        | PHP 8.1     |
+| 2.9.x       | PHP 8.0     |
+| 2.0-2.8     | PHP 7.4     |
+| < 2.0       | PHP 5.6     |
+
+## Troubleshooting
+
+### "Database needs to be reinstalled" Error
+
+This usually means the migration couldn't complete. Try:
+
+1. Restore your database backup
+2. Check that your `.env` credentials are correct
+3. Ensure your MySQL/MariaDB user has ALTER TABLE permissions
+
+### Features Not Working After Upgrade
+
+1. **Clear browser cache** completely
+2. **Check browser console** (F12) for JavaScript errors
+3. **Rebuild assets** if you're running from source:
+
+   ```bash
+   npm install
+   npm run build:all
+   ```
+
+### Tests Not Auto-Advancing
+
+If tests don't advance to the next word after upgrading:
+
+1. Clear your browser cache
+2. Check if JavaScript is loading correctly (F12 > Console)
+3. Try a different browser to isolate the issue
+
+### Database Connection Errors
+
+Verify your `.env` file has the correct settings:
+
+```bash
+DB_HOST=localhost      # Or your database host
+DB_USER=root           # Your database username
+DB_PASSWORD=           # Your database password
+DB_NAME=learning-with-texts
+```
+
+## Checking Your Version
+
+To see your current LWT version:
+
+1. Look at the footer of any LWT page
+2. Or check the `dbversion` value in your database's `settings` table
+
+## Downgrading
+
+Downgrading is **not officially supported** because newer database migrations cannot be reversed automatically. If you need to downgrade:
+
+1. Restore your database backup from before the upgrade
+2. Use the older LWT files
+
+This is why backups before upgrading are essential.
+
+## Getting Help
+
+If you encounter issues:
+
+- [GitHub Issues](https://github.com/HugoFara/lwt/issues) - Report bugs or search existing issues

docs/404.html

@@ -9,7 +9,7 @@
     <link rel="preload stylesheet" href="/docs/assets/style.JSR2-pMR.css" as="style">
     <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
 
-    <script type="module" src="/docs/assets/app.ckiVg2pP.js"></script>
+    <script type="module" src="/docs/assets/app.apQhqRhn.js"></script>
     <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
     <link rel="icon" href="/docs/assets/images/lwt_icon.png">
     <link rel="apple-touch-icon" href="/docs/assets/images/apple-touch-icon-57x57.png">
@@ -18,7 +18,7 @@
   </head>
   <body>
     <div id="app"></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"changelog.md\":\"D-Ya70a9\",\"developer_api.md\":\"Cvfyka0X\",\"developer_contributing.md\":\"CTt53uUA\",\"developer_icon-migration.md\":\"B-jtgdlM\",\"developer_js-php-modernization-plan.md\":\"Bb3KQ9yP\",\"developer_v3-changes.md\":\"DVPZBgTg\",\"guide_faq.md\":\"C0BvW6nh\",\"guide_getting-started.md\":\"DbT121eA\",\"guide_how-to-learn.md\":\"DRtwGqxO\",\"guide_how-to-use.md\":\"Dll6op2m\",\"guide_installation.md\":\"g8CtzQbF\",\"guide_post-installation.md\":\"23x4gBln\",\"guide_troubleshooting_ipad.md\":\"DLwINN0X\",\"guide_troubleshooting_wordpress.md\":\"BNCUbkXq\",\"index.md\":\"CfRhdxOD\",\"legal_license.md\":\"CSn3UMW8\",\"legal_links.md\":\"DE6l5SW6\",\"legal_third-party-licenses.md\":\"AM24dijs\",\"reference_database-schema.md\":\"IbR0ML6E\",\"reference_export-templates.md\":\"V4de5Gbu\",\"reference_features.md\":\"C9eg8jGp\",\"reference_keyboard-shortcuts.md\":\"DnHCnyN9\",\"reference_language-setup.md\":\"CUkll5hM\",\"reference_new-features.md\":\"Cd6no244\",\"reference_restrictions.md\":\"DljYZhD_\",\"reference_term-scores.md\":\"lnIZ7pv_\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"LWT Documentation\",\"description\":\"Learning with Texts - Documentation\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/assets/images/lwt_icon_big.png\",\"siteTitle\":\"LWT Docs\",\"nav\":[{\"text\":\"Home\",\"link\":\"/\"},{\"text\":\"Getting Started\",\"link\":\"/guide/getting-started\"},{\"text\":\"User Guide\",\"items\":[{\"text\":\"Installation\",\"link\":\"/guide/installation\"},{\"text\":\"Post-Installation\",\"link\":\"/guide/post-installation\"},{\"text\":\"How to Use\",\"link\":\"/guide/how-to-use\"},{\"text\":\"FAQ\",\"link\":\"/guide/faq\"}]},{\"text\":\"Reference\",\"link\":\"/reference/features\"},{\"text\":\"Developer\",\"link\":\"/developer/api\"},{\"text\":\"Changelog\",\"link\":\"/changelog\"}],\"sidebar\":{\"/guide/\":[{\"text\":\"Getting Started\",\"items\":[{\"text\":\"Introduction\",\"link\":\"/guide/getting-started\"},{\"text\":\"Installation\",\"link\":\"/guide/installation\"},{\"text\":\"Post-Installation\",\"link\":\"/guide/post-installation\"}]},{\"text\":\"Using LWT\",\"items\":[{\"text\":\"How to Learn\",\"link\":\"/guide/how-to-learn\"},{\"text\":\"How to Use\",\"link\":\"/guide/how-to-use\"},{\"text\":\"FAQ\",\"link\":\"/guide/faq\"}]},{\"text\":\"Troubleshooting\",\"items\":[{\"text\":\"iPad/Tablet Setup\",\"link\":\"/guide/troubleshooting/ipad\"},{\"text\":\"WordPress Integration\",\"link\":\"/guide/troubleshooting/wordpress\"}]}],\"/reference/\":[{\"text\":\"Reference\",\"items\":[{\"text\":\"Features\",\"link\":\"/reference/features\"},{\"text\":\"New Features\",\"link\":\"/reference/new-features\"},{\"text\":\"Keyboard Shortcuts\",\"link\":\"/reference/keyboard-shortcuts\"},{\"text\":\"Language Setup\",\"link\":\"/reference/language-setup\"},{\"text\":\"Term Scores\",\"link\":\"/reference/term-scores\"},{\"text\":\"Export Templates\",\"link\":\"/reference/export-templates\"},{\"text\":\"Database Schema\",\"link\":\"/reference/database-schema\"},{\"text\":\"Restrictions\",\"link\":\"/reference/restrictions\"}]}],\"/developer/\":[{\"text\":\"Developer Guide\",\"items\":[{\"text\":\"API Reference\",\"link\":\"/developer/api\"},{\"text\":\"Contributing\",\"link\":\"/developer/contributing\"},{\"text\":\"V3 Changes\",\"link\":\"/developer/v3-changes\"}]}],\"/legal/\":[{\"text\":\"Legal\",\"items\":[{\"text\":\"License\",\"link\":\"/legal/license\"},{\"text\":\"Third-Party Licenses\",\"link\":\"/legal/third-party-licenses\"},{\"text\":\"Links\",\"link\":\"/legal/links\"}]}]},\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/HugoFara/lwt\"}],\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Released into the Public Domain under the Unlicense.\",\"copyright\":\"Learning with Texts Community\"},\"editLink\":{\"pattern\":\"https://github.com/HugoFara/lwt/edit/main/docs-src/:path\",\"text\":\"Edit this page on GitHub\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"changelog.md\":\"B5PnDPvR\",\"developer_api.md\":\"Cvfyka0X\",\"developer_contributing.md\":\"CTt53uUA\",\"developer_icon-migration.md\":\"B-jtgdlM\",\"developer_js-php-modernization-plan.md\":\"Bb3KQ9yP\",\"developer_v3-changes.md\":\"DVPZBgTg\",\"guide_faq.md\":\"C0BvW6nh\",\"guide_getting-started.md\":\"DbT121eA\",\"guide_how-to-learn.md\":\"DRtwGqxO\",\"guide_how-to-use.md\":\"Dll6op2m\",\"guide_installation.md\":\"Cf2KlytL\",\"guide_post-installation.md\":\"23x4gBln\",\"guide_troubleshooting_ipad.md\":\"DLwINN0X\",\"guide_troubleshooting_wordpress.md\":\"BNCUbkXq\",\"guide_upgrade.md\":\"D72fu_Ej\",\"index.md\":\"CfRhdxOD\",\"legal_license.md\":\"CSn3UMW8\",\"legal_links.md\":\"DE6l5SW6\",\"legal_third-party-licenses.md\":\"AM24dijs\",\"reference_database-schema.md\":\"IbR0ML6E\",\"reference_export-templates.md\":\"V4de5Gbu\",\"reference_features.md\":\"C9eg8jGp\",\"reference_keyboard-shortcuts.md\":\"DnHCnyN9\",\"reference_language-setup.md\":\"CUkll5hM\",\"reference_new-features.md\":\"Cd6no244\",\"reference_restrictions.md\":\"DljYZhD_\",\"reference_term-scores.md\":\"lnIZ7pv_\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"LWT Documentation\",\"description\":\"Learning with Texts - Documentation\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/assets/images/lwt_icon_big.png\",\"siteTitle\":\"LWT Docs\",\"nav\":[{\"text\":\"Home\",\"link\":\"/\"},{\"text\":\"Getting Started\",\"link\":\"/guide/getting-started\"},{\"text\":\"User Guide\",\"items\":[{\"text\":\"Installation\",\"link\":\"/guide/installation\"},{\"text\":\"Post-Installation\",\"link\":\"/guide/post-installation\"},{\"text\":\"How to Use\",\"link\":\"/guide/how-to-use\"},{\"text\":\"FAQ\",\"link\":\"/guide/faq\"}]},{\"text\":\"Reference\",\"link\":\"/reference/features\"},{\"text\":\"Developer\",\"link\":\"/developer/api\"},{\"text\":\"Changelog\",\"link\":\"/changelog\"}],\"sidebar\":{\"/guide/\":[{\"text\":\"Getting Started\",\"items\":[{\"text\":\"Introduction\",\"link\":\"/guide/getting-started\"},{\"text\":\"Installation\",\"link\":\"/guide/installation\"},{\"text\":\"Upgrading\",\"link\":\"/guide/upgrade\"},{\"text\":\"Post-Installation\",\"link\":\"/guide/post-installation\"}]},{\"text\":\"Using LWT\",\"items\":[{\"text\":\"How to Learn\",\"link\":\"/guide/how-to-learn\"},{\"text\":\"How to Use\",\"link\":\"/guide/how-to-use\"},{\"text\":\"FAQ\",\"link\":\"/guide/faq\"}]},{\"text\":\"Troubleshooting\",\"items\":[{\"text\":\"iPad/Tablet Setup\",\"link\":\"/guide/troubleshooting/ipad\"},{\"text\":\"WordPress Integration\",\"link\":\"/guide/troubleshooting/wordpress\"}]}],\"/reference/\":[{\"text\":\"Reference\",\"items\":[{\"text\":\"Features\",\"link\":\"/reference/features\"},{\"text\":\"New Features\",\"link\":\"/reference/new-features\"},{\"text\":\"Keyboard Shortcuts\",\"link\":\"/reference/keyboard-shortcuts\"},{\"text\":\"Language Setup\",\"link\":\"/reference/language-setup\"},{\"text\":\"Term Scores\",\"link\":\"/reference/term-scores\"},{\"text\":\"Export Templates\",\"link\":\"/reference/export-templates\"},{\"text\":\"Database Schema\",\"link\":\"/reference/database-schema\"},{\"text\":\"Restrictions\",\"link\":\"/reference/restrictions\"}]}],\"/developer/\":[{\"text\":\"Developer Guide\",\"items\":[{\"text\":\"API Reference\",\"link\":\"/developer/api\"},{\"text\":\"Contributing\",\"link\":\"/developer/contributing\"},{\"text\":\"V3 Changes\",\"link\":\"/developer/v3-changes\"}]}],\"/legal/\":[{\"text\":\"Legal\",\"items\":[{\"text\":\"License\",\"link\":\"/legal/license\"},{\"text\":\"Third-Party Licenses\",\"link\":\"/legal/third-party-licenses\"},{\"text\":\"Links\",\"link\":\"/legal/links\"}]}]},\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/HugoFara/lwt\"}],\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Released into the Public Domain under the Unlicense.\",\"copyright\":\"Learning with Texts Community\"},\"editLink\":{\"pattern\":\"https://github.com/HugoFara/lwt/edit/main/docs-src/:path\",\"text\":\"Edit this page on GitHub\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
 
   </body>
 </html>