https://github.com/digitallinguistics/dlx2html
A JavaScript library for converting linguistic data to HTML
https://github.com/digitallinguistics/dlx2html
digital-humanities digital-linguistics glossing language language-documentation linguistics morphology
Last synced: 5 months ago
JSON representation
A JavaScript library for converting linguistic data to HTML
- Host: GitHub
- URL: https://github.com/digitallinguistics/dlx2html
- Owner: digitallinguistics
- License: mit
- Created: 2022-12-11T04:47:17.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-12T03:40:51.000Z (7 months ago)
- Last Synced: 2024-11-07T09:53:20.549Z (6 months ago)
- Topics: digital-humanities, digital-linguistics, glossing, language, language-documentation, linguistics, morphology
- Language: JavaScript
- Homepage:
- Size: 294 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# dlx2html
A JavaScript library for converting linguistic data to HTML for presenting on the web.
Written using modern ES modules, useable in both Node and the browser.
When writing about linguistic data, linguists use a format called an **interlinear glossed example** which shows each of the parts of a word (morphemes) and their meanings. This allows people who are not familiar with the language under discussion to read the examples and understand their structure and meaning. Below is a very simple example from Swahili:
```txt
# Swahili
ninaenda
ni-na-end-a
1SG-PRES-go-IND
I am going
```
These interlinear glossed examples follow a very specific format, originally specified in the [Leipzig Glossing Rules][Leipzig]. Another specification, called [DaFoDiL][DaFoDiL], formalizes how such data should be structured when being stored as JSON or worked with as a plain old JavaScript object (POJO).
The `dlx2html` library takes one or more interlinear glosses in the DaFoDiL format and converts them to HTML for representing linguistic examples on the web.
The `dlx2html` library does not add any styling to the output HTML. Users should either add their own CSS styles, or use the compatible [Digital Linguistics Style Library][Styles]. The structure of the output HTML and CSS classes are described below.
If using this library for research, please cite it using the model below:
> Hieber, Daniel W. {year}. @digitallinguistics/dlx2html. . DOI: [10.5281/zenodo.10720085](https://zenodo.org/doi/10.5281/zenodo.10720085).
## Samples
The following pages demo the HTML output from the library. They are styled using the [DLx styles library][Styles].
- [Algonquian](/samples/html/Algonquian.html)
- [Chitimacha](/samples/html/Chitimacha.html)
- [Chitimacha Text](/samples/html/Chitimacha-text.html)
- [Mohawk](/samples/html/Mohawk.html)
- [Nuuchahnulth](/samples/html/Nuuchahnulth.html)
- [Old Latin](/samples/html/OldLatin.html)
- [Swahili](/samples/html/Swahili.html)
## Usage
This library is written in JavaScript, and may be run as either a [Node.js][Node] module or as a script in the browser. See the [Node.js learning path][learn-Node] for more information about Node.js, how to install it, and how to run programs with it.
### Node.js
To use `dlx2html` in Node:
1. Install the package.
```cmd
npm install @digitallinguistics/dlx2html
# OR
yarn add @digitallinguistics/dlx2html
```
2. Import the package and use it to convert the data to HTML.
```js
// Import the dlx2html module.
import convert from '@digitallinguistics/dlx2html'
import { readFile } from 'node:fs/promises'
// Load the data from a JSON-formatted DaFoDiL file.
const json = await readFile(`examples.json`, `utf-8`)
const data = JSON.parse(json)
// Convert the text to HTML.
const html = convert(data, { /* specify options here */ })
console.log(html) //
...
```
### Browser
To use `dlx2html` in the browser:
1. Download the latest version of the library from the [releases][releases] page. Copy the `dlx2html.js` file to your project.
2. Import and use the script in your code:
```html
// Import the dlx2html module
import convert from './dlx2html.js'
// Get a reference to your data.
const json = document.body.innerText
const data = JSON.parse(data)
// Convert the text to HTML.
const html = convert(data, { /* specify options here */ })
// Insert the HTML into your page.
document.body.innerHTML = html
```
### API
Calling the `dlx2html` function returns an HTML string.
## Options
| Option | type | Default | Description |
| --------------- | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `abbreviations` | Object | `{}` | An object hash providing the full descriptions of gloss abbreviations, e.g. `"sg"` => `"singular"`. If present, these will be used to populate the `title` attribute of `` elements for glosses. Note that the abbreviations are case-sensitive. |
| `analysisLang` | String | undefined | An [IETF language tag][lang-tags] to use as the default value of the `lang` attribute for any data in the analysis language (metadata, literal translation, free translation, glosses, literal word translation). If `undefined`, no `lang` tag is added, which means that browsers will assume that the analysis language is the same as the HTML document. |
| `classes` | Array | `['igl']` | An array of classes to apply to the wrapper element. |
| `glosses` | Boolean | `false` | Options for wrapping glosses in `` tags.
If set to `false` (default), no `` tags are added to the glosses.
If set to `true`, an `` tag is wrapped around any glosses in CAPS, any numbers, and any of `sg`, `du`, or `pl` (lowercased). Note that text within the `` will be converted to lowercase, since by convention glosses are rendered in smallcaps (and uppercase letters display as normal uppercase letters even when in smallcaps). |
| `tag` | String | `'div'` | The HTML tag to wrap each interlinear gloss in. Can also be a custom tag (useful for HTML custom elements). |
| `targetLang` | String | undefined | An [IETF language tag][lang-tags] to use as the default value of the `lang` attribute for any data in the target language. |
## HTML Structure
This section describes the structure of the HTML output by this library, and the classes added to the HTML elements. You can see sample HTML output by the program in the `samples/` folder, as well as the [DLx Styles][Styles] library.
**Note:** The output HTML does not contain much extraneous whitespace and therefore is not very human-readable. If you want more readable output, use a formatting library like [Prettier][Prettier] to format the result.
Each utterance/example in the original data is wrapped in a `
` element by default. You can customize both the tag that is used for the wrapper and the classes applied to it with the `tag` and `classes` options. For example, to wrap each utterance in ``, you would provide the following options:
```js
const options = {
classes: [`interlinear`],
tag: `li`
}
```
You can apply three different types of emphasis to the data:
| Scription | HTML Output | Renders As |
| ------------ | ----------------------- | --------------------- |
| `***text***` | `text` | text |
| `**text**` | `text` | text |
| `*text*` | `text` | text |
| `_text_` | `text` | text |
### Additional Notes
- The language code (`\lg`) is not displayed. It is merely used to set the `lang` attribute on elements where appropriate. To display the language of an utterance, use the metadata field (`\#`).
- The speaker (`\sp`) and source (`\s`) data are combined into a single element strutured as follows: `
{speaker} ({source})
`.
- Notes fields (`\n`) are not added to the HTML by default.
- Individual glosses receive the `.gl` class.
## CSS
The CSS classes for each line type are as follows:
| Line | CSS Class |
| ---------------------- | ----------- |
| metadata | `ex-header` |
| source | `ex-source` |
| transcript | `trs` |
| phonemic transcription | `txn` |
| phonetic transcription | `phon` |
| word transcription | `w` |
| morphemic analysis | `m` |
| glosses | `glosses` |
| literal translation | `lit` |
| timespan | `timespan` |
| free translation | `tln` |
| word translation | `wlt` |
If the language of the text is specified, it is set as the value of the `lang` attribute for data in the target language wherever relevant. Whenever the language of analysis data (metadata, glosses, translations, etc.) is specified, it is passed through to the `lang` attribute of the relevant analysis language elements (`
`).
When the data occurs in multiple orthographies, the orthography of the data is specified in the `data-ortho` attribute. For example, the following data is transformed to the HTML that follows:
```txt
\trs-Modern Wetkx hus naancaakamankx wetk hi hokmiqi.
\trs-Swadesh wetkšˊ husˊ na·nča·kamankšˊ wetkˊ hi hokmiʔiˊ.
\tln He left his brothers.
```
```html
Wetkx hus naancaakamankx wetk hi hokmiqi.
wetkšˊ husˊ na·nča·kamankšˊ wetkˊ hi hokmiʔiˊ.
He left his brothers.
```
[DaFoDiL]: https://format.digitallinguistics.io/
[lang-tags]: https://datatracker.ietf.org/doc/html/rfc5646
[learn-Node]: https://nodejs.dev/en/learn/
[Leipzig]: https://www.eva.mpg.de/lingua/resources/glossing-rules.php
[Node]: https://nodejs.org/
[Prettier]: https://prettier.io/
[releases]: https://github.com/digitallinguistics/dlx2html/releases
[Styles]: https://styles.digitallinguistics.io/