Support for markdown output in help messages

[mgrojo]

This functionality can be used to provide on-line versions of the help messages for alire.ada.dev.

It goes with alire-project/clic#29

[mgrojo]

See comments in alire-project/clic#29

I paste here some examples from Alire.

[mgrojo]

SUMMARY

Add or remove dependencies

USAGE

alr with [options] [{ [--del] [versions]... | --from <gpr_file>... | [versions] --use [--commit REF] [--branch NAME]} ] | --solve | --tree | --versions

OPTIONS

--del Remove given dependencies
--from Use dependencies declared within GPR project file
--graph Show ASCII graph of dependencies
--branch=NAME Branch to track in repository
--commit=REF Commit to retrieve from repository
--use=PATH|URL Add a dependency pinned to some external source
--solve Show complete solution to dependencies
--tree Show complete dependency tree
--versions Show version status of dependencies

GLOBAL OPTIONS

-c (--config=ARG) Override configuration folder location
-f (--force) Keep going after a recoverable troublesome situation
-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
--prefer-oldest Prefer oldest versions instead of newest when resolving dependencies
--version Displays version and exits
-q Limit output to errors
-v Be more verbose (use twice for extra detail)
-d (--debug[]) Enable debug-specific log messages

DESCRIPTION

Inspect and manage dependencies.

• Inspecting dependencies:
  Run without arguments prints current dependencies. Use --solve to print the
  solution in use for these dependencies.

• Adding dependencies from the command line:
  Dependencies are added by giving their name, and removed by using the --del
  flag. Dependencies cannot be simultaneously added and removed in a single
  invocation.

• Adding dependencies pinned to external sources:
  When a single crate name is accompanied by an --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; 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.

• Adding dependencies from a GPR file:
  The project file given with --from will be scanned looking for comments
  that contain the sequence '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 preserved.

Example of GPR file contents:

with "libhello"; -- alr with libhello

Version selection syntax (global policy applies within the allowed version
subsets):

crate Newest/oldest version
crate=version Exact version
crate^version Major-compatible version
crate~version Minor-compatible version

[mgrojo]

USAGE

alr help [|]

ARGUMENTS

<command> Command for which to show a description
<topic> Topic for which to show a description

GLOBAL OPTIONS

-c (--config=ARG) Override configuration folder location
-f (--force) Keep going after a recoverable troublesome situation
-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
--prefer-oldest Prefer oldest versions instead of newest when resolving dependencies
--version Displays version and exits
-q Limit output to errors
-v Be more verbose (use twice for extra detail)
-d (--debug[]) Enable debug-specific log messages

COMMANDS

General
help Shows help on the given command/topic
config List, Get, Set or Unset configuration options
install Manage installation prefixes
toolchain Manage Alire-provided toolchains
version Show detailed version, configuration, and environment information

Index
get Fetch a published crate
index Manage indexes used by current configuration
search Search for a string in names and properties of crates
show Display information about a crate version

Crate
build Build the library or executables of the crate
clean Clean generated files or downloaded dependencies
edit Start GNAT Studio with Alire build environment setup
exec Run the given command in the alire project context
init Create a new crate for an executable or library
pin Pin dependencies to exact versions
printenv Print the build environment variables
run Launch an executable built by the crate
update Update some or all dependencies to a newer version
with Add or remove dependencies

Testing
action List or manually trigger action hooks
dev Developer helpers
test Test the compilation of all or some releases

Publish
publish Help publishing a new version of a crate

TOPICS

aliases User defined command aliases
identifiers Naming rules for crate and index names
toolchains Configuration and use of toolchains

ALIASES

gnatcov exec -P2 -- gnatcov
gnatprove exec -P1 -- gnatprove

[mgrojo]

SUMMARY

Build the library or executables of the crate

USAGE

alr build [options] [--] [gprbuild switches and arguments]

OPTIONS

--release Set root build profile to Release
--validation Set root build profile to Validation
--development Set root build profile to Development (default)
--profiles=ARG Comma-separated list of = values (see description)

GLOBAL OPTIONS

-c (--config=ARG) Override configuration folder location
-f (--force) Keep going after a recoverable troublesome situation
-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
--prefer-oldest Prefer oldest versions instead of newest when resolving dependencies
--version Displays version and exits
-q Limit output to errors
-v Be more verbose (use twice for extra detail)
-d (--debug[]) Enable debug-specific log messages

DESCRIPTION

Invokes gprbuild to compile all targets in the current crate.

A build profile can be selected with the appropriate switch. The profile is
applied to the root release only, whereas dependencies are built in release
mode. Use --profiles for more overrides.

--profiles=*|%|<crate1>=<profile>[,<crate2>=<profile>...]
Apply profiles to individual crates.
Use *= to set all profiles.
Use %= to set profiles of crates without a setting in a manifest
only.

Running 'alr build' without profile switches defaults to development (root
crate) + release (dependencies). Indirect builds through, e.g., 'alr run'
will use the last 'alr build' configuration.

[Fabien-Chouteau]

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.

[mgrojo]

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.

[mgrojo]

Superseded by #1464