Support for markdown output in help messages

[mgrojo]

Users of CLIC can use this functionality to provide on-line versions of the help messages.

[mgrojo]

This is the suggested improvement of the idea I already tried in alire-project/alire.ada.dev#23
This can be improved further, but I wanted first to receive feedback. One of my doubts is if API changes for CLIC will be accepted, provided that Alire is updated, or there are other users of the library, and it's better if the evolution is only through API extension.

I have the application to Alire also ready, but it is straightforward from the example. In any case, I will do an associated PR shortly.

I paste some examples of the output. It can be improved if more changes are made in how the help message is composed. I feel that the decoration of the message should be more semantic, so it could accommodate better Markdown and other future formats if needed (although markdown is already a good input format for many conversors).

[mgrojo]

clic_example 0.0.0

USAGE

clic_example [global options] [command options] []

clic_example help [|]

ARGUMENTS

<command> Command to execute
<arguments> List of arguments for the command

GLOBAL OPTIONS

-h (--help) Display general or command-specific help
-n (--non-interactive) Assume default answers for all user prompts
--no-color Disables colors in output
--no-tty Disables control characters in output
--markdown Enables output of markdown format for help

COMMANDS

help Shows help on the given command/topic
config List, Get, Set or Unset configuration options
tty Show tty colors
user_input Asks questions...
switches_and_args Print all the sub-command switches and args
double_dash Switch parsing before -- (double dash)
subsub Subcommands in a subcommand

TOPICS

topic_example Just an example of CLIC help topic

ALIASES

blink tty --blink
error_alias tty --test
alias_to_switch --plop

[mgrojo]

SUMMARY

List, Get, Set or Unset configuration options

USAGE

clic_example config [options] [--list] [--show-origin] [key_regex] | --get | --set | --unset

OPTIONS

--list List configuration options
--show-origin Show origin of configuration values in --list
--get Print value of a configuration option
--set Set a configuration option
--unset Unset a configuration option
--global Set and Unset global configuration instead of the local one
--builtins-doc Print Markdown list of built-in configuration options

GLOBAL OPTIONS

-h (--help) Display general or command-specific help
-n (--non-interactive) Assume default answers for all user prompts
--no-color Disables colors in output
--no-tty Disables control characters in output
--markdown Enables output of markdown format for help

DESCRIPTION

Provides a command line interface to the Alire configuration option files.

Option names (keys) can use lowercase and uppercase alphanumeric characters
from the Latin alphabet. Underscores and dashes can also be used except as
first or last character. Dot '.' is used to specify sub-categories, e.g.
'user.name' or 'user.email'.

Option values can be integers, float, Boolean (true or false) or strings. The
type detection is automatic, e.g. 10 is integer, 10.1 is float, true is
Boolean. You can force a value to be set a string by using double-quotes,
e.g.
"10.1" or "true". Extra type checking is used for built-in options (see
below).

Built-in configuration options:

[mgrojo]

SUMMARY

Print all the sub-command switches and args

USAGE

clic_example switches_and_args [options] [switches] [args]

GLOBAL OPTIONS

-h (--help) Display general or command-specific help
-n (--non-interactive) Assume default answers for all user prompts
--no-color Disables colors in output
--no-tty Disables control characters in output
--markdown Enables output of markdown format for help

DESCRIPTION

[mgrojo]

One difficult topic is alignment of the lists using AAA.Table_IO. Preserving the alighnment could only be done in markdown converting all the list to a code block, like the following, but then any other formatting inside the block is not interpreted. So I think the current approach is better.

In my opinion, the long option should also be wrapped with the TTY_Description, but currently it is not.

GLOBAL OPTIONS

-h (--help)             Display general or command-specific help
-n (--non-interactive)  Assume default answers for all user prompts
--no-color              Disables colors in output
--no-tty                Disables control characters in output
--markdown              Enables output of markdown format for help

[Fabien-Chouteau]

For me this is not the right way to add a Markdown output for the help pages. You may want to print the help in markdown without changing the formatting of the other outputs of your program.

Also it doesn't make much sens to outputting markdown for other parts of a command line program.

What I did for my [Man page POChttps://github.com//pull/12/files)) is to add a special Print_Man_Page to the CLIC.Subcommand.Instance package.

[Fabien-Chouteau]

But I like the idea of a Markdown output for the help :)

[mgrojo]

My rationale for doing it through the formatting parameters of CLIC.Subcommand.Instance is that all the logic already present in Display_Help can be reused. In fact, when looking at that generic parameters, I figured out that something like I'm doing was envisioned.

For example, the recent change about the global switches (a6bea52) would have to be applied in two places if there is a different help page generation for both formats like in #12. Isn't it better if there is a single place where the page is composed and the format can be parameterized?

You may want to print the help in markdown without changing the formatting of the other outputs of your program.

But the help printing is a single purpose command. When you print the help page, either for generating a markdown format or for directly reading, this will be the single action performed by the application, it doesn't make sense to generate any other output.

Where I agree undoubtedly is that, instead of a global switch (--markdown) to be combined with --help as I thought it, it should be a single switch for a specific subcommand. I was influence by how --no-tty and similar switches worked and implemented it similarly, but always thinking in this --markdown switch to be used along with --help or the help subcommand, not for any other program output.

[Fabien-Chouteau]

Isn't it better if there is a single place where the page is composed and the format can be parameterized?

This solution does work with TTY and Markdown, but it's not going to work for Man or HTML because of more complex output structures (lists in HTML for instance). So we will need another ad-hoc way to have those formats.

@mosteo up to you.

[mgrojo]

If Markdown works well, HTML is indeed the final output of the former.

But, in any case, if @mosteo thinks the same, I don't have any problem in changing it to the other approach.

[mosteo]

I think we should emit a single format that is suitable for conversion with e.g. pandoc rather than having multiple generators. If the logic can be reused for the single chosen format, I'd prefer that, but if as @Fabien-Chouteau says, there are structures that won't work, then that forces our hand to have a separate generator.

The way I'd go about it would be to use a sample complex page to check both issues: that it can be converted properly and whether the existent logic can be reused.

[mgrojo]

Superseded by #30