📖 User Guide

Complete instructions for using FLEx Interlinear Copy Assistant

Getting Started

Installation

Windows Users

  1. Download FLEx.Interlinear.Copy.Assistant.exe from the latest release
  2. No installation required - just double-click the .exe file to run
  3. Windows may show a security warning for downloaded files - click "More info" then "Run anyway"

macOS and Linux Users

  1. Ensure Python 3.x is installed on your system
  2. Install the required dependency:
    pip install pyperclip
  3. Download flex-interlinear-copy.py
  4. Run the script:
    python3 flex-interlinear-copy.py
Note for macOS users: You may need to grant clipboard access permissions when first running the application.

Basic Workflow

The typical workflow for using this tool follows these steps:

Step 1: Copy Your Data

In FLEx or your spreadsheet application, select and copy the interlinear data you want to convert. The data should be in tab-separated format with rows like:

Step 2: Launch the Application

When you start the application, it automatically pastes the current clipboard contents into the preview window. You'll see your data displayed in a text box at the top of the window.

Step 3: Select Output Format

Use the dropdown menu to choose your desired output format:

LaTeX Options:

XLingPaper Options:

Other Formats:

Step 4: Configure Options

Use the checkboxes to customize the output:

Step 5: Convert and Copy

Click the "Convert and Re-Copy!" button. The converted output is automatically copied to your clipboard, ready to paste into your document.

Step 6: Paste into Your Document

Go to your LaTeX editor, Word processor, or XML editor and paste (Ctrl+V or Cmd+V). The formatted interlinear text will be inserted.

Manual Entry Mode

If you don't have data in FLEx, or want to create examples from scratch, use the manual entry feature:

  1. Click "Manually Enter Interlinear Example..." button
  2. Type or paste a source-language sentence in the dialog that appears
  3. A spreadsheet-like editor opens with your sentence split into cells
  4. Add rows for morphemes, glosses, etc. using the "Add Row" button
  5. Use "Split Cell" to divide a cell at the cursor position
  6. Use "Delete Row" to remove unwanted rows
  7. Enter the free translation in the text field at the bottom
  8. Click "Done" when finished
Known Issue: The manual editor has some bugs and may not work reliably in all cases. This is a known limitation being actively worked on.

Format-Specific Instructions

📝 Recommended: Using Overleaf.com (Online LaTeX Editor)

Overleaf.com is the easiest way to use LaTeX output from this tool. It's a free online editor that requires no software installation and automatically handles compilation. Follow these detailed steps:

Step 1: Create or Open Your Project

  1. Go to www.overleaf.com and sign in (or create a free account)
  2. Either create a New Project (green button) or open an existing project
  3. If creating new, select "Blank Project" and give it a name

Step 2: ⚙️ Configure the Compiler (CRITICAL)

⚠️ IMPORTANT: You MUST change the compiler to XeLaTeX or LuaLaTeX. The default pdfLaTeX will NOT work with interlinear examples and may not support IPA characters.
  1. Click the Menu button in the top-left corner (looks like three horizontal lines ☰)
  2. The settings panel opens on the left side of the screen
  3. Scroll down to find the "Compiler" dropdown menu
  4. Click on it and select either:
    • XeLaTeX (recommended) - better font support
    • LuaLaTeX (also works well)
  5. The menu will automatically save your choice - you'll see "Compiler: XeLaTeX" displayed

Step 3: 📦 Upload the MIT Interlinear Package

  1. Download the interlinear.sty file (right-click → Save As)
  2. In Overleaf, look at the left sidebar where your project files are listed
  3. Find and click the "Upload" icon/button (usually at the top of the file list, looks like an upload arrow ⬆)
  4. Select "Project Files" from the dropdown
  5. Click "Select files" and choose the interlinear.sty file you downloaded
  6. Click "Upload" - the file will appear in your project file list

Step 4: 🔧 Configure Your Document Preamble

In your main .tex file (usually main.tex), add these lines after the \documentclass{...} line but before \begin{document}:

% Required package for interlinear examples
\usepackage{interlinear}

% Required for IPA characters and special fonts
\usepackage{fontspec}

% Recommended: Set a font that supports IPA (Charis SIL)
\setmainfont{Charis SIL}
About Charis SIL: This is a free font designed for linguistic work with excellent IPA character support. Overleaf has it pre-installed, so just adding \setmainfont{Charis SIL} will work immediately!

Step 5 (Optional): Add Custom LaTeX Styles

If you enabled "Predefined LaTeX Styles" in the FLEx Interlinear Copy Assistant, add these commands to your preamble (after the packages):

% Custom formatting commands
\newcommand{\extitle}[1]{\textbf{\underline{#1}}}
\newcommand{\exsubtitle}[1]{\textit{#1}}
\newcommand{\txtref}[1]{\hfill\textit{#1}}

Step 6: ✂️ Paste Your Interlinear Examples

  1. In the document body (between \begin{document} and \end{document}), place your cursor where you want the example
  2. Paste the LaTeX code you copied from FLEx Interlinear Copy Assistant (Ctrl+V or Cmd+V)
  3. The code will include \begin{exe}, \ex, \glll or \gll commands, and \end{exe}

Step 7: ▶️ Compile and View

  1. Click the green "Recompile" button at the top of the preview pane
  2. Wait a few seconds for compilation to complete
  3. Your formatted interlinear examples will appear in the PDF preview on the right!
  4. If you see errors, they'll appear in red at the bottom - click on them to see details
💡 Pro Tips:
  • Overleaf auto-saves constantly - no need to manually save
  • Turn on "Auto Compile" (in the Menu) to see updates as you type
  • Use the "History" feature to revert to earlier versions if needed
  • Download your project as a ZIP file using Menu → Download → Source

🖥️ Using LaTeX on Your Computer (Advanced Users)

If you prefer to use LaTeX on your local machine:

Prerequisites:

📄 Using XLingPaper (XML Mind Editor)

XLingPaper is a specialized XML editor for linguistic papers developed by SIL International. It uses XML Mind XMLEditor as its underlying editor. Learn more at SIL's website.

⚠️ CRITICAL: XLingPaper does NOT allow pasting code into the graphical (WYSIWYG) editor. You MUST switch to XML Source view to insert examples.

Step 1: 🎯 Position Your Cursor

  1. Open your XLingPaper document in XMLMind
  2. In the graphical view (default WYSIWYG view), click where you want to insert your interlinear example
  3. This could be in a section, a paragraph, or inside an example environment
  4. Make note of your location - you'll need to find it in the XML code

Step 2: 🔄 Switch to XML Source View

  1. Go to the menu bar at the top
  2. Click View → XML Source (or press the keyboard shortcut if configured)
  3. The editor switches to show the raw XML code of your document
  4. You'll see tags like <section>, <p>, <example>, etc.

Step 3: 🔍 Find the Correct Insertion Point

  1. Locate the XML tags corresponding to where you clicked in the graphical view
  2. Look for appropriate container tags:
    • Inside an <example> tag for a new interlinear
    • After a </example> closing tag to add a new example
    • Inside a <listInterlinear> if adding to an existing list
  3. Place your cursor at the insertion point (usually just before a closing tag or after content)

Step 4: ✂️ Paste the XLingPaper XML Code

  1. Paste the XML code you copied from FLEx Interlinear Copy Assistant (Ctrl+V or Cmd+V)
  2. The pasted code will include tags like:
    • <example>, <interlinear> for single examples
    • <listInterlinear> for list items
    • <lineGroup>, <line>, <wrd> for the interlinear structure
    • <free> for free translations
  3. Make sure the pasted code is properly nested within the existing XML structure
⚠️ Be Very Careful: Incorrect XML placement can corrupt your document! Make sure opening and closing tags match and are properly nested.

Step 5: ✅ Validate and Switch Back

  1. XMLMind will usually highlight XML syntax errors in red if there are any problems
  2. Check that all your opening tags have matching closing tags
  3. Go back to View → Normal View (or WYSIWYG view) to see the formatted result
  4. Your interlinear example should now appear in the document!

Step 6: 💾 Save and Continue

  1. Save your document (Ctrl+S or Cmd+S)
  2. If XMLMind reports validation errors, go back to XML Source view to fix them
  3. You can now continue editing or add more examples using the same process
💡 XLingPaper Tips:
  • Always save before switching views - this helps prevent data loss
  • Use Ctrl+Z (Undo) if something goes wrong
  • Keep a backup copy of your document before making major changes
  • Consult the XLingPaper documentation for XML structure details
  • If you're new to XML, practice with a test document first

Using HTML Output

The HTML output creates a clean table suitable for:

The generated table uses basic HTML with inline styles, making it compatible with most platforms. FLEx row labels are automatically bolded.

Understanding Data Processing

Automatic Cleaning

The tool automatically performs several cleaning operations:

1. Removing Blank Columns

Columns that are completely empty across all rows are automatically removed to create cleaner output.

2. Handling Numbered Examples

If your data includes example numbers in the first column, the tool attempts to handle them intelligently, preserving them where appropriate.

3. Morpheme Break Markers

The tool recognizes morpheme boundary markers (-, =, _, .) and can:

4. Free Translation Formatting

Rows starting with "Free" or surrounded by single quotes are automatically recognized as free translations and formatted appropriately for each output format.

FLEx Label Processing

When "Remove FLEx row labels" is checked, the tool:

Tips and Best Practices

For Best Results:

Keyboard Shortcuts:

Troubleshooting:

Example Workflow

Converting a FLEx Example to LaTeX

Step-by-step example:

  1. In FLEx, select your interlinear text and copy it (Ctrl+C)
  2. Launch FLEx Interlinear Copy Assistant
  3. Your data appears in the preview window
  4. Select "LaTeX - MIT interlinear package - Single Example" from dropdown
  5. Check "Remove FLEx row labels" (should be on by default)
  6. Check "Remove Column breaks between Morphemes" (should be on by default)
  7. Click "Convert and Re-Copy!"
  8. Open your LaTeX editor
  9. Paste (Ctrl+V) where you want the example to appear
  10. Compile with XeLaTeX or LuaLaTeX

The output will be a properly formatted LaTeX interlinear example ready to compile!