From 02f725125cc8e1e2d8a1b8e6bea1c7f2428ca331 Mon Sep 17 00:00:00 2001 From: toasted-nutbread Date: Fri, 22 May 2020 20:20:00 -0400 Subject: [PATCH] README updates (#549) * Use fragments relative to the current URL * Adjust description in section about deleting individual dictionaries * Adjust description about online dictionaries * Adjust description about support for additional languages * Punctuation adjustments * Clarify {cloze-prefix} and {cloze-suffix} descriptions * Update/fix description of duplicate cards. * Fix description of HTML-less Anki templates * Clarify {sentence} description * Adjust description for development section * Replace grammatical first person * No promises for the impossible * Remove "please" * Use lower case for kanji, kana, katakana, hiragana, furigana --- README.md | 152 +++++++++++++++++++++++++++--------------------------- 1 file changed, 77 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 73529b96..f499ac07 100644 --- a/README.md +++ b/README.md @@ -18,26 +18,26 @@ Yomichan provides advanced features not available in other browser-based diction ## Table of Contents ## -* [Installation](https://foosoft.net/projects/yomichan/#installation) -* [Dictionaries](https://foosoft.net/projects/yomichan/#dictionaries) -* [Basic Usage](https://foosoft.net/projects/yomichan/#basic-usage) -* [Custom Dictionaries](https://foosoft.net/projects/yomichan/#custom-dictionaries) -* [Anki Integration](https://foosoft.net/projects/yomichan/#anki-integration) - * [Flashcard Configuration](https://foosoft.net/projects/yomichan/#flashcard-configuration) - * [Flashcard Creation](https://foosoft.net/projects/yomichan/#flashcard-creation) -* [Keyboard Shortcuts](https://foosoft.net/projects/yomichan/#keyboard-shortcuts) -* [Development](https://foosoft.net/projects/yomichan/#development) - * [Dependencies](https://foosoft.net/projects/yomichan/#dependencies) -* [Frequently Asked Questions](https://foosoft.net/projects/yomichan/#frequently-asked-questions) -* [Screenshots](https://foosoft.net/projects/yomichan/#screenshots) -* [License](https://foosoft.net/projects/yomichan/#license) +* [Installation](#installation) +* [Dictionaries](#dictionaries) +* [Basic Usage](#basic-usage) +* [Custom Dictionaries](#custom-dictionaries) +* [Anki Integration](#anki-integration) + * [Flashcard Configuration](#flashcard-configuration) + * [Flashcard Creation](#flashcard-creation) +* [Keyboard Shortcuts](#keyboard-shortcuts) +* [Development](#development) + * [Dependencies](#dependencies) +* [Frequently Asked Questions](#frequently-asked-questions) +* [Screenshots](#screenshots) +* [License](#license) ## Installation ## Yomichan comes in two flavors: *stable* and *testing*. Over the years, this extension has evolved to contain many -complex features, which have become increasingly difficult for me to test across different browsers, versions, and -environments. All new changes are initially introduced into the *testing* version, and when I am reasonably confident -that they are bug free, they will get promoted to the *stable* version. If you are technically savvy and don't mind +complex features which have become increasingly difficult to test across different browsers, versions, and +environments. New changes are initially introduced into the *testing* version, and after some time spent ensuring +that they are relatively bug free, they will be promoted to the *stable* version. If you are technically savvy and don't mind submitting issues on GitHub, try the *testing* version; otherwise, the *stable* version will be your best bet. * **Google Chrome** @@ -54,10 +54,10 @@ submitting issues on GitHub, try the *testing* version; otherwise, the *stable* There are several free Japanese dictionaries available for Yomichan, with two of them having glossaries available in different languages. You must download and import the dictionaries you wish to use in order to enable Yomichan -definition lookups. If you have proprietary EPWING dictionaries that you would like to use, please see the [Yomichan +definition lookups. If you have proprietary EPWING dictionaries that you would like to use, check the [Yomichan Import](https://foosoft.net/projects/yomichan-import) page to learn how to convert and import them into Yomichan. -Please be aware that the non-English dictionaries contain fewer entries than their English counterparts. Even if your +Be aware that the non-English dictionaries contain fewer entries than their English counterparts. Even if your primary language is not English, you may consider also importing the English version for better coverage. * **[JMdict](https://www.edrdg.org/enamdict/enamdict_doc.html)** (Japanese vocabulary) @@ -74,12 +74,12 @@ primary language is not English, you may consider also importing the English ver * [jmnedict.zip](https://foosoft.net/projects/yomichan/dl/dict/jmnedict.zip) * **[KireiCake](https://kireicake.com/rikaicakes/)** (Japanese slang) * [kireicake.zip](https://foosoft.net/projects/yomichan/dl/dict/kireicake.zip) -* **[KANJIDIC](http://nihongo.monash.edu/kanjidic2/index.html)** (Japanese Kanji) +* **[KANJIDIC](http://nihongo.monash.edu/kanjidic2/index.html)** (Japanese kanji) * [kanjidic\_english.zip](https://foosoft.net/projects/yomichan/dl/dict/kanjidic_english.zip) * [kanjidic\_french.zip](https://foosoft.net/projects/yomichan/dl/dict/kanjidic_french.zip) * [kanjidic\_portuguese.zip](https://foosoft.net/projects/yomichan/dl/dict/kanjidic_portuguese.zip) * [kanjidic\_spanish.zip](https://foosoft.net/projects/yomichan/dl/dict/kanjidic_spanish.zip) -* **[Innocent Corpus](https://web.archive.org/web/20190309073023/https://forum.koohii.com/thread-9459.html#pid168613)** (Term and Kanji frequencies across 5000+ novels) +* **[Innocent Corpus](https://web.archive.org/web/20190309073023/https://forum.koohii.com/thread-9459.html#pid168613)** (Term and kanji frequencies across 5000+ novels) * [innocent\_corpus.zip](https://foosoft.net/projects/yomichan/dl/dict/innocent_corpus.zip) * **[Kanjium](https://github.com/mifunetoshiro/kanjium)** (Pitch dictionary, see [related project page](https://github.com/toasted-nutbread/yomichan-pitch-accent-dictionary) for details) * [kanjium_pitch_accents.zip](https://foosoft.net/projects/yomichan/dl/dict/kanjium_pitch_accents.zip) @@ -92,7 +92,7 @@ primary language is not English, you may consider also importing the English ver 2. Click on the *spanner/monkey wrench* icon in the middle to open the options page. -3. Import the dictionaries you wish to use for term and Kanji searches. If you do not have any dictionaries installed +3. Import the dictionaries you wish to use for term and kanji searches. If you do not have any dictionaries installed (or enabled), Yomichan will warn you that it is not ready for use by displaying an orange exclamation mark over its icon. This exclamation mark will disappear once you have installed and enabled at least one dictionary. @@ -108,21 +108,21 @@ primary language is not English, you may consider also importing the English ver not available, you will hear a short click instead. You can configure the sources used to retrieve audio samples in the options page. -6. Click on individual Kanji in the term definition results to view additional information about those characters +6. Click on individual kanji in the term definition results to view additional information about those characters, including stroke order diagrams, readings, meanings, as well as other useful data. [![](https://foosoft.net/projects/yomichan/img/ui-kanji-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-kanji.png) ## Custom Dictionaries ## -Yomichan supports the use of custom dictionaries including the esoteric but popular +Yomichan supports the use of custom dictionaries, including the esoteric but popular [EPWING](https://ja.wikipedia.org/wiki/EPWING) format. They were often utilized in portable electronic dictionaries similar to the ones pictured below. These dictionaries are often sought after by language learners for their correctness and excellent coverage of the Japanese language. -Unfortunately, as most of the dictionaries released in this format are proprietary, I am unable to bundle them with -Yomichan. You will need to procure these dictionaries yourself and import them with [Yomichan -Import](https://foosoft.net/projects/yomichan-import). Please see the project page for additional details. +Unfortunately, as most of the dictionaries released in this format are proprietary, they are unable to be bundled with +Yomichan. Instead, you will need to procure these dictionaries yourself and import them using [Yomichan +Import](https://foosoft.net/projects/yomichan-import). Check the project page for additional details. [![Pocket EPWING dictionaries](https://foosoft.net/projects/yomichan/img/epwing-devices-thumb.png)](https://foosoft.net/projects/yomichan/img/epwing-devices.jpg) @@ -130,11 +130,11 @@ Import](https://foosoft.net/projects/yomichan-import). Please see the project pa Yomichan features automatic flashcard creation for [Anki](https://apps.ankiweb.net/), a free application designed to help you retain knowledge. This feature requires the prior installation of an Anki plugin called [AnkiConnect](https://foosoft.net/projects/anki-connect). -Please see the respective project page for more information about how to set up this software. +Check the respective project page for more information about how to set up this software. ### Flashcard Configuration ### -Before flashcards can be automatically created, you must configure the templates used to create term and/or Kanji notes. +Before flashcards can be automatically created, you must configure the templates used to create term and/or kanji notes. If you are unfamiliar with Anki deck and model management, this would be a good time to reference the [Anki Manual](https://docs.ankiweb.net/#/). In short, you must specify what information should be included in the flashcards that Yomichan creates through AnkiConnect. @@ -155,17 +155,17 @@ Flashcard fields can be configured with the following steps: -------|------------ `{audio}` | Audio sample of a native speaker's pronunciation in MP3 format (if available). `{cloze-body}` | Raw, inflected term as it appeared before being reduced to dictionary form by Yomichan. - `{cloze-prefix}` | Text for the containing `{sentence}` from the start up to the value of `{cloze-body}`. - `{cloze-suffix}` | Text for the containing `{sentence}` from the value of `{cloze-body}` to the end. + `{cloze-prefix}` | Fragment of the containing `{sentence}` starting at the beginning of `{sentence}` until the beginning of `{cloze-body}`. + `{cloze-suffix}` | Fragment of the containing `{sentence}` starting at the end of `{cloze-body}` until the end of `{sentence}`. `{dictionary}` | Name of the dictionary from which the card is being created (unavailable in *grouped* mode). `{document-title}` | Title of the web page that the term appeared in. - `{expression}` | Term expressed as Kanji (will be displayed in Kana if Kanji is not available). - `{furigana}` | Term expressed as Kanji with Furigana displayed above it (e.g. 日本語にほんご). - `{furigana-plain}` | Term expressed as Kanji with Furigana displayed next to it in brackets (e.g. 日本語[にほんご]). + `{expression}` | Term expressed as kanji (will be displayed in kana if kanji is not available). + `{furigana}` | Term expressed as kanji with furigana displayed above it (e.g. 日本語にほんご). + `{furigana-plain}` | Term expressed as kanji with furigana displayed next to it in brackets (e.g. 日本語[にほんご]). `{glossary}` | List of definitions for the term (output format depends on whether running in *grouped* mode). `{reading}` | Kana reading for the term (empty for terms where the expression is the reading). `{screenshot}` | Screenshot of the web page taken at the time the term was added. - `{sentence}` | Sentence, quote, or phrase in which the term appears in the source content. + `{sentence}` | Sentence, quote, or phrase that the term appears in from the source content. `{tags}` | Grammar and usage tags providing information about the term (unavailable in *grouped* mode). `{url}` | Address of the web page in which the term appeared in. @@ -173,38 +173,38 @@ Flashcard fields can be configured with the following steps: Marker | Description -------|------------ - `{character}` | Unicode glyph representing the current Kanji. + `{character}` | Unicode glyph representing the current kanji. `{cloze-body}` | Raw, inflected parent term as it appeared before being reduced to dictionary form by Yomichan. - `{cloze-prefix}` | Text for the containing `{sentence}` from the start up to the value of `{cloze-body}`. - `{cloze-suffix}` | Text for the containing `{sentence}` from the value of `{cloze-body}` to the end. + `{cloze-prefix}` | Fragment of the containing `{sentence}` starting at the beginning of `{sentence}` until the beginning of `{cloze-body}`. + `{cloze-suffix}` | Fragment of the containing `{sentence}` starting at the end of `{cloze-body}` until the end of `{sentence}`. `{dictionary}` | Name of the dictionary from which the card is being created. - `{document-title}` | Title of the web page that the Kanji appeared in. - `{glossary}` | List of definitions for the Kanji. - `{kunyomi}` | Kunyomi (Japanese reading) for the Kanji expressed as Katakana. - `{onyomi}` | Onyomi (Chinese reading) for the Kanji expressed as Hiragana. - `{screenshot}` | Screenshot of the web page taken at the time the Kanji was added. - `{sentence}` | Sentence, quote, or phrase in which the character appears in the source content. - `{url}` | Address of the web page in which the Kanji appeared in. + `{document-title}` | Title of the web page that the kanji appeared in. + `{glossary}` | List of definitions for the kanji. + `{kunyomi}` | Kunyomi (Japanese reading) for the kanji expressed as katakana. + `{onyomi}` | Onyomi (Chinese reading) for the kanji expressed as hiragana. + `{screenshot}` | Screenshot of the web page taken at the time the kanji was added. + `{sentence}` | Sentence, quote, or phrase that the character appears in from the source content. + `{url}` | Address of the web page in which the kanji appeared in. -When creating your model for Yomichan, *please make sure that you pick a unique field to be first*; fields that will -contain `{expression}` or `{character}` are ideal candidates for this. Anki does not require duplicate flashcards to be -added to a deck and uses the first field in the model to check for duplicates. If, for example, you have `{reading}` -configured to be the first field in your model and already have 橋はし in your deck, you will not -be able to create a flashcard for 箸はし, because they share the same reading. +When creating your model for Yomichan, *make sure that you pick a unique field to be first*; fields that will +contain `{expression}` or `{character}` are ideal candidates for this. Anki does not allow duplicate flashcards to be +added to a deck by default; it uses the first field in the model to check for duplicates. For example, if you have `{reading}` +configured to be the first field in your model and 橋はし is already in your deck, you will not +be able to create a flashcard for 箸はし because they share the same reading. ### Flashcard Creation ### Once Yomichan is configured, it becomes trivial to create new flashcards with a single click. You will see the following -icons next to term definitions. +icons next to term definitions: -* Clicking ![](https://foosoft.net/projects/yomichan/img/btn-add-expression.png) adds the current expression as Kanji (e.g. 食べる). -* Clicking ![](https://foosoft.net/projects/yomichan/img/btn-add-reading.png) adds the current expression as Hiragana or Katakana (e.g. たべる). +* Clicking ![](https://foosoft.net/projects/yomichan/img/btn-add-expression.png) adds the current expression as kanji (e.g. 食べる). +* Clicking ![](https://foosoft.net/projects/yomichan/img/btn-add-reading.png) adds the current expression as hiragana or katakana (e.g. たべる). Below are some troubleshooting tips you can try if you are unable to create new flashcards: * Individual icons will appear grayed out if a flashcard cannot be created for the current definition (e.g. it already exists in the deck). -* If all of the buttons appear grayed out then you should double-check your deck and model configuration settings. -* If no icons appear at all, please make sure that Anki is running in the background and that [AnkiConnect](https://foosoft.net/projects/anki-connect) has been installed. +* If all of the buttons appear grayed out, then you should double-check your deck and model configuration settings. +* If no icons appear at all, make sure that Anki is running in the background and that [AnkiConnect](https://foosoft.net/projects/anki-connect) has been installed. ## Keyboard Shortcuts ## @@ -219,7 +219,7 @@ The following shortcuts are available on search results: Shortcut | Action ---------|------- -Esc | Cancel current search +Esc | Cancel current search. Alt + PgUp | Page up through results. Alt + PgDn | Page down through results. Alt + End | Go to last result. @@ -230,17 +230,18 @@ Shortcut | Action Alt + e | Add current term as expression to Anki. Alt + r | Add current term as reading to Anki. Alt + p | Play audio for current term. -Alt + k | Add current Kanji to Anki. +Alt + k | Add current kanji to Anki. ## Development ## -Working on Yomichan and related tools is very time consuming and I am always on the lookout for code contributions from -other developers who want to help out. I take pride in the high quality of the codebase and ask you to follow the -following basic guidelines when creating pull requests: +As feature development and improvements to Yomichan can be time consuming, contributions are welcome from +any developers who want to help out. Below are a few guidelines to ensure contributions have a good level +of quality and consistency: -* Please discuss large features before writing code. +* Open GitHub issues to discuss large features before writing code. * Follow the [conventions and style](.eslintrc.json) of the existing code. -* Write clean, modern ES6 code (`const`/`let`, `await`, arrow functions, etc.) +* Test changes using the continuous integration tests included in the repository (`npm ci; npm test`). +* Write clean, modern ES6 code (`const`/`let`, `async`/`await`, arrow functions, etc.) * Large pull requests without a clear scope will not be merged. * Incomplete or non-standalone features will not be merged. @@ -277,7 +278,7 @@ one of the following solutions should work for you: feature to reset your user profile. It appears that the Firefox profile system can corrupt itself preventing IndexedDB from being accessible to Yomichan. -**Why does the Kanji results page display "No data found" for several fields?** +**Why does the kanji results page display "No data found" for several fields?** You are using data from the KANJIDIC dictionary that was exported for an earlier version of Yomichan. It does not contain the additional information which newer versions of Yomichan expect. Unfortunately, since major browser @@ -288,16 +289,16 @@ your database and install the latest version of the KANJIDIC to see additional i Developing Yomichan is a constant balance between including useful features and keeping complexity at a minimum. With the new user-editable card template system, it is possible to create text-only cards without having to double -the number field of templates in the extension itself. If you would like to stop HTML tags from being added to your +the number of field templates in the extension itself. If you would like to stop HTML tags from being added to your cards, simply copy the contents of the [text-only field template](https://foosoft.net/projects/yomichan/dl/fields.txt) into the template box on the Anki settings page (make sure you have the *Show advanced options* checkbox ticked), making sure to replace the existing values. **Will you add support for online dictionaries?** -Online dictionaries will never be implemented because it is impossible to support them in a robust way. In order to -perform Japanese deinflection, Yomichan must execute dozens of database queries per every single word. Factoring in -network latency and the fragility of web scraping, I do not believe that it is possible to realize a good user +Online dictionaries will not be implemented because it is not possible to support them in a robust way. In order to +perform Japanese deinflection, Yomichan must execute dozens of database queries for every single word. Factoring in +network latency and the fragility of web scraping, it would not be possible to maintain a good and consistent user experience. **Is it possible to use Yomichan with files saved locally on my computer with Chrome?** @@ -308,21 +309,22 @@ will likely never be possible to use Yomichan with PDF files. **Is it possible to delete individual dictionaries without purging the database?** -Although it is technically possible to purge specific dictionaries, due to the limitations of the underlying browser -IndexedDB system, this process is *extremely* slow. For example, it can take up to ten minutes to delete a single -moderately-sized term dictionary! Instead of including a borderline unusable feature in Yomichan, I have chosen to -disable dictionary deletion entirely. +Yomichan is able to delete individual dictionaries, but keep in mind that this process can be *very* slow and can +cause the browser to become unresponsive. The time it takes to delete a single dictionary can sometimes be roughly +the same as the time it originally took to import, which can be significant for certain large dictionaries. **Why aren't EPWING dictionaries bundled with Yomichan?** -The vast majority of EPWING dictionaries are proprietary, so unfortunately I am unable to legally include them in -this extension for copyright reasons. +The vast majority of EPWING dictionaries are proprietary, so they are unfortunately not able to be included in +this extension due to copyright reasons. **When are you going to add support for $MYLANGUAGE?** -Developing Yomichan requires a significant understanding of Japanese sentence structure and grammar. I have no time -to invest in learning yet another language; therefore other languages will not be supported. I will also not accept -pull request containing this functionality, as I will ultimately be the one maintaining your code. +Developing Yomichan requires a decent understanding of Japanese sentence structure and grammar, and other languages +are likely to have their own unique set of rules for syntax, grammar, inflection, and so on. Supporting additional +languages would not only require many additional changes to the codebase, it would also incur significant maintenance +overhead and knowledge demands for the developers. Therefore, suggestions and contributions for supporting +new languages will be declined, allowing Yomichan's focus to remain Japanese-centric. ## Legal ##