From 6334a7fdb422d1947dfb9c3c8009273d6254c9b7 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Wed, 14 Oct 2026 22:43:34 +0800 Subject: [PATCH] Publish the wiki from docs/wiki of the repository (en, da, ms) --- Architecture-da.md | 40 ++++++++++++++++++++++++++++ Architecture-ms.md | 40 ++++++++++++++++++++++++++++ Architecture.md | 40 ++++++++++++++++++++++++++++ Home-da.md | 30 +++++++++++++++++++++ Home-ms.md | 30 +++++++++++++++++++++ Home.md | 30 +++++++++++++++++++++ Install-da.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++ Install-ms.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++ Install.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++ Usage-da.md | 49 ++++++++++++++++++++++++++++++++++ Usage-ms.md | 49 ++++++++++++++++++++++++++++++++++ Usage.md | 49 ++++++++++++++++++++++++++++++++++ _Sidebar.md | 12 +++++++++ 13 files changed, 564 insertions(+) create mode 100644 Architecture-da.md create mode 100644 Architecture-ms.md create mode 100644 Architecture.md create mode 100644 Home-da.md create mode 100644 Home-ms.md create mode 100644 Home.md create mode 100644 Install-da.md create mode 100644 Install-ms.md create mode 100644 Install.md create mode 100644 Usage-da.md create mode 100644 Usage-ms.md create mode 100644 Usage.md create mode 100644 _Sidebar.md diff --git a/Architecture-da.md b/Architecture-da.md new file mode 100644 index 0000000..c784377 --- /dev/null +++ b/Architecture-da.md @@ -0,0 +1,40 @@ +# Arkitektur + +馃寪 [English](Architecture) 路 **Dansk** 路 [Bahasa Malaysia](Architecture-ms) + +Programmet er bygget i fire lag under `src/flash_card/`. Importer peger indad; `lint-imports` kontrollerer det. + +| Lag | Indeholder | M氓 importere | +| --- | --- | --- | +| `domain` | `Card`, `LanguagePair`, `Vocabulary`, `Deck`, fejlene og repository-gr忙nsefladerne | ingenting | +| `application` | `StudySession`, `open_study_session`, `CardDto` og `SpeechPort` | `domain` | +| `infrastructure` | CSV-repositories og tale-adaptere | `application`, `domain` | +| `presentation` | `FlashCardView`, `FlashCardViewModel` (MVVM) og kompositionsroden `app.py` | alle lag | + +Alle konstanter st氓r i `src/flash_card/constants.py`. + +## Hvor er hvert opgavetrin? + +| Opgave | Kode | +| --- | --- | +| Trin 1: vindue, l忙rred, billede, tekster, knapper | `FlashCardView.__init__` i `presentation/features/flash_card/flash_card_view.py`; billederne laves af `tools/generate_images.py` | +| Trin 2: l忙s CSV, tilf忙ldigt ord ved hvert tryk | `CsvVocabularyRepository` og `read_word_list` (erstatter `pandas`), `Deck.draw`, `StudySession.next_card`, `FlashCardView.next_card` | +| Trin 3: vend efter 3 sekunder | `FlashCardView.flip_card`, `FlashCardView.flip_timer` (`after`, `after_cancel`), `FlashCardViewModel.flip_card` | +| Trin 4: kendte ord, `words_to_learn.csv` | `FlashCardView.is_known`, `StudySession.mark_known`, `CsvProgressRepository`, `open_study_session` | +| Ekstra: tale | `SpeechPort`, `GttsSpeech`, `NullSpeech`, `build_speech` i `presentation/app.py` | + +## Hvorfor en lagdelt l酶sning til en lille opgave? + +Reglerne (hvilket kort der kommer n忙ste gang, hvad et kendt ord g酶r) testes uden vindue og uden filsystem. Vinduet, CSV-filerne og taletjenesten kan udskiftes uden at r酶re reglerne. Se ADR-0001 og ADR-0002 i `docs/adr/`. + +## Test + +| Mappe | Hvad den tester | +| --- | --- | +| `tests/unit/` | Hvert lag for sig, med falske objekter til portene | +| `tests/integration/` | Den rigtige ordliste og fremgangsfilen i en midlertidig mappe | +| `tests/e2e/` | Det rigtige Tkinter-vindue (springes over uden sk忙rm) | + +## Projektdokumenter + +Business case, plan, design og gennemgangsrapporter ligger i `docs/`. Arbejdet blev udf酶rt i syv milep忙le, 茅n pull request hver: se `docs/milestones/`. diff --git a/Architecture-ms.md b/Architecture-ms.md new file mode 100644 index 0000000..6b838fb --- /dev/null +++ b/Architecture-ms.md @@ -0,0 +1,40 @@ +# Seni bina + +馃寪 [English](Architecture) 路 [Dansk](Architecture-da) 路 **Bahasa Malaysia** + +Program dibina dalam empat lapisan di bawah `src/flash_card/`. Import menuju ke dalam; `lint-imports` memeriksanya. + +| Lapisan | Mengandungi | Boleh mengimport | +| --- | --- | --- | +| `domain` | `Card`, `LanguagePair`, `Vocabulary`, `Deck`, ralat dan antara muka repositori | tiada | +| `application` | `StudySession`, `open_study_session`, `CardDto` dan `SpeechPort` | `domain` | +| `infrastructure` | Repositori CSV dan penyesuai suara | `application`, `domain` | +| `presentation` | `FlashCardView`, `FlashCardViewModel` (MVVM) dan akar komposisi `app.py` | semua lapisan | + +Semua pemalar terdapat dalam `src/flash_card/constants.py`. + +## Di manakah setiap langkah tugasan? + +| Tugasan | Kod | +| --- | --- | +| Langkah 1: tetingkap, kanvas, imej, teks, butang | `FlashCardView.__init__` dalam `presentation/features/flash_card/flash_card_view.py`; imej dibuat oleh `tools/generate_images.py` | +| Langkah 2: baca CSV, perkataan rawak setiap tekanan | `CsvVocabularyRepository` dan `read_word_list` (menggantikan `pandas`), `Deck.draw`, `StudySession.next_card`, `FlashCardView.next_card` | +| Langkah 3: terbalik selepas 3 saat | `FlashCardView.flip_card`, `FlashCardView.flip_timer` (`after`, `after_cancel`), `FlashCardViewModel.flip_card` | +| Langkah 4: perkataan diketahui, `words_to_learn.csv` | `FlashCardView.is_known`, `StudySession.mark_known`, `CsvProgressRepository`, `open_study_session` | +| Tambahan: suara | `SpeechPort`, `GttsSpeech`, `NullSpeech`, `build_speech` dalam `presentation/app.py` | + +## Mengapa program berlapis untuk tugasan kecil? + +Peraturan (kad mana yang seterusnya, apa yang berlaku apabila perkataan diketahui) diuji tanpa tetingkap atau sistem fail. Tetingkap, fail CSV dan perkhidmatan suara boleh diganti tanpa menyentuh peraturan. Lihat ADR-0001 dan ADR-0002 dalam `docs/adr/`. + +## Ujian + +| Folder | Apa yang diuji | +| --- | --- | +| `tests/unit/` | Setiap lapisan sendiri, dengan objek palsu untuk port | +| `tests/integration/` | Senarai perkataan sebenar dan fail kemajuan dalam folder sementara | +| `tests/e2e/` | Tetingkap Tkinter sebenar (dilangkau tanpa paparan) | + +## Dokumen projek + +Kes perniagaan, pelan, reka bentuk dan rekod semakan terdapat dalam `docs/`. Kerja dilakukan dalam tujuh pencapaian, satu pull request setiap satu: lihat `docs/milestones/`. diff --git a/Architecture.md b/Architecture.md new file mode 100644 index 0000000..d462070 --- /dev/null +++ b/Architecture.md @@ -0,0 +1,40 @@ +# Architecture + +馃寪 **English** 路 [Dansk](Architecture-da) 路 [Bahasa Malaysia](Architecture-ms) + +The program is built in four layers under `src/flash_card/`. Imports point inward; `lint-imports` checks this. + +| Layer | Holds | May import | +| --- | --- | --- | +| `domain` | `Card`, `LanguagePair`, `Vocabulary`, `Deck`, the errors and the repository interfaces | nothing | +| `application` | `StudySession`, `open_study_session`, `CardDto` and `SpeechPort` | `domain` | +| `infrastructure` | The CSV repositories and the speech adapters | `application`, `domain` | +| `presentation` | `FlashCardView`, `FlashCardViewModel` (MVVM) and the composition root `app.py` | all layers | + +All constants are in `src/flash_card/constants.py`. + +## Where is each assignment step? + +| Assignment | Code | +| --- | --- | +| Step 1: window, canvas, image, texts, buttons | `FlashCardView.__init__` in `presentation/features/flash_card/flash_card_view.py`; images made by `tools/generate_images.py` | +| Step 2: read the CSV, random word on each press | `CsvVocabularyRepository` and `read_word_list` (replace `pandas`), `Deck.draw`, `StudySession.next_card`, `FlashCardView.next_card` | +| Step 3: flip after 3 seconds | `FlashCardView.flip_card`, `FlashCardView.flip_timer` (`after`, `after_cancel`), `FlashCardViewModel.flip_card` | +| Step 4: known words, `words_to_learn.csv` | `FlashCardView.is_known`, `StudySession.mark_known`, `CsvProgressRepository`, `open_study_session` | +| Extra: speech | `SpeechPort`, `GttsSpeech`, `NullSpeech`, `build_speech` in `presentation/app.py` | + +## Why a layered program for a small assignment? + +The rules (which card comes next, what a known word does) are tested without a window or a file system. The window, the CSV files and the speech service can be replaced without touching the rules. See ADR-0001 and ADR-0002 in `docs/adr/`. + +## Tests + +| Folder | What it tests | +| --- | --- | +| `tests/unit/` | Each layer alone, with fakes for the ports | +| `tests/integration/` | The real word list and the progress file in a temporary folder | +| `tests/e2e/` | The real Tkinter window (skipped when no display exists) | + +## Project documents + +The business case, plan, design and review records are in `docs/`. The work was done in seven milestones, one pull request each: see `docs/milestones/`. diff --git a/Home-da.md b/Home-da.md new file mode 100644 index 0000000..ad17b2c --- /dev/null +++ b/Home-da.md @@ -0,0 +1,30 @@ +# Flash Card + +馃寪 [English](Home) 路 **Dansk** 路 [Bahasa Malaysia](Home-ms) + +Et flashkortprogram til at l忙re de mest almindelige malajiske ord med danske overs忙ttelser. Det er l酶sningen p氓 dag 31 i Udemys kursus *100 Days of Code: The Complete Python Pro Bootcamp*. + +![Forsiden af et kort: det malajiske ord](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/raw/branch/main/docs/images/screenshot-front.png) +![Bagsiden af kortet efter tre sekunder: den danske overs忙ttelse](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/raw/branch/main/docs/images/screenshot-back.png) + +| Side | L忙s den, n氓r du vil | +| --- | --- | +| [Installation](Install-da) | Oprette `.venv`, installere programmet og k酶re testene | +| [Brug](Usage-da) | 脴ve kortene, forst氓 fremgangsfilen og bruge indstillingerne | +| [Arkitektur](Architecture-da) | Se lagene og finde koden til hvert opgavetrin | + +## De fire opgavetrin + +| Trin | Hvad programmet g酶r | Milep忙l | +| --- | --- | --- | +| 1. Brugerflade | Et vindue med et kort og to knapper | MIL-002 | +| 2. Nye flashkort | Et tilf忙ldigt ord fra ordlisten ved hvert tryk p氓 en knap | MIL-003 | +| 3. Vend kortene | Efter 3 sekunder viser kortet den danske overs忙ttelse | MIL-004 | +| 4. Gem din fremgang | Kendte ord fjernes, og resten gemmes i `words_to_learn.csv` | MIL-005 | +| Ekstra | Det malajiske ord bliver udtalt (valgfrit) | MIL-006 | + +## Til kursister + +Opgavens funktionsnavne er bevaret: `next_card`, `flip_card`, `is_known` og attributterne `flip_timer` og `current_card`. Data l忙ses med standardbibliotekets `csv`-modul i stedet for `pandas`, s氓 kerneprogrammet ikke har nogen afh忙ngigheder ved k酶rsel. + +Repository: diff --git a/Home-ms.md b/Home-ms.md new file mode 100644 index 0000000..8dc8566 --- /dev/null +++ b/Home-ms.md @@ -0,0 +1,30 @@ +# Flash Card + +馃寪 [English](Home) 路 [Dansk](Home-da) 路 **Bahasa Malaysia** + +Program kad imbas untuk mempelajari perkataan Melayu yang paling kerap digunakan beserta terjemahan Denmark. Ia ialah penyelesaian hari ke-31 kursus Udemy *100 Days of Code: The Complete Python Pro Bootcamp*. + +![Bahagian depan kad: perkataan Melayu](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/raw/branch/main/docs/images/screenshot-front.png) +![Bahagian belakang kad selepas tiga saat: terjemahan Denmark](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/raw/branch/main/docs/images/screenshot-back.png) + +| Halaman | Baca apabila anda mahu | +| --- | --- | +| [Pemasangan](Install-ms) | Mencipta `.venv`, memasang program dan menjalankan ujian | +| [Penggunaan](Usage-ms) | Berlatih dengan kad, memahami fail kemajuan dan menggunakan pilihan | +| [Seni bina](Architecture-ms) | Melihat lapisan dan mencari kod bagi setiap langkah tugasan | + +## Empat langkah tugasan + +| Langkah | Apa yang program lakukan | Pencapaian | +| --- | --- | --- | +| 1. Antara muka pengguna | Tetingkap dengan satu kad dan dua butang | MIL-002 | +| 2. Kad imbas baharu | Satu perkataan rawak daripada senarai perkataan setiap kali butang ditekan | MIL-003 | +| 3. Terbalikkan kad | Selepas 3 saat kad menunjukkan terjemahan Denmark | MIL-004 | +| 4. Simpan kemajuan anda | Perkataan yang diketahui dibuang dan selebihnya disimpan dalam `words_to_learn.csv` | MIL-005 | +| Tambahan | Perkataan Melayu disebut (pilihan) | MIL-006 | + +## Untuk peserta kursus + +Nama fungsi tugasan dikekalkan: `next_card`, `flip_card`, `is_known`, serta atribut `flip_timer` dan `current_card`. Data dibaca dengan modul `csv` pustaka standard dan bukan `pandas`, jadi program teras tidak mempunyai kebergantungan semasa larian. + +Repositori: diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..e2a2426 --- /dev/null +++ b/Home.md @@ -0,0 +1,30 @@ +# Flash Card + +馃寪 **English** 路 [Dansk](Home-da) 路 [Bahasa Malaysia](Home-ms) + +A flash card program for learning the most frequent Malay words with their Danish translations. It is the solution of day 31 of Udemy's *100 Days of Code: The Complete Python Pro Bootcamp*. + +![The front of a card: the Malay word](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/raw/branch/main/docs/images/screenshot-front.png) +![The back of the card after three seconds: the Danish translation](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/raw/branch/main/docs/images/screenshot-back.png) + +| Page | Read it when you want to | +| --- | --- | +| [Install](Install) | Create the `.venv`, install the program and run the tests | +| [Usage](Usage) | Study the cards, understand the progress file, use the options | +| [Architecture](Architecture) | See the layers and find the code of each assignment step | + +## The four assignment steps + +| Step | What the program does | Milestone | +| --- | --- | --- | +| 1. User interface | A window with a card and two buttons | MIL-002 | +| 2. New flash cards | A random word from the word list on every button press | MIL-003 | +| 3. Flip the cards | After 3 seconds the card shows the Danish translation | MIL-004 | +| 4. Save your progress | Known words are removed and the rest is saved in `words_to_learn.csv` | MIL-005 | +| Extra | The Malay word is spoken (optional) | MIL-006 | + +## For course participants + +The function names of the assignment are kept: `next_card`, `flip_card`, `is_known`, and the attributes `flip_timer` and `current_card`. The data is read with the standard library `csv` module instead of `pandas`, so the core program has no runtime dependency. + +Repository: diff --git a/Install-da.md b/Install-da.md new file mode 100644 index 0000000..b58c6ab --- /dev/null +++ b/Install-da.md @@ -0,0 +1,65 @@ +# Installation + +馃寪 [English](Install) 路 **Dansk** 路 [Bahasa Malaysia](Install-ms) + +## Krav + +- Python 3.13 eller nyere med Tkinter (p氓 Debian eller Ubuntu: `sudo apt install python3-tk`). +- `git`. +- Valgfrit: en internetforbindelse og tilvalget `speech`, hvis du vil h酶re det malajiske ord. + +## Hent koden + +```bash +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card.git +cd 031-flash-card +``` + +## Opret og brug et lokalt virtuelt milj酶 + +Windows (PowerShell): + +```powershell +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Linux og macOS: + +```bash +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +- `.[dev]` tilf酶jer `pytest`, `ruff`, `mypy` og `import-linter`. Brug `.`, hvis du kun vil k酶re programmet. +- Hvis PowerShell n忙gter at k酶re `Activate.ps1`, s氓 k酶r `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` 茅n gang. +- Forlad milj酶et med `deactivate`; slet mappen `.venv` for at starte forfra. + +## Udtalt malajisk ord (valgfrit) + +```bash +python -m pip install -e ".[speech]" +``` + +Det installerer `gTTS` og `playsound==1.2.2`. Uden tilvalget virker programmet uden lyd. + +## K酶r og test + +```bash +python -m flash_card +python -m pytest +``` + +Vinduestesten i `tests/e2e/` springes over, n氓r der ikke er en sk忙rm. + +## Dokumentation af kildekoden + +```bash +doxygen Doxyfile +``` + +HTML-filerne skrives til `docs/doxygen/html/index.html`. diff --git a/Install-ms.md b/Install-ms.md new file mode 100644 index 0000000..d457ad5 --- /dev/null +++ b/Install-ms.md @@ -0,0 +1,65 @@ +# Pemasangan + +馃寪 [English](Install) 路 [Dansk](Install-da) 路 **Bahasa Malaysia** + +## Keperluan + +- Python 3.13 atau lebih baharu dengan Tkinter (pada Debian atau Ubuntu: `sudo apt install python3-tk`). +- `git`. +- Pilihan: sambungan internet dan tambahan `speech` jika anda mahu mendengar perkataan Melayu. + +## Dapatkan kod + +```bash +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card.git +cd 031-flash-card +``` + +## Cipta dan gunakan persekitaran maya setempat + +Windows (PowerShell): + +```powershell +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Linux dan macOS: + +```bash +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +- `.[dev]` menambah `pytest`, `ruff`, `mypy` dan `import-linter`. Gunakan `.` jika anda hanya mahu menjalankan program. +- Jika PowerShell enggan menjalankan `Activate.ps1`, jalankan `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` sekali. +- Keluar daripada persekitaran dengan `deactivate`; padam folder `.venv` untuk bermula semula. + +## Perkataan Melayu bersuara (pilihan) + +```bash +python -m pip install -e ".[speech]" +``` + +Ini memasang `gTTS` dan `playsound==1.2.2`. Tanpa tambahan ini program berfungsi tanpa bunyi. + +## Jalankan dan uji + +```bash +python -m flash_card +python -m pytest +``` + +Ujian tetingkap dalam `tests/e2e/` dilangkau apabila tiada paparan. + +## Dokumentasi kod sumber + +```bash +doxygen Doxyfile +``` + +HTML ditulis ke `docs/doxygen/html/index.html`. diff --git a/Install.md b/Install.md new file mode 100644 index 0000000..45a04f4 --- /dev/null +++ b/Install.md @@ -0,0 +1,65 @@ +# Install + +馃寪 **English** 路 [Dansk](Install-da) 路 [Bahasa Malaysia](Install-ms) + +## Requirements + +- Python 3.13 or later with Tkinter (on Debian or Ubuntu: `sudo apt install python3-tk`). +- `git`. +- Optional: an internet connection and the `speech` extra to hear the Malay word. + +## Get the code + +```bash +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card.git +cd 031-flash-card +``` + +## Create and use a local virtual environment + +Windows (PowerShell): + +```powershell +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Linux and macOS: + +```bash +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +- `.[dev]` adds `pytest`, `ruff`, `mypy` and `import-linter`. Use `.` if you only want to run the program. +- If PowerShell refuses to run `Activate.ps1`, run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once. +- Leave the environment with `deactivate`; delete the `.venv` folder to start over. + +## Spoken Malay word (optional) + +```bash +python -m pip install -e ".[speech]" +``` + +This installs `gTTS` and `playsound==1.2.2`. Without it the program works silently. + +## Run and test + +```bash +python -m flash_card +python -m pytest +``` + +The window test in `tests/e2e/` is skipped when no display is available. + +## Documentation of the source code + +```bash +doxygen Doxyfile +``` + +The HTML is written to `docs/doxygen/html/index.html`. diff --git a/Usage-da.md b/Usage-da.md new file mode 100644 index 0000000..ce724ee --- /dev/null +++ b/Usage-da.md @@ -0,0 +1,49 @@ +# Brug + +馃寪 [English](Usage) 路 **Dansk** 路 [Bahasa Malaysia](Usage-ms) + +## 脴v kortene + +1. Start programmet med `python -m flash_card`. +2. Et kort viser et malajisk ord. Pr酶v at huske den danske overs忙ttelse. +3. Efter tre sekunder vender kortet og viser overs忙ttelsen. +4. Tryk p氓 det gr酶nne flueben, hvis du kendte ordet, eller p氓 det r酶de kryds, hvis du ikke gjorde. +5. Et nyt tilf忙ldigt ord vises. Gentag. + +Et ord, du har markeret som kendt, fjernes og kommer ikke igen. N氓r der ikke er flere ord, st氓r der "Nothing left to learn" p氓 kortet. + +## Din fremgang + +- F酶rste gang du trykker p氓 det gr酶nne flueben, skriver programmet `data/words_to_learn.csv` med de ord, du endnu ikke kan. +- N忙ste start bruger den fil. Findes den ikke, bruger programmet hele ordlisten `data/ms-da.csv`. +- For at starte forfra skal du slette `data/words_to_learn.csv`. +- Det r酶de kryds 忙ndrer aldrig filen. + +## Filformat + +Begge filer er UTF-8-tekst med 茅t kort pr. linje og cellerne adskilt af semikolon. F酶rste linje har de to sprogkoder. + +```text +ms;da +aku;mig +yang;hvilke +``` + +## Indstillinger + +| Indstilling | Betydning | +| --- | --- | +| `--data-dir ` | Mappen med `ms-da.csv` og `words_to_learn.csv` (standard: `data/` i repositoryet) | +| `--no-speech` | Udtal ikke det malajiske ord, selv om tilvalget til tale er installeret | + +## Brug et andet sprogpar + +L忙g en fil med samme format i datamappen og kald den `ms-da.csv`, eller ret `VOCABULARY_FILE_NAME` og `LANGUAGE_NAMES` i `src/flash_card/constants.py`. Kodene i overskriften vises som sprognavne fra `LANGUAGE_NAMES`; ukendte koder vises med store bogstaver. + +## Fejlfinding + +| Problem | Hvad du skal g酶re | +| --- | --- | +| `No module named tkinter` | Installer Tkinter (`python3-tk` p氓 Debian og Ubuntu) | +| Ingen lyd | Installer tilvalget `speech` og tjek netv忙rket; programmet logger en advarsel, n氓r udtalen mislykkes | +| Programmet stopper med en meddelelse om filen | CSV-filen er forkert opbygget; meddelelsen n忙vner filen og linjen. Filen bliver ikke overskrevet | diff --git a/Usage-ms.md b/Usage-ms.md new file mode 100644 index 0000000..bd4424d --- /dev/null +++ b/Usage-ms.md @@ -0,0 +1,49 @@ +# Penggunaan + +馃寪 [English](Usage) 路 [Dansk](Usage-da) 路 **Bahasa Malaysia** + +## Berlatih dengan kad + +1. Mulakan program dengan `python -m flash_card`. +2. Kad menunjukkan satu perkataan Melayu. Cuba ingat terjemahan Denmarknya. +3. Selepas tiga saat kad terbalik dan menunjukkan terjemahan. +4. Tekan tanda semak hijau jika anda tahu perkataan itu, atau pangkah merah jika tidak. +5. Satu perkataan rawak baharu muncul. Ulang. + +Perkataan yang anda tandakan sebagai diketahui dibuang dan tidak muncul lagi. Apabila tiada perkataan lagi, kad menunjukkan "Nothing left to learn". + +## Kemajuan anda + +- Kali pertama anda menekan tanda semak hijau, program menulis `data/words_to_learn.csv` dengan perkataan yang anda belum tahu. +- Permulaan seterusnya menggunakan fail itu. Jika ia tiada, program menggunakan senarai penuh `data/ms-da.csv`. +- Untuk bermula semula, padam `data/words_to_learn.csv`. +- Pangkah merah tidak pernah mengubah fail. + +## Format fail + +Kedua-dua fail ialah teks UTF-8 dengan satu kad setiap baris dan sel dipisahkan oleh koma bertitik. Baris pertama mengandungi dua kod bahasa. + +```text +ms;da +aku;mig +yang;hvilke +``` + +## Pilihan + +| Pilihan | Maksud | +| --- | --- | +| `--data-dir ` | Folder yang mengandungi `ms-da.csv` dan `words_to_learn.csv` (lalai: `data/` dalam repositori) | +| `--no-speech` | Jangan sebut perkataan Melayu, walaupun tambahan suara dipasang | + +## Gunakan pasangan bahasa lain + +Letakkan fail dengan format yang sama dalam folder data dan namakannya `ms-da.csv`, atau ubah `VOCABULARY_FILE_NAME` dan `LANGUAGE_NAMES` dalam `src/flash_card/constants.py`. Kod pada baris pertama dipaparkan sebagai nama bahasa daripada `LANGUAGE_NAMES`; kod yang tidak dikenali dipaparkan dengan huruf besar. + +## Penyelesaian masalah + +| Masalah | Apa yang perlu dilakukan | +| --- | --- | +| `No module named tkinter` | Pasang Tkinter (`python3-tk` pada Debian dan Ubuntu) | +| Tiada bunyi | Pasang tambahan `speech` dan periksa rangkaian; program mencatat amaran apabila penyebutan gagal | +| Program berhenti dengan mesej tentang fail | Fail CSV tidak betul; mesej menyebut fail dan barisnya. Fail tidak ditulis ganti | diff --git a/Usage.md b/Usage.md new file mode 100644 index 0000000..96291b6 --- /dev/null +++ b/Usage.md @@ -0,0 +1,49 @@ +# Usage + +馃寪 **English** 路 [Dansk](Usage-da) 路 [Bahasa Malaysia](Usage-ms) + +## Study the cards + +1. Start the program with `python -m flash_card`. +2. A card shows a Malay word. Try to remember its Danish translation. +3. After three seconds the card turns over and shows the translation. +4. Press the green tick when you knew the word, or the red cross when you did not. +5. A new random word appears. Repeat. + +A word you marked as known is removed and does not come up again. When no word is left, the card says "Nothing left to learn". + +## Your progress + +- The first time you press the green tick, the program writes `data/words_to_learn.csv` with the words you do not know yet. +- The next start uses that file. If it does not exist, the program uses the full word list `data/ms-da.csv`. +- To start again, delete `data/words_to_learn.csv`. +- The red cross never changes the file. + +## File format + +Both files are UTF-8 text with one card per line and the cells separated by a semicolon. The first line holds the two language codes. + +```text +ms;da +aku;mig +yang;hvilke +``` + +## Options + +| Option | Meaning | +| --- | --- | +| `--data-dir ` | Folder that holds `ms-da.csv` and `words_to_learn.csv` (default: `data/` of the repository) | +| `--no-speech` | Do not speak the Malay word, even when the speech extra is installed | + +## Use another language pair + +Put a file with the same format in the data folder and name it `ms-da.csv`, or change `VOCABULARY_FILE_NAME` and `LANGUAGE_NAMES` in `src/flash_card/constants.py`. The header codes are shown as language names from `LANGUAGE_NAMES`; unknown codes are shown in upper case. + +## Troubleshooting + +| Problem | What to do | +| --- | --- | +| `No module named tkinter` | Install Tkinter (`python3-tk` on Debian and Ubuntu) | +| No sound | Install the `speech` extra and check the network; the program logs a warning when speaking fails | +| The program stops with a message about the file | The CSV file is malformed; the message names the file and the line. The file is not overwritten | diff --git a/_Sidebar.md b/_Sidebar.md new file mode 100644 index 0000000..4996869 --- /dev/null +++ b/_Sidebar.md @@ -0,0 +1,12 @@ +**Flash Card** + +- [Home](Home) +- [Install](Install) +- [Usage](Usage) +- [Architecture](Architecture) + +**Languages** + +- English: [Home](Home) 路 [Install](Install) 路 [Usage](Usage) 路 [Architecture](Architecture) +- Dansk: [Hjem](Home-da) 路 [Installation](Install-da) 路 [Brug](Usage-da) 路 [Arkitektur](Architecture-da) +- Bahasa Malaysia: [Utama](Home-ms) 路 [Pemasangan](Install-ms) 路 [Penggunaan](Usage-ms) 路 [Seni bina](Architecture-ms)