fix(pkg_list): add description of used colors

doc/commands/check-upgrade.8.rst

@@ -39,6 +39,11 @@ is provided, it checks for updates for the entire system.
 ``DNF5`` will exit with code `100`` if updates are available and list them; `0` if no updates
 are available.
 
+If terminal is available, list of the packages is colored, packages available for reinstall are
+(by default) colored with bold green and packages available for upgrade with bold blue. This
+behavior can be adjusted in configuration via
+:ref:`color_list_available_upgrade <_color_list_available_upgrade_options-label>` and
+:ref:`color_list_available_reinstall <_color_list_available_reinstall_options-label>` options.
 
 Options
 =======

doc/commands/list.8.rst

@@ -35,6 +35,12 @@ Description
 
 Prints lists of packages based on the provided parameters.
 
+If terminal is available, list of the packages is colored, packages available for reinstall are
+(by default) colored with bold green and packages available for upgrade with bold blue. This
+behavior can be adjusted in configuration via
+:ref:`color_list_available_upgrade <_color_list_available_upgrade_options-label>` and
+:ref:`color_list_available_reinstall <_color_list_available_reinstall_options-label>` options.
+
 
 Options
 =======

include/libdnf5-cli/output/pkg_colorizer.hpp

@@ -54,6 +54,11 @@ class LIBDNF_CLI_API PkgColorizer {
     /// @return Escape sequence for the color.
     std::string get_pkg_color(const IPackage & package);
 
+    /// Get a string describing the coloring scheme of the output produced by
+    /// the colorizer.
+    /// @return Description string, already escaped.
+    std::string get_coloring_description();
+
 private:
     LIBDNF_CLI_LOCAL std::string to_escape(const std::string & color);
 

libdnf5-cli/output/package_list_sections.cpp

@@ -106,7 +106,11 @@ void PackageListSections::print(const std::unique_ptr<PkgColorizer> & colorizer)
             std::cout << std::endl;
         }
         if (!heading.empty()) {
-            std::cout << heading << std::endl;
+            std::cout << heading;
+            if (libdnf5::cli::tty::is_coloring_enabled()) {
+                std::cout << " " << colorizer->get_coloring_description();
+            }
+            std::cout << std::endl;
         }
         scols_table_print_range(table, first, last);
         separator_needed = true;

libdnf5-cli/output/pkg_colorizer.cpp

@@ -46,6 +46,7 @@ const std::map<std::string_view, std::string_view> color_to_escape = {
     {"cyan", "\033[36m"},
     {"gray", "\033[37m"},
     {"white", "\033[1;37m"},
+    {"reset", "\033[0m"},
 };
 
 }
@@ -106,4 +107,30 @@ std::string PkgColorizer::to_escape(const std::string & color) {
     return output;
 }
 
+std::string PkgColorizer::get_coloring_description() {
+    std::ostringstream desc;
+    desc << "(";
+
+    // [NOTE](mfocko) Is there a possibility of any other meaning?
+    // Colorizer is written generically (with respect to the ordering against
+    // the “base set” of packages), but currently it is only used in the meaning
+    // as described below.
+    for (auto && [description, color] : {
+             std::make_pair("install", color_not_found),
+             std::make_pair("downgrade", color_lt),
+             std::make_pair("reinstall", color_eq),
+             std::make_pair("upgrade", color_gt),
+         }) {
+        if (color.empty()) {
+            // skip uncolored packages
+            continue;
+        }
+
+        desc << " " << color << description << color_to_escape.at("reset");
+    }
+    desc << " )";
+
+    return desc.str();
+}
+
 }  // namespace libdnf5::cli::output