README // Add notices regarding the raw data to import.

Author: ShikiSuen

README.md

@@ -4,6 +4,8 @@ Swift: [![Swift](https://github.com/vChewing/KeyKeyUserDBKit/actions/workflows/c
 
 Yahoo! 奇摩輸入法 (KeyKey) 使用者資料庫解密 Swift Package。
 
+請務必詳讀下文「使用前注意」章節。
+
 > **💻 C# 版**: `WinNT/` 目錄下含有 .NET 實作版本，詳見其自身的 [README.md](WinNT/README.md)。
 >
 > C#: [![.NET](https://github.com/vChewing/KeyKeyUserDBKit/actions/workflows/ci.yml/badge.svg)](https://github.com/vChewing/KeyKeyUserDBKit/actions/workflows/ci.yml) [![NuGet](https://img.shields.io/nuget/v/vChewing.Utils.KeyKeyUserDBKit)](https://www.nuget.org/packages/vChewing.Utils.KeyKeyUserDBKit) [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
@@ -28,6 +30,31 @@ Yahoo! 奇摩輸入法 (KeyKey) 使用者資料庫解密 Swift Package。
 - 📖 讀取使用者詞彙資料（單元圖 (Unigram)、雙元圖 (Bigram)、候選字覆蓋）
 - 🔄 支援 `Sequence` 與 `AsyncSequence` 迭代
 
+## 使用前注意
+
+奇摩輸入法的使用者片語辭典格式有兩種：`文殊文字檔（MJSR Text）` 以及 `SmartMandarinUserData.db`。
+
+這裡闡述一些注意事項。
+
+> ☠️不遵守的話，本工具恐無法完整讀取檔案。雖然不會損毀原始檔案就是了。
+
+### 1. `文殊文字檔（MJSR Text）` 注意事項：
+
+使用奇摩輸入法自身的辭典編輯器匯出的文字檔案會是 `文殊文字檔（Manjusri Text）` 格式（下文簡稱 MJSR 資料）。請務必注意該格式不要被擅自編輯：
+
+- 如果第一行有被修改過或遺失的話，則整篇檔案都會被拒絕讀入。
+- 如果檔案末尾的 `<database></database>` XML 章節遺失的話，您將無法復原「雙元圖快取」與「候選字覆蓋」這兩類資料。
+- 至於 Unigram 則都是以明文形式存儲在 MJSR 資料內的。
+
+### 2. `SmartMandarinUserData.db` 存取時的注意事項（WinNT 與 macOS 須知）：
+
+該資料檔案是經過 CEROD 加密的 SQLite 檔案、且被奇摩輸入法實時存取。
+
+- 讀取資料時，奇摩輸入法本體必須不得正在運行於系統當中。不然的話，本工具恐無法完整讀取所有的資料、甚至直接無法讀取任何資料。
+- 如果輸入法已經運行的話，請務必手動結束輸入法的 Process（處理程序，進程）、且不得使用暴力手段強行終止。
+  - **這是為了給輸入法充足的時間來寫入 SQLite 日誌內容**。
+  - 對此感到棘手者，請在系統輸入法清單內暫時移除奇摩輸入法、然後重新開機、再讀取 `SmartMandarinUserData.db` 檔案。
+
 ## 專案結構
 
 ```
@@ -118,7 +145,7 @@ for gram in allGrams {
 
 // 或分別讀取各類型資料
 let unigrams = try db.fetchUnigrams()           // 單元圖
-let bigrams = try db.fetchBigrams()             // 雙元圖
+let bigrams = try db.fetchBigrams()             // 雙元圖快取
 let bigrams5 = try db.fetchBigrams(limit: 5)    // 限制筆數
 let overrides = try db.fetchCandidateOverrides() // 候選字覆蓋
 

WinNT/README.md

@@ -6,6 +6,8 @@
 
 這是 KeyKeyUserDBKit Swift Package 的 .NET 10 移植版本，可用於 Windows & Linux & macOS 等所有受 .NET 10 支援的平台系統版本。
 
+請務必詳讀下文「使用前注意」章節。
+
 ## 目的
 
 奇摩輸入法在 2012 年停止開發，最終官方支援的 macOS 系統版本是 macOS 10.8 Mountain Lion。從 macOS 10.9 Mavericks 開始，該輸入法原廠的片語編輯器徹底罷工。雖然官方釋出的最終原始碼（僅限 Yahoo 奇摩被允許授權公開的部分，不包含 SQLite CEROD）小修小補之後仍舊可以將片語編輯器重新建置，但因為 CEROD 原始碼的缺失、導致輸入法本體無法建置成「可以無縫讀取既有使用者片語資料」的樣子。
@@ -26,6 +28,31 @@
 - 📖 讀取使用者詞彙資料（單元圖、雙元圖、候選字覆蓋）
 - 🔄 支援 `IEnumerable<Gram>` 與 `IAsyncEnumerable<Gram>` 迭代
 
+## 使用前注意
+
+奇摩輸入法的使用者片語辭典格式有兩種：`文殊文字檔（MJSR Text）` 以及 `SmartMandarinUserData.db`。
+
+這裡闡述一些注意事項。
+
+> ☠️不遵守的話，本工具恐無法完整讀取檔案。雖然不會損毀原始檔案就是了。
+
+### 1. `文殊文字檔（MJSR Text）` 注意事項：
+
+使用奇摩輸入法自身的辭典編輯器匯出的文字檔案會是 `文殊文字檔（Manjusri Text）` 格式（下文簡稱 MJSR 資料）。請務必注意該格式不要被擅自編輯：
+
+- 如果第一行有被修改過或遺失的話，則整篇檔案都會被拒絕讀入。
+- 如果檔案末尾的 `<database></database>` XML 章節遺失的話，您將無法復原「雙元圖快取」與「候選字覆蓋」這兩類資料。
+- 至於 Unigram 則都是以明文形式存儲在 MJSR 資料內的。
+
+### 2. `SmartMandarinUserData.db` 存取時的注意事項（WinNT 與 macOS 須知）：
+
+該資料檔案是經過 CEROD 加密的 SQLite 檔案、且被奇摩輸入法實時存取。
+
+- 讀取資料時，奇摩輸入法本體必須不得正在運行於系統當中。不然的話，本工具恐無法完整讀取所有的資料、甚至直接無法讀取任何資料。
+- 如果輸入法已經運行的話，請務必手動結束輸入法的 Process（處理程序，進程）、且不得使用暴力手段強行終止。
+  - **這是為了給輸入法充足的時間來寫入 SQLite 日誌內容**。
+  - 對此感到棘手者，請在系統輸入法清單內暫時移除奇摩輸入法、然後重新開機、再讀取 `SmartMandarinUserData.db` 檔案。
+
 ## 專案結構
 
 ```
@@ -104,7 +131,7 @@ foreach (var gram in allGrams)
 
 // 或分別讀取各類型資料
 var unigrams = db.FetchUnigrams();           // 單元圖
-var bigrams = db.FetchBigrams();             // 雙元圖
+var bigrams = db.FetchBigrams();             // 雙元圖快取
 var bigrams5 = db.FetchBigrams(5);           // 限制筆數
 var overrides = db.FetchCandidateOverrides(); // 候選字覆蓋