hxltmcli (#22): improved more documentation

EticaAI · Oct 19, 2021 · 87a7a75 · 87a7a75
1 parent 476e4fd
commit 87a7a75
Show file tree

Hide file tree

Showing 4 changed files with 77 additions and 13 deletions.
diff --git a/hxltm/archivum/README.adoc b/hxltm/archivum/README.adoc
@@ -199,7 +199,7 @@ include::../../testum/hxltm/resultatum/hxltm-exemplum-linguam.por-Latn_spa-Latn.
 
 [#GSheets]
 === `+GSheets+`:
-==== Google Sheets (via CSV import)
+==== Google Sheets, HXLTM container (read-only; native support as data source)
 
 [source,yaml]
 ----
@@ -218,6 +218,9 @@ include::../../ontologia/cor.hxltm.yml[tag=normam_JSON-kv]
 [#TBX-Basim]
 === `+TBX-Basim+`:
 ==== TermBase eXchange (TBX) Basic 2.1
+////
+==== TermBase eXchange (TBX) Basic 2.1
+////
 
 [source,yaml]
 ----
@@ -315,7 +318,7 @@ include::../../testum/hxltm/resultatum/hxltm-exemplum-linguam.utx[]
 
 [#XML]
 === `+XML+`:
-==== XML Glōssārium (generic multilingual XML)'
+==== XML Glōssārium, HXLTM container (generic multilingual XML)'
 
 [source,yaml]
 ----
@@ -363,7 +366,7 @@ include::../../testum/hxltm/resultatum/hxltm-exemplum-linguam.por-Latn--spa-Latn
 
 [#XLIFF-obsoletum]
 === `+XLIFF-obsoletum+`:
-==== XML Localization Interchange File Format (XLIFF) v1.2 (too old, no draft)
+==== XML Localization Interchange File Format (XLIFF) v1.2
 
 [source,yaml]
 ----
@@ -386,7 +389,7 @@ include::../../testum/hxltm/resultatum/hxltm-exemplum-linguam.por-Latn--spa-Latn
 
 [#XLSX]
 === `+XLSX+`:
-==== Microsoft Excel (no plugins to read data directly from .XSLX)
+==== Microsoft Excel, HXLTM container (read-only; native support as data source)
 
 [source,yaml]
 ----

diff --git a/ontologia/cor.hxltm.yml b/ontologia/cor.hxltm.yml
@@ -224,10 +224,23 @@ normam:
   GSheets:
     __meta:
       # archivum_extensionem: None
+      descriptionem: |
+        _[eng-Latn]
+        Both URL GSheets and local/remote file of Microsoft Excel have built
+        read-only access in support for reference cli implementation
+        as container for data source without intermediate file transformation
+        to CSV container of HXLTM. This means humans don't need to edit CSV
+        files directly.
+
+        The support on `hxltmcli` to write directly to GSheets and
+        Microsoft Excel is unlikely to be implemented.
+        [eng-Latn]_
       normam:
         - <https://developers.google.com/sheets/api>
       nomen:
-        eng-Latn: 'Google Sheets (via CSV import)'
+        # eng-Latn: 'Google Sheets (via CSV import)'
+        # eng-Latn: 'Google Sheet (native support to read, but not write, data directly from GSheets)'
+        eng-Latn: 'Google Sheets, HXLTM container (read-only; native support as data source)'
       situs_interretialis:
         referens_officinale:
           - <https://www.google.com/sheets/about/>
@@ -302,12 +315,12 @@ normam:
       archivum_extensionem: 
         - .tmeta.json
         - .tmeta.yml
-      normam:
-        - <https://hdp.etica.ai/hxltm/archivum/#HXLTM-TMETA>
       descriptionem: |
         _[eng-Latn]
         To be documented.
         [eng-Latn]_
+      normam:
+        - <https://hdp.etica.ai/hxltm/archivum/#HXLTM-TMETA>
       nomen:
         eng-Latn: 'HXLTM Terminologium Multilinguam Meta'
       situs_interretialis:
@@ -320,9 +333,20 @@ normam:
 
   #### JSON-kv: JSON key: val; id/source -> target _____________________________
   # tag::normam_JSON-kv[]
+
+  # TODO: create at least one different exporter, JSON-2, since JSON-kv
+  #       would be harder to explain how to document on HXLTM sheets than
+  #       create the exporter
   JSON-kv:
     __meta:
       archivum_extensionem: .json
+      descriptionem: |
+        _[eng-Latn]
+        This export/importer needs to be created. One level is trivial, but 2
+        or more nested levels would be simpler for end user just use
+        **HXLTM Ad Hoc Fōrmulam (HXLTM templated export)** to have full
+        control.
+        [eng-Latn]_
       normam:
         # Not sure where to find some place to 'explain' this format
         - <https://angular.io/guide/i18n#change-the-source-language-file-location>
@@ -1159,7 +1183,7 @@ normam:
         - <https://docs.oasis-open.org/xliff/v1.2/os/xliff-core-1.2-strict.xsd>
         - <http://docs.oasis-open.org/xliff/v1.2/cs02/xliff-core-1.2-transitional.xsd>
       nomen:
-        eng-Latn: 'XML Localization Interchange File Format (XLIFF) v1.2 (too old, no draft)'
+        eng-Latn: 'XML Localization Interchange File Format (XLIFF) v1.2'
 
     asa:
       modus_operandi:
@@ -1332,8 +1356,20 @@ normam:
   XLSX:
     __meta:
       archivum_extensionem: .xlsx
+      descriptionem: |
+        _[eng-Latn]
+        Both URL GSheets and local/remote file of Microsoft Excel have built
+        read-only access in support for reference cli implementation
+        as container for data source without intermediate file transformation
+        to CSV container of HXLTM. This means humans don't need to edit CSV
+        files directly.
+
+        The support on `hxltmcli` to write directly to GSheets and
+        Microsoft Excel is unlikely to be implemented.
+        [eng-Latn]_
       nomen:
-        eng-Latn: 'Microsoft Excel (native support to read, but not write, data directly with .XSLX)'
+        eng-Latn: 'Microsoft Excel, HXLTM container (read-only; native support as data source)'
+        # eng-Latn: 'Microsoft Excel (native support to read, but not write, data directly with .XSLX)'
 
     asa:
       modus_operandi:

diff --git a/ontologia/json/cor.hxltm.json b/ontologia/json/cor.hxltm.json
@@ -124,11 +124,12 @@
     },
     "GSheets": {
       "__meta": {
+        "descriptionem": "_[eng-Latn]\nBoth URL GSheets and local/remote file of Microsoft Excel have built\nread-only access in support for reference cli implementation\nas container for data source without intermediate file transformation\nto CSV container of HXLTM. This means humans don't need to edit CSV\nfiles directly.\n\nThe support on `hxltmcli` to write directly to GSheets and\nMicrosoft Excel is unlikely to be implemented.\n[eng-Latn]_\n",
         "normam": [
           "<https://developers.google.com/sheets/api>"
         ],
         "nomen": {
-          "eng-Latn": "Google Sheets (via CSV import)"
+          "eng-Latn": "Google Sheets, HXLTM container (read-only; native support as data source)"
         },
         "situs_interretialis": {
           "referens_officinale": [
@@ -180,9 +181,32 @@
         }
       }
     },
+    "HXLTM-TMETA": {
+      "__meta": {
+        "archivum_extensionem": [
+          ".tmeta.json",
+          ".tmeta.yml"
+        ],
+        "descriptionem": "_[eng-Latn]\nTo be documented.\n[eng-Latn]_\n",
+        "normam": [
+          "<https://hdp.etica.ai/hxltm/archivum/#HXLTM-TMETA>"
+        ],
+        "nomen": {
+          "eng-Latn": "HXLTM Terminologium Multilinguam Meta"
+        },
+        "situs_interretialis": {
+          "referens_officinale": [
+            "<https://hdp.etica.ai/hxltm>",
+            "<https://github.com/EticaAI/HXL-Data-Science-file-formats/labels/HXLTM>",
+            "<https://github.com/EticaAI/HXL-Data-Science-file-formats/issues/24>"
+          ]
+        }
+      }
+    },
     "JSON-kv": {
       "__meta": {
         "archivum_extensionem": ".json",
+        "descriptionem": "_[eng-Latn]\nThis export/importer needs to be created. One level is trivial, but 2\nor more nested levels would be simpler for end user just use\n**HXLTM Ad Hoc Fōrmulam (HXLTM templated export)** to have full\ncontrol.\n[eng-Latn]_\n",
         "normam": [
           "<https://angular.io/guide/i18n#change-the-source-language-file-location>",
           "<https://www.i18next.com/misc/json-format>",
@@ -678,7 +702,7 @@
           "<http://docs.oasis-open.org/xliff/v1.2/cs02/xliff-core-1.2-transitional.xsd>"
         ],
         "nomen": {
-          "eng-Latn": "XML Localization Interchange File Format (XLIFF) v1.2 (too old, no draft)"
+          "eng-Latn": "XML Localization Interchange File Format (XLIFF) v1.2"
         }
       },
       "asa": {
@@ -731,8 +755,9 @@
     "XLSX": {
       "__meta": {
         "archivum_extensionem": ".xlsx",
+        "descriptionem": "_[eng-Latn]\nBoth URL GSheets and local/remote file of Microsoft Excel have built\nread-only access in support for reference cli implementation\nas container for data source without intermediate file transformation\nto CSV container of HXLTM. This means humans don't need to edit CSV\nfiles directly.\n\nThe support on `hxltmcli` to write directly to GSheets and\nMicrosoft Excel is unlikely to be implemented.\n[eng-Latn]_\n",
         "nomen": {
-          "eng-Latn": "Microsoft Excel (native support to read, but not write, data directly with .XSLX)"
+          "eng-Latn": "Microsoft Excel, HXLTM container (read-only; native support as data source)"
         }
       },
       "asa": {

diff --git a/ontologia/json/cor.hxltm.json.sum b/ontologia/json/cor.hxltm.json.sum
@@ -1 +1 @@
-SHA384 (cor.hxltm.json) = e670a001cfa26e79120104c9b7f091a7a2f86bd270a57ffbab85f87e04e5d29c77f9130d91ba81dc654d874df1007f32
+SHA384 (cor.hxltm.json) = 40956f17393fb9b133a0d29d13a51f093514d98fdcef16f96ea9eb4d1e09f28fb8696a02efa0c0d960c292a84309023d
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		SHA384 (cor.hxltm.json) = e670a001cfa26e79120104c9b7f091a7a2f86bd270a57ffbab85f87e04e5d29c77f9130d91ba81dc654d874df1007f32
		SHA384 (cor.hxltm.json) = 40956f17393fb9b133a0d29d13a51f093514d98fdcef16f96ea9eb4d1e09f28fb8696a02efa0c0d960c292a84309023d