Macro sections

macro_rules! sections {
    () => { ... };
    ($($rest:tt)*) => { ... };
}

Macro to declare a list of help sections. This can be passed to Help to print it.

There are three kinds of sections:

1. Normal sections, wrapped in square brackets. Refer to the text macro for the syntax. Example:

   ["test" c:"cyan" R!"bold red"]

   Each section is terminated by a line break.

2. Named sections. Example:

   "USAGE" {
       ["section 1"]
       ["section 2"]
   }

   Named sections are always preceded by a blank line. Child sections are indented with 4 spaces.

3. Tables. Example:

   table Auto {
       "argument 1" => {
           ["help for argument 1"]
       }
       "argument 2" => {
           ["help for argument 2"]
           ["and some more help!"]
       }
   }

   With short help, this is rendered as

   argument 1   help for argument 1
   argument 2   help for argument 2
                and some more help!

   With long help, this is rendered as

   argument 1
           help for argument 1
   
   argument 2
           help for argument 2
           and some more help!

   The argument name (left column) must be a string literal. It is displayed in color.

   The table keyword must be followed by either Auto or Compact. If Compact is used, then the compact format is used for both the short and long help. If Auto is used, the compact format is used for short help and the longer format is used for long help.

Beyond that, each section can be preceded by Short or Long. By default, sections are included both in the long and short help. With the Short modifier, it is only shown in the short help, and sections preceded by Long only appear in the long help. Example:

sections!(
    Short ["Short help text"]
    Long ["This is more detailed help text"]
    ["This is shown either way"]

    table Auto {
        "argument 1" => {
            ["description"]
            Long ["Further details only shown in long help"]
        }
        "argument 2" => {
            Long ["This argument isn't shown in the short help"]
        }
    }

    // table only shown in long help:
    Long table Compact {}

    Long "MORE DETAILS" {
        ["named section only shown in long help"]
    }
);