Update documentation for repod-file

docs/repod/installation.rst:
Mention `repod-file` instead of `db2json`/ `json2db` as the latter are
removed.

docs/repod/tooling.rst:
Replace the documentation for `db2json`/ `json2db` with new
documentation on the various subcommands of `repod-file`.

docs/repod/installation.rst

@@ -19,8 +19,7 @@ The repod project can be used from a git clone of the project, with the help of
   poetry install
 
 Afterwards it is possible to make use of existing :ref:`tooling` with the help
-of ``poetry run`` (e.g. ``poetry run db2json --help`` or ``poetry run json2db
---help``).
+of ``poetry run`` (e.g. ``poetry run repod-file --help``).
 
 .. |poetry| raw:: html
 

docs/repod/tooling.rst

@@ -7,31 +7,100 @@ Tooling
 The repod project provides scripts, that can be used to manipulate data, which
 is related to the repositories it can manage.
 
-.. _db2json:
+.. _repod-file:
 
-db2json
--------
+repod-file
+----------
 
-The ``db2json`` script can be used to transform a :ref:`sync database` (both
-:ref:`default sync database` and :ref:`files sync database` files are
-supported) into the JSON files found in a :ref:`management repository`.
+The ``repod-file`` script can be used to inspect and transform data related to
+:ref:`package`, :ref:`sync database` and :ref:`management repository` files.
 
 .. note::
 
-   Refer to ``db2json --help`` for further information on options and
-   parameters.
+   Refer to ``repod-file --help`` for further information on subcommands,
+   options and parameters.
+
+.. _inspect_package_files:
+
+Inspecting Package files
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+:ref:`package` files can be inspected to review the metadata contained in them.
+
+To get the entire metadata collected by repod, use:
+
+.. code:: sh
+
+  repod-file package inspect <package> <signature>
+
+.. note::
+
+  The signature file is optional, but if present should be added to the call to
+  ``repod-file`` as it provides the additional ``pgpsig`` data for the output.
+
+The output of ``repod-file package inspect`` can be modified by using the
+``-p``/ ``--pretty`` option (for pretty printing the JSON output).
+
+To only display subsets of the data, refer to the following flags:
+
+* ``-B``/ ``--buildinfo`` (for :ref:`buildinfo`)
+* ``-M``/ ``--mtree`` (for :ref:`mtree`)
+* ``-P``/ ``--pkginfo`` (for :ref:`pkginfo`).
+
+.. _package_to_management_repo:
+
+Import Package metadata to management repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The metadata retrieved from :ref:`package` files and their :ref:`package
+signature` can be transformed to their respective :ref:`management repository`
+representation. For this to produce meaningful and complete output, all
+packages (and their signatures) of a given ``pkgbase`` (see |package
+splitting|) need to be consumed at once.
+
+.. code:: sh
+
+  repod-file package import <package> <signature> <repo>
+
+.. note::
+
+  All packages must either be provided with or without their accompanying
+  signatures. If signatures are present the packages and signatures are to be
+  provided in tuples of two (the first is always the package, the second always
+  the signature). The last parameter is always considered as the output
+  directory.
+
+The output of the above command may be displayed using the ``-d``/
+``--dry-run`` flag (nothing is written to the output directory in this case).
+To pretty print the JSON output use the ``-p``/ ``--pretty`` flag.
+
+.. _syncdb_to_management_repo:
+
+Transform repository sync databases to management repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:ref:`sync database` files can be transformed to representations used in the
+context of a :ref:`management repository`.
+
+.. note::
+
+  :ref:`files sync database` files are required to create :ref:`management
+  repository` files, that contain information on files contained in the
+  respective packages they represent! This data is not contained in the
+  :ref:`default sync database` files!
 
 For testing purposes, the system's |pacman| sync databases in
-``/var/lib/pacman/sync/`` can be used.
+``/var/lib/pacman/sync/`` can be used (this assumes a system that makes use of
+pacman as package manager).
 
-To transform :ref:`default sync database` files in a temporary directory, you
-can use the following:
+To transform :ref:`default sync database` files and output them to a temporary
+directory, you can use the following:
 
 .. code:: sh
 
   DEFAULT_JSON_OUTPUT="$(mktemp -d)"
   echo "$DEFAULT_JSON_OUTPUT"
-  db2json /var/lib/pacman/sync/core.db "$DEFAULT_JSON_OUTPUT"
+  repod-file syncdb export /var/lib/pacman/sync/core.db "$DEFAULT_JSON_OUTPUT"
 
 To be able to use :ref:`files sync database` files, make sure to update them
 first.
@@ -40,47 +109,57 @@ first.
 
   pacman -Fy
 
-Afterwards you are able to transform the files in a temporary directory as
-well:
+Afterwards you are able to transform the files and output them to a temporary
+directory as well:
 
 .. code:: sh
 
   FILES_JSON_OUTPUT="$(mktemp -d)"
   echo "$FILES_JSON_OUTPUT"
-  db2json /var/lib/pacman/sync/core.files "$FILES_JSON_OUTPUT"
+  repod-file syncdb export /var/lib/pacman/sync/core.files "$FILES_JSON_OUTPUT"
 
-.. _json2db:
+.. _management_repo_to_syncdb:
 
-json2db
--------
+Transform management repositories to repository sync databases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``json2db`` script can be used to transform the JSON files found in a
-:ref:`management repository` into a :ref:`sync database` (both :ref:`default
-sync database` and :ref:`files sync database` files are supported).
+The JSON files contained in a :ref:`management repository` can be transformed
+into a :ref:`sync database` (both :ref:`default sync database` and :ref:`files
+sync database` files are created).
 
-.. note::
+After following the examples in :ref:`syncdb_to_management_repo` it is possible
+to use the created files and turn them back into :ref:`sync database` files.
 
-   Refer to ``json2db --help`` for further information on options and
-   parameters.
+.. code:: sh
 
-After following the examples in :ref:`db2json` it is possible to use the
-created files and turn them back into :ref:`sync database` files.
+  SYNC_DB_OUTPUT="$(mktemp -d)"
+  echo "$SYNC_DB_OUTPUT"
+  repod-file management export "$FILES_JSON_OUTPUT" "$SYNC_DB_OUTPUT/core.db"
 
-.. code:: sh
+The above creates ``"$SYNC_DB_OUTPUT/core.db"`` as well as
+``"$SYNC_DB_OUTPUT/core.files"``.
+
+.. _json_schema_export:
 
-   DEFAULT_DB_OUTPUT="$(mktemp -d)"
-   echo "$DEFAULT_DB_OUTPUT"
-   json2db "$DEFAULT_JSON_OUTPUT" "$DEFAULT_DB_OUTPUT/core.db"
+Export JSON schema
+^^^^^^^^^^^^^^^^^^
 
-Analogous to the above the example for the :ref:`files sync database` looks
-very similar.
+To export the |JSON schema|, which represents the validation logic of repod, use:
 
 .. code:: sh
 
-   FILES_DB_OUTPUT="$(mktemp -d)"
-   echo "$FILES_DB_OUTPUT"
-   json2db -f "$FILES_JSON_OUTPUT" "$FILES_DB_OUTPUT/core.files"
+  REPOD_SCHEMA="$(mktemp -d)"
+  echo "$REPOD_SCHEMA"
+  repod-file schema export "$REPOD_SCHEMA"
 
 .. |pacman| raw:: html
 
   <a target="blank" href="https://man.archlinux.org/man/pacman.8">pacman</a>
+
+.. |JSON schema| raw:: html
+
+  <a target="blank" href="https://en.wikipedia.org/wiki/JSON#Metadata_and_schema">JSON schema</a>
+
+.. |package splitting| raw:: html
+
+  <a target="blank" href="https://man.archlinux.org/man/PKGBUILD.5#PACKAGE_SPLITTING">package splitting</a>