Change file structure, Add more documentation

surrsurus · Nov 13, 2017 · 97dbff3 · 97dbff3
1 parent 7c14117
commit 97dbff3
Show file tree

Hide file tree

Showing 6 changed files with 143 additions and 70 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,5 @@
-# text-to-ipa
+# text-to-ipa ![JS Version](https://img.shields.io/badge/javascript-ES6-orange.svg) [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
 Text to IPA converter in JavaScript
 
 This comes with the core dictionary lookup and example frontend. This project assumes you will be running this translator in a browser of some sort. `text-to-ipa.js` contains the main logic for loading the `ipadict.txt` and looking up words, while `converter-form.js` and `example-translator.html` provide an interface.
@@ -7,16 +8,65 @@ Further reading on how this all takes place can be found inside the respective `
 
 An example you can use is in the `example-translator.html` file. Just download the repository and open up that file in a web browser.
 
-# Live example
+## Getting Started
+
+This tool implies that the CMU-IPA Dictionary _will_ be used. You can load any dictionary you want into this program, but the method to lookup words assumes it will be in the CMU format.
+
+This was kind of a pain to get working, as most of the time was found looking for a good IPA dictionary which was ultimately found [here](http://people.umass.edu/nconstan/CMU-IPA/). This dictionary is included with this repository by default.
+
+### Deploying
+
+1. Include the following in the web page you want to deploy a converter to:
+
+```
+<script src="./text-to-ipa.js"></script>
+<script src="./converter-form.js"></script>
+```
+
+2. Point the TextToIPA Object to the CMU IPA Dictionary like such:
+
+```
+window.onload = TextToIPA.loadDict('./ipadict.txt');
+```
+
+3. Set up a UI for the converter in the webpage. Here's an example:
+
+```
+<div id="js-text-to-ipa-form">
+
+  <ul style="list-style-type: none;">
+    <li><textarea id="ipa-in" placeholder="Write text here!" rows="4" cols="50"></textarea></li>
+    <li class="button"><button type="button" id="js-ipa-submit" onClick="ConverterForm.convert('ipa-in', 'ipa-out', 'ipa-err')">Convert!</button></li>
+    <li><textarea readonly id="ipa-out" placeholder="aʊtpʊt gəʊz hɪə!" rows="4" cols="50"></textarea></li>
+  </ul>
+
+  <ul style="list-style-type: none;">
+    <li><noscript><p>This converter will not work unless Javascript is enabled.</p></noscript></li>
+    <li>
+      <div id="ipa-err">
+        <p>Errors will go here if you make any. (This will be overwritten!)</p>
+      </div>
+    </li>
+  </ul>
+</div>
+```
+
+See examples for more.
+
+### Example
 
 For a styled and better looking version instead of one that has no CSS you can test it on my website [here](http://surrsur.us/projects/ipa/english-to-ipa.html)
 
-# How Does it Work?
+### Basic Usage
 
 This converter will simply look up each word in the CMU to IPA dictionary, and pop out the resulting phonetic text.
 
-## Note
+## License
 
-This tool implies that the CMU-IPA Dictionary _will_ be used. You can load any dictionary you want into this program, but the method to lookup words assumes it will be in the CMU format.
+<img align="center" src="https://licensebuttons.net/l/GPL/2.0/88x62.png" alt="GPL" width=100>
+
+This code is released under the GNU GENERAL PUBLIC LICENSE. All works in this repository are meant to be utilized under this license. You are entitled to remix, remodify, and redistribute this program as you see fit, under the condition that all derivative works must use the GPL Version 3.
+
+## Acknowledgements
 
-This was kind of a pain to get working, as most of the time was found looking for a good IPA dictionary which was ultimately found [here](http://people.umass.edu/nconstan/CMU-IPA/).
+[CMU IPA Dictionary](http://people.umass.edu/nconstan/CMU-IPA/)
diff --git a/example-translator.html b/example-translator.html
diff --git a/examples/example-translator.html b/examples/example-translator.html
@@ -0,0 +1,69 @@
+<html lang="en">
+
+<head>
+
+  <meta charset="utf-8">
+
+  <title>Text to IPA Generator</title>
+
+</head>
+
+<body>
+  <!-- Load in the scripts first -->
+  <script src="../lib/text-to-ipa.js"></script>
+  <script src="../lib/converter-form.js"></script>
+
+  <!-- Load dictionary on window load, you may want to change this according to your needs.
+  To demonstrate this program, it's just done on window load though.
+  NOTE: This program implies that the CMU IPA dictionary (http://people.umass.edu/nconstan/CMU-IPA/)
+  has been loaded with loadDict(). This dictionary is by default included with this
+  program under the name 'ipadict.txt'. This _WILL NOT WORK_ with any other IPA dictionary.
+  -->
+  <script>
+    // Chrome will error here, therefore it isnt the dev browser of choice. Use Firefox instead.
+    // This is because the `loadDict()` method will use an XHTTP Request to get the file, which chrome won't like because
+    // It's on the local machine. If you try to read the file from say, the GitHub repository, it *still* won't work,
+    // because it's not hosted on the same site. It's not worth the trouble to use a workaround especially when the program
+    // works as intended when used on a live website. See http://surrsur.us/projects/ipa/english-to-ipa.html.
+    window.onload = TextToIPA.loadDict('../lib/ipadict.txt');
+  </script>
+
+  <p>Use the following text areas to convert english to it's IPA equivalent.</p>
+  <p>This is NOT case sensitive and punctuation is ignored.</p>
+  <br />
+  <p>Note: If you are using chrome and this is being ran locally, the dictionary will not load due to the way Chrome handles XHTTP Requests. It does handle them normally on proper websites. Check out a live example <a href="http://surrsur.us/projects/ipa/english-to-ipa.html">here</a></p>
+  <br />
+
+  <!-- Create a form div -->
+  <div id="js-text-to-ipa-form">
+
+    <ul style="list-style-type: none;">
+      <!-- ipa-in is the designated ID to determine where text will be input from -->
+      <li><textarea id="ipa-in" placeholder="Write text here" rows="4" cols="50"></textarea></li>
+
+      <!-- This submit button runs the conversion on the input text
+      As you can see, when this buton is pressed, the conver() function is ran
+      where the input, output, and error IDs are given as parameters.
+      These can be set to whatever you like, as long as inID and outID are text areas, and errID is a div.
+      -->
+      <li class="button"><button type="button" id="js-ipa-submit" onClick="ConverterForm.convert('ipa-in', 'ipa-out', 'ipa-err')">Convert!</button></li>
+      <!-- ipa-out is the designated ID to determine where the converted text will be output to -->
+      <li><textarea readonly id="ipa-out" placeholder="aʊtpʊt gəʊz hɪə" rows="4" cols="50"></textarea></li>
+
+    </ul>
+
+    <ul style="list-style-type: none;">
+      <li><noscript><p>This converter will not work unless Javascript is enabled.</p></noscript></li>
+      <li>
+        <!-- ipa-err is the designated ID to determine where any errors with the translation will go -->
+        <div id="ipa-err">
+          <p>Errors will go here if you make any. (This will be overwritten)</p>
+        </div>
+      </li>
+    </ul>
+
+  </div>
+
+</body>
+
+</html>
diff --git a/converter-form.js → lib/converter-form.js b/converter-form.js → lib/converter-form.js
@@ -41,6 +41,8 @@ if (typeof ConverterForm !== 'object') {
   'use strict';
 
   // Error messages
+  // Store error messages in the ConverterForm Object for accessing later without
+  // polluting the global namespace.
 
   // Error message if a word entered is not defined within the dictionary
   if (typeof ConverterForm._undefMsg !== 'string') {

diff --git a/ipadict.txt → lib/ipadict.txt b/ipadict.txt → lib/ipadict.txt
diff --git a/text-to-ipa.js → lib/text-to-ipa.js b/text-to-ipa.js → lib/text-to-ipa.js
@@ -8,9 +8,14 @@
 //  has multiple IPA pronunciations, as well as the IPA text itself (pronunciations
 //  included).
 
+//  This can be viewed as an API to loading the CMU IPA Dictionary, and looking up words in it.
+//  This API is used by `converter-form.js` to give it functionality and a UI, though you can design
+//  your own for any purpose you so desire.
+
 // NOTE: This program implies that the CMU IPA dictionary (http://people.umass.edu/nconstan/CMU-IPA/)
 // will be used to get IPA translations. This dictionary is by default included with this
-// program under the name 'ipadict.txt'. This _WILL NOT WORK_ with any other IPA dictionary.
+// program under the name 'ipadict.txt' in the `lib` directory. 
+// This _WILL NOT WORK_ with any other IPA dictionary.
 
 //      TextToIPA.loadDict(location)
 //          location    Location to load the dictionary from. Since it's gotten
@@ -27,6 +32,8 @@
 //          a text attribute. The error determines if the word exists in IPA,
 //          if the word has multiple pronunciations. The text is the resulting
 //          IPA text of the lookup. See converter-form.js for how to utilize this.
+//          return      IPAWord Object with text under the `text` attribute
+//          and and errors under the `error` attribute.
 
 // ESLint settings. We want console logging and some problems may exist
 // with undefined objects (TextToIPA) but we check for these
@@ -51,15 +58,15 @@ if (typeof TextToIPA !== 'object') {
   }
 
   // Create a constructor for an IPAWord that makes displaying them and
-  // associated errors much easier.
-  // NOTE: This need not exist outside this program.
+  // associated errors much easier. 
   function IPAWord(error, text) {
     this.error = error;
     this.text = text;
   }
 
   // Functions
 
+  // Parse the dictionary. Only used by `loadDict`.
   if (typeof TextToIPA._parseDict !== 'function') {
     TextToIPA._parseDict = function (lines) {
       console.log('TextToIPA: Beginning parsing to dict...');
@@ -149,8 +156,11 @@ if (typeof TextToIPA !== 'object') {
           // Return the new word
           return new IPAWord(error, text);
 
+        // Otherwise the word isn't in the dictionary
         } else {
+
           return new IPAWord('undefined', word);
+
         }
 
       }
@@ -162,5 +172,6 @@ if (typeof TextToIPA !== 'object') {
 }());
 
 // Load dict
-// Could be intensive, might only want to load when necessary
-// window.onload = TextToIPA.loadDict('./ipadict.txt');
+// Could be intensive, might only want to load when necessary. Therefore it is commented out.
+// Feel free to re-enable if you want to just load the dictionary here, instead of somewhere else
+// window.onload = TextToIPA.loadDict('./path/to/dict.txt');