-
Notifications
You must be signed in to change notification settings - Fork 19
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.
We now recommend publishing with GitHub instead of the instructions below, unless you will use LingView with private or confidential data. By using GitHub, you can easily publish your LingView website on the internet, as well as get the best use out of other features that were added after our paper was published.
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. 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 does not have any attached media.
You will need to have Node.js version 12.x installed to run the pre-processing scripts. Instructions for downloading Node can be found at http://blog.npmjs.org/post/85484771375/how-to-install-npm. For Windows: pick one of the Node 12.x installershttps://nodejs.org/download/release/v12.22.12/ that ends with ".msi". For Linux: pick one whose filename matches your OS. For Mac: you can use a download from that page, or use a Node version manager such as NVM. All of these Node installation methods include NPM, the Node package manager.
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.
Then run
npm run quick-build
This will pack the LingView site into a form that can be easily displayed on the web.
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 either File > Export Interlinear > Verifiable generic XML or File > Export Interlinear > FLEXTEXT. (If your FLEx file has audio or video, use FLEXTEXT.) 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.
npm run quick-build
The quick-build script will run both ELAN and FLEx preprocessing scripts on every available file. For ELAN files, and also for .flextext files that include time information (such as those exported from ELAN), the script will attempt to find matching audio or video files. Importantly, the script is also responsible for rebuilding the site index and then packaging the changes so that they can actually appear on the site. Therefore, we recommend running this command 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 do npm run quick-build as described above.
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 quick-build 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 quick-build 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 ELAN, FLEx, or media files, simply delete the files. Then do npm run quick-build as described above, so that your changes will appear in the index.
The text commands on this page 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. For your changes to appear, you will need to do npm run quick-build as described above. This will update the bundle.js file.
Most LingView users don't need to change the UI, but if you want to add an About page, change the UI's display language to something other than English, or make other changes to how LingView displays your content, this is how to do it. If you're changing the display language, you should also edit preprocessing/flex/tier_registry.js so that the tier names of FLEx files will display in the correct language.