-
Notifications
You must be signed in to change notification settings - Fork 20
Workflow
This page, adapted from section 4 of our openly-accessible paper, describes the workflow for building and maintaining a collection of texts in LingView.
To use the software, begin by downloading the repository stored at https://github.com/BrownCLPS/LingView.git and extracting the zip file. You may place the extracted file anywhere on your computer, but to follow along with these instructions, we recommend extracting to your Desktop and renaming the extracted directory from "LingView-master" to simply "LingView". Open the extracted directory in File Explorer (on Windows) or Finder (on Mac). At this point, you will be able to view sample files by opening the index.html file with your browser. (Note: Google Chrome's same-origin policy will prevent the website from loading without a server. To get around this, you may choose to run a Python SimpleHttpServer (or equivalent) from the root LingView directory. Alternatively, the website will run offline without a server in Firefox or in Safari, after changing Safari's preferences.) LingView comes with two sample files, named "Intro" and "Singo a'i." The former was exported from ELAN and has associated audio/video, while the latter was exported from FLEx and therefore does not have any attached media.
If you do not have Node.js installed, you will need it to run the pre-processing scripts. Instructions for downloading Node can be found at http://blog.npmjs.org/post/85484771375/how-to-install-npm. Once you have installed Node.js and NPM (both of which are included in the previously linked download), you will need to install some packages. These are listed in the package.json file. Simply navigate to the root LingView directory, as described in the "Terminal" section, and run
npm install
This will read the required packages from the package.json file and install them for you. It is preferable to use NPM version 4.6.x for this process.
This section describes the steps for displaying your own ELAN and FLEx files using the LingView software.
For ELAN, the program automatically generates .eaf files. Simply copy these files to the data/elan_files directory. For FLEx, you must export the files into the correct XML format. To do so, open the file in FLEx, go to the "Analyze" tab, and select File > Export Interlinear > Verifiable generic XML. Save the resulting .xml file in the data/flex_files directory.
Place any corresponding media files (WAV, MP3, or MP4) into the data/media_files directory.
Once the ELAN, FLEx, and media files are in place, run the following command as described in the "Terminal" section.
node preprocessing/rebuild.js
This will run both ELAN and FLEx preprocessing scripts on every available file. For ELAN files, the script will attempt to find matching audio or video files. Importantly, this script is also responsible for rebuilding the site index. Therefore, we recommend running the rebuild script after deleting or editing any files.
After this process, when you open the index.html file with your browser, you will see your ELAN and FLEx files included in the index. You may repeat this process whenever you wish to add additional ELAN, FLEx, or media files.
Use the appropriate workflow for the type of data you want to change.
To update files, make the desired changes using ELAN, FLEx, or your favorite audio/video editor, save the result to the corresponding data/elan_files, data/flex_files, or data/media_files directory, and then run the rebuild script as described in the "Adding Files" section.
The website can show metadata for each story, including title, author, description, and other fields; the full list is here. This data, which is displayed on the story index and on the individual story pages, can be added or changed using the edit.js script. To use this script, first open index.html in your browser, navigate to the story you want to edit, and locate the unique ID associated with that story. This is a 36-character string found at the end of the story URL. For example, if the url is https://brownclps.github.io/LingView/\#/story/97b8ab3b-d2a5-428a-aa68-0aa304ba1c44, the unique ID is 97b8ab3b-d2a5-428a-aa68-0aa304ba1c44. With this unique ID copied to your clipboard, return to your terminal and type the following command:
node preprocessing/edit.js unique_id
where "unique_id" is replaced with the 36-character string described above. This script will offer a number of prompts, allowing you to edit the story title, description, etc. Repeat this process with any other stories whose metadata you wish to edit. After making these changes, run the rebuild script again so that they will appear on the LingView site.
Each ELAN file contains one or more annotation types or "tiers", such as transcription, translation, and morphemes. ELAN allows its users to hide or reorder these tiers at will, and it stores the current configuration in a separate .pfsx preferences file. (FLEx doesn't.) You may omit this file to use a default order, or you may open the file and edit its tier configuration in ELAN, which automatically creates or updates the preferences file. When the rebuild script is run, LingView checks the data/elan_files directory for a .pfsx file whose name matches the ELAN file. If one is found, LingView uses the specified tier order and completely omits any hidden tiers.
To remove an ELAN or FLEx file, first locate its unique ID as described in the "Editing Metadata" section. With this unique ID copied to your clipboard, return to your terminal and type the following command from the root project directory:
node preprocessing/delete.js unique_id
where \verb|unique_id| is replaced with the 36-character ID. If the file has associated media, you will be prompted to delete or retain the associated media files. Repeat this process for any other stories you wish to delete. Finally, run the rebuild script as described above so that your changes will appear in the index.
To remove a media file from the LingView site while leaving its ELAN file in place, delete the media file from the data/media_files directory and then run the the rebuild script for the changes to appear on the site.
The text commands in this section must be run from a terminal, a text-based interface, which comes preinstalled on all Mac, Windows, and Linux computers. On Mac, the Terminal app can be found using Spotlight search. On Windows, the relevant app is called Windows PowerShell (not Windows PowerShell ISE) and it can be found by tapping the Windows key to bring up the start menu, and then searching for the app's name. After opening the terminal, navigate to the root LingView directory using the cd command. For example, if you saved the LingView directory on your Desktop with the name "LingView":
cd ~/Desktop/LingView
At the end of each command you type in the terminal, tap the Enter or Return key to execute the command.
Most of the JavaScript code that runs on the site is stored in js/bundle.js. This code was automatically generated by Webpack, a module bundler which converts the ReactJS files (in .jsx format) into a single JavaScript file. To make edits to the front-end/UI code, we recommend editing the ReactJS files which are contained in the jsx/ directory. However, since the website reads from the bundle.js file, this will not cause immediate changes on the site. Rather, you will need to re-bundle with the following command:
npm run webpack
This will update the bundle.js file and modify the site accordingly.