Sequence/Dynamic diagram - simplify to "one" Rel() call; add layout option SHOW_INDEX()

[kirchsth]

related to #307 (simple solution)

• Sequence diagrams

  • all custom index values and special relationships can be defined with one Rel(...,?index,?rel) call
    (no RelIndex() and RelSpecialIndex() are required anymore and are removed, details see below)
  • new SHOW_INDEX() layout macro

• Dynamic diagrams

  • all custom index values can be defined with via the Rel(...,?index) calls
    (no RelIndex...() calls are required anymore, based on the same pattern which is used by the sequence diagram)

• Update documentation (README.md and LayoutOptions.md)

It can be tested via my extended branch

BR Helmut

Dynamic sample with new (extended) Rel() calls, which replaces the old RelIndex() calls

@startuml
!include https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/C4_Dynamic.puml

AddRelTag("unchangedSyntax", $textColor=$ARROW_COLOR, $lineColor=$ARROW_COLOR)
AddRelTag("newSyntax", $textColor="green", $lineColor="green")
AddRelTag("obsoleteRelIndex", $textColor="red", $lineColor="red")

LAYOUT_TOP_DOWN()

Person(customer, Customer)
System_Boundary(c1, "Customer Information") {
    Container(app, "Customer Application", "Javascript, Angular")
    Container(customer_service, "Customer Service", "Java, Spring Boot")
    Container(message_bus, "Message Bus", "RabbitMQ")
    Container(reporting_service, "Reporting Service", "Ruby")
    Container(audit_service, "Audit Service", "C#/.NET")
    ContainerDb(customer_db, "Customer Database", "Oracle 12c")
    ContainerDb(reporting_db, "Reporting Database", "MySQL")
    Container(audit_store, "Audit Store", "Event Store")
}

' all without explicit index remain unchanged
Rel_D(customer, app, "Updates his profile using", "HTTPS", $tags="unchangedSyntax")
Rel(app, customer_service, "Updates customer information using", "JSON/HTTPS", "description", $tags="unchangedSyntax")
Rel_R(customer_service, customer_db, "Stores data in", "JDBC", $tags="unchangedSyntax")

' $index cab be first arg too (like the old RelIndex... calls), as long it is written with $index=.... 
Rel_D($index=Index(3)-1, customer_service, message_bus, "Sends customer update events to", "async", $tags="newSyntax")
Rel_U($index=LastIndex()-2, customer_service, app, "Confirm update to", "async", $tags="newSyntax")

' $index can be last if index has e.g. lower logic priority
Rel_L(message_bus, reporting_service, "Sends customer update events to", "async", $tags="newSyntax", $index=Index()-1)
Rel(reporting_service, reporting_db, "Stores data in", $tags="newSyntax", $index=Index()-1)

' Old RelIndex... calls which are obsolete in the meantime
RelIndex_R(SetIndex(5)-2, message_bus, audit_service, "Sends customer update events to", "async", $tags="obsoleteRelIndex")
RelIndex(Index()-2, audit_service, audit_store, "Stores events in", $tags="obsoleteRelIndex")

SHOW_LEGEND()
@enduml

Part of the updated documentation

(C4 styled) Sequence diagram specific layout options

• SHOW_ELEMENT_DESCRIPTIONS(?show): show or hide (hidden is default) all element/participant related descriptions
• SHOW_FOOT_BOXES(?show): show or hide (hidden is default) all element/participant related foot boxes
• SHOW_INDEX(?show): show or hide (hidden is default) the relationship (call) related index (sequence number)

show is defined with $show=true and hide is defined with $show=false

...

SHOW_INDEX(?show)

@startuml
!include https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/C4_Sequence.puml

SHOW_INDEX()

Person(admin, "Administrator")
System_Boundary(c1, 'Sample')
    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
' in a sequence diagram Boundary_End() has to be used instead of  { }
Boundary_End()
System(twitter, "Twitter")

Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml