From ed710ed71cf5cac814a9cfa4fdded766a9e238b8 Mon Sep 17 00:00:00 2001 From: Alex Yatskov Date: Tue, 14 Mar 2017 21:10:48 -0700 Subject: [PATCH] Updating README.md --- README.md | 142 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 84 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 1c038116..3acd75ca 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,100 @@ # Yomichan # -Yomichan turns your browser into a tool for building Japanese language literacy by helping you to decipher texts which -would be otherwise too difficult tackle. This extension was inspired in part by -[Rikaichan](https://addons.mozilla.org/en-US/firefox/addon/rikaichan/) and -[Rikaikun](https://chrome.google.com/webstore/detail/rikaikun/jipdnfibhldikgcjhfnomkfpcebammhp?hl=en), but it stands -apart in its goal of being a all-encompassing learning tool as opposed to a mere browser-based dictionary. It is the -evolution of the [Yomichan](https://foosoft.net/projects/yomichan-anki) plugin that I developed for Anki when I began studying Japanese. +Yomichan turns your web browser into a tool for building Japanese language literacy by helping you to decipher texts +which would be otherwise too difficult tackle. This extension is similar to +[Rikaichan](https://addons.mozilla.org/en-US/firefox/addon/rikaichan/) for Firefox and +[Rikaikun](https://chrome.google.com/webstore/detail/rikaikun/jipdnfibhldikgcjhfnomkfpcebammhp?hl=en) for Chrome, but it +stands apart in its goal of being a all-encompassing learning tool as opposed to a mere browser-based dictionary. -## Requirements ## +Yomichan provides advanced features not available in other browser-based dictionaries: -For basic functionality: +* Interactive popup definition window for displaying search results. +* On-demand audio playback for select dictionary definitions. +* Kanji stroke order diagrams are just a click away for most characters. +* Custom search page for easily executing custom search queries. +* Support for multiple dictionary formats including [EPWING](https://ja.wikipedia.org/wiki/EPWING) via + the [Yomichan Import](https://foosoft.net/projects/yomichan-import) tool. +* Automatic note creation for the [Anki](https://apps.ankiweb.net/) flashcard program via + the [AnkiConnect](https://foosoft.net/projects/anki-connect) plugin. +* Clean, modern code makes it easy for developers to [contribute](https://github.com/FooSoft/yomichan) new features. -* [Google Chrome](https://www.google.com/chrome/browser/desktop/) (versions 45+) -* [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/new/) (versions 51+) +## Browser Support ## -For development: +* Google Chrome (versions 45+) -* [Git LFS](https://git-lfs.github.com/) -* [Go](https://golang.org/) -* [Handlebars](http://handlebarsjs.com/) -* [Node.js](https://nodejs.org/) + [![](https://foosoft.net/projects/yomichan/img/chrome-web-store.png)](https://chrome.google.com/webstore/detail/yomichan/ogmnaimimemjmbakcfefmnahgdfhfami) -## Installation ## +* Mozilla Firefox (versions 51+) -Yomichan can downloaded free of charge from the [Chrome Web -Store](https://chrome.google.com/webstore/detail/yomichan/ogmnaimimemjmbakcfefmnahgdfhfami) and the [Firefox -Marketplace](https://addons.mozilla.org/en-US/firefox/addon/yomichan/). If you find this extension helpful and -appreciate the time that was spent developing it, I would kindly ask that you leave a positive review. Your support and -feedback encourages continued development of this tool. + [![](https://foosoft.net/projects/yomichan/img/firefox-marketplace.png)](https://addons.mozilla.org/en-US/firefox/addon/yomichan/) -[![](https://foosoft.net/projects/yomichan/img/store.png)](https://chrome.google.com/webstore/detail/yomichan/ogmnaimimemjmbakcfefmnahgdfhfami) -[![](https://foosoft.net/projects/yomichan/img/market.png)](https://addons.mozilla.org/en-US/firefox/addon/yomichan/) + Yomichan is sitting in a queue to be reviewed and signed by Mozilla. This process can take months; if you wish to + use this extension today: -At present, Yomichan is sitting in a queue to be reviewed and signed by Mozilla. If you don't want to wait for several -weeks for approval and wish to use this extension in Firefox today, you can follow the steps below: + 1. Type `about:config` into the browser address bar. + 2. Skip past the "voiding your warranty" nag screen. + 3. Type `xpinstall.signatures.required` into the search bar on top. + 4. Double-click the displayed entry to set its value to `false`. + 5. Install extension as usual from the [Firefox Marketplace](https://addons.mozilla.org/en-US/firefox/addon/yomichan/). -1. Type `about:config` into the browser address bar. -2. Skip past the "voiding your warranty" nag screen. -3. Type `xpinstall.signatures.required` into the search bar on top. -4. Double-click the displayed entry to set its value to `false`. -5. Install extension as usual from the [Firefox Marketplace](https://addons.mozilla.org/en-US/firefox/addon/yomichan/). +## Basic Features ## -## Basic Functionality ## +1. Click on the ![](https://foosoft.net/projects/yomichan/img/logo.png) icon in the browser toolbar to open the Yomichan actions dialog. -1. Click on the ![](https://foosoft.net/projects/yomichan/img/logo.png) icon in the browser toolbar to open the Yomichan options page. -2. Import the dictionaries (bundled or custom) you wish to use for term and Kanji searches. -3. Hold down Shift (or the middle mouse button) as you hover over text to see term definitions. -4. Click on the ![](https://foosoft.net/projects/yomichan/img/play-audio.png) icon to hear the term pronounced by a native speaker (if audio is available). -5. Click on Kanji in the definition window to view additional information about that character. + [![Actions dialog](https://foosoft.net/projects/yomichan/img/ui-actions-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-actions.png) + +2. Click on the *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 + (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. + + [![Dictionary importer](https://foosoft.net/projects/yomichan/img/ui-import-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-import.png) + +4. Hold down the Shift key or the middle mouse button as you move your mouse over text to display a popup + window containing term definitions. This window will only be shown if definitions were found and it can be dismissed + by clicking anywhere outside of it. + + [![Term search results](https://foosoft.net/projects/yomichan/img/ui-terms-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-terms.png) + +5. Click on the ![](https://foosoft.net/projects/yomichan/img/button-play-audio.png) icon to hear the term pronounced by a native speaker. If an audio sample is not + available, you will hear a short click instead. + +6. Click on individual Kanji in the term definition results to view additional information about those characters + including readings, meanings, and a stroke order diagram. + + [![Kanji search results](https://foosoft.net/projects/yomichan/img/ui-kanji-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-kanji.png) ## Custom Dictionaries ## -Yomichan supports importing of custom dictionaries including the esoteric but popular -[EPWING](https://ja.wikipedia.org/wiki/EPWING) format. For more information about how to use this feature, please see -the [Yomichan Import](https://foosoft.net/projects/yomichan-import) project page. +Yomichan supports the use of custom dictionaries including the esoteric but popular +[EPWING](https://ja.wikipedia.org/wiki/EPWING) format. 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. + +[![Pocket dictionaries](https://foosoft.net/projects/yomichan/img/dictionary-thumb.png)](https://foosoft.net/projects/yomichan/img/dictionary.jpg) ## Anki Integration ## Yomichan features automatic flashcard creation for [Anki](http://ankisrs.net/), a free application designed to help you -retain knowledge. This functionality requires prior installation of the -[AnkiConnect](https://foosoft.net/projects/anki-connect/) plugin. The installation process can be done in three steps: - -1. Open the *Install Add-on* dialog by selecting *Tools* > *Add-ons* > *Browse & Install* in Anki. -2. Input *2055492159* into the text box labeled *Code* and press the *OK* button to proceed. -3. Restart Anki when prompted to do so in order to complete the installation of AnkiConnect. - -When using AnkiConnect, Anki must be kept running in the background for automatic flashcard creation to function. +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. ### Flashcard Configuration ### -Before flashcards can be automatically created through Yomichan, Anki must be configured as follows: +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](http://ankisrs.net/docs/manual.html). In short, you must specify what information should be included in the +flashcards that Yomichan creates through AnkiConnect. This can be accomplished with the following steps: -1. In your web browser, open the Yomichan options page by clicking the ![](https://foosoft.net/projects/yomichan/img/logo.png) icon. -2. Activate the *Terms* or the *Kanji* tab, depending on the type of card template you wish to configure. -3. Select the Anki deck and model to use when creating new flashcards (see the [Anki Manual](http://ankisrs.net/docs/manual.html) for more details). -4. Populate the model fields with markup representing contextual properties for the current vocabulary term or Kanji: +1. Open the Yomichan options page and scroll down to the section labeled *Anki Options*. +2. Tick the checkbox labeled *Enable Anki integration* (Anki must be running with [AnkiConnect](https://foosoft.net/projects/anki-connect) installed). +3. Select the type of template to configure by clicking on either the *Terms* or *Kanji* tabs. +4. Select the Anki deck and model to use for new creating new flashcards of this type. +5. Fill out the displayed model fields with markers representing the information you wish to include: #### Markers for Term Cards #### @@ -101,12 +121,18 @@ Before flashcards can be automatically created through Yomichan, Anki must be co `{onyomi}` | Onyomi (Chinese reading) for the Kanji expressed as Hiragana. `{url}` | Address of the web page in which the Kanji appeared in. -5. Click on the ![](https://foosoft.net/projects/yomichan/img/add-expression.png) icon to add the current expression using Kanji (e.g. 食べる). If the icon - appears grayed out, this means that a new flashcard cannot be created with the current configuration (please verify - your Anki deck and model settings). -6. Click on the ![](https://foosoft.net/projects/yomichan/img/add-reading.png) icon to add the current expression using the reading alone (e.g. たべる). If - the icon appears grayed out, this means that a new flashcard cannot be created with the current configuration - (please verify your Anki deck and model settings). +### 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. + +* Clicking ![](https://foosoft.net/projects/yomichan/img/button-add-expression.png) adds the current expression as Kanji (e.g. 食べる). +* Clicking ![](https://foosoft.net/projects/yomichan/img/button-add-reading.png) adds the current expression as Hiragana or Katakana (e.g. たべる). + +These icons will appear grayed out if a flashcard cannot be created for the current definition (it already exists in the +deck, for example). If all of the buttons appear grayed out then you should double-check your deck and model +configuration settings (see the Flashcard Configuration section above). If no icons appear at all, please make sure that +Anki is running in the background. ## Frequently Asked Questions ##