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.