From 6c69ffa83c1a7f534217e5af643c8bd1b4d2078b Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Wed, 21 Jan 2026 21:37:57 +0200
Subject: docs: document Bulgarian-Bulgarian batch file format (double equals
 ==)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update README.md with complete batch file format documentation
  - Expanded from 3 to 5 supported formats
  - Added Format 4: Bulgarian-Bulgarian (monolingual) using double equals
  - Clarified Format 2 as English→Bulgarian with single equals
  - Noted that bg-bg cards generate two separate audio files

- Update CLI help text to show batch file format examples
  - Added example of double equals syntax
  - Clarified single equals creates English→Bulgarian cards

This closes the documentation gap for the Bulgarian-Bulgarian flashcard feature
that was already implemented in the codebase.
---
 README.md               | 27 ++++++++++++++++++++-------
 internal/cli/command.go |  3 ++-
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 951ae17..b9ad8e7 100644
--- a/README.md
+++ b/README.md
@@ -154,7 +154,7 @@ Key features:
 
 #### Batch file format
 
-Create a text file with Bulgarian words, optionally with English translations. The tool supports three flexible formats:
+Create a text file with Bulgarian words, optionally with English translations or Bulgarian definitions. The tool supports five flexible formats:
 
 **Format 1: Bulgarian words only (will be translated to English)**
 ```
@@ -165,7 +165,7 @@ Create a text file with Bulgarian words, optionally with English translations. T
 вода
 ```
 
-**Format 2: Bulgarian words with translations (no translation needed)**
+**Format 2: Bulgarian words with English translations (single equals =)**
 ```
 книга = book
 стол = table
@@ -174,6 +174,8 @@ Create a text file with Bulgarian words, optionally with English translations. T
 молив = pencil
 ```
 
+Creates English→Bulgarian flashcards (front: English, back: Bulgarian).
+
 **Format 3: English words only (will be translated to Bulgarian)**
 ```
 = apple
@@ -183,18 +185,29 @@ Create a text file with Bulgarian words, optionally with English translations. T
 = water
 ```
 
-**Format 4: Mixed format (all three types can be combined)**
+**Format 4: Bulgarian-Bulgarian (monolingual - double equals ==)**
+```
+ябълка == плод
+котка == домашно животно
+куче == млекопитающо
+```
+
+Creates Bulgarian→Bulgarian flashcards (front: Bulgarian word, back: Bulgarian definition). Useful for monolingual learning where both sides are in Bulgarian. Uses double equals (`==`) to distinguish from the English format.
+
+**Format 5: Mixed format (all four types can be combined)**
 ```
 книга = book
-котка
+котка == домашно животно
 = table
-куче
-молив = pencil
-= window
+куче = dog
+вода == течност
+молив
 ```
 
 When translations are provided, they are used directly without calling the translation API, saving time and API quota. When only English is provided (format starting with `=`), the tool will automatically translate it to Bulgarian. Spaces around the words and translations are automatically trimmed.
 
+Bulgarian-Bulgarian cards generate two separate audio files (front and back pronunciation).
+
 ## Configuration
 
 Create an optional `~/config/totalrecall/config.yaml` file. You can copy the example file provided:
diff --git a/internal/cli/command.go b/internal/cli/command.go
index 155cb40..bf73221 100644
--- a/internal/cli/command.go
+++ b/internal/cli/command.go
@@ -29,7 +29,8 @@ Examples:
 
 Batch file formats:
   ябълка                          # Bulgarian word (will be translated to English)
-  ябълка = apple                  # Bulgarian with translation provided
+  ябълка = apple                  # English→Bulgarian card (single equals)
+  ябълка == определение           # Bulgarian→Bulgarian card (double equals)
   = apple                         # English only (will be translated to Bulgarian)`,
 		Args:    cobra.MaximumNArgs(1),
 		Version: internal.Version,
-- 
cgit v1.2.3