From 8fc07256c495e0e0206105981596ef850c54c0d5 Mon Sep 17 00:00:00 2001 From: Emerson Rocha Date: Tue, 16 Nov 2021 21:28:07 -0300 Subject: [PATCH] documentation-reorganization (#8): asciidoctor is so beautiful to edit books, wow --- docs/eng-Latn/draft-eng-Latn.adoc | 498 +++++++++++++++++++++++++++++- 1 file changed, 486 insertions(+), 12 deletions(-) diff --git a/docs/eng-Latn/draft-eng-Latn.adoc b/docs/eng-Latn/draft-eng-Latn.adoc index 1f3e4b1..6c99136 100644 --- a/docs/eng-Latn/draft-eng-Latn.adoc +++ b/docs/eng-Latn/draft-eng-Latn.adoc @@ -1,5 +1,11 @@ = Multilingual Terminology in Humanitarian Language Exchange: the HXLTM lexicography field guide +EticaAI, Collaborators_of ; Rocha, Emerson :toc: 1 +:toclevels: 4 +:version-label: HXLTM Live eddition +:variable-documentation-live-link: https://hxltm.etica.ai/ +:variable-python-package-manager-name: hxltm-eticaai +:variable-python-package-manager-released-version: 0.8.9rc2 //// - https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/ @@ -9,11 +15,17 @@ == Preface -This book, both available online and as an ebook, is designed as a field guide for person's doing practical lexicography and need a kickstart on how to use HXLTM tools. +This book, both available online on {variable-documentation-live-link} and as an ebook, +is designed as a field guide for person's doing practical lexicography and need a kickstart on how to use HXLTM tools. -=== Non-audience -If you are either an academic researcher, technology expert or interested in help with translations, please contact the authors directly. +[NOTE] +.Non-audience (for this field guide) +==== +If you are either an academic researcher, +technology expert or interested in help with translations, +please contact the authors directly. +==== //// It is still recommended to take a quick look at this guide. @@ -21,6 +33,7 @@ The public domain license is more than flexible. This means you can //// +<<< == Getting started @@ -37,19 +50,34 @@ All functionality intended for field lexicographers using HXLTM documented here Choose at least one of the options. -==== Local installation +==== Python package alternative + +hxltm-eticaai Python package:: https://pypi.org/project/hxltm-eticaai/ +Pypi, Python package manager:: https://pip.pypa.io/ +Python:: https://www.python.org/ +===== Active use + +[subs="attributes"] [source,bash] ---- -pip install hxltm-eticaai +pip install {variable-python-package-manager-name} --upgrade ---- -==== Docker +===== Conservative + +[subs="attributes"] +[source,bash] +---- +pip install {variable-python-package-manager-name}={variable-python-package-manager-released-version} +---- + +==== Docker alternative #TODO: this is a draft. Will eventually be updated (2021-11-16T23:16:00Z)# -==== GitHub Action +==== GitHub Action alternative #TODO: this is a draft. Will eventually be updated (2021-11-16T23:16:00Z)# @@ -129,9 +157,12 @@ include::../bin/hxltmdexml.py[tag=epilogum] <<< -== How to interpret this book +== Introduction +:sectnums: + +=== How to interpret this book -=== A self-testing approach +==== A self-testing approach Parts of this field guide show, in this order: @@ -155,14 +186,457 @@ can be relevant for who is debugging. One of the reasons for such an approach is greater assurance that the documentation will be updated since several parts of this are literally generated with each release. New data conventions can be added (or removed) over time, but this approach focuses on making it easier to release more frequently. -This book obviously do not contain all tests that are done, but what is here, feature-by-feature (or bug-by-bug) - +This book obviously do not contain all tests that are done, but what is here, +feature-by-feature (or bug-by-bug) what is used on the field. +//// (...) - Sadly, data formats which are not importable back (so a export+import could be used to test) and do not exist some automated strategy to check of they are valid are extra hard to make full automated checks. +//// + +<<< + +[#HXLTM-archivum-dialecton] +== HXLM core file dialects +:sectnums: + +[#HXLTM] +=== `+HXLTM+` +==== Terminologia Multilinguae (priore HXL Trānslātiōnem Memoriam), Datum ideam + +//// +Naming the HXL TM + +Terminologia Multilinguae + +- https://en.wiktionary.org/wiki/terminus#Latin +- https://en.wiktionary.org/wiki/logium#Latin +- https://en.wiktionary.org/wiki/multi-#English +- https://en.wiktionary.org/wiki/lingua#Latin +- https://en.wiktionary.org/wiki/multilingual +lingua +//// + + + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_HXLTM] +---- + +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=HXLTM_CSV] +---- + +//// +[#CSV-HXL-XLIFF] +=== `+CSV-HXL-XLIFF+`: +==== HXLated bilingual CSV (+ up to 5 source alt) for XLIFF + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_CSV-HXL-XLIFF] +---- + +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=CSV-HXL-XLIFF] +---- +//// + +[#HXLTM-TMETA] +=== `+HXLTM-TMETA+`: +==== HXLTM Terminologia Multilinguae Meta + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_HXLTM-TMETA] +---- + +//// +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=HXLTM-ASA] +---- +//// + +[#HXLTM-ASA] +=== `+HXLTM-ASA+`: +==== HXLTM Abstractum Syntaxim Arborem + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_HXLTM-ASA] +---- + + +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=HXLTM-ASA] +---- + +[#HXLTM-archivum-exportandum] +== HXLTM Normam (HXLTM interoperability with conventions/standards) + +TIP: The `hxltmcli` and (for importing XML, as long as you map the + tags and attributes, as this page already do for TMX, TBX, XLIFFs, ...) + `+hxltmdexml+` *are designed to work with gigabyte size datasets*. + The ontology file can be customized with `--archivum-configurationem` + which means both edit or create new exporters/importers are possible. + +//// +TIP: Consider the formats here as example of how to export HXLTM. + `hxltmcli --archivum-configurationem path/to/mycopy.hxltm.yml`. +//// + + +[#CSV-3] +=== `+CSV-3+`: +==== CSV 3 bilingual Source + Objective + Comment + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_CSV-3] +---- + +===== Command line examples + + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=CSV-3] +---- + +===== Result example + +- https://github.com/EticaAI/hxltm/blob/main/testum/resultatum/hxltm-exemplum-linguam.por-Latn_spa-Latn.csv + +[source,csv] +---- +include::../testum/resultatum/hxltm-exemplum-linguam.por-Latn_spa-Latn.csv[] +---- + +[#GSheets] +=== `+GSheets+`: +==== Google Sheets, HXLTM container (read-only; native support as data source) + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_GSheets] +---- + +[#HXL-Proxy] +=== `+HXL-Proxy+`: +==== HXL-Proxy (read-only; native support as data source) + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_HXL-Proxy] +---- + +[#JSON-kv] +=== `+JSON-kv+`: +==== JSON key: val; id/source -> target (draft) + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_JSON-kv] +---- + +[#TBX-Basim] +=== `+TBX-Basim+`: +==== TermBase eXchange (TBX) Basic 2.1 +//// +==== TermBase eXchange (TBX) Basic 2.1 +//// + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_TBX-Basim] +---- + +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=TBX-Basim] +---- + +===== Result example + +[source,xml] +---- +include::../testum/resultatum/hxltm-exemplum-linguam.tbx[] +---- + + +[#TSV-3] +=== `+TSV-3+`: +==== TSV-3 bilingual Source + Objective + Comment + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_TSV-3] +---- + +===== Command line examples + + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=TSV-3] +---- + +===== Result example + +- https://github.com/EticaAI/hxltm/blob/main/testum/resultatum/hxltm-exemplum-linguam.por-Latn_spa-Latn.tsv + +[source,tsv] +---- +include::../testum/resultatum/hxltm-exemplum-linguam.por-Latn_spa-Latn.tsv[] +---- + +[#TMX] +=== `+TMX+`: +==== Translation Memory eXchange format (TMX) + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_TMX] +---- + +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=TMX] +---- +===== Result example + +- https://github.com/EticaAI/hxltm/blob/main/testum/resultatum/hxltm-exemplum-linguam.tmx + +[source,xml] +---- +include::../testum/resultatum/hxltm-exemplum-linguam.tmx[] +---- + +[#UTX] +=== `+UTX+`: +==== Universal Terminology eXchange (UTX) (working draft) + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_UTX] +---- + +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=UTX] +---- +===== Result example + +- https://github.com/EticaAI/hxltm/blob/main/testum/resultatum/hxltm-exemplum-linguam.utx + +[source,xml] +---- +include::../testum/resultatum/hxltm-exemplum-linguam.utx[] +---- + +[#XML] +=== `+XML+`: +==== XML Glōssārium, HXLTM container (generic multilingual XML)' + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_XML] +---- + +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=XML] +---- +===== Result example + +- https://github.com/EticaAI/hxltm/blob/main/testum/resultatum/hxltm-exemplum-linguam.tmx + +[source,xml] +---- +include::../testum/resultatum/hxltm-exemplum-linguam.hxltm.xml[] +---- + + +[#XLIFF] +=== `+XLIFF+`: +==== XML Localization Interchange File Format (XLIFF) v2.1 + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_XLIFF] +---- + +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=XLIFF] +---- + +===== Result example + +[source,xml] +---- +include::../testum/resultatum/hxltm-exemplum-linguam.por-Latn--spa-Latn.xlf[] +---- + +[#XLIFF-obsoletum] +=== `+XLIFF-obsoletum+`: +==== XML Localization Interchange File Format (XLIFF) v1.2 + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_XLIFF-obsoletum] +---- + +===== Command line examples + +[source,bash] +---- +include::../testum/disciplinam-manuale-anglicum.sh[tag=XLIFF-obsoletum] +---- + +===== Result example + +[source,xml] +---- +include::../testum/resultatum/hxltm-exemplum-linguam.por-Latn--spa-Latn.xlf[] +---- + +[#XLSX] +=== `+XLSX+`: +==== Microsoft Excel, HXLTM container (read-only; native support as data source) + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_XLSX] +---- + +[#YAML] +=== `+YAML+`: +==== YAML (planned, but no draft) + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=normam_YAML] +---- + +[#HXLTM-ad-hoc] +== HXLTM Ad Hoc Fōrmulam (HXLTM templated export) + +TIP: *About create new HXLTM Ad Hoc*: different from customizable + link:++#HXLTM-archivum-exportandum++[HXLTM Normam] + (support for gigabyte size data manipulation) the use of this strategy + is more optimized for end user who is unlikely o care about load data + in chunks and try to explain how to import back to HXLTM working file. + +NOTE: TODO: this is a draft. Document already implemented functionality + +//// += Appendix +:appendix-caption: Exhibit +:sectnums: +:toc: +//// + +== HXLTM ontologies + +[#ontologia] +=== Ontologia + +Full file at https://github.com/EticaAI/hxltm/blob/main/ontologia/cor.hxltm.215.yml. + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=ontologia] +---- + +[#ontologia-aliud] +=== Aliases + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=ontologia_aliud] +---- + +[#ontologia-datum-typum] +=== Data types + +[source,yaml] +---- +include::../ontologia/cor.hxltm.215.yml[tag=ontologia_datum_typum] +---- + +[#hxltmcli--help] +== `+hxltmcli --help+` + +[source,bash] +---- +# hxltmcli can be installed with hxltm-eticaai +# @see https://pypi.org/project/hxltm-eticaai/ +pip install hxltm-eticaai + +hxltmcli --help +---- + +[source] +---- +include::../testum/hxltmcli--help_eng-Latn.txt[] +---- +[#hxltmdexml--help] +== `+hxltmdexml --help+` + +[source,bash] +---- +# hxltmdexml can be installed with hxltm-eticaai +# @see https://pypi.org/project/hxltm-eticaai/ +pip install hxltm-eticaai + +hxltmdexml --help +---- + +[source] +---- +include::../testum/hxltmdexml--help_eng-Latn.txt[] +---- + +== Glossary +:sectnums: + +=== Arabic numerals + +#TODO: this is a draft. Will eventually be updated (2021-11-16T23:45:00Z)# +== License +link:UNLICENSE[image:../img/public-domain.png[Public Domain Dedication]] +The https://github.com/EticaAI[EticaAI] has dedicated the work to the +link:../../UNLICENSE[public domain] by waiving all of their rights to the +work worldwide under copyright law, including all related and +neighboring rights, to the extent allowed by law. You can copy, modify, +distribute and perform the work, even for commercial purposes, all +without asking permission.