I would like to suggest a new style for CMD parameter visualisation.

0 votes
asked Apr 15, 2021 in Wanted features by SieDa
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)?
commented Apr 15, 2021 by SieDa

Coding Example:

@CMD
cmd git

sub remote
opt verbose "[-v|--verbose]" :: Verbose

sub show
opt n "[-n]"
var name "<name>"

sub update
opt prune "[-p | --prune]"
var group "<group>"
var remote "<remote>"

    git --> remote
    remote --> verbose
    verbose --> show
        show --> n
        n --> name [dots]

    verbose --> update
        update --> prune
        prune --> opt(alt(group | remote) [dots])

sub add
opt target "[-t <branch>]"
opt master "[-m <master>]"
opt f "[-f]"
opt tags "[--[no-]tags]"
opt mirror "[--mirror=(fetch|push)]"
var addname "<name>"
var addurl "<url>"

    git --> add
    add --> target
        target --> master
        master --> f
        f --> tags
        tags --> mirror
        mirror --> addname
        addname --> addurl

sub rename
var oldname "<old>"
var newname "<new>"

    git --> rename
    rename -> old
        old -> new

sub remove
var name "<name>"

    git --> remove
    remove -> name

sub sethead "set-head"
var setname "<name>"
alt auto "-a | --auto"
alt delete "-d | --delete"
var branch "<branch>"

    git --> sethead
    sethead --> setname
        setname --> alt(auto | delete | branch)

sub setbranches "set-branches"
opt add "[--add]"
var setbrname "<name>"
var branch "<branch>"…​

    git --> setbranches
    gitsetbranches --> add
        add --> setbrname
        setbrname --> branch [dots]

sub geturl "get-url"
opt fetch "[--fetch]" [undefined]
note Fetch URLs are queried as a standard.

opt push "[--push]"
note Push URLs are queried rather than fetch URLs

opt all "[--all]"
note All URLs for the remote will be listed

opt geturlopts opt(fetch | push | all)
var remotename "<name>" :: Remote name
note The remote name is needed for the query of URLs.

    git --> geturl
    note Retrieves the URLs for a remote.

    geturl --> geturlopts
    geturlopts--> remotename

sub seturl "set-url"
var change "--change" [undefined]
var add "--add"
var delete "--delete"
opt chgpush "[--push]"
opt addpush "[--push]"
opt delpush "[--push]"

var chgname "<name>"
var addname "<name>"
var delname "<name>"
var chgurl "<newurl>"
var addurl "<newurl>"
var delurl "<url>"
opt oldurl "[<oldurl>]"

    git --> seturl
    seturl --> change
    seturl --> add
    seturl --> delete

        change --> chgpush
        chgpush --> chgname
        chgname  --> chgurl
        chgurl --> oldurl

        add --> addpush
        addpush --> addname
        addname  --> addurl

        delete --> delpush
        delpush --> delname
        delname  --> delurl

sub prune
opt ndry "[-n | --dry-run]"
var prunename "<name>" [dots]

    git --> prune
    prune --> ndry
        ndry --> prunename
@endcmd

commented Apr 17, 2021 by Martin (8,360 points)

I notice that "remote" is both a "sub" and a "var"; would that not be ambiguous?
In your description you said "The result might show up similar to this diagram but with lot less off efforts".  But I don't see any diagram - was there supposed to be one linked or pictured?  The suggestion does suffer from lack of example target picture, however rough/approximate.

commented Apr 17, 2021 by SieDa
edited Apr 17, 2021

Good Point. How to resolve naming conflicts between different objects needs to be discussed, if that is an issue internally - generating it, might lead to a generic approach:

sub subrmt "remote"
var varrmt "remote"

I did not chekc the code for validity yet blush, just quickly written to check, if it makes sense for others as well.

commented Apr 17, 2021 by SieDa
edited Apr 17, 2021
commented Apr 20, 2021 by Martin (8,360 points)
edited Apr 20, 2021 by Martin

Thank you; it is a lot clearer to me now.  

In some ways it is just a different style of mindmap diagram (crossed with wbs) - perhaps if Plantuml just provided some extra styling features for mindmap (orthogonal arrows, child nodes never above parent, box width multiple of unit width, force cascade if double indent, support comment notes, etc) you would have the tools to create the diagram you want, and more concisely.  (Plantuml might be more amenable to extending an existing diagram type, than creating a new one - I speculate).

(Note, I'm not a Plantuml developer, just an interested bystander.  I have no idea whether this is a diagram type that the Plantuml team would be interested in coding or not.)

Your answer

Your name to display (optional):
Privacy: Your email address will only be used for sending these notifications.
Anti-spam verification:

[Antispam2 Feature: please please wait 1 or 2 minutes (this message will disappear) before pressing the button otherwise it will fail](--------)
To avoid this verification in future, please log in or register.
...