Merge branch 'dev'

This commit is contained in:
Alex Yatskov 2017-09-24 12:18:39 -07:00
commit 2c215b58d5

112
README.md
View File

@ -12,10 +12,8 @@ Yomichan provides advanced features not available in other browser-based diction
* On-demand audio playback for select dictionary definitions. * On-demand audio playback for select dictionary definitions.
* Kanji stroke order diagrams are just a click away for most characters. * Kanji stroke order diagrams are just a click away for most characters.
* Custom search page for easily executing custom search queries. * Custom search page for easily executing custom search queries.
* Support for multiple dictionary formats including [EPWING](https://ja.wikipedia.org/wiki/EPWING) via * Support for multiple dictionary formats including [EPWING](https://ja.wikipedia.org/wiki/EPWING) via the [Yomichan Import](https://foosoft.net/projects/yomichan-import) tool.
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.
* 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. * Clean, modern code makes it easy for developers to [contribute](https://github.com/FooSoft/yomichan) new features.
## Downloads ## ## Downloads ##
@ -28,13 +26,9 @@ Yomichan provides advanced features not available in other browser-based diction
[![](https://foosoft.net/projects/yomichan/img/firefox-marketplace.png)](https://addons.mozilla.org/en-US/firefox/addon/yomichan/) [![](https://foosoft.net/projects/yomichan/img/firefox-marketplace.png)](https://addons.mozilla.org/en-US/firefox/addon/yomichan/)
All extension versions must be reviewed before they are publicly accessible on the Firefox Marketplace. As this
review process can take several months to complete, the approved version of the extension is often out of date. If
you are interested in using the latest and greatest version, please consider using the [locally hosted](https://foosoft.net/projects/yomichan/dl/latest.xpi) version instead.
## Dictionaries ## ## Dictionaries ##
There are three free Japanese dictionaries available for Yomichan, with two of them having versions with glossaries in 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 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, please see the [Yomichan
Import](https://foosoft.net/projects/yomichan-import) page to learn how to convert and import them into Yomichan. Import](https://foosoft.net/projects/yomichan-import) page to learn how to convert and import them into Yomichan.
@ -58,40 +52,41 @@ primary language is not English, you may consider also importing the English ver
* **[KireiCake](https://kireicake.com/rikaicakes/)** (Japanese slang) * **[KireiCake](https://kireicake.com/rikaicakes/)** (Japanese slang)
* [kireicake.zip](https://foosoft.net/projects/yomichan/dl/dict/kireicake.zip) * [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) ([ver. 1.3.5 and older](https://foosoft.net/projects/yomichan/dl/dict/kanjidic_english_old.zip)) * [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) ([ver. 1.3.5 and older](https://foosoft.net/projects/yomichan/dl/dict/kanjidic_french_old.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) ([ver. 1.3.5 and older](https://foosoft.net/projects/yomichan/dl/dict/kanjidic_portuguese_old.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) ([ver. 1.3.5 and older](https://foosoft.net/projects/yomichan/dl/dict/kanjidic_spanish_old.zip)) * [kanjidic_spanish.zip](https://foosoft.net/projects/yomichan/dl/dict/kanjidic_spanish.zip)
* **[Innocent Corpus](https://forum.koohii.com/post-168613.html#pid168613)** (Frequency list of terms and Kanji in 5000+ novels) * **[Innocent Corpus](https://forum.koohii.com/post-168613.html#pid168613)** (Term and Kanji frequencies across 5000+ novels)
* [innocent_corpus.zip](https://foosoft.net/projects/yomichan/dl/dict/innocent_corpus.zip) * [innocent_corpus.zip](https://foosoft.net/projects/yomichan/dl/dict/innocent_corpus.zip)
## Basic Usage ## ## Basic Usage ##
1. Click on the ![](https://foosoft.net/projects/yomichan/img/yomichan-icon.png) icon in the browser toolbar to open the Yomichan actions dialog. 1. Click on the ![](https://foosoft.net/projects/yomichan/img/yomichan-icon.png) icon in the browser toolbar to open the Yomichan actions dialog.
[![Actions dialog](https://foosoft.net/projects/yomichan/img/ui-actions-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-actions.png) [![](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. 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 (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. 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) [![](https://foosoft.net/projects/yomichan/img/ui-import-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-import.png)
4. Hold down the <kbd>Shift</kbd> key or the middle mouse button as you move your mouse over text to display a popup 4. Hold down the <kbd>Shift</kbd> 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 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. 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) [![](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/btn-play-audio.png) icon to hear the term pronounced by a native speaker. If an audio sample is 5. Click on the ![](https://foosoft.net/projects/yomichan/img/btn-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. 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 readings, meanings, and a stroke order diagram. including stroke order diagrams, readings, meanings, as well as other useful data.
[![Kanji search results](https://foosoft.net/projects/yomichan/img/ui-kanji-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-kanji.png) [![](https://foosoft.net/projects/yomichan/img/ui-kanji-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-kanji.png)
## Custom Dictionaries ## ## Custom Dictionaries ##
@ -125,7 +120,9 @@ Flashcard fields can be configured with the following steps:
2. Tick the checkbox labeled *Enable Anki integration* (Anki must be running with [AnkiConnect](https://foosoft.net/projects/anki-connect) installed). 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. 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. 4. Select the Anki deck and model to use for new creating new flashcards of this type.
5. Fill the model fields with markers corresponding to the information you wish to include (several can be used): 5. Fill the model fields with markers corresponding to the information you wish to include (several can be used at
once). Advanced users can also configure the actual [Handlebars](http://handlebarsjs.com/) templates used to create
the flashcard contents (this is strictly optional).
#### Markers for Term Cards #### #### Markers for Term Cards ####
@ -161,10 +158,10 @@ Flashcard fields can be configured with the following steps:
`{url}` | Address of the web page in which the Kanji appeared in. `{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 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. Anki does not require duplicate flashcards to be added to contain `{expression}` or `{character}` are ideal candidates for this. Anki does not require duplicate flashcards to be
a deck and uses the first field in the model to check for duplicates. If, for example, you have `{reading}` configured added to a deck and uses the first field in the model to check for duplicates. If, for example, you have `{reading}`
to be the first field in your model and already have <ruby><rt>はし</rt></ruby> in your deck, you will not be able to configured to be the first field in your model and already have <ruby><rt>はし</rt></ruby> in your deck, you will not
create a flashcard for <ruby><rt>はし</rt></ruby>, because they share the same reading. be able to create a flashcard for <ruby><rt>はし</rt></ruby>, because they share the same reading.
### Flashcard Creation ### ### Flashcard Creation ###
@ -213,24 +210,24 @@ other developers who want to help out. I take pride in the high quality of the c
following basic guidelines when creating pull requests: following basic guidelines when creating pull requests:
* Please discuss large features before writing code. * Please discuss large features before writing code.
* Follow the conventions and style of the existing code. * Follow the [conventions and style](https://raw.githubusercontent.com/FooSoft/dotfiles/master/.eslintrc.json) of the existing code.
* Write clean, modern ES6 code (`const`/`let`, promises, arrow functions, etc.) * Write clean, modern ES6 code (`const`/`let`, `await`, arrow functions, etc.)
* Large pull requests without a clear scope will not be merged. * Large pull requests without a clear scope will not be merged.
* Incomplete or non-standalone features will not be merged. * Incomplete or non-standalone features will not be merged.
### Templates ### ### Templates ###
Yomichan uses [Handlebars](http://handlebarsjs.com/) templates for user interface and Anki note formatting. The source Yomichan uses [Handlebars](http://handlebarsjs.com/) templates for user interface generation. The source templates are
templates are found in the `tmpl` directory and the compiled version is stored in the `ext/bg/js/templates.js` file. If found in the `tmpl` directory and the compiled version is stored in the `ext/bg/js/templates.js` file. If you modify the
you modify the source templates, you will need to also recompile them. If you are developing on Linux or Mac OS X, you source templates, you will need to also recompile them. If you are developing on Linux or Mac OS X, you can use the
can use the included `build_tmpl.sh` and `build_tmpl_auto.sh` (requires included `build_tmpl.sh` and `build_tmpl_auto.sh` shell scripts to do this for you
[inotify-tools](https://github.com/rvoicilas/inotify-tools/wiki)) shell scripts to do this for you. Otherwise, simply ([inotify-tools](https://github.com/rvoicilas/inotify-tools/wiki) required). Otherwise, simply execute `handlebars
execute `handlebars tmpl/*.html -f ext/bg/js/templates.js` from the project's base directory. tmpl/*.html -f ext/bg/js/templates.js` from the project's base directory to compile all the templates.
### Dependencies ### ### Dependencies ###
Yomichan relies on several third-party libraries to function. The following are links to homepages and snapshots of the Yomichan uses several third-party libraries to function. Below are links to homepages and snapshots of the exact
exact versions used for distribution. versions packaged.
* Bootstrap Toggle: [homepage](http://www.bootstraptoggle.com/) - [snapshot](https://github.com/minhur/bootstrap-toggle/archive/b76c094.zip) * Bootstrap Toggle: [homepage](http://www.bootstraptoggle.com/) - [snapshot](https://github.com/minhur/bootstrap-toggle/archive/b76c094.zip)
* Bootstrap: [homepage](http://getbootstrap.com/) - [snapshot](https://github.com/twbs/bootstrap/releases/download/v3.3.7/bootstrap-3.3.7-dist.zip) * Bootstrap: [homepage](http://getbootstrap.com/) - [snapshot](https://github.com/twbs/bootstrap/releases/download/v3.3.7/bootstrap-3.3.7-dist.zip)
@ -245,8 +242,9 @@ exact versions used for distribution.
* **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 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. Please purge your database and install contain the additional information which newer versions of Yofomichan expect. Unfortunately, since major browser
the latest version of the KANJIDIC to see additional information about characters. implementations of IndexedDB do not provide reliable means for selective bulk data deletion, you will need purge
your database and install the latest version of the KANJIDIC to see additional information about characters.
* **Can I still create cards without HTML formatting? The option for it is gone!** * **Can I still create cards without HTML formatting? The option for it is gone!**
@ -264,32 +262,18 @@ exact versions used for distribution.
network latency and the fragility of web scraping, I do not believe that it is possible to realize a good user network latency and the fragility of web scraping, I do not believe that it is possible to realize a good user
experience. experience.
* **What happened to AnkiWeb integration? Why was it removed?** * **Is it possible to use Yomichan with files saved locally on my computer with Chrome?**
The author of Anki wants to maintain tight control of AnkiWeb by restricting automated web requests, while at the In order to use Yomichan with local files in Chrome, you must first tick the *Allow access to file URLs* checkbox
same time not providing an API for adding or removing flash cards. As circumventing these limitations led to account for Yomichan on the extensions page. Due to the restrictions placed on browser addons in the WebExtensions model, it
restrictions placed on users of this extension, I was forced to remove this feature. Note that it is still possible
to automatically generate flashcards with the [AnkiConnect](https://foosoft.net/projects/anki-connect) plugin.
* **Is it possible to use Yomichan with files saved locally on my computer?**
It in order to be able use Yomichan with local files in Chrome, you must first tick the *Allow access to file URLs*
checkbox for Yomichan on the Chrome extensions page. Due to restrictions placed on browser extensions by Chrome, it
will likely never be possible to use Yomichan with PDF files. will likely never be possible to use Yomichan with PDF files.
* **Is it possible to delete individual dictionaries without resetting the database?** * **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 Although it is technically possible to purge specific dictionaries, due to the limitations of the underlying browser
database system, this process is *extremely* slow. For example, it can take up to ten minutes to delete a term IndexedDB system, this process is *extremely* slow. For example, it can take up to ten minutes to delete a single
dictionary of moderate size! Instead of including a borderline unusable feature in Yomichan, I disabled dictionary moderately-sized term dictionary! Instead of including a borderline unusable feature in Yomichan, I have chosen to
deletion entirely. disable dictionary deletion entirely.
* **Why doesn't Yomichan work after being removed and reinstalled on Firefox?**
Uninstalling Yomichan on Firefox may sometimes leave the dictionary database in an undefined state. Although most of
the data has been deleted, the metadata describing it appears unchanged. This can make it look like you have
dictionaries installed when you actually do not. Purge the database and reimport your dictionaries to fix this
problem.
* **Why aren't EPWING dictionaries bundled with Yomichan?** * **Why aren't EPWING dictionaries bundled with Yomichan?**
@ -298,10 +282,9 @@ exact versions used for distribution.
* **When are you going to add support for $MYLANGUAGE?** * **When are you going to add support for $MYLANGUAGE?**
Developing Yomichan required a significant understanding of Japanese sentence structure and grammar. I presently Developing Yomichan requires a significant understanding of Japanese sentence structure and grammar. I have no time
have no time to invest in learning yet another language; therefore other languages will not be supported. I will to invest in learning yet another language; therefore other languages will not be supported. I will also not accept
also not be accepting pull request containing this functionality, as I will ultimately be the one maintaining your pull request containing this functionality, as I will ultimately be the one maintaining your code.
code.
## Screenshots ## ## Screenshots ##
@ -324,4 +307,3 @@ GNU General Public License for more details.
You should have received a copy of the GNU General Public License You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>. along with this program. If not, see <http://www.gnu.org/licenses/>.