Unclear documentation in Catalog Format Specification

[michael-hardeman]

I had some trouble understanding what tools I had at my disposal when writing my alire.toml. I think the documentation could be improved in the catalog-format-spec file. The issues I had were:

1. Within #Release-Information under specific properties there are various references to various "expressions", but we don't have a full specification of the various expression kinds. Here are some examples of those:
   • [available.'case(distribution)'] Dynamic Boolean expression
   • [depends-on] array of dynamic dependencies expressions
   • [project-files] expressions are accepted
2. What can be the variable in case expression?
   • I've seen os, distribution, word-size, toolchain all referenced. What else?
   • Can I define my own?
3. There also appears to be an Environment variable expansion system available.
   • I've seen ${CRATE_ROOT} and ${DISTRIB_ROOT}. Are there other environment variables exposed?
   • Can I define my own?
4. What are the purposes of the folders created by alire when you init a project (specifically I don't understand the share folder)

Suggestion:
Expressions seem like an extension of TOML? I don't see them referenced in the spec and so they need to be specified. Create a section for Expressions and the various kinds of them. Each time the text "Dynamic Boolean Expression" or "Dynamic Case Expression" appears it can simply link to the new section that fully describes the syntax of that construction.

[mosteo]

Hi @michael-hardeman, I think I answered some of your questions on Gitter, but not all of them. Of course it will be better to have all that clarified in the docs.

There are some of those that I think are already addressed: for example, case expressions are described in the Information Encoding section.

Likewise, accepted case arguments are in Parameters. Basically, you found them all.

Likewise, the only environment variables that are understood are the two you found. They're explicitly listed in the environment description, but they're somewhat buried there (as they're not understood anywhere else); probably this should be clarified too.

For most entries in the manifest described in that spec, it says/omits the "dynamic" moniker on purpose, but I'm sure we missed some, and as it's in plain language, it's not clear what is intended to be normative. I think we could clarify that by having a fixed structure like entry (static/dynamic, type): description.

Expressions are simply TOML tables, so not exactly a TOML extension. alr is the one that, when parsing the TOML tables, makes the interpretation as a dynamic construction.