ninja doc: more cleanup

(cherry picked from commit 9b14e2c)

docs/deployment/ninja/command/export-audit.adoc

@@ -1,6 +1,6 @@
 = Export audit
 
-#TODO split into export and import#
+//TODO split into export and import
 
 [NOTE]
 Audit export/import uses the same format as objects, even utilizing `<objects>` element,

docs/deployment/ninja/command/import-audit.adoc

@@ -1,3 +1,3 @@
 = Import audit
 
-#TODO#
+//TODO

docs/deployment/ninja/command/initial-objects.adoc

@@ -38,7 +38,7 @@ There are two main scenarios that can be followed:
 * <<No changes in initial objects>>
 * <<Custom changes in initial objects>>
 
-==== No changes in initial objects
+== No changes in initial objects
 
 This one is the simplest case.
 If there are no custom changes in initial objects made by users, then ninja can update initial objects automatically.
@@ -50,7 +50,7 @@ Following command can be used (please use `--dry-run` if you want to see what wi
 ./bin/ninja.sh initial-objects --no-merge
 ----
 
-==== Custom changes in initial objects
+== Custom changes in initial objects
 
 If there are custom changes in initial objects made by users, then ninja can help you merge them.
 First, dry run is recommended to see what needs to be done, optionally with report of changes:
@@ -68,7 +68,7 @@ If there are objects (filtered by types or oids) that can be handled without mer
 ./bin/ninja.sh initial-objects --no-merge [--type securityPolicy,valuePolicy,...] [--oid 93ae3cd3-b34d-4093-ad49-adba573a95ba]
 ----
 
-==== Important updates
+== Important updates
 
 There is at least one object - securityPolicy that needs to be updated when upgrading LTS from 4.4 to 4.8.
 If there are no custom changes in securityPolicy, following command can be used:

docs/deployment/ninja/command/upgrade-distribution.adoc

@@ -1,3 +1,3 @@
 = Upgrade distribution
 
-#TODO#
+//TODO

docs/deployment/ninja/command/upgrade-objects.adoc

@@ -1,13 +1,25 @@
 = Upgrade objects
 
-Command `upgrade-objects` can be used to _upgrade_ objects to get rid deprecated or obsolete items and configuration.
-This operation can use CSV output file of `verify` command.
+Command `upgrade-objects` can be used to _upgrade_ objects to get rid of deprecated or obsolete data and configuration.
+This operation should be used with CSV output file from `verify` command.
+For more information about verification, see xref:./verify.adoc[].
+
+Verification report should be reviewed before running upgrade command.
+It is important to understand what will be changed and how can it affect the system.
+
+Only verification items with _type = seamless_ will be updated.
+Scope of upgrade-objects command can be set in several ways:
+
+* by oid (`--oid`)
+* by type (`-t, --type`) and filter (`-f, --filter`)
+
+This way it is possible to upgrade only specific objects.
+Verification items can be skipped also using last column in CSV file.
+Any of `true`, `t`, `yes`, `y` will tell ninja to skip the item.
 
 .Example of command that upgrades objects, also with
 [source,bash]
 ----
 ./bin/ninja.sh upgrade-objects \
   --verification-file verify-output.csv
 ----
-
-#TODO#

docs/deployment/ninja/command/verify.adoc

@@ -1,19 +1,53 @@
 = Verify
 
-Command that verifies objects in midPoint repository.
-It displays warnings about objects to `SYSOUT` or file.
-Similarly to export, one can define oid, multiple types or filter to filter verified objects.
-Simple usage to verify all objects in the repository for all warnings:
+Verification is a process that reads objects from midPoint repository and checks whether they are compatible with new version of midPoint.
+Verification checks for deprecated, removed elements or other issues that can cause problems during or after upgrade.
 
-.Example which verifies all objects in repository, checks all warnings
-[source,bash]
-----
-./bin/ninja.sh verify
-----
+Different categories for verification can be set turned on via switch `--verification-category [DEPRECATED|REMOVED|PLANNED_REMOVAL|INCORRECT_OIDS]`.
+By default, all categories are checked.
+
+By default, ninja displays warnings about objects to `SYSOUT`.
+Output can be redirected to file using `-o`, `--output`.
+
+Verification can run while midPoint is running.
+The whole verification can be split into multiple parts, each part verifying a subset of similar objects using `-f, --filter` and `-t, --type` options.
+This way verification reports can be simpler to read and easier to understand, since they should contain smaller set of issues.
+
+Verification results can be reported in two styles plain and CSV.
+The switch for report style is `--report-style [plain|csv]`.
+Plain style is set as default option, while CSV is better for further processing and review.
+CSV report style creates two files - CSV and XML.
+XML will contain list of deltas for each object, describing what ninja wants to change on object to _upgrade_ it.
+
+The CSV report contain three sets of columns:
+
+* Object identification (oid, name, type)
+* Verification item information (status, path, message)
+* Upgrade information (multiple columns see <<Upgrade information>>)
+
+== Upgrade information
+
+Upgrade information consists of following columns:
+
+* *Identifier* - unique identifier of verification/upgrade item which can be used to group similar items together when processing reports.
+* *Phase* - upgrade phase in which item should be updated (before or after midPoint is upgraded).
+* *Priority*
+** *Critical* - midPoint may fail to start or work properly if such verification item is not fixed (updated).
+Critical item would also halt upgrade procedure in next phase, unless this check is explicitly skipped using `--skip-verification` option.
+** *Necessary* - verification item should be fixed, midPoint should not fail to start, but some features might not work properly.
+** *Optional* - this item doesn't have to be necessarily fixed, but it's recommended to do so.
+E.g. deprecated configuration which might be removed in version after next one.
+* *Type*
+** *Seamless* - such item can be handled by ninja automatically without any user interaction.
+E.g. there's clear migration path without any change in functionality.
+** *Preview* - ninja can provide new configuration for such item, but it's recommended to review it before applying.
+** *Manual* - ninja can't provide any configuration for such item, user has to fix it manually.
+Reason can be that there's currently no migration path (removed feature) or there are multiple possible solutions that doesn't map configuration 1:1.
+* *Description* - contains more information, mainly on how to upgrade/update such item.
+* *Skip* - last column in CSV report, can be used to mark items that should be skipped during object upgrade.
 
-There is a `-w` switch that can be used to select specific warnings to display.
-Currently, it only supports values deprecated and plannedRemoval.
-Following command will show warnings about planned removal of items used by all objects in the repository:
+Such CSV report has to be used as input for upgrade objects command with option `--verification-file`.
+See xref:./upgrade-objects.adoc[] for more information.
 
 .Example which verifies all objects in repository, checks only planned removal of items
 [source,bash]

docs/deployment/ninja/use-case/upgrade-with-ninja.adoc

@@ -35,7 +35,7 @@ For concrete examples of upgrade scenarios, please see <<Upgrade procedure examp
 .. Stop midPoint
 .. <<Upgrade DB schema>>
 .. <<Upgrade installation,Upgrade midPoint installation>>
-.. <<Initial objects,Update initial objects>>
+.. xref:./<<Initial objects,Update initial objects>>
 .. Start midPoint
 .. <<Verify connector references in resources>>
 
@@ -629,55 +629,9 @@ More information about task migration can be found in xref:/midpoint/reference/t
 Verification is a process that reads objects from midPoint repository and checks whether they are compatible with new version of midPoint.
 Verification checks for deprecated, removed elements or other issues that can cause problems during or after upgrade.
 
-Different categories for verification can be set turned on via switch `--verification-category [DEPRECATED|REMOVED|PLANNED_REMOVAL|INCORRECT_OIDS]`.
-By default, all categories are checked.
-
-Verification can run while midPoint is running.
-The whole verification can be split into multiple parts, each part verifying a subset of similar objects using `-f, --filter` and `-t, --type` options.
-This way verification reports can be simpler to read and easier to understand, since they should contain smaller set of issues.
-
-Verification results can be reported in two styles plain and CSV.
-The switch for report style is `--report-style [plain|csv]`.
-Plain style is set as default option, while CSV is better for further processing and review.
-CSV report style creates two files - CSV and XML.
-XML will contain list of deltas for each object, describing what ninja wants to change on object to _upgrade_ it.
-
-The CSV report contain three sets of columns:
-
-* Object identification (oid, name, type)
-* Verification item information (status, path, message)
-* Upgrade information
-
-==== Upgrade information
-
-Upgrade information consists of following columns:
-
-* *Identifier* - unique identifier of verification/upgrade item which can be used to group similar items together when processing reports.
-* *Phase* - upgrade phase in which item should be updated (before or after midPoint is upgraded).
-* *Priority*
-** *Critical* - midPoint may fail to start or work properly if such verification item is not fixed (updated).
-Critical item would also halt upgrade procedure in next phase, unless this check is explicitly skipped using `--skip-verification` option.
-** *Necessary* - verification item should be fixed, midPoint should not fail to start, but some features might not work properly.
-** *Optional* - this item doesn't have to be necessarily fixed, but it's recommended to do so.
-E.g. deprecated configuration which might be removed in version after next one.
-* *Type*
-** *Seamless* - such item can be handled by ninja automatically without any user interaction.
-E.g. there's clear migration path without any change in functionality.
-** *Preview* - ninja can provide new configuration for such item, but it's recommended to review it before applying.
-** *Manual* - ninja can't provide any configuration for such item, user has to fix it manually.
-Reason can be that there's currently no migration path (removed feature) or there are multiple possible solutions that doesn't map configuration 1:1.
-* *Description* - contains more information, mainly on how to upgrade/update such item.
-* *Skip* - last column in CSV report, can be used to mark items that should be skipped during object upgrade.
-Such CSV report has to be used as input for upgrade objects command with option `--verification-file`.
-
-Objects can be upgraded by using CSV report from verify:
-//Report only needed if there are objects/items to be skipped:
+Command `upgrade-objects` can be used to _upgrade_ objects to get rid of deprecated or obsolete data and configuration found by verification.
 
-[source,bash]
-----
-./bin/ninja.sh upgrade-objects \
-  --verification-file verify-output.csv --report-style csv
-----
+See more information about verification in xref:../command/verify.adoc[] and xref:../command/upgrade-objects.adoc[] command documentation.
 
 === Upgrade DB schema
 

docs/upgrade/upgrade-guide.adoc

@@ -19,7 +19,7 @@ Upgrades of _evaluation_, _demo_, _development_ and similar environments can usu
 NOTE: Starting with midPoint version 4.8 (also backported to 4.4.6, 4.7.2 and later) ninja tool was extended.
 Multiple new commands related to upgrade procedure were added.
 For simple deployments ninja can perform upgrade of objects, database and binaries.
-For more information see xref:/midpoint/reference/deployment/ninja/upgrade-with-ninja/[Upgrade with ninja].
+For more information see xref:/midpoint/reference/deployment/ninja/use-case/upgrade-with-ninja/[].
 
 WARNING: Please read the *entire* guide *before* starting the upgrade.
 MidPoint is a flexible platform, often deployed in unusual situations.