Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for markdown output in help messages #1460

Closed
wants to merge 2 commits into from
Closed

Support for markdown output in help messages #1460

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6dd4546
Support for markdown output in help messages
mgrojo Sep 20, 2023
fb4c9d1
Fix pin for "Support for markdown output in help messages"
mgrojo Sep 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion alire.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ windows = { ALIRE_OS = "windows" }
[[pins]]
aaa = { url = "https://github.com/mosteo/aaa", commit = "ecc38772bd4a6b469b54c62363766ea1c0e9f912" }
ada_toml = { url = "https://github.com/mosteo/ada-toml", commit = "da4e59c382ceb0de6733d571ecbab7ea4919b33d" }
clic = { url = "https://github.com/alire-project/clic", commit = "6879b90876a1c918b4e112f59c6db0e25b713f52" }
clic = { url = "https://github.com/alire-project/clic", commit = "5c936c1e65ec4f6ba5428433a36d9cb3ee06764d" }
dirty_booleans = { url = "https://github.com/mosteo/dirty_booleans", branch = "main" }
diskflags = { url = "https://github.com/mosteo/diskflags", branch = "main" }
gnatcoll = { url = "https://github.com/alire-project/gnatcoll-core.git", commit = "4e663b87a028252e7e074f054f8f453661397166" }
Expand Down
2 changes: 1 addition & 1 deletion deps/clic
Open in desktop
Submodule clic updated 12 files
+5 −5 example/src/clic_ex-commands-subsub.adb
+17 −3 example/src/clic_ex-commands.adb
+6 −6 example/src/clic_ex-commands.ads
+1 −1 src/clic-config.ads
+44 −0 src/clic-formatter.adb
+22 −0 src/clic-formatter.ads
+19 −0 src/clic-markdown.adb
+12 −0 src/clic-markdown.ads
+1 −1 src/clic-subcommand-instance.adb
+4 −2 src/clic-subcommand-instance.ads
+1 −1 src/clic-subcommand.ads
+1 −1 src/clic-tty.ads
15 changes: 14 additions & 1 deletion src/alr/alr-commands.adb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,9 @@ package body Alr.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

Version_Only : aliased Boolean := False;
-- Just display the current version and exit

Expand Down Expand Up @@ -157,6 +160,12 @@ package body Alr.Commands is
Long_Switch => "--no-tty",
Help => "Disables control characters in output");

Define_Switch (Config,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea of a Markdown output for the help (see my comment on the implementation in CLIC).

I don't think this should be a global switch though, because it would mean all of the Alire output should be formatted in Markdown which doesn't make sens in my opinion.

Printing help in markdown format is not something users will do by themselves. It's more something that we want to do for the alire.ada.dev website. So for me this should be added to the alr dev command (https://github.com/alire-project/alire/blob/master/src/alr/alr-commands-dev.ads).

Something like

alr dev --help-doc-makrdown

That will print all the help pages for all the commands in markdown format.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with you, it doesn't make sense to combine this global switch with any other else command but help or the --help switches. I thought in using them together when generating the help pages for the website. If you use --markdown for anything else, it doesn't have any effect, which is the part where it makes no longer sense.

I wasn't aware of the dev subcommand. It makes much sense to add this functionality there, although I have doubts about generating the help pages at once, because that will avoid redirecting each page to a specific markdown file. I already have some code for the website that iterates through all the commands and topics, running alr --markdown ${topic} --help and also for alr --markdown help. I will look at how could this be done using alr dev and reach you again with the changes.

Markdown_Help'Access,
Long_Switch => "--markdown",
Help =>
"Enables output of markdown format for help");

Define_Switch (Config,
Prefer_Oldest'Access,
Long_Switch => "--prefer-oldest",
Expand Down Expand Up @@ -452,7 +461,11 @@ package body Alr.Commands is
end if;

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;

-- Use CLIC.TTY selection/detection of TTY
Expand Down
11 changes: 6 additions & 5 deletions src/alr/alr-commands.ads
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down
Loading