The new diagram format to describe CMD parameters is activated by
```
@startcmd
: :
@endcmd
```
You might discuss and improve the initial idea or explain, why such does not make sense;-)
Command
Each **command** name is naturally typed.
To define a command, you start with the new keyword 'cmd'.
If a cmd name contains special characters like "-",
find a unique PlantUML name and explain the shown value in "cmd-name".
In CMD-Diagrams the cmd is represented
in a rounded-corner box with white background.
```
cmd cname
cmd cmdname "cmd-name"
```
Each **subcommand** name is naturally typed.
To define a subcommand you start with the keyword 'sub'.
If a sub name contains special characters like "-",
find a unique PlantUML name and explain the shown value in "sub-name".
In CMD-Diagrams the sub is represented
in a rounded-corner box with white background.
```
sub sname
sub subname "sub-name"
```
Using them in a CMD-Diagram can place them in a single line
or in a new line to enable descriptions by PlantUML notes on the right side.
At each cmd name a new tree is started in the diagram, they are left aligned
on the page to provide space for notes on the right side.
```
cname -> sname
cmdname --> subname
```
For **notes** in CMD Diagrams, the rest of the line is used
to place the descriptions and the next object in the relationship is moved,
if the text needs more lines.
If the nextobj(s) is(are) in the same line (by ->), the comment is placed
in the nextline starting under nextobj, to allow further objects in
further lines to be placed.
The CMD-Diagram can be used with [no-notes] option
to not show descriptions or with [notes] to easily switch both versions
of more or less described CMD-Diagrams.
```
@startcmd [no-notes]
: :
cname --> nextobj
note descriptions
cmdname --> nextobj
note descriptions
more descriptions
end note
@endcmd
```
It would be nice to give notes overall in PlantUML a level for output: note[n],
where "[n]" is an option and Standard is '0' for always or '1', ... , '9'.
And you can control which levels are shown in a diagram, by naming the levels in
the diagram: [notes 1,2] to show level 0-2 or [no-notes 0,2-9] to show level 1.
By such you can handle different Informations Set's in one diagram description.
**Optional values** are included in brackets: "[optional]".
To define an option you start with the keyword 'opt'.
Each option set needs a unique PlantUML name.
Alternative options are separated by "|".
A single option is representated
in a rounded corner box with lightorange background.
```
opt onam1 "opt1"
opt onam2 "opt2"
opt onams "opt1 | opt2"
```
Using them in a CMD-Diagram can define each single option
or a set of options to enable comments for each or both on the right side.
Options are included by PlantUML function 'opt()'.
Inside a CMD-Diagram the results are equivalent:
```
opt(oname1 | oname2)
opt(onams)
```
**Variable** place holders are included in brackets: "<variable>".
To define a Variable you start with the keyword 'var'.
Each variable needs a unique PlantUML name.
A single variable is representated
in a rounded corner box with lightgreen background to make aware, it is needed.
**Repeated** variables or values are described by three dots "..." or "…"
and they are added by the option [dots] or by loop(var).
```
var vname1 "<var1>"
var vname2 "<var2>"
```
Inside a CMD-Diagram the results are equivalent, but a Loop can be visualized by an arrow, if the loop content is put into a separated box:
```
vname1 [dots]
loop(<vname1>)
```
**Alternatives** are described by round brackets: "(val | <var>)",
where variables or alernative values can be combined inside, separated by "|".
To define an alternative value you start with the keyword 'alt'.
Each alternative value needs a unique PlantUML name.
A single alternatives is representated
in a rounded corner box with lightblue background to make aware, it is special.
A set of alternatives are included by PlantUML function 'alt()'.
```
alt anam "val"
var vnam "<var>"
```
Inside a CMD-Diagram the results are equivalent:
```
(anam | vnam)
alt(anam | vnam)
```
Define a representation for each cmd, subcmd, opt, var , alt.
For opt, var and alt allow to enter a short description of the object.
As if you would describe the field in a GUI to enter data and having a field name and a short description you use to visualize related to the field.
```
opt onam : oshort
var vnam : vshort
alt anam : ashort
```
Define relationships between those objects defined.
Each definition gets a name and a text, shown in the diagram.
If the text is the same, it can be ommitted.
The short description is represented as a text shown on top of the representation box (":") or like a note (note [0]) related to the name (::), which might be nice to read through the **human readable** command definitionen in one column on the right having other extra notes added with an indent.
```
<def> name1 "text1" : short1
<def> name2 "text2" :: short2
```
If you want to explain an object by notes, you need to leave
some space on the right and place further attributes into a new
line by "-->" or two new lines "--->" otherwise just have the
relations on a single line "->" and the note is following
in cascaded style below the next object.
To use a standard value of an attribute of a command parameter is wide spread.
It can be defined as
- the standard parameter (show it as the first value out of alternatives)
- by omitting the alternatives (sometimes even not defining a standard value)
To desribe omitted standard values, where no parameter is defined at all,
it is a good idea to show the non existing standard as a "hidden" attribute
to better explain the behaviour of a command.
We describe this value as [undefined] and show it in light grey box with med grey font colour if it is a single value shown or as a med grey font colour, if it is inside a set of alternatives or options.
As an example: Git Remote with it's options.
The result might show up similar to this diagram but with lot less off efforts, less gaps and perfect addition of notes.
With some minor transformation it's possible to generate many of them out of code definitions automatically.
I made no decision about the representation of the end, like in BNF.
With PlantUML the arrow might contain a hint for the finalization at some point: --| .
p.s. how can I provide an example (svg, plantuml)?
