update JSON format, add documentation on formats

git-svn-id: svn://tug.org/texlive/trunk@45620 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 116 insertions, 0 deletions

diff --git a/Master/tlpkg/doc/JSON-formats.txt b/Master/tlpkg/doc/JSON-formats.txt
new file mode 100644
index 00000000000..6f8a8bf8967
--- /dev/null
+++ b/Master/tlpkg/doc/JSON-formats.txt
@@ -0,0 +1,116 @@
+JSON formats for the various outputs of tlmgr
+=============================================
+
+Guaranteed to be present fields are marked with a *
+
+TLPOBJ
+------
+JSON object with key/values according to the underlying structure with a few
+exception (docfiles and docfiledata are merged). Details:
+
+* String type:
+  *name, shortdesc, longdesc, *category, catalogue, containerchecksum,
+  srccontainerchecksum, doccontainerchecksum
+  Example: "name": "12many"
+
+* Number type:
+  *revision, runsize, docsize, srcsize, containersize, srccontainersize, doccontainersize
+  Example: "revision": 12345
+
+* Boolean type:
+  available, installed, relocated
+  Example: "relocated": false
+
+* Array type (with the sub-type in parenthesis):
+  - of String type: runfiles, srcfiles, executes, depends, postactions
+    Example: "runfiles": [ "texmf-dist/...", "texmf-dist/...file2" ]
+  - of Object type:
+    . docfiles: keys: *file, language, details (all Strings)
+      Example:
+        [ { "file": "docfile1", "lang": "en" }, { "file": "docfile2", "detail": "readme file" } ]
+
+* Object type:
+  - binfiles: keys are architecture names, values are arrays of strings (list of binfiles)
+    Example: { "x86_64-linux": [ "binfile1", "binfile2", ... ], "win32": [ "binfile3" ] }
+  - binsize: keys are architecture names, values are numbers
+    Example: { "x86_64-linux": 1233, "win32": 333 }
+  - cataloguedata: keys are topics, version, license, ctan, date, values are all strings
+    Example: { "topics": "graphic", "version": "1.23" }
+
+
+Note: A minimal TLPOBJ might look like
+{
+  "name": "minimal",
+  "category": "Package",
+  "revision": 12345
+}
+
+
+
+TLPOBJINFO
+----------
+This JSON format is dumped on tlmgr info --data json and is slightly different
+format compared to TLPOBJ above:
+
+Removed fields: revision
+Added fields:
+- Number type: lrev, rrev -- local and remote revision of the package
+- Boolean type: available (available at repository), installed
+
+
+TLPDBSINGLE
+-----------
+JSON object with the following fields:
+* Object type:
+  - options: keys are the tlmgr names of %TLConfig::TLPDBOptions, that is
+    . Number type: autobackup, fileassocs
+    . Boolean type: formats, desktop_integration, generate_updmap, docfiles, 
+                    srcfiles, postcode, w32_multi_user
+    . String type: backupdir, location, sys_bin, sys_info, sys_man
+    . Object type: repository: keys are tags, values are Strings
+       if there is only one location then the tag is "main"
+    Example:
+      "options": {
+        "autobackup": 2,
+        "formats": false,
+        "postcode": true,
+        "backupdir": "/backup/tl",
+        "repository": {
+          "main": "http://mirror.ctan.org/systems/texlive/tlnet",
+          "tlcontrib": "..."
+        }
+      }
+
+  - settings: keys are the names of %TLConfig::TLPDBSettings, that is
+    . Boolean type: usertree
+    . String type: platform
+    . Array type: available_architectures (Strings)
+
+  - configs: keys are the names of %TLConfig::TLPDBConfigs, that is
+    . Boolean type: container_split_src_files, container_split_doc_files
+    . String type: container_format, minrelease, release
+
+* Array type:
+  - tlpkgs: JSON array of TLPOBJs in JSON format
+
+
+TLPDB
+-----
+This format is used when dumping tlpdb, local or remote
+JSON object with the following fields:
+keys are tags, values are tlpdb in TLPDBSINGLE format
+Example:
+{
+  "main": {
+    "options": {...},
+    "tlpkgs": [...]
+  },
+  "tlcontrib": {
+    "option": {...},
+    "tlpkgs": [...]
+  }
+}
+
+
+TODO
+  UPDATE JSON format