Merge pull request #55 from DrMarkusVoss/52-add-requirements-in-docs-as-code-format-with-traceability-to-architecture-elements

further example and small typo fixes.

Author: DrMarkusVoss

Examples_Reqs.md

@@ -2,8 +2,8 @@
 These are examples from the `./test/examples/WeatherStation` section. You find the
 source code of the .puml and .yaml files that form the example model repository
 there. In order to get the example running on your computer, you need
-to run first `pumla init`, then `pumla update`" in the examples directory, 
-because the paths in the model repo file (./test/examples/WeatherStation/reqsrepo_json.puml)
+to run first `pumla init`, then `pumla update` in the examples directory, 
+because the paths in the reqs repo file (./test/examples/WeatherStation/reqsrepo_json.puml)
 need to be updated to the directory structure on your computer. Currently
 the model repo file has the paths from the structure as I have it on my
 machine. You can't run the pumla update from the main path of pumla, as
@@ -12,7 +12,7 @@ The examples section will be ignored from the top level. So you have to go
 down to the examples and call the pumla update from that directory.
 
 If you are changing the contents of the examples to play around, in order for a
-change to become alive, you need to call `pumla update` again. cd 
+change to become alive, you need to call `pumla update` again. 
 
 ## E#0: Creating Re-usable Requirements
 Other than with architecture elements, in `pumla` you write the requirements in YAML and not
@@ -73,14 +73,25 @@ the trace between the requirements is exposed. All with just one `pumla` macro c
 
 ![](test/examples/WeatherStation/pics/exampleAllReqsBrief.png)
 ### E#1.3: Overview of all requirements (Cheat Sheet)
-See here, how with one `pumla` macro `PUMLAPutAllReqsTable()`  and overview table is put onto
+See here, how with one `pumla` macro `PUMLAPutAllReqsTable()`  an overview table is put onto
 the diagram, counting the requirements and showing in which files they are implemented.
 
 [./test/examples/WeatherStation/exampleReqCheatSheet.puml](test/examples/WeatherStation/exampleReqCheatSheet.puml)
 
 ![](test/examples/WeatherStation/pics/exampleReqCheatSheet.png)
 
-## E#2: Put single requirements onto a diagram
+### E#1.4: Overview of all requirements that have a dedicated status value
+See here, how with one `pumla` macro `PUMLAPutAllReqsWithStatusTable("decided")`  an overview table is put onto
+the diagram showing only requirements with the status "decided", counting the requirements and showing in which
+files they are implemented.
+
+[./test/examples/WeatherStation/exampleReqsWithStatusValue.puml](test/examples/WeatherStation/exampleReqsWithStatusValue.puml)
+
+![](test/examples/WeatherStation/pics/exampleReqsWithStatusValue.png)
+
+A similar macro exists to create an overview selecting wrt. the "type" attribute: `PUMLAPutAllReqsWithTypeTable($value)`.
+
+## E#2: Putting single requirements onto a diagram
 Here is an example where two requirements are put onto a diagram, one with a reduced subset of
 attributes. 
 

pumla_internal.puml

@@ -22,11 +22,11 @@ end note
 !end procedure
 
 !unquoted procedure PUMLAPutElementErrorCheck($suc, $elemalias)
-PUMLAErrorCheck($suc, $elemalias, "Could not put element with alias", "Element was not found in model repo.", "- try to update the model repo, or %newline()- check the alias for misspellings.")
+PUMLAErrorCheck($suc, $elemalias, "Could not put element with alias", "Element was not found in model/req repo.", "- try to update the model/req repo, or %newline()- check the alias for misspellings.")
 !end procedure
 
 !unquoted procedure PUMLACreateInstanceError($elemalias)
-PUMLAErrorCheck("0", $elemalias, "Could not create instance of element with alias", "The element that should be instantiated %newline()was not found in the model repo.", "- try to update the model repo, or %newline()- check the alias for misspellings.")
+PUMLAErrorCheck("0", $elemalias, "Could not create instance of element with alias", "The element that should be instantiated %newline()was not found in the model repo.", "- try to update the model/req repo, or %newline()- check the alias for misspellings.")
 !end procedure
 
 ' --------------------------------------------

pumla_macros_reqs.puml

@@ -1,4 +1,3 @@
-@startuml
 
 ' ############################################
 ' ---------------------------------------------
@@ -31,9 +30,6 @@
     !return $result
 !endfunction
 
-
-
-
 ' ############################################
 ' ---------------------------------------------
 ' introduce "newline" into a string in order to
@@ -284,7 +280,7 @@ note as allreqstable
 !if $r.status==$value
 !$cntstat=$cntstat+1
 | | | | | | |
-| $r.alias | $r.type | $r.content | $r.status | $r.derived_from | $r.derived_to | $r.in_file |
+| $r.alias | $r.type | _PUMLABreakLineSL($r.content) | $r.status | formatListSL($r.derived_from) | formatListSL($r.derived_to) | $r.in_file |
 !endif
 !endfor
 

test/examples/WeatherStation/exampleReqsWithStatusValue.puml

@@ -0,0 +1,11 @@
+@startuml
+!include reqsrepo_json.puml
+!include pumla_macros.puml
+
+top to bottom direction
+
+' put table overview with all reqs that
+' have a status that matches "decided"
+PUMLAPutAllReqsWithStatusTable("decided")
+
+@enduml

test/examples/WeatherStation/exampleSingleReqs.puml

@@ -6,7 +6,7 @@ top to bottom direction
 
 ' show how a requirement with with full
 ' description is put onto a diagram
-PUMLAPutReq(REQ_WS1)
+PUMLAPutReq(REQ_WS)
 
 ' show how a requirement with a brief
 ' description is put onto a diagram