Support for markdown output in help messages

example/src/clic_ex-commands-subsub.adb

@@ -23,11 +23,11 @@ package body CLIC_Ex.Commands.Subsub is
          Put_Line            => Ada.Text_IO.Put_Line,
          Put_Error           => Ada.Text_IO.Put_Line,
          Error_Exit          => GNAT.OS_Lib.OS_Exit,
-         TTY_Chapter         => CLIC.TTY.Info,
-         TTY_Description     => CLIC.TTY.Description,
-         TTY_Version         => CLIC.TTY.Version,
-         TTY_Underline       => CLIC.TTY.Underline,
-         TTY_Emph            => CLIC.TTY.Emph);
+         TTY_Chapter         => CLIC.Formatter.Chapter,
+         TTY_Description     => CLIC.Formatter.Description,
+         TTY_Version         => CLIC.Formatter.Version,
+         TTY_Underline       => CLIC.Formatter.Underline,
+         TTY_Emph            => CLIC.Formatter.Emph);
    begin
       Sub.Register (new Sub.Builtin_Help);
       Sub.Register (new CLIC_Ex.Commands.TTY.Instance);

example/src/clic_ex-commands.adb

@@ -1,6 +1,6 @@
 with AAA.Strings;
 
-with CLIC.TTY;
+with CLIC.Formatter;
 with CLIC.User_Input;
 with CLIC.Config.Load;
 
@@ -22,6 +22,9 @@ package body CLIC_Ex.Commands is
    No_TTY : aliased Boolean := False;
    --  Used to disable control characters in output
 
+   Markdown_Help : aliased Boolean := False;
+   --  Used to enable help display in markdown format
+
    -------------------------
    -- Set_Global_Switches --
    -------------------------
@@ -50,6 +53,13 @@ package body CLIC_Ex.Commands is
                      No_TTY'Access,
                      Long_Switch => "--no-tty",
                      Help        => "Disables control characters in output");
+
+      Define_Switch (Config,
+                     Markdown_Help'Access,
+                     Long_Switch => "--markdown",
+                     Help        =>
+                       "Enables output of markdown format for help");
+
    end Set_Global_Switches;
 
    -------------
@@ -61,11 +71,15 @@ package body CLIC_Ex.Commands is
       Sub_Cmd.Parse_Global_Switches;
 
       if No_TTY then
-         CLIC.TTY.Force_Disable_TTY;
+         CLIC.Formatter.Force_Disable_TTY;
+      end if;
+
+      if Markdown_Help then
+         CLIC.Formatter.Enable_Markdown;
       end if;
 
       if not No_Color and then not No_TTY then
-         CLIC.TTY.Enable_Color (Force => False);
+         CLIC.Formatter.Enable_Color (Force => False);
          --  This may still not enable color if TTY is detected to be incapable
       end if;
 

example/src/clic_ex-commands.ads

@@ -2,7 +2,7 @@
 private with Ada.Text_IO;
 private with GNAT.OS_Lib;
 private with CLIC.Subcommand.Instance;
-private with CLIC.TTY;
+private with CLIC.Formatter;
 private with CLIC.Config;
 
 package CLIC_Ex.Commands is
@@ -24,9 +24,9 @@ private
       Put_Line            => Ada.Text_IO.Put_Line,
       Put_Error           => Ada.Text_IO.Put_Line,
       Error_Exit          => GNAT.OS_Lib.OS_Exit,
-      TTY_Chapter         => CLIC.TTY.Info,
-      TTY_Description     => CLIC.TTY.Description,
-      TTY_Version         => CLIC.TTY.Version,
-      TTY_Underline       => CLIC.TTY.Underline,
-      TTY_Emph            => CLIC.TTY.Emph);
+      TTY_Chapter         => CLIC.Formatter.Chapter,
+      TTY_Description     => CLIC.Formatter.Description,
+      TTY_Version         => CLIC.Formatter.Version,
+      TTY_Underline       => CLIC.Formatter.Underline,
+      TTY_Emph            => CLIC.Formatter.Emph);
 end CLIC_Ex.Commands;

src/clic-config.ads

@@ -29,7 +29,7 @@ package CLIC.Config with Preelaborate is
      access function (Key : Config_Key; Value : TOML.TOML_Value)
                       return Boolean;
    --  Return False when a Key/Value combination is not valid. Can be used to
-   --  check formating of string value like email address for instance.
+   --  check formatting of string value like email address for instance.
 
    procedure Import (This   : in out Instance;
                      Table  :        TOML.TOML_Value;

src/clic-formatter.adb

@@ -0,0 +1,44 @@
+with CLIC.TTY;
+with CLIC.Markdown;
+
+package body CLIC.Formatter is
+
+   Markdown_Enabled : Boolean := False;
+
+   procedure Enable_Markdown is
+   begin
+      Markdown_Enabled := True;
+   end Enable_Markdown;
+
+   procedure Force_Disable_TTY renames TTY.Force_Disable_TTY;
+   procedure Enable_Color (Force : Boolean := False)
+     renames TTY.Enable_Color;
+
+   function Chapter (Str : String) return String is
+     (if Markdown_Enabled
+      then Markdown.Chapter (Str)
+      else TTY.Bold (Str));
+
+
+   function Description (Str : String) return String is
+     (if Markdown_Enabled
+      then Markdown.Code (Str)
+      else TTY.Description (Str));
+
+   function Version (Str : String) return String is
+     (if Markdown_Enabled
+      then Markdown.Italic (Str)
+      else TTY.Version (Str));
+
+   function Underline (Str : String) return String is
+     (if Markdown_Enabled
+      then Markdown.Bold (Str)
+      else TTY.Underline (Str));
+
+   function Emph (Str : String) return String is
+     (if Markdown_Enabled
+      then Markdown.Code (Str)
+      else TTY.Emph (Str));
+
+
+end CLIC.Formatter;

src/clic-formatter.ads

@@ -0,0 +1,22 @@
+package CLIC.Formatter
+with Preelaborate
+is
+
+   -- Provides markdown or TTY formatting for displaying help pages.
+
+   procedure Force_Disable_TTY;
+
+   procedure Enable_Markdown;
+   --  Enables markdown output of formatting functions.
+
+   procedure Enable_Color (Force : Boolean := False);
+   --  Prepares colors for the terminal output. Unless Force, will do nothing
+   --  if a console redirection is detected.
+
+   function Chapter (Str : String) return String;
+   function Description (Str : String) return String;
+   function Version (Str : String) return String;
+   function Underline (Str : String) return String;
+   function Emph (Str : String) return String;
+
+end CLIC.Formatter;

src/clic-markdown.adb

@@ -0,0 +1,19 @@
+
+package body CLIC.Markdown is
+
+   function Chapter (Str : String) return String is
+     ("## " & Str);
+
+   function Plain_Text (Str : String) return String is
+      (Str);
+
+   function Code (Str : String) return String is
+     ('`' & Str & '`');
+
+   function Bold (Str : String) return String is
+     ('*' & Str & '*');
+
+   function Italic (Str : String) return String is
+     ('_' & Str & '_');
+
+end CLIC.Markdown;

src/clic-markdown.ads

@@ -0,0 +1,12 @@
+
+package CLIC.Markdown
+with Preelaborate
+is
+
+   function Chapter (Str : String) return String;
+   function Plain_Text (Str : String) return String;
+   function Code (Str : String) return String;
+   function Bold (Str : String) return String;
+   function Italic (Str : String) return String;
+
+end CLIC.Markdown;

src/clic-subcommand-instance.adb

@@ -494,7 +494,7 @@ package body CLIC.Subcommand.Instance is
          Table.Append (TTY_Description ("<arguments>"));
          Table.Append ("List of arguments for the command");
 
-         Table.Print (Separator => "   ",
+         Table.Print (Separator => "  ",
                       Put_Line  => Put_Line_For_Access'Access);
       end;
 

src/clic-subcommand-instance.ads

@@ -20,8 +20,10 @@ generic
    --  Used to signal that the program should terminate with the give error
    --  code. Typicaly use GNAT.OS_Lib.OS_Exit.
 
-   --  The procedures below are used to format the output such as usage and
-   --  help. Use CLIC.Subcommand.No_TTY if you don't want or need formating.
+   --  The functions below are used to format the output such as usage and
+   --  help. Use CLIC.Subcommand.No_TTY if you don't want or need formatting.
+   --  CLIC also provides ready implementations in CLIC.Formatter, CLIC.TTY
+   --  and CLIC.Markdown.
    with function TTY_Chapter (Str : String) return String;
    with function TTY_Description (Str : String) return String;
    with function TTY_Version (Str : String) return String;

src/clic-subcommand.ads

@@ -165,7 +165,7 @@ package CLIC.Subcommand is
    function No_TTY (Str : String) return String
    is (Str);
    --  Use this function for the TTY_* generic parameters of
-   --  CLIC.Subcommand.Instance if you don't want or need TTY formating.
+   --  CLIC.Subcommand.Instance if you don't want or need TTY formatting.
 
 private
 

src/clic-tty.ads

@@ -19,7 +19,7 @@ is
 
    procedure Force_Disable_TTY
      with Post => not Is_TTY;
-   --  Disable TTY support even if availabe
+   --  Disable TTY support even if available
 
    --------------------
    -- Color enabling --