{"id":20137931,"url":"https://github.com/scdh/oxbytei","last_synced_at":"2025-04-09T17:51:53.593Z","repository":{"id":40777885,"uuid":"440988476","full_name":"SCDH/oxbytei","owner":"SCDH","description":"oXygen framework configured by TEI","archived":false,"fork":false,"pushed_at":"2025-03-25T12:36:06.000Z","size":1280,"stargazers_count":8,"open_issues_count":2,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-25T13:40:01.574Z","etag":null,"topics":["annotations","digital-edition","digital-humanities","editor","lsp","oxygenxml","oxygenxml-framework","tei","tei-xml"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SCDH.png","metadata":{"files":{"readme":"README.md","changelog":"changeLog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-22T21:27:43.000Z","updated_at":"2025-03-25T12:34:07.000Z","dependencies_parsed_at":"2024-07-08T11:33:22.478Z","dependency_job_id":"520c723c-62de-45a1-a36d-e33234ec0626","html_url":"https://github.com/SCDH/oxbytei","commit_stats":null,"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SCDH%2Foxbytei","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SCDH%2Foxbytei/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SCDH%2Foxbytei/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SCDH%2Foxbytei/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SCDH","download_url":"https://codeload.github.com/SCDH/oxbytei/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248083175,"owners_count":21045054,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotations","digital-edition","digital-humanities","editor","lsp","oxygenxml","oxygenxml-framework","tei","tei-xml"],"created_at":"2024-11-13T21:30:36.946Z","updated_at":"2025-04-09T17:51:53.568Z","avatar_url":"https://github.com/SCDH.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# oXbytei #\n\n![release](https://github.com/scdh/oxbytei/actions/workflows/release.yml/badge.svg)\n![tests](https://github.com/scdh/oxbytei/actions/workflows/test-main.yml/badge.svg)\n\n## tl;dr ##\n\nInstall from\n\n```\nhttps://scdh.github.io/oxbytei/descriptor.xml\n```\n\n\nSTATE: in production\n\n## An oXygen framework configured by TEI ##\n\noXbytei [ɔx bʌtaj] (greco-english tongue and french ears) is a generic\n[oXygen](https://www.oxygenxml.com/) framework for editing\n[TEI](https://tei-c.org/). It offers high-level functions that\nfacilitate everyday work on TEI documents. Its name originates from\nthe idea, to use as much information as we can from the TEI header to\nconfigure the framework's actions. But since the header's information\nis not sufficient for most editing actions, oXbytei also introduces a\nconfiguration file to oXygen frameworks, which makes it the next\ngeneration framework. You can read more about the design principles in\nthe [Wiki](https://github.com/SCDH/oxbytei/wiki).\n\n\n## Features / Functions #\n\n- **Critical apparatus**: According to what is stated in\n  [`\u003cvariantEncoding\u003e`](https://www.tei-c.org/release/doc/tei-p5-doc/de/html/ref-variantEncoding.html)\n  a new apparatus entry is generated from the _user selection_ and\n  inserted into the document. The selected text goes into\n  `\u003clem\u003e`. Supported variant encodings: **all** but external\n  location-referenced. [`@wit`](https://www.tei-c.org/release/doc/tei-p5-doc/de/html/ref-att.witnessed.html)\n  can be selected based on the witnesses supplied via\n  [`sourceDesc/listWit//witness`](https://www.tei-c.org/release/doc/tei-p5-doc/de/html/TC.html#TCAPWL).\n- **Suggestions**: A flexible and extensible plugin system generates\n  suggestions for attribute values etc. in a context-aware\n  manner. E.g. the framework by default sets up suggestions for `@ref`\n  of `\u003cpersName\u003e`, `\u003cplaceName\u003e` or `@corresp` of `\u003cbibl\u003e` by\n  evaluating [prefix\n  definitions](https://www.tei-c.org/release/doc/tei-p5-doc/de/html/ref-listPrefixDef.html)\n  in the document header.  The plugin system is flexible enough to add\n  plugins for querying RESTful webservices. Available plugins range\n  from generating suggestions via XSLT, XQuery, XPath, from CSV, from\n  SPARQL over local files or a remote endpoint, etc.\n- **Configurable user dialogs**: Simply declare by configuration which\n  type of dialog you want to have for a specific editing context,\n  e.g. a multiple select dialog for `@wit` on `\u003crdg\u003e`. Dialogs\n  are plugins that implement an interface for communicating with\n  plugins that provide suggestions for content completion. There're\n  combo boxes, editable combo boxes, multi select dialogs based on\n  check boxes etc.\n- **Attribute editor**: These configurable dialogs and suggetions are\n  used in a generic schema-aware attribute editor.\n- **Language**: Set `@xml:lang` by selecting a language registered in\n  the header by\n  [`langUsage`](https://www.tei-c.org/release/doc/tei-p5-doc/de/html/ref-langUsage.html)\n- **Different markup styles**: When annotating persons, places\n  etc. you can choose between markup styles: E.g. in *aggregative*\n  style (default) the user selection is wrapped into an element if and\n  only if the selection's start and end point are on the same parent\n  node. Otherwise, each text node between is wrapped and the elements\n  are linked by [`@next` and\n  `@prev`](https://www.tei-c.org/release/doc/tei-p5-doc/de/html/SA.html#SAAG). Alternative\n  styles include\n  [`att.spanning`](https://www.tei-c.org/release/doc/tei-p5-doc/de/html/ref-att.spanning.html)\n  and anchor-based markup.\n- **Annotations**: Surround the _user selection_ with empty `\u003canchor\u003e`\n  elements carrying unique IDs and then insert a\n  [`\u003cspan\u003e`](https://www.tei-c.org/release/doc/tei-p5-doc/de/html/AI.html#AISP)\n  referencing the anchors somewhere else in the document. Also select\n  `span/@ana` from `\u003cinterp\u003e` elements in the document\n  (default). Other sources/references for `@ana` can be configured.\n- **Navigation in anchor-based markup**: a) Find annotations and\n  apparatus entries for the current position; b) highlight (select)\n  the span of text referenced by an annotation or apparatus entry.\n- **Multiple level inheritance**: Instead of an `oxbytei.framework`\n  file, oXbytei uses an [extension\n  script](https://www.oxygenxml.com/doc/versions/23.1/ug-editor/topics/framework-customization-script.html)\n  as introduced in oXygen 23.1. This makes it possible to inherit from\n  base frameworks on [multiple\n  levels](https://www.youtube.com/watch?v=e8NwqN16p18\u0026t=13m24s). You're\n  able to write your own framework on top of oXbytei, which operates\n  on top of TEI P5.\n- **Powerful author operations**: The Java code base defines some\n  powerful author operations, that you can re-use for your own\n  actions.\n\nOn the road map:\n\n- a plugin for getting content completion suggestions from RDF\n  endpoints\n- editor operations for generating RDF/OWL based annotations (see\n  branch `annotation-rdf`)\n- **Melt and cristallize anchors**: The anchors inserted for your\n  double end-point attached apparatus, for your annotations or for\n  other markup, will pollute your edited text. Melting is the process\n  of joining anchors, which are direct siblings, into one anchor or\n  even integrating the ID into another tag. Cristallizing is the\n  process of giving a referring element back its own anchors, after\n  there was a melting. This is needed when a reference point to the\n  edited text has to be moved.\n- exploit `\u003ctagsDecl\u003e` etc.\n- **Index**\n\n\nRead more in the [**Wiki**](https://github.com/scdh/oxbytei/wiki).\n\nYou should also have a look at\n[oXbytao](https://github.com/scdh/oxbytao), which might already extend\noXbytei to your project-specific needs.\n\n## Why to try ##\n\nNovice oXygen users: You want to customize a bit, e.g. provide a\nselect box for an attribute like `rdg/@wit` and add some CSS. However,\nyou don't want to invest into framework customization but stay with X\ntechnologies like XQuery or XSLT.\n\nThen the configurable plugin system of oXbytei will give you what you\nneed and [oXbytao](https://github.com/scdh/oxbytao) will offer you\nsimple CSS customization on a project/user basis.\n\nExperienced users: Are you tired of framework development, where you\ndefine tons of author actions for setting attribute values and where\nyou have to hard-code content into `${ask(...)}` or write nested\n`${ask(...${xpath_eval(...)}...}` which are so complicated that you\ndon't understand them any more on the next day? Or, are you sick of\ncoding form components with hard-coded content or complex XPath\nexpressions in them into a flavoured CSS?\n\nThen you should give oXbytei a try: It lets you generate the values\nfor selection for a specific editing context like `rdg/@wit` with a\nplugin that e.g. evaluates one of your XQuery scripts. And it lets you\ndeclare which UI form (free type, single select, multiple select) you\nwant to have for an editing context, e.g. multiple select for\n`rdg/@wit`. In the config file you can just tie the generation of\nselection options and the appropriate UI form together for a specific\nediting context. oXbytei's design is all about separation of concerns\nand consistent interfaces.\n\n\n## Package ##\n\n### Requirements ###\n\noXbytei requires oXygen \u003e= 23.1, because it makes use of an [extension\nscript](https://www.oxygenxml.com/doc/versions/23.1/ug-editor/topics/framework-customization-script.html)\nfor framework configuration. With extension scripts you gain multiple\nlevel inheritance and transparent updates, i.e. updates on lower level\nframeworks can be installed without the need to update the stack of\nframeworks based on it.\n\n### Installation ###\n\nThe framework can be installed with \u0026lt;oXygen/\u003e's installation and\nupdate mechanism. Therefore, the following URL has to be entered into\nthe form *Show addons from:* of the dialogue box from ***Help** -\u003e\n**Install new addons**...*.\n\n\n[https://scdh.github.io/oxbytei/descriptor.xml](https://scdh.github.io/oxbytei/descriptor.xml)\n\nNote: The framework is not signed with a key. You can simply ignore\nthe warning, which oXygen throws during the installation process.\n\n![Dialog \"Install new addons\"](images/install.png)\n\n\nAs an alternative, the framework can be packaged locally for\ninstallation or it can be installed for hacking.\n\n#### Packaging locally ####\n\nPackaging is done with [`maven`](https://maven.apache.org/).\n\n```{shell}\nmvn generate-sources\nmvn package\n```\n\nThis will create a file named `oxbytei-\u003cVERSION\u003e-package.zip` in the\n`target` folder. This zip-File is the same as the one distributed\nunder the above mentioned URL.\n\nIn order to use oXbytei with older versions of oXygen, you can\ngenerate an old-school dot-framework file from the extension script\nusing the *Compile Framework Extension script* as described in the\n[documentation](https://www.oxygenxml.com/doc/versions/23.1/ug-editor/topics/framework-customization-script.html)\nand then use local packaging.\n\n#### Hacking / Development ####\n\nInstalling the framework as an \u0026lt;oXygen/\u003e package will make it\nread-only. For hacking on it's code you can install it by registering\nthe path to the cloned repository in \u0026lt;oXygen/\u003e's settings.\n\n- 1) Clone this repository into a subfolder of an \u0026lt;oXygen/\u003e\n  project, e.g. `oxbytei`. (It may also be sym-linked there.)\n\n- 2) Start \u0026lt;oXygen/\u003e and select `Options` -\u003e `Preferences` from the\n  menu. Expand `Document Type Association` on the left and select\n  `Locations [P]` under it. Click `Add` to add a new additional\n  framework directory.  Enter `${pdu}/oxbytei` as directory and click\n  `OK`. (Note: `${pdu}` is an [editor\n  variable](https://www.oxygenxml.com/doc/versions/22.1/ug-editor/topics/editor-variables.html)\n  and points to the root folder of the current project.)\n\n- 3) Run maven to get dependencies\n\n```{shell}\nmvn generate-sources\nmvn package\n```\n\n- 4) Create symbolic links for *all* the jar files from the folder\n`target/lib` to the folder `frameworks/oxbytei`:\n\n```{shell}\ncd frameworks/oxbytei\nln -s ../../target/lib/teilsp.jar .\nln -s ../../target/lib/oxbytei-core.jar .\nln -s ../../target/lib/slf4j-api.jar .\n...\n```\n\n- 5) In your project's root folder (aka `${pd}`, see above), create a\n  symbolic link to oXybytei's `frameworks/oxbytei` folder.\n\n```{shell}\ncd \u003cproject-directory\u003e\nln -s \u003coXybytei-directory\u003e/frameworks/oxbytei oxbytei\n```\n\n- 6) Close and restart \u0026lt;oXygen/\u003e. The framework is now present as an\n  extension to the default TEI P5 framework.\n\n\nNote for Windows (no symbolic links) users: Clone the framework into\nyour project folder in step 1. Then use\n`{pd}/oxbytei/frameworks/oxbytei` in step 2. You have to copy all the\njar files from step 4. You can skip step 5 then. But you will have to\ncopy oxbytei.jar every time you recompile the code.\n\n\n\n#### Logging ####\n\nGetting logs may be the key to solving problems during development or\nconfiguration. oXbytei uses slf4j as a logging tool and oXygen ships\nwith log4j, which slf4j passes its messages to. Simply running oXygen\nfrom the commandline (instead of clicking the desktop icon) may help,\nbecause you get the log of some error messages. To get the full logs,\none has to [turn on logging in\noXygen](https://www.oxygenxml.com/doc/versions/23.0/ug-editor/topics/problem-report-submitted-on-technical-support-form.html)\nby putting a log4j config file into the application folder.\n\n### Regression Tests ###\n\nBesides Java unit tests there are regression tests based on\n[`XSpec`](https://github.com/xspec/xspec) in `test/xspec`. The tests\ncan easily be run with maven from the root directory of the\nrepository:\n\n```{shell}\nmvn test\n```\n\nMaven will install all required packages for running the tests,\ne.g. `XSpec` and `Saxon-HE`. A detailed test report can be viewed with\nthe browser in `target/xspec-reports/index.html`.\n\nNote, that the tests need intermediate files to be generated in mavens\n`generate-resources` phase. If you want to run the tests using saxon,\nhave a look at the pom-file to see what's needed.\n\n\n### Releasing ###\n\nReleases of installable packages will be created with github actions\non tags with a name matching the pattern\n`[0-9]+\\.[0-9]+\\.[0-9]+(-.*)?`,\ni.e. `\u003cMAJOR\u003e.\u003cMINOR\u003e.\u003cBUGFIX\u003e[-\u003cSUFFIX\u003e]`. But only tags matching the\npattern `[0-9]+\\.[0-9]+\\.[0-9]+` will result in an update of the\ndescriptor file.--So, releases with a suffix are considered kind of\nbeta and will only occur in the tag's release bundle.\n\nTo produce a release:\n\n- first push the branch to be released\n- then tag it with the tag name matching the above pattern\n\nThis will produce a release on [releases/tag/\u003cTAG_NAME\u003e](releases/tag)\nand update the [descriptor\nfile](https://scdh.github.io/oxbytei/descriptor.xml).\n\nNOTE: Git release tags are the single source of truth for release\nnumbers and release triggers. There is no version information in the\npom file. A default version number is contained in\n`.mvn/maven.config`, which should be kept up to date. However, it is\noverridden in the CI/CD pipelines by the release tag.\n\n## Design principles ##\n\n- Installation and updating must be simple, i.e. no additional tools\n  and compilers required.\n\n- Keep things flexible through configuration.\n\n- The default configuration must be reasonable.\n\n### Design Principles regarding the Java code base ###\n\n- Keep the Java code base that depends on oXygen as small as possible\n  und put it in the namespace `de.wwu.scdh.oxbytei`!\n\n  - Code for user interaction also belongs to here.\n\n  - Offer content completion in text mode *and* in author mode.\n\n- Source out as much business logic as possible to the namespace\n  `de.wwu.scdh.teilsp`!\n\n  - Keep things extensible.\n\n  - Use plugins based on Java's SPI to provide suggestions for content\n    completion.\n\n\t- No user interaction allowed in such plugins, but their\n      interfaces distinguish between intialization phase and query\n      phase, so that user interaction can be done in oXbytei.\n\n  - Do not hardcode assumptions about TEI usage – and not about\n    whether this XML dialect is used at all either – into Java\n    classes.\n\n    - Exception: Plugins\n\n  - Put all such assumptions into the configuration file.\n\n### Design principles regarding other oXygen framework components ###\n\n- Offer recursively defined author mode actions.\n\n  - Reason: This allows atomization of editing actions. So frameworks\n    deriving (based on) oXbytei can have a minimal codebase for\n    overriding single editing atoms.\n\n  - Get feedback: Are they accepted by the users?\n\n## Vision\n\n`de.wwu.scdh.teilsp` contains code which is not specific to the\noXygen editor. It serves as a layer of abstraction and can be plugged\ninto other editors, too. It's intended to be the germ of a TEI\n[LSP](https://langserver.org/) implementation based on Lemminx and\nwill be sourced out to it's own repository in the future.\n\nIt provides the interfaces for plugins and the plugin loader, which\nevaluates the current editing context for loading and initializing\nplugins. So plugins can be developed for this layer of abstraction.\n\n## Plugins ##\n\noXbytei makes use of Java's SPI for loading plugins. There are\ndifferent plugin interfaces, for several functions. Configurable\nplugins are initialized with arguments from the configuration file and\nwith the current editing context, where the arguments can be declared\nspecifically for an editing context.\n\n- `de.wwu.scdh.teilsp.services.extensions.ILabelledEntriesProvider` is\n  an interface for plugins that collect content completion suggestions\n  and present them as values with human readable labels. E.g. plugins\n  for linking persons where each person is a mapped to unique ID\n  (maybe from a local or global norm file) and where its name is\n  presented as a human readable label. There are plugins for accessing\n  XML data by XPath expressions or by XQuery. There is also a plugin\n  for declaring values and labels in the configuration file.\n\n- `de.wwu.scdh.teilsp.ui.ISelctionDialog` is an interface for UI\n  dialogs. There are plugins for free typing and for selecting from\n  content completion suggestions provided as labelled entries (see\n  above) with combo boxes (single selection) or check boxes (multiple\n  selection) etc.\n\n\n\n# License #\n\nMIT\n\n## Included Software and other Material ##\n\nThe included ![languageicon](frameworks/oxbytei/images/lang-24.png)\nicon was desigend by Onur Mustak Cobanli an is distributed on\n[http://languageicon.org/](http://languageicon.org/) by under a CC\nlicence with Relax-Attribution term.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscdh%2Foxbytei","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscdh%2Foxbytei","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscdh%2Foxbytei/lists"}