Dev command to output help page in markdown format

src/alire/alire-config-builtins.ads

@@ -95,7 +95,8 @@ package Alire.Config.Builtins is
      (Key => "solver.autonarrow",
       Def => True,
       Help =>
-        "If true, `alr with` will replace 'any' dependencies with the"
+        "If true, " & Formatter.Terminal ("alr with")
+      & " will replace 'any' dependencies with the"
       & " appropriate caret/tilde dependency.");
 
    --  TOOLCHAIN
@@ -133,7 +134,7 @@ package Alire.Config.Builtins is
         "If true, Alire will not attempt to update dependencies even after "
       & "the manifest is manually edited, or when no valid solution has "
       & "been ever computed. All updates have to be manually requested "
-      & "through `alr update`");
+      & "through " & Formatter.Terminal ("alr update"));
 
    --  USER
 

src/alire/alire-roots.adb

@@ -1832,7 +1832,8 @@ package body Alire.Roots is
             if not Needed.Is_Complete then
                Trace.Warning
                  ("There are missing dependencies"
-                  & " (use `alr with --solve` for details).");
+                    & " (use " & Formatter.Terminal ("alr with --solve")
+                    & " for details).");
             end if;
 
             This.Sync_Manifest_And_Lockfile_Timestamps;

src/alire/alire-toolchains.ads

@@ -94,7 +94,8 @@ package Alire.Toolchains is
                 & Utils.TTY.Name ("gnat_native") & " or "
                 & Utils.TTY.Name ("gnat_riscv_elf") & ". ")
      .Append ("")
-     .Append ("Use " & TTY.Terminal ("alr toolchain --help") & " to obtain "
+     .Append ("Use " & Formatter.Terminal ("alr toolchain --help")
+              & " to obtain "
               & "information about toolchain management. Alire can be "
               & "configured to rely on a toolchain installed by the user in "
               & "the environment, or to use one of the indexed toolchains "

src/alire/alire.adb

@@ -180,7 +180,7 @@ package body Alire is
       if +Err /= "" then
          Err := Err
            & " You can see the complete identifier naming rules"
-           & " with 'alr help identifiers'";
+           & " with '" & Formatter.Terminal ("alr help identifiers") & "'";
       end if;
 
       if Err /= "" then

src/alire/alire.ads

@@ -15,6 +15,7 @@ pragma Warnings (On);
 
 with Simple_Logging;
 with CLIC.TTY;
+with CLIC.Formatter;
 
 package Alire with Preelaborate is
 
@@ -240,6 +241,7 @@ package Alire with Preelaborate is
    package Trace renames Simple_Logging;
 
    package TTY renames CLIC.TTY;
+   package Formatter renames CLIC.Formatter;
 
    Log_Level : Simple_Logging.Levels renames Simple_Logging.Level;
    --  This one selects the verbosity level of the logging library. The usage

src/alr/alr-commands-build.adb

@@ -146,18 +146,21 @@ package body Alr.Commands.Build is
          & "whereas dependencies are built in release mode. Use "
          & Switch_Profiles & " for more overrides.")
        .New_Line
-       .Append (Switch_Profiles & "="
-         & TTY.Emph ("*|%|<crate1>=<profile>[,<crate2>=<profile>...]"))
+       .Append (Formatter.Terminal (Switch_Profiles & "="
+         & ("*|%|<crate1>=<profile>[,<crate2>=<profile>...]")))
        .Append ("   Apply profiles to individual crates.")
-       .Append ("   Use " & TTY.Emph ("*=<profile>") & " to set all profiles.")
-       .Append ("   Use " & TTY.Emph ("%=<profile>") & " to set profiles of "
+       .Append ("   Use " & Formatter.Terminal ("*=<profile>")
+                & " to set all profiles.")
+       .Append ("   Use " & Formatter.Terminal ("%=<profile>")
+                & " to set profiles of "
          & "crates without a setting in a manifest only.")
        .New_Line
-       .Append ("Running '" & TTY.Terminal ("alr build") & "' without profile "
+       .Append ("Running '" & Formatter.Terminal ("alr build")
+         & "' without profile "
          & "switches defaults to development (root crate) + release "
          & " (dependencies). Indirect builds through, e.g., '"
-         & TTY.Terminal ("alr run") & "' will use the last '"
-         & TTY.Terminal ("alr build") & "' configuration.")
+         & Formatter.Terminal ("alr run") & "' will use the last '"
+         & Formatter.Terminal ("alr build") & "' configuration.")
       );
 
    --------------------
@@ -188,7 +191,8 @@ package body Alr.Commands.Build is
         (Config,
          Cmd.Profiles'Access,
          "", Switch_Profiles & "=",
-         "Comma-separated list of <crate>=<profile> values (see description)");
+         "Comma-separated list of " & Formatter.Terminal ("<crate>=<profile>")
+           & " values (see description)");
 
    end Setup_Switches;
 

src/alr/alr-commands-config.adb

@@ -196,7 +196,8 @@ package body Alr.Commands.Config is
         (Config      => Config,
          Output      => Cmd.Show_Origin'Access,
          Long_Switch => "--show-origin",
-         Help        => "Show origin of configuration values in --list");
+         Help        => "Show origin of configuration values in "
+           & Formatter.Terminal ("--list"));
 
       Define_Switch
         (Config      => Config,

src/alr/alr-commands-dev.adb

@@ -1,5 +1,8 @@
+with Ada.Strings.Unbounded;
 with Ada.Strings.UTF_Encoding.Wide_Wide_Strings;
 
+with CLIC.Formatter;
+
 with Alire.Selftest;
 
 package body Alr.Commands.Dev is
@@ -24,6 +27,58 @@ package body Alr.Commands.Dev is
       Trace.Always (Encode ("ⓘ✓"));
    end Print_UTF_8_Sequence;
 
+   -------------------
+   -- Print_MD_Help --
+   -------------------
+
+   procedure Print_MD_Help is
+
+      use Ada.Strings.Unbounded;
+
+      Last_Group : Unbounded_String;
+
+      procedure Put_MD_Command
+        (Group : Unbounded_String;
+         Cmd : not null CLIC.Subcommand.Command_Access) is
+      begin
+
+         if Group /= Last_Group then
+            New_Line;
+            Put_Line ("# " & To_String (Group) & " Commands");
+
+            Last_Group := Group;
+         end if;
+
+         Put_Line ("## " & Formatter.Terminal ("alr " & Cmd.Name));
+
+         New_Line;
+         Sub_Cmd.Display_Help (Cmd.Name);
+         New_Line;
+
+      end Put_MD_Command;
+
+      procedure Put_MD_Topic
+        (Topic : not null CLIC.Subcommand.Help_Topic_Access) is
+      begin
+         New_Line;
+         Put_Line ("## " & Topic.Name);
+         Sub_Cmd.Display_Help (Topic.Name);
+         New_Line;
+      end Put_MD_Topic;
+
+   begin
+      CLIC.Formatter.Enable_Markdown;
+
+      Put_Line ("# Usage Help");
+      Sub_Cmd.Display_Usage;
+
+      Sub_Cmd.Iterate_Commands (Process => Put_MD_Command'Access);
+
+      Put_Line ("# Topics");
+      Sub_Cmd.Iterate_Topics (Process => Put_MD_Topic'Access);
+
+   end Print_MD_Help;
+
    -------------
    -- Execute --
    -------------
@@ -56,6 +111,10 @@ package body Alr.Commands.Dev is
       if Cmd.UTF_8_Test then
          Print_UTF_8_Sequence;
       end if;
+
+      if Cmd.MD_Help then
+         Print_MD_Help;
+      end if;
    end Execute;
 
    ----------------------
@@ -105,6 +164,11 @@ package body Alr.Commands.Dev is
                      Cmd.UTF_8_Test'Access,
                      "", "--utf8",
                      "Print a known UTF-8 sequence");
+
+      Define_Switch (Config,
+                     Cmd.MD_Help'Access,
+                     "", "--help-doc-markdown",
+                     "Print a complete help page in markdown format");
    end Setup_Switches;
 
 end Alr.Commands.Dev;

src/alr/alr-commands-dev.ads

@@ -37,6 +37,7 @@ private
       Raise_Except : aliased Boolean := False;
       Self_Test    : aliased Boolean := False;
       UTF_8_Test   : aliased Boolean := False; -- Produce some UTF-8 output
+      MD_Help      : aliased Boolean := False;
    end record;
 
 end Alr.Commands.Dev;

src/alr/alr-commands-exec.adb

@@ -123,7 +123,8 @@ package body Alr.Commands.Exec is
         (Config,
          Cmd.Prj'Access,
          Switch => "-P?",
-         Help => "Add ""-P <PROJECT_FILE>"" to the command switches");
+         Help => "Add """ & Formatter.Terminal ("-P <PROJECT_FILE>")
+           & """ to the command switches");
    end Setup_Switches;
 
 end Alr.Commands.Exec;

src/alr/alr-commands-exec.ads

@@ -29,12 +29,15 @@ package Alr.Commands.Exec is
        .Append ("This can be used to run tools or scripts on Alire projects.")
        .New_Line
        .Append ("The ""-P"" switch can be used to ask Alire to insert a ")
-       .Append ("""-P <PROJECT_FILE>"" switch to the command arguments.")
+       .Append ("""" & Formatter.Terminal ("-P <PROJECT_FILE>")
+                  & """ switch to the command arguments.")
        .Append ("""-P"" takes an optional position argument to specify where")
        .Append ("to insert the extra switch. ""-P1"" means first position, ")
        .Append ("""-P2"" second position, etc. ""-P-1"" means last position, ")
        .Append ("""-P-2"" penultimate position, etc. ""-P"" equals ""-P1"".")
-       .Append ("For example ""alr exec -P2 -- python3 main.py arg1"" will")
+       .Append ("For example, """
+                & Formatter.Terminal ("alr exec -P2 -- python3 main.py arg1")
+                & """ will")
        .Append ("run the following command:")
        .Append ("[""python3"", ""main.py"", ""-P"", ""crate.gpr"", ""arg1""]")
       );

src/alr/alr-commands-install.adb

@@ -108,8 +108,8 @@ package body Alr.Commands.Install is
        .New_Line
        .Append ("Installation prefixes are intended to make binaries or "
          & "dynamic libraries available outside of the Alire environment, "
-         & "normally by adding the " & TTY.URL ("<prefix>/bin")
-         &  " folder to the user's path.")
+         & "normally by adding the " & Formatter.Terminal ("<prefix>/bin")
+         & " folder to the user's path.")
        .New_Line
        .Append ("Although Alire will vet trivially detectable conflicts "
          & "(e.g., trying to install two executable release with different "
@@ -118,11 +118,13 @@ package body Alr.Commands.Install is
          & "regard to the final consistency of installations.")
        .New_Line
        .Append ("That said, binary crates from the Alire project (" & Binaries
-         & "), as well as crates initialized with `alr` using default "
+         & "), as well as crates initialized with "
+         & Formatter.Terminal ("alr") & " using default "
          & "templates, should be able to coexist in a same installation prefix"
          & " without issue.")
        .New_Line
-       .Append ("You can use the --force to reinstall already installed "
+       .Append ("You can use the " & Formatter.Terminal ("--force")
+         & " to reinstall already installed "
          & "releases.")
       );
 

src/alr/alr-commands-pin.adb

@@ -248,17 +248,20 @@ package body Alr.Commands.Pin is
       .New_Line
       .Append ("Without arguments, show existing pins.")
       .New_Line
-      .Append ("Use --all to pin the whole current solution.")
+      .Append ("Use " & Formatter.Terminal ("--all")
+               & " to pin the whole current solution.")
       .New_Line
       .Append ("Specify a single crate to modify its pin.")
       .New_Line
-      .Append ("Use the --use <PATH|URL> switch to"
-               & " use the target to fulfill a dependency locally"
+      .Append ("Use the " & Formatter.Terminal ("--use <PATH|URL>")
+               & " switch to use the target to fulfill a dependency locally"
                & " instead of looking for indexed releases."
-               & " An optional reference can be specified with --commit;"
+               & " An optional reference can be specified with "
+               & Formatter.Terminal ("--commit") & ";"
                & " the pin will be frozen at the commit currently matching"
                & " the reference.  Alternatively, a branch to track can be"
-               & " specified with --branch. Use `alr update` to refresh the"
+               & " specified with " & Formatter.Terminal ("--branch") & ". "
+               & "Use " & Formatter.Terminal ("alr update") & " to refresh the"
                & " tracking pin contents.")
      );
 

src/alr/alr-commands-printenv.adb

@@ -66,8 +66,9 @@ package body Alr.Commands.Printenv is
                  " for instance before starting an IDE.")
       .New_Line
       .Append ("Examples:")
-      .Append ("  - eval $(alr printenv --unix)")
-      .Append ("  - alr printenv --powershell | Invoke-Expression")
+      .New_Line
+      .Append ("* eval $(alr printenv --unix)")
+      .Append ("* alr printenv --powershell | Invoke-Expression")
      );
 
    --------------------

src/alr/alr-commands-publish.ads

@@ -31,12 +31,14 @@ package Alr.Commands.Publish is
                 & " a local or remote git repository.")
        .New_Line
        .Append ("For the common use case of a github-hosted repository,"
-                & " issue `alr publish` after committing and pushing"
-                & " the new release version.")
+                & " issue " & Formatter.Terminal ("alr publish")
+                & " after committing and pushing the new release version.")
        .New_Line
-       .Append ("Use --tar to create a source archive ready to be uploaded.")
+       .Append ("Use " & Formatter.Terminal ("--tar")
+                & " to create a source archive ready to be uploaded.")
        .New_Line
-       .Append ("Use --manifest to use metadata in a non-default file.")
+       .Append ("Use " & Formatter.Terminal ("--manifest")
+                & " to use metadata in a non-default file.")
        .New_Line
        .Append ("See the above link for help with other scenarios."));
 

src/alr/alr-commands-search.adb

@@ -286,21 +286,25 @@ package body Alr.Commands.Search is
    is
      (AAA.Strings.Empty_Vector
       .Append ("Searches the given substring in crate names (or properties"
-               & " with --property), and shows the most recent release"
-               & " of matching crates (unless --full is specified).")
+               & " with " & Formatter.Terminal ("--property")
+               & "), and shows the most recent release"
+               & " of matching crates (unless " & Formatter.Terminal ("--full")
+               & " is specified).")
       .New_Line
-      .Append ("Use --crates to get a simple list of only crate names and "
+      .Append ("Use " & Formatter.Terminal ("--crates")
+               & " to get a simple list of only crate names and "
                & " descriptions. Otherwise,"
                & " besides version, description and release notes, a status"
                & " column with the following status flags is provided:")
       .New_Line
-      .Append ("E: the release is externally provided.")
-      .Append ("S: the release is available through a system package.")
-      .Append ("U: the release is not available in the current platform.")
-      .Append ("X: the release has dependencies that cannot be resolved.")
+      .Append ("* E: the release is externally provided.")
+      .Append ("* S: the release is available through a system package.")
+      .Append ("* U: the release is not available in the current platform.")
+      .Append ("* X: the release has dependencies that cannot be resolved.")
       .New_Line
-      .Append ("The reasons for unavailability (U) can be ascertained with"
-               & " 'alr show <crate>=<version>'.")
+      .Append ("The reasons for unavailability (U) can be ascertained with:")
+      .New_Line
+      .Append (Formatter.Terminal ("alr show <crate>=<version>"))
       .New_Line
       .Append ("Unresolvable releases (X) should not happen in platforms"
                & " with assigned maintainers. Common reasons are missing"
@@ -330,7 +334,8 @@ package body Alr.Commands.Search is
         (Config,
          Cmd.Detect'Access,
          "", "--external-detect",
-         "Detect externally-provided releases (implies --external)");
+         "Detect externally-provided releases (implies "
+         & Formatter.Terminal ("--external") & ")");
 
       Define_Switch (Config,
                      Cmd.Full'Access,