From c47044a2c0920db7f3449b9638af9fe3d7d50d13 Mon Sep 17 00:00:00 2001 From: mgrojo Date: Sat, 23 Sep 2023 18:15:21 +0200 Subject: [PATCH 1/6] Support for markdown output in help messages This functionality can be used to provide on-line versions of the help messages for alire.ada.dev. The help is generated in a single markdown page with appropiate section titles, so it can have a table of contents. --- deps/clic | 2 +- src/alr/alr-commands-dev.adb | 64 ++++++++++++++++++++++++++++++++++++ src/alr/alr-commands-dev.ads | 1 + src/alr/alr-commands.adb | 2 +- src/alr/alr-commands.ads | 11 ++++--- 5 files changed, 73 insertions(+), 7 deletions(-) diff --git a/deps/clic b/deps/clic index 6879b9087..03cdf563a 160000 --- a/deps/clic +++ b/deps/clic @@ -1 +1 @@ -Subproject commit 6879b90876a1c918b4e112f59c6db0e25b713f52 +Subproject commit 03cdf563a906cffc9f8a951d0b825397b812d79b diff --git a/src/alr/alr-commands-dev.adb b/src/alr/alr-commands-dev.adb index 4b84110f4..79d3ac5db 100644 --- a/src/alr/alr-commands-dev.adb +++ b/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 ("## `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; diff --git a/src/alr/alr-commands-dev.ads b/src/alr/alr-commands-dev.ads index b83011bf5..519a56f66 100644 --- a/src/alr/alr-commands-dev.ads +++ b/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; diff --git a/src/alr/alr-commands.adb b/src/alr/alr-commands.adb index 62facdfda..a65a04cd5 100644 --- a/src/alr/alr-commands.adb +++ b/src/alr/alr-commands.adb @@ -452,7 +452,7 @@ package body Alr.Commands is end if; if No_TTY then - CLIC.TTY.Force_Disable_TTY; + CLIC.Formatter.Force_Disable_TTY; end if; -- Use CLIC.TTY selection/detection of TTY diff --git a/src/alr/alr-commands.ads b/src/alr/alr-commands.ads index 0857684ad..e141d9426 100644 --- a/src/alr/alr-commands.ads +++ b/src/alr/alr-commands.ads @@ -6,6 +6,7 @@ with Alire.Solver; with Alire.Version; with CLIC.Subcommand; +with CLIC.Formatter; private with GNAT.IO; private with CLIC.Subcommand.Instance; @@ -143,11 +144,11 @@ private Put_Error => Put_Error, Error_Exit => OS_Lib.Bailout, Set_Global_Switches => Set_Global_Switches, - TTY_Chapter => Alire.TTY.Bold, - TTY_Description => Alire.TTY.Description, - TTY_Version => Alire.TTY.Version, - TTY_Underline => Alire.TTY.Underline, - TTY_Emph => Alire.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); Unset : constant String := "unset"; -- Canary for when a string switch is given without value From 06006b48fb91485ce87140d24c8751cb0c1029f8 Mon Sep 17 00:00:00 2001 From: mgrojo Date: Sat, 14 Oct 2023 19:00:13 +0200 Subject: [PATCH 2/6] Improve markdown output (specially for Jekyll) * Use `Formatter.Terminal` for command lines and switches not passed through `Hightlight_Switches` * Avoid any which is not quoted as code * Use consistent formatting for lists with "*" and not "-" * Use indentation as a way to get preformat in appropriate cases --- deps/clic | 2 +- src/alire/alire-config-builtins.ads | 5 +++-- src/alire/alire-roots.adb | 3 ++- src/alire/alire-toolchains.ads | 3 ++- src/alire/alire.adb | 2 +- src/alire/alire.ads | 2 ++ src/alr/alr-commands-build.adb | 20 ++++++++++++-------- src/alr/alr-commands-config.adb | 3 ++- src/alr/alr-commands-dev.adb | 2 +- src/alr/alr-commands-exec.adb | 3 ++- src/alr/alr-commands-exec.ads | 7 +++++-- src/alr/alr-commands-install.adb | 10 ++++++---- src/alr/alr-commands-pin.adb | 13 ++++++++----- src/alr/alr-commands-printenv.adb | 4 ++-- src/alr/alr-commands-publish.ads | 10 ++++++---- src/alr/alr-commands-search.adb | 25 +++++++++++++++---------- src/alr/alr-commands-show.adb | 18 +++++++++++------- src/alr/alr-commands-test.adb | 11 ++++++++--- src/alr/alr-commands-toolchain.ads | 2 +- src/alr/alr-commands-topics-aliases.ads | 2 +- src/alr/alr-commands-withing.adb | 18 +++++++++++------- src/alr/alr-commands.adb | 9 +++++---- src/alr/alr-commands.ads | 3 ++- src/alr/alr.ads | 2 ++ 24 files changed, 111 insertions(+), 68 deletions(-) diff --git a/deps/clic b/deps/clic index 03cdf563a..69e3ab91b 160000 --- a/deps/clic +++ b/deps/clic @@ -1 +1 @@ -Subproject commit 03cdf563a906cffc9f8a951d0b825397b812d79b +Subproject commit 69e3ab91b7bf6eec8cd4e739af148ddbb32558cb diff --git a/src/alire/alire-config-builtins.ads b/src/alire/alire-config-builtins.ads index 2212837dc..c0b52f22e 100644 --- a/src/alire/alire-config-builtins.ads +++ b/src/alire/alire-config-builtins.ads @@ -66,7 +66,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 @@ -104,7 +105,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 diff --git a/src/alire/alire-roots.adb b/src/alire/alire-roots.adb index 2184c42da..278f373a1 100644 --- a/src/alire/alire-roots.adb +++ b/src/alire/alire-roots.adb @@ -1806,7 +1806,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; diff --git a/src/alire/alire-toolchains.ads b/src/alire/alire-toolchains.ads index d2848e071..1965f875c 100644 --- a/src/alire/alire-toolchains.ads +++ b/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 " diff --git a/src/alire/alire.adb b/src/alire/alire.adb index 42c814ae0..e31eddf05 100644 --- a/src/alire/alire.adb +++ b/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 diff --git a/src/alire/alire.ads b/src/alire/alire.ads index 26773475a..b68515c32 100644 --- a/src/alire/alire.ads +++ b/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 diff --git a/src/alr/alr-commands-build.adb b/src/alr/alr-commands-build.adb index e4327b58d..6c6e400d5 100644 --- a/src/alr/alr-commands-build.adb +++ b/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 ("*|%|=[,=...]")) + .Append (Formatter.Terminal (Switch_Profiles & "=" + & ("*|%|=[,=...]"))) .Append (" Apply profiles to individual crates.") - .Append (" Use " & TTY.Emph ("*=") & " to set all profiles.") - .Append (" Use " & TTY.Emph ("%=") & " to set profiles of " + .Append (" Use " & Formatter.Terminal ("*=") + & " to set all profiles.") + .Append (" Use " & Formatter.Terminal ("%=") + & " 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 = values (see description)"); + "Comma-separated list of " & Formatter.Terminal ("=") + & " values (see description)"); end Setup_Switches; diff --git a/src/alr/alr-commands-config.adb b/src/alr/alr-commands-config.adb index b990a089e..b1e1b1fba 100644 --- a/src/alr/alr-commands-config.adb +++ b/src/alr/alr-commands-config.adb @@ -202,7 +202,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, diff --git a/src/alr/alr-commands-dev.adb b/src/alr/alr-commands-dev.adb index 79d3ac5db..164eaa388 100644 --- a/src/alr/alr-commands-dev.adb +++ b/src/alr/alr-commands-dev.adb @@ -49,7 +49,7 @@ package body Alr.Commands.Dev is Last_Group := Group; end if; - Put_Line ("## `alr " & Cmd.Name & "`"); + Put_Line ("## " & Formatter.Terminal ("alr " & Cmd.Name)); New_Line; Sub_Cmd.Display_Help (Cmd.Name); diff --git a/src/alr/alr-commands-exec.adb b/src/alr/alr-commands-exec.adb index cf50a2bc2..a52374029 100644 --- a/src/alr/alr-commands-exec.adb +++ b/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 "" to the command switches"); + Help => "Add """ & Formatter.Terminal ("-P ") + & """ to the command switches"); end Setup_Switches; end Alr.Commands.Exec; diff --git a/src/alr/alr-commands-exec.ads b/src/alr/alr-commands-exec.ads index 9a91a99a1..ecfc78c5c 100644 --- a/src/alr/alr-commands-exec.ads +++ b/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 "" switch to the command arguments.") + .Append ("""" & Formatter.Terminal ("-P ") + & """ 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""]") ); diff --git a/src/alr/alr-commands-install.adb b/src/alr/alr-commands-install.adb index 3bcf17019..4712fdd62 100644 --- a/src/alr/alr-commands-install.adb +++ b/src/alr/alr-commands-install.adb @@ -103,8 +103,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 ("/bin") - & " folder to the user's path.") + & "normally by adding the " & Formatter.Terminal ("/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 " @@ -113,11 +113,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.") ); diff --git a/src/alr/alr-commands-pin.adb b/src/alr/alr-commands-pin.adb index ec1899266..f36b7303f 100644 --- a/src/alr/alr-commands-pin.adb +++ b/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 switch to" - & " use the target to fulfill a dependency locally" + .Append ("Use the " & Formatter.Terminal ("--use ") + & " 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.") ); diff --git a/src/alr/alr-commands-printenv.adb b/src/alr/alr-commands-printenv.adb index 2a765de1d..e5d13fe70 100644 --- a/src/alr/alr-commands-printenv.adb +++ b/src/alr/alr-commands-printenv.adb @@ -58,8 +58,8 @@ 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") + .Append (" * eval $(alr printenv --unix)") + .Append (" * alr printenv --powershell | Invoke-Expression") ); -------------------- diff --git a/src/alr/alr-commands-publish.ads b/src/alr/alr-commands-publish.ads index b56500ee3..f575f8b4c 100644 --- a/src/alr/alr-commands-publish.ads +++ b/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.")); diff --git a/src/alr/alr-commands-search.adb b/src/alr/alr-commands-search.adb index 4332cbb67..01198cfb4 100644 --- a/src/alr/alr-commands-search.adb +++ b/src/alr/alr-commands-search.adb @@ -284,21 +284,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 ='.") + .Append ("The reasons for unavailability (U) can be ascertained with:") + .New_Line + .Append (Formatter.Terminal ("alr show =")) .New_Line .Append ("Unresolvable releases (X) should not happen in platforms" & " with assigned maintainers. Common reasons are missing" @@ -328,7 +332,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, diff --git a/src/alr/alr-commands-show.adb b/src/alr/alr-commands-show.adb index 4730cd8a3..b8fb69113 100644 --- a/src/alr/alr-commands-show.adb +++ b/src/alr/alr-commands-show.adb @@ -346,19 +346,22 @@ package body Alr.Commands.Show is .Append ("Shows information found in the loaded indexes about a" & " specific release (see below to narrow the searched" & " milestones). By default, only direct dependencies are" - & " reported. With --solve, a full solution is resolved and" + & " reported. With " & Formatter.Terminal ("--solve") + & ", a full solution is resolved and" & " reported in list and graph form.") .New_Line - .Append ("With --external, the external definitions for a crate are" + .Append ("With " & Formatter.Terminal ("--external") + & ", the external definitions for a crate are" & " shown, instead of information about a particular release") .New_Line - .Append ("The --dependents switch accepts these values:") - .Append (" * " & TTY.Terminal ("direct") + .Append ("The " & Formatter.Terminal ("--dependents") + & " switch accepts these values:") + .Append (" * " & Formatter.Terminal ("direct") & " (default) shows direct dependents.") - .Append (" * " & TTY.Terminal ("all") + .Append (" * " & Formatter.Terminal ("all") & " shows all dependents, including indirect ones, " & "and all dependency chains.") - .Append (" * " & TTY.Terminal ("shortest") + .Append (" * " & Formatter.Terminal ("shortest") & " shows all dependents, including " & "indirect ones, but only once, and a shortest-length chain.") .New_Line @@ -378,7 +381,8 @@ package body Alr.Commands.Show is Define_Switch (Config, Cmd.Dependents'Access, "", "--dependents?", - "Show dependent crates (ARG=direct|shortest|all)", + "Show dependent crates (" + & Formatter.Terminal ("ARG=direct|shortest|all") & ")", Argument => "=ARG"); Define_Switch (Config, diff --git a/src/alr/alr-commands-test.adb b/src/alr/alr-commands-test.adb index cfe4c35dd..e78229ce1 100644 --- a/src/alr/alr-commands-test.adb +++ b/src/alr/alr-commands-test.adb @@ -590,13 +590,17 @@ package body Alr.Commands.Test is return AAA.Strings.Vector is (AAA.Strings.Empty_Vector .Append ("Tests the retrievability and buildability of all or" - & " specific releases. Unless --continue or --redo is given," + & " specific releases. Unless " + & Formatter.Terminal ("--continue") + & " or " & Formatter.Terminal ("--redo") & " is given," & " the command expects to be run in an empty folder.") .New_Line .Append ("After completion, a report in text, markup and junit format" & " will be available in the current directory. A complete log" & " of each release building process will be available in" - & " respective /alire/alr_test.log files.") + & " respective " + & Formatter.Terminal ("/alire/alr_test.log") + & " files.") .New_Line .Append (Crate_Version_Sets)); @@ -633,7 +637,8 @@ package body Alr.Commands.Test is (Config, Cmd.Redo'Access, Long_Switch => "--redo", - Help => "Retest releases already in folder (implies --continue)"); + Help => "Retest releases already in folder (implies " + & Formatter.Terminal ("--continue") & ")"); Define_Switch (Config, diff --git a/src/alr/alr-commands-toolchain.ads b/src/alr/alr-commands-toolchain.ads index 6967b80b7..98ca608d4 100644 --- a/src/alr/alr-commands-toolchain.ads +++ b/src/alr/alr-commands-toolchain.ads @@ -43,7 +43,7 @@ package Alr.Commands.Toolchain is & " optional version set to make available or remove a tool.") .New_Line .Append - ("Run `" & TTY.Terminal ("alr help toolchains") & "` for further " + ("Run " & Formatter.Terminal ("alr help toolchains") & " for further " & "information about toolchain management and use.") ); diff --git a/src/alr/alr-commands-topics-aliases.ads b/src/alr/alr-commands-topics-aliases.ads index a572b944f..fd0da6400 100644 --- a/src/alr/alr-commands-topics-aliases.ads +++ b/src/alr/alr-commands-topics-aliases.ads @@ -23,7 +23,7 @@ package Alr.Commands.Topics.Aliases is .Append ("For example the following command:") .Append ("""$ alr config --set --global alias.graph 'show --graph'""") .Append ("Defines a global alias for the 'show' command with a ") - .Append ("'--graph' switch.") + .Append ("'" & Formatter.Emph ("--graph") & "' switch.") .New_Line .Append ("""$ alr graph"" is equivalent to ""alr show --graph""")); diff --git a/src/alr/alr-commands-withing.adb b/src/alr/alr-commands-withing.adb index bce6f55f8..7dc2bc957 100644 --- a/src/alr/alr-commands-withing.adb +++ b/src/alr/alr-commands-withing.adb @@ -352,18 +352,22 @@ package body Alr.Commands.Withing is & " simultaneously added and removed in a single invocation.") .New_Line .Append ("* Adding dependencies pinned to external sources:") - .Append ("When a single crate name is accompanied by an --use PATH|URL" + .Append ("When a single crate name is accompanied by a " + & Formatter.Terminal ("--use PATH|URL") & " argument, the crate is always fulfilled for any required" & " version by the sources found at the given target." - & " 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" - & " tracking pin contents.") + & " specified with " & Formatter.Terminal ("--branch") + & ". Use '" & Formatter.Terminal ("alr update") + & "' to refresh the tracking pin contents.") .New_Line .Append ("* Adding dependencies from a GPR file:") - .Append ("The project file given with --from will be scanned looking" - & " for comments that contain the sequence 'alr with'. " + .Append ("The project file given with " & Formatter.Terminal ("--from") + & " will be scanned looking for comments that contain the" + & " sequence '" & Formatter.Terminal ("alr with") & "'. " & " These will be processed individually as if they had been" & " given in the command line, starting with no dependencies." & " That is, only dependencies given in the GPR file will be" @@ -371,7 +375,7 @@ package body Alr.Commands.Withing is .New_Line .Append ("Example of GPR file contents:") .New_Line - .Append ("with ""libhello""; -- alr with libhello") + .Append (Formatter.Terminal ("with ""libhello""; -- alr with libhello")) .New_Line .Append (Crate_Version_Sets)); diff --git a/src/alr/alr-commands.adb b/src/alr/alr-commands.adb index a65a04cd5..e6edb0110 100644 --- a/src/alr/alr-commands.adb +++ b/src/alr/alr-commands.adb @@ -534,10 +534,11 @@ package body Alr.Commands is .Append ("Version selection syntax (global policy applies " & "within the allowed version subsets):") .New_Line - .Append ("crate " & ASCII.HT & "Newest/oldest version") - .Append ("crate=version" & ASCII.HT & "Exact version") - .Append ("crate^version" & ASCII.HT & "Major-compatible version") - .Append ("crate~version" & ASCII.HT & "Minor-compatible version"); + -- Additional indentation will enable the preformat mode in markdown + .Append (" crate " & ASCII.HT & "Newest/oldest version") + .Append (" crate=version" & ASCII.HT & "Exact version") + .Append (" crate^version" & ASCII.HT & "Major-compatible version") + .Append (" crate~version" & ASCII.HT & "Minor-compatible version"); end Crate_Version_Sets; -------------- diff --git a/src/alr/alr-commands.ads b/src/alr/alr-commands.ads index e141d9426..603998399 100644 --- a/src/alr/alr-commands.ads +++ b/src/alr/alr-commands.ads @@ -148,7 +148,8 @@ private TTY_Description => CLIC.Formatter.Description, TTY_Version => CLIC.Formatter.Version, TTY_Underline => CLIC.Formatter.Underline, - TTY_Emph => CLIC.Formatter.Emph); + TTY_Emph => CLIC.Formatter.Emph, + TTY_Terminal => CLIC.Formatter.Terminal); Unset : constant String := "unset"; -- Canary for when a string switch is given without value diff --git a/src/alr/alr.ads b/src/alr/alr.ads index cf9c372c8..f36cafb3c 100644 --- a/src/alr/alr.ads +++ b/src/alr/alr.ads @@ -4,6 +4,7 @@ with Alire; with Simple_Logging; with CLIC.TTY; +with CLIC.Formatter; package Alr with Preelaborate is @@ -26,6 +27,7 @@ package Alr with Preelaborate is package Trace renames Simple_Logging; package TTY renames CLIC.TTY; + package Formatter renames CLIC.Formatter; function "+" (S : Alire.UString) return String renames Alire.UStrings.To_String; From 4f86e2383ad1f99796e097808c62d9b8b458874d Mon Sep 17 00:00:00 2001 From: mgrojo Date: Sat, 14 Oct 2023 19:56:45 +0200 Subject: [PATCH 3/6] Avoid indentation in lists to make it work with Jekyll --- src/alr/alr-commands-printenv.adb | 4 ++-- src/alr/alr-commands-show.adb | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/alr/alr-commands-printenv.adb b/src/alr/alr-commands-printenv.adb index 806afa974..0bf6e123a 100644 --- a/src/alr/alr-commands-printenv.adb +++ b/src/alr/alr-commands-printenv.adb @@ -66,8 +66,8 @@ 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") + .Append ("* eval $(alr printenv --unix)") + .Append ("* alr printenv --powershell | Invoke-Expression") ); -------------------- diff --git a/src/alr/alr-commands-show.adb b/src/alr/alr-commands-show.adb index 07d8c2634..aab7a0fee 100644 --- a/src/alr/alr-commands-show.adb +++ b/src/alr/alr-commands-show.adb @@ -362,12 +362,12 @@ package body Alr.Commands.Show is .New_Line .Append ("The " & Formatter.Terminal ("--dependents") & " switch accepts these values:") - .Append (" * " & Formatter.Terminal ("direct") + .Append ("* " & Formatter.Terminal ("direct") & " (default) shows direct dependents.") - .Append (" * " & Formatter.Terminal ("all") + .Append ("* " & Formatter.Terminal ("all") & " shows all dependents, including indirect ones, " & "and all dependency chains.") - .Append (" * " & Formatter.Terminal ("shortest") + .Append ("* " & Formatter.Terminal ("shortest") & " shows all dependents, including " & "indirect ones, but only once, and a shortest-length chain.") .New_Line From cbd419d8b27699c1e26313b9020ff34478052cb6 Mon Sep 17 00:00:00 2001 From: mgrojo Date: Sat, 14 Oct 2023 20:34:44 +0200 Subject: [PATCH 4/6] Fix `pandoc` output Add a new line before lists * It can be read better in the terminal * It make the list work with `pandoc` Add new CLIC commit also for `pandoc`. --- deps/clic | 2 +- src/alr/alr-commands-printenv.adb | 1 + src/alr/alr-commands-show.adb | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/deps/clic b/deps/clic index 2a5861dcd..56f505778 160000 --- a/deps/clic +++ b/deps/clic @@ -1 +1 @@ -Subproject commit 2a5861dcdba0d431b26283d487fa97584183ea21 +Subproject commit 56f5057781d5913eeab65c8d5811aa6b60477b1d diff --git a/src/alr/alr-commands-printenv.adb b/src/alr/alr-commands-printenv.adb index 0bf6e123a..644291e98 100644 --- a/src/alr/alr-commands-printenv.adb +++ b/src/alr/alr-commands-printenv.adb @@ -66,6 +66,7 @@ package body Alr.Commands.Printenv is " for instance before starting an IDE.") .New_Line .Append ("Examples:") + .New_Line .Append ("* eval $(alr printenv --unix)") .Append ("* alr printenv --powershell | Invoke-Expression") ); diff --git a/src/alr/alr-commands-show.adb b/src/alr/alr-commands-show.adb index aab7a0fee..cf8c7e195 100644 --- a/src/alr/alr-commands-show.adb +++ b/src/alr/alr-commands-show.adb @@ -362,6 +362,7 @@ package body Alr.Commands.Show is .New_Line .Append ("The " & Formatter.Terminal ("--dependents") & " switch accepts these values:") + .New_Line .Append ("* " & Formatter.Terminal ("direct") & " (default) shows direct dependents.") .Append ("* " & Formatter.Terminal ("all") From 2fc647cf8942549adf699a3d46d6d1f37a530c9b Mon Sep 17 00:00:00 2001 From: mgrojo Date: Sat, 14 Oct 2023 20:57:02 +0200 Subject: [PATCH 5/6] Add CLIC fix for lists of options --- deps/clic | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deps/clic b/deps/clic index 56f505778..65b825b10 160000 --- a/deps/clic +++ b/deps/clic @@ -1 +1 @@ -Subproject commit 56f5057781d5913eeab65c8d5811aa6b60477b1d +Subproject commit 65b825b10ebc80f3b49d8cba04c61cfe625808ac From dd60348d0c62a85781962508292c3f9a9963ef17 Mon Sep 17 00:00:00 2001 From: mgrojo Date: Sun, 15 Oct 2023 16:53:34 +0200 Subject: [PATCH 6/6] Fix test due to line of call Trace.Debug call being greater than 99 When the line has three digits, the space is not present. Example: [Alr.Commands.Dev.Execute] (alr-commands-dev.adb:32 ) debug: In dev --filter versus [Alr.Commands.Dev.Execute] (alr-commands-dev.adb:100) debug: In dev --filter --- testsuite/tests/debug/logging-scopes/test.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/testsuite/tests/debug/logging-scopes/test.py b/testsuite/tests/debug/logging-scopes/test.py index cbf7cbbc1..1cc3558a9 100644 --- a/testsuite/tests/debug/logging-scopes/test.py +++ b/testsuite/tests/debug/logging-scopes/test.py @@ -24,7 +24,7 @@ p = run_alr('-vv', '-d+dev', 'dev', '--filter', quiet=False) assert_match('Filtering mode: WHITELIST\n' 'Filtering substring: dev\n' - '\[Alr.Commands.Dev.Execute\] \(alr-commands-dev.adb:[0-9]* \)' + '\[Alr.Commands.Dev.Execute\] \(alr-commands-dev.adb:[0-9]* *\)' ' -->> In dev --filter', p.out.strip())