Skip to content

Commit 58f4258

Browse files
bjornregnellbjornregnell
committed
generate quickref, shorten some concept descriptions
1 parent 687965a commit 58f4258

File tree

5 files changed

+150
-26
lines changed

5 files changed

+150
-26
lines changed

‎docs/concepts-GENERATED.csv

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,16 @@ Example Attr StrAttr A description that illustrates some entity by a typical ins
2222
Expectation Attr StrAttr A required output of a test in order to be counted as passed.
2323
Failure Attr StrAttr A description of a runtime error that prevents the normal execution of a system.
2424
Feature EntType GeneralEnt A releasable characteristic of a product. A high-level, coherent bundle of requirements.
25-
Field EntType DataEnt A data attribute that is part of another entity, such as a class
25+
Field EntType DataEnt A data attribute that is part of another entity, such as a class.
2626
Frequency Attr IntAttr A number of occurrences per time unit.
2727
Function EntType FunctionalEnt A description of how input is mapped to output. A capability of a system to do something specific.
2828
Gist Attr StrAttr A short and simple description. A summary capturing the essence of an entity.
2929
Goal EntType GeneralEnt An intention of a stakeholder or desired system property.
30-
Idea EntType GeneralEnt A concept or thought (potentially interesting).
30+
Idea EntType GeneralEnt A concept or thought, potentially interesting.
3131
Image EntType GeneralEnt A visual representation, picture or diagram.
3232
Input Attr StrAttr Data consumed by an entity,
33-
Interface EntType GeneralEnt A defined way to interact with a system.
34-
Issue EntType GeneralEnt Something needed to be fixed or work to do.
33+
Interface EntType GeneralEnt A way to interact with a system.
34+
Issue EntType GeneralEnt Something to be fixed or work to do.
3535
Item EntType GeneralEnt An article in a collection, enumeration, or series.
3636
Label EntType GeneralEnt A descriptive tag used to classify something.
3737
Location Attr StrAttr A location of a resource such as a web address or a path to a file of persistent data.
@@ -40,7 +40,7 @@ Member EntType DataEnt A data entity that is part of another entity. More specif
4040
Min Attr IntAttr A minimum estimated or assigned value.
4141
Model Model General A collection of model elements, which can be entities, attributes or relations.
4242
Module EntType DesignEnt A collection of coherent functions and interfaces.
43-
Order Attr IntAttr An ordinal number of an entity (1st, 2nd, ...).
43+
Order Attr IntAttr An ordinal number (1st, 2nd, ...).
4444
Output Attr StrAttr Data produced by an entity, e.g. a function or a test.
4545
Prio Attr IntAttr A level of importance of an entity. Short for priority.
4646
Probability Attr IntAttr A likelihood expressed as whole percentages that something (e.g. a risk) occurs.
@@ -67,7 +67,7 @@ Task EntType FunctionalEnt A piece of work by users, potentially supported by a
6767
Term EntType GeneralEnt A word or group of words having a particular meaning in a particular domain.
6868
Test EntType GeneralEnt A procedure to check if requirements are met.
6969
Text Attr StrAttr An paragraph or general description.
70-
Title Attr StrAttr A general or descriptive heading. One or more leading # indicate heading level.
70+
Title Attr StrAttr A general or descriptive heading.
7171
UseCase EntType FunctionalEnt A goal-fulfilling interaction between users and a product in a specific usage context.
7272
User EntType ContextEnt A human interacting with a system.
7373
Value Attr IntAttr Some general integer value.

‎reqT-quickref.pdf

26.3 KB
Binary file not shown.

‎src/main/scala/02-meta-model.scala

Lines changed: 116 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ object meta:
66
trait ConceptGroup
77

88
enum EntGroup extends ConceptGroup:
9-
case ContextEnt, GeneralEnt, DataEnt, FunctionalEnt, QualityEnt, DesignEnt, VariabilityEnt
9+
case GeneralEnt, ContextEnt, DataEnt, FunctionalEnt, QualityEnt, DesignEnt, VariabilityEnt
1010
import EntGroup.*
1111

1212
enum RelGroup extends ConceptGroup:
@@ -31,10 +31,10 @@ object meta:
3131
// https://www.atlassian.com/agile/project-management/epics-stories-themes
3232
GeneralEnt -> "Feature" -> "A releasable characteristic of a product. A high-level, coherent bundle of requirements.",
3333
GeneralEnt -> "Goal" -> "An intention of a stakeholder or desired system property.",
34-
GeneralEnt -> "Idea" -> "A concept or thought (potentially interesting).",
34+
GeneralEnt -> "Idea" -> "A concept or thought, potentially interesting.",
3535
GeneralEnt -> "Image" -> "A visual representation, picture or diagram.",
36-
GeneralEnt -> "Interface" -> "A defined way to interact with a system.",
37-
GeneralEnt -> "Issue" -> "Something needed to be fixed or work to do.",
36+
GeneralEnt -> "Interface" -> "A way to interact with a system.",
37+
GeneralEnt -> "Issue" -> "Something to be fixed or work to do.",
3838
GeneralEnt -> "Item" -> "An article in a collection, enumeration, or series.",
3939
GeneralEnt -> "Label" -> "A descriptive tag used to classify something.",
4040
GeneralEnt -> "Req" -> "Something needed or wanted. An abstract term denoting any type of information relevant to the (specification of) intentions behind system development. Short for requirement.",
@@ -46,7 +46,7 @@ object meta:
4646

4747
DataEnt -> "Data" -> "A data entity, type, class, or record stored or processed by a system.", // or Data or DataEntity or DataType?
4848
DataEnt -> "Class" -> "An extensible template for creating objects. A set of objects with certain attributes in common. A category.", // somewhat redundant with Data but the latter is more general
49-
DataEnt -> "Field" -> "A data attribute that is part of another entity, such as a class", // or DataField or DataAttribute or DataProperty
49+
DataEnt -> "Field" -> "A data attribute that is part of another entity, such as a class.", // or DataField or DataAttribute or DataProperty
5050
DataEnt -> "Member" -> "A data entity that is part of another entity. More specific alternatives: field, function.", // or DataField or DataAttribute or DataProperty
5151
DataEnt -> "Relationship" -> "A specific way that data types are connected.", // or Association or Relation or DataRelation
5252

@@ -76,6 +76,10 @@ object meta:
7676

7777
val entityConcepts: ArraySeq[(String,String)] = entityConceptGroups.map((gn, d) => gn._2 -> d).sorted
7878

79+
val entTypeGroupMap: Map[EntType, EntGroup] = entityConceptGroups.map((gn, d) => EntType.valueOf(gn._2) -> gn._1).toMap
80+
81+
val entGroupTypesMap: Map[EntGroup, Set[EntType]] = entTypeGroupMap.toSeq.groupBy(_._2).map((x, xs) => x -> xs.map(_._1).toSet)
82+
7983
val strAttrConcepts = ArraySeq[(String,String)](
8084
"Comment" -> "A note with a remark or a discussion on an entity.",
8185
"Constraints" -> "A collection of propositions that constrain a solution space or restrict possible attribute values.",
@@ -84,7 +88,7 @@ object meta:
8488
"Expectation" -> "A required output of a test in order to be counted as passed.",
8589
"Failure" -> "A description of a runtime error that prevents the normal execution of a system.",
8690
"Gist" -> "A short and simple description. A summary capturing the essence of an entity.",
87-
"Title" -> "A general or descriptive heading. One or more leading # indicate heading level.",
91+
"Title" -> "A general or descriptive heading.",
8892
"Input" -> "Data consumed by an entity, ",
8993
"Location" -> "A location of a resource such as a web address or a path to a file of persistent data.",
9094
"Output" -> "Data produced by an entity, e.g. a function or a test.",
@@ -101,7 +105,7 @@ object meta:
101105
"Frequency" -> "A number of occurrences per time unit. ",
102106
"Max" -> "A maximum estimated or assigned value.",
103107
"Min" -> "A minimum estimated or assigned value.",
104-
"Order" -> "An ordinal number of an entity (1st, 2nd, ...).",
108+
"Order" -> "An ordinal number (1st, 2nd, ...).",
105109
"Prio" -> "A level of importance of an entity. Short for priority.",
106110
"Probability" -> "A likelihood expressed as whole percentages that something (e.g. a risk) occurs.",
107111
"Profit" -> "A gain or return of some entity, e.g. in monetary terms.",
@@ -329,6 +333,7 @@ object meta:
329333
|
330334
|extension (e: Ent)
331335
|""".stripMargin ++ relationNames.map(entExtensions).mkString("","\n", "").stripMargin
336+
end generate
332337

333338
def graph(showElem: Boolean = true, showElemType: Boolean = true): String =
334339
import GraphVizGen.*
@@ -385,4 +390,107 @@ object meta:
385390
recordNode(entType, fontSize = 9) ("enum " + entType, entTypeValues),
386391
recordNode(strAttrType, fontSize = 9) ("enum " + strAttrType, strAttrTypeValues),
387392
recordNode(intAttrType, fontSize = 9) ("enum " + intAttrType, intAttrTypeValues),
388-
) else Seq()))
393+
) else Seq()))
394+
395+
end graph
396+
397+
object QuickRef:
398+
val ending = "\\end{multicols*}\n\\end{document}"
399+
400+
val preamble =
401+
s"""|%!TEX encoding = UTF-8 Unicode
402+
|\\documentclass[a4paper,oneside]{article}
403+
|
404+
|\\usepackage[top=18mm,bottom=3mm, hmargin=10mm,landscape]{geometry}
405+
|
406+
|\\usepackage[utf8]{inputenc}
407+
|\\usepackage[T1]{fontenc}
408+
|
409+
|\\usepackage{tgtermes}
410+
|\\usepackage{lmodern}
411+
|\\usepackage[scaled=0.9]{beramono} % inconsolata or beramono ???
412+
|\\usepackage{microtype} % Slightly tweak font spacing for aesthetics
413+
|
414+
|\\usepackage{fancyhdr}
415+
|\\pagestyle{fancy}
416+
|\\chead{\\url{http://github.com/reqT/reqT-lang/docs/reqT-quickref.pdf}}
417+
|\\lhead{The reqT QuickRef}
418+
|\\rhead{Compiled \\today}
419+
|
420+
|\\usepackage{hyperref}
421+
|\\hypersetup{colorlinks=true, linkcolor=blue, urlcolor=blue}
422+
|\\usepackage[usenames,dvipsnames,svgnames,table]{xcolor}
423+
|${LatexGen.defineColors}
424+
|\\usepackage{listings}
425+
|${LatexGen.lstDefineStyle}
426+
|\\lstset{style=reqT}
427+
|\\usepackage{multicol}
428+
|
429+
|\\setlength\\parindent{0em}
430+
|\\setlength\\headsep{1em}
431+
|\\setlength\\footskip{0em}
432+
|\\usepackage{titlesec}
433+
| \\titlespacing{\\section}{0pt}{3pt}{2pt}
434+
| \\titlespacing{\\subsection}{0pt}{3pt}{2pt}
435+
| \\titlespacing{\\subsubsection}{0pt}{3pt}{2pt}
436+
|
437+
|\\usepackage{graphicx}
438+
|
439+
|\\pagenumbering{gobble}
440+
|
441+
|\\renewcommand{\\rmdefault}{\\sfdefault}
442+
|
443+
|\\begin{document}
444+
|""".stripMargin
445+
446+
def conceptDef(concept: String, definition: String): String =
447+
s"\\hangindent=1em\\lstinline+$concept+ $definition \n"
448+
449+
val body =
450+
s"""|
451+
|\\fontsize{9.1}{11}\\selectfont
452+
|
453+
|\\begin{multicols*}{4}
454+
|
455+
|\\section*{The reqT meta-model}
456+
|\\raggedright
457+
|A model is a sequence of elements. An element can be a node or a relation. A node can be an entity or an attribute. An entity has a type and an id. An attribute has a type and a value and it can be a string attribute or an integer attribute. A relation connects an entity to a sub-model via a relation type.
458+
|
459+
|\\noindent\\hspace*{-2.1em}\\includegraphics[width=8.2cm]{metamodel-Elem-GENERATED.pdf}
460+
|
461+
|\\section*{\\texttt{enum EntType}}
462+
|${
463+
val subsections = for eg <- EntGroup.values yield
464+
val head = s"\\subsection*{\\texttt{EntGroup.$eg}}"
465+
val es = entGroupTypesMap(eg).toSeq.map(_.toString).sorted
466+
val xs = es.map(e => conceptDef(e, conceptMap(e).descr))
467+
head + xs.mkString("\n", "\n", "\n")
468+
subsections.mkString("\n")
469+
}
470+
|
471+
|\\section*{\\texttt{enum relType}}
472+
|${
473+
val xs = for (s, c) <- relTypes yield
474+
conceptDef(s, conceptMap(s).descr)
475+
xs.mkString("\n")
476+
}
477+
|
478+
|\\section*{\\texttt{enum StrAttrType}}
479+
|${
480+
val xs = for (s, c) <- strAttrConcepts yield
481+
conceptDef(s, conceptMap(s).descr)
482+
xs.mkString("\n")
483+
}
484+
|
485+
|\\section*{\\texttt{enum IntAttrType}}
486+
|${
487+
val xs = for (s, c) <- intAttrConcepts yield
488+
conceptDef(s, conceptMap(s).descr)
489+
xs.mkString("\n")
490+
}
491+
|
492+
|""".stripMargin
493+
494+
val toLatex = preamble + body + ending
495+
496+

‎src/main/scala/05-LatexGen.scala

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,11 @@ package reqt
22

33
object LatexGen:
44
def defineColors: String =
5-
s"""|%\\usepackage[usenames,dvipsnames,svgnames,table]{xcolor}
6-
|\\definecolor{entityColor}{RGB}{0,100,200}
5+
s"""|\\definecolor{entityColor}{RGB}{0,100,200}
76
|\\definecolor{attributeColor}{RGB}{0,100,50}
87
|\\definecolor{relationColor}{RGB}{160,0,30}
98
|""".stripMargin
10-
9+
1110
def lstDefineStyle: String =
1211
s"""|\\lstdefinestyle{reqT}{
1312
| %belowcaptionskip=1\\baselineskip,
@@ -23,4 +22,4 @@ object LatexGen:
2322
| emph={[3]${meta.attributeNames.mkString{","}}},
2423
| emphstyle={[3]\\bfseries\\color{attributeColor}},
2524
|}
26-
|""".stripMargin
25+
|""".stripMargin

‎src/test/scala/generateLang.scala

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,12 @@ extension (s: String)
66
try pw.write(s) finally pw.close()
77

88
val modelFile = "src/main/scala/03-model-GENERATED.scala"
9-
val docsDir = "docs"
9+
val docsDir = "docs/"
10+
val targetDir = "target/"
1011
val langSpecFile = docsDir + "/langSpec-GENERATED.md"
1112
val conceptFile = docsDir + "/concepts-GENERATED.csv"
12-
def graphFile(mod: String) = docsDir + s"/metamodel$mod-GENERATED.dot"
13+
def graphFile(mod: String) = s"metamodel$mod-GENERATED.dot"
14+
val quickRefFile ="reqT-quickref.tex"
1315

1416
@main def generateLang =
1517
println(s"Generating $modelFile")
@@ -23,11 +25,26 @@ def graphFile(mod: String) = docsDir + s"/metamodel$mod-GENERATED.dot"
2325
println(s"Generating $conceptFile")
2426
meta.csv("\t").saveTo(conceptFile)
2527

28+
val gfs = IArray("-Model", "-Elem", "-ElemType", "-All").map(graphFile)
2629
println(s"Generating graph files: metamodel-*-GENERATED.dot")
27-
meta.graph(showElem=false, showElemType=false).saveTo(graphFile("-Model"))
28-
meta.graph(showElem=true, showElemType=false).saveTo(graphFile("-Elem"))
29-
meta.graph(showElem=false, showElemType=true).saveTo(graphFile("-ElemType"))
30-
meta.graph(showElem=true, showElemType=true).saveTo(graphFile("-All"))
30+
meta.graph(showElem=false, showElemType=false).saveTo(docsDir + gfs(0))
31+
meta.graph(showElem=true, showElemType=false) .saveTo(docsDir + gfs(1))
32+
meta.graph(showElem=false, showElemType=true) .saveTo(docsDir + gfs(2))
33+
meta.graph(showElem=true, showElemType=true) .saveTo(docsDir + gfs(3))
34+
35+
if isDotInstalled() then
36+
import scala.sys.process._
37+
for f <- gfs do
38+
println(s"Generating pdf files in $targetDir for graph: $f")
39+
val q = if (isWindows) '"'.toString else ""
40+
val cmd =
41+
Seq("dot",s"-Tpdf", "-o", s"$targetDir$q${newFileType(f, ".pdf")}$q",
42+
s"$q$docsDir$f$q")
43+
fixCmd(cmd).!
44+
45+
println(s"Generating $quickRefFile in $targetDir")
46+
meta.QuickRef.toLatex.saveTo(targetDir + quickRefFile)
47+
println(os.proc("latexmk", "-pdf", "-silent", quickRefFile).call(cwd = os.pwd / targetDir.stripSuffix("/")))
3148

3249
object showDeprecations:
3350
def apply(isVisible: Boolean = true) = if isVisible then println(report)
@@ -37,7 +54,7 @@ object showDeprecations:
3754
def p = xs.sorted.mkString(", ").wrap(72)
3855

3956
s"""|
40-
|--++ CHANGES SINCE reqT ${old.version}
57+
|--++ CHANGES SINCE reqT ${old.version3}
4158
| -- Deleted entities: ${deletedEntities.size} \n${deletedEntities.p}
4259
| ++ Added entities: ${addedEntities.size} \n${addedEntities.p}
4360
| -- Deleted attributes: ${deletedAttributes.size} \n${deletedAttributes.p}
@@ -59,7 +76,7 @@ object showDeprecations:
5976
def addedRelations = meta.relationNames.diff(old.relations)
6077

6178
object old:
62-
val version = "3.1.7"
79+
val version3 = "3.1.7"
6380

6481
val entities = Vector("Term", "Barrier", "Member", "Target", "Function", "MockUp", "Interface", "Event", "Scenario", "Release", "App", "Configuration", "UseCase", "Req", "Ticket", "Goal", "Variant", "Meta", "Story", "Section", "Resource", "Quality", "Service", "Actor", "System", "Label", "VariationPoint", "Component", "Design", "User", "Breakpoint", "Test", "Relationship", "Item", "Issue", "WorkPackage", "Class", "Product", "State", "Epic", "Screen", "Feature", "Data", "Domain", "Risk", "Stakeholder", "Task", "Module", "Idea")
6582

0 commit comments

Comments
 (0)