From 581044887a16d37c90116da544f5d9d600faa80c Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Tue, 17 Sep 2024 16:56:36 +0200
Subject: more fixes for reqs2tex

---
 scripts/tex.py | 3 ---
 1 file changed, 3 deletions(-)

(limited to 'scripts/tex.py')

diff --git a/scripts/tex.py b/scripts/tex.py
index 2509a87..59c6895 100644
--- a/scripts/tex.py
+++ b/scripts/tex.py
@@ -47,6 +47,3 @@ def esc(plain):
 def tabrule(*cells):
   return "&".join(cells) + "\\\\"
 
-def label2ref(*labels):
-  return ",".join(["req:" + label.replace('.', ':') for label in labels])
-
-- 
cgit v1.2.3


From 1df61d671706436c17e23bc9dcdc3bbd0f14a167 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Tue, 17 Sep 2024 17:35:19 +0200
Subject: labels/refs working inside requirements.tex

---
 scripts/reqs2tex.py | 28 +++++++++++++++++-----------
 scripts/tex.py      | 17 +++++++++++++++--
 2 files changed, 32 insertions(+), 13 deletions(-)

(limited to 'scripts/tex.py')

diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py
index 8c2236a..700d05f 100755
--- a/scripts/reqs2tex.py
+++ b/scripts/reqs2tex.py
@@ -107,19 +107,25 @@ def fmt_aux(data):
   return "\n".join(out)
 
 def fmt_tex(data):
-  out = []
+  out = ""
   for item in data:
-    out.append(
-      tex.cmd('subsection', item[KEY.ID]) +\
-      tex.cmd('label', label2ref(item[KEY.LABEL])) +\
-      tex.cmd('par') +\
-      tex.env('description',
-        tex.cmd('item', ['Priority']) + item[KEY.PRIORITY].title() +\
-        tex.cmd('item', ['Requirement']) + item[KEY.DESCRIPTION] +\
-        (tex.cmd('item', ['Definition of done']) + item[KEY.DONE] if item[KEY.DONE] is not None else "")
-      )
+    out += tex.join(
+      tex.cmd('subsection', item[KEY.ID]),
+      tex.withatletter(
+        tex.cmd('cref@constructprefix', 'requirement', r'\cref@result'),
+        tex.pedef('@currentlabel', item[KEY.ID]),
+        tex.pedef('@currentlabelname', item[KEY.ID]),
+        tex.pedef('cref@currentlabel', tex.group(['requirement'], [''], [r'\cref@result']) + item[KEY.ID]),
+      ),
+      tex.cmd('label', ['requirement'], label2ref(item[KEY.LABEL])),
+      tex.cmd('par'),
+      tex.env('description', tex.join(
+        tex.cmd('item', ['Priority']) + item[KEY.PRIORITY].title(),
+        tex.cmd('item', ['Requirement']) + item[KEY.DESCRIPTION],
+        (tex.cmd('item', ['Definition of done']) + item[KEY.DONE] if item[KEY.DONE] is not None else ""),
+      ))
     )
-  return "".join(out)
+  return out
 
 def main(input_file):
   data = {}
diff --git a/scripts/tex.py b/scripts/tex.py
index 59c6895..eebf8ec 100644
--- a/scripts/tex.py
+++ b/scripts/tex.py
@@ -9,6 +9,9 @@ def group(*args):
       out += "{" + arg + "}"
   return out
 
+def join(*things):
+  return "".join(things)
+
 def string(content):
   return r"\string" + content
 
@@ -18,11 +21,14 @@ def cmd(*args):
   if len(args) == 0: args = [""]
   return f"\\{name}" + group(*args)
 
+def pedef(*args):
+  return r"\protected@edef" + cmd(*args)
+
 def csdef(*args):
   return r"\def" + cmd(*args)
 
-def auxout(content):
-  return r"\write\@auxout" + group(content)
+def auxout(*content):
+  return r"\write\@auxout" + group(join(*content))
 
 def scmd(*args):
   return string(cmd(*args))
@@ -47,3 +53,10 @@ def esc(plain):
 def tabrule(*cells):
   return "&".join(cells) + "\\\\"
 
+def withatletter(*content):
+  return join(
+    cmd('makeatletter'),
+    *content,
+    cmd('makeatother'),
+  )
+
-- 
cgit v1.2.3


From de6821389604dc5254b285a1ca13b19ffb1905b5 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Tue, 17 Sep 2024 19:33:16 +0200
Subject: cleanup

---
 scripts/tex.py      |   9 +++++
 scripts/time2tex.py | 111 ++++++++++++++++++++++++++--------------------------
 2 files changed, 65 insertions(+), 55 deletions(-)

(limited to 'scripts/tex.py')

diff --git a/scripts/tex.py b/scripts/tex.py
index eebf8ec..e8fc65b 100644
--- a/scripts/tex.py
+++ b/scripts/tex.py
@@ -60,3 +60,12 @@ def withatletter(*content):
     cmd('makeatother'),
   )
 
+def explist(*items):
+  out = []
+  for item in items:
+    if isinstance(item, str) or not hasattr(item, '__iter__'):
+      out.append(item)
+    else:
+      out += explist(*item)
+  return out
+
diff --git a/scripts/time2tex.py b/scripts/time2tex.py
index 8c3dd9b..a5d6802 100755
--- a/scripts/time2tex.py
+++ b/scripts/time2tex.py
@@ -35,35 +35,30 @@ def fmt_member_overview(times):
     tracked[time["name"]] += time["duration"]
     total_time += time["duration"]
 
-  out = ""
-
-  # header
-  out += tex.cmd('toprule')
-  out += tex.tabrule(tex.cmd('textbf', 'Member'), tex.cmd('textbf', 'Tracked'), '')
-  out += tex.cmd('midrule')
-
-  # member overview
   members = sorted(list(set(time["name"] for time in times)))
-  for name in members:
-    out += tex.tabrule(name, fmt_duration(tracked[name]), fmt_percentage(tracked[name] / total_time))
-  out += tex.cmd('midrule')
-
-  # sum
-  out += tex.tabrule('', fmt_duration(total_time), '')
-  out += tex.cmd('bottomrule')
-
-  out = tex.env('tabular', 'lr@{~}l', out)
-  out = tex.cmd('centering') +\
-        out +\
-        tex.cmd('caption', 'Tracked time per group member') +\
-        tex.cmd('label', 'tab:time-member')
-  out = tex.env('table', out)
-
-  return out
+  return tex.env('table', tex.join(
+    tex.cmd('centering'),
+    tex.env('tabular', 'lr@{~}l', tex.join(
+      tex.cmd('toprule'),
+      tex.tabrule(tex.cmd('textbf', 'Member'), tex.cmd('textbf', 'Tracked')),
+      tex.cmd('midrule'),
+      *[
+        tex.tabrule(
+          name,
+          fmt_duration(tracked[name]),
+          fmt_percentage(tracked[name] / total_time))
+        for name in members
+      ],
+      tex.cmd('midrule'),
+      tex.tabrule('', fmt_duration(total_time), ''),
+      tex.cmd('bottomrule'),
+    )),
+    tex.cmd('caption', 'Tracked time per group member'),
+    tex.cmd('label', 'tab:time-member'),
+  ))
 
 def fmt_weekly_overview(times):
   # calculations
-  out = ""
   weeks = []
   member_totals = {}
   total_time = sum(time["duration"] for time in times)
@@ -93,34 +88,40 @@ def fmt_weekly_overview(times):
   for member in members:
     member_totals[member] = sum(time["duration"] for time in times if time["name"] == member)
 
-  # TODO: refactor
-  # begin table
-  out += r"\begin{table}\centering"
-  out += r"\fitimg{"
-  out += f"\\begin{{tabular}}{{l{'r@{~}l' * len(members)}@{{\\qquad}}r}}\\toprule"
-  out += r"\textbf{\#}"
-  for member in members:
-    out += f"&\\textbf{{{member}}}&"
-  out += r"&\textbf{Subtotal}\\\midrule{}"
-
-  for entry in weeks:
-    out += f"{entry['num']}"
-    for member in members:
-      out += f"&{fmt_duration(entry['members'][member])}&{fmt_percentage(entry['members'][member] / entry['total'])}"
-    out += f"&{fmt_duration(entry['total'])}\\\\"
-
-  out += r"\midrule{}"
-  for member in members:
-    out += f"&{fmt_duration(member_totals[member])}&{fmt_percentage(member_totals[member] / total_time)}"
-  out += f"&{fmt_duration(total_time)}\\\\"
-
-  # end table
-  out += r"\bottomrule\end{tabular}"
-  out += r"}" # \fitimg
-  out += r"\caption{Tracked time per week}\label{tab:time-weekly}"
-  out += r"\end{table}"
-
-  return out
+  return tex.env('table', tex.join(
+    tex.cmd('centering'),
+    tex.cmd('fitimg',
+      tex.env('tabular', r'l' + r'r@{~}l' * len(members) + r'@{\qquad}r', tex.join(
+        tex.cmd('toprule'),
+        tex.tabrule(*[
+          tex.cmd('textbf', cell)
+          for cell in [
+            tex.esc("#"),
+            *tex.explist([ member, "" ] for member in members),
+            "Subtotal",
+          ]
+        ]),
+        tex.cmd('midrule'),
+        *[
+          tex.tabrule(*[
+            str(entry['num']),
+            *tex.explist(
+              [
+                fmt_duration(entry['members'][member]),
+                fmt_percentage(entry['members'][member] / entry['total']),
+              ]
+              for member in members
+            ),
+            fmt_duration(entry['total']),
+          ])
+          for entry in weeks
+        ],
+        tex.cmd('bottomrule'),
+      )),
+    ),
+    tex.cmd('caption', 'Tracked time per week'),
+    tex.cmd('label', 'tab:time-weekly'),
+  ))
 
 def duration2secs(duration):
   out = 0 # output (seconds)
@@ -182,13 +183,13 @@ def parse(content):
   return out
 
 def fmt(times):
-  return "\n\n".join([
+  return tex.join(
     tex.cmd('section', 'Overviews'),
     tex.cmd('subsection', 'Members'),
     fmt_member_overview(times),
     tex.cmd('subsection', 'Weekly'),
     fmt_weekly_overview(times),
-  ])
+  )
 
 def main(input_file):
   content = ""
-- 
cgit v1.2.3


From 0027f5df316892f121bb9f4b5b6b641646273ff0 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Wed, 18 Sep 2024 14:54:48 +0200
Subject: add requirements + improve generated reqs.tex

---
 projdoc.cls         |  7 +++++--
 reqs.toml           | 39 ++++++++++++++++++++++++++++++---------
 requirements.tex    |  1 +
 scripts/reqs2tex.py | 15 ++++++++-------
 scripts/tex.py      | 10 ++++++++++
 5 files changed, 54 insertions(+), 18 deletions(-)

(limited to 'scripts/tex.py')

diff --git a/projdoc.cls b/projdoc.cls
index 7420d38..fccf8c1 100644
--- a/projdoc.cls
+++ b/projdoc.cls
@@ -215,8 +215,11 @@
 	selection={recorded and deps and see},
 ]
 
-% requirements
-\externaldocument{reqs}[requirements.pdf]
+% allow cross-references to requirements.pdf from all documents except
+% requirements.pdf itself
+\IfEq*{\jobname}{requirements}{}{
+	\externaldocument{reqs}[requirements.pdf]
+}
 
 % default document header/trailer
 \makeatletter
diff --git a/reqs.toml b/reqs.toml
index c05cf71..6645ea4 100644
--- a/reqs.toml
+++ b/reqs.toml
@@ -10,33 +10,46 @@
 # (cross-)referenced from LaTeX by prefixing this ID with `req:` and
 # substituting dots for colons (i.e. this requirement is referenced as
 # \cref{req:audio:async-api}).
-[audio.async-api]
+[audio]
 # Requirement type ('system' | 'user')
-type = 'system'
+type = 'user'
 # MoSCoW priority ('must' | 'should' | 'could' | 'will not')
 priority = 'must'
 # Requirement body. Supports LaTeX formatting. (tip: use single quotes so
 # backslash doesn't act as an escape character)
 description = '''
-The public audio \gls{api} supports starting audio samples asynchronously
-(i.e.~fire and forget).
+The engine allows the game programmer to easily start, pause and stop
+background music, while simultaniously playing sound effects.
 '''
-# Definition of done (user requirements only). If 'done' is a string, it is
-# treated as LaTeX code (like description), if it is a list of strings, each
-# item is treated as the ID of another requirement.
+# Definition of done. If 'done' is a string, it is treated as LaTeX code, if it
+# is a list of strings, each item is treated as the ID of another requirement,
+# and the references are checked before LaTeX runs.
+done = [
+	'audio.async-api',
+	'audio.handle',
+	'audio.stream-mix',
+	'audio.volume',
+]
 #done = 'When I feel like it'
-#done = [ 'audio.handle', 'audio.stream-mix' ]
 # Requirements that are no longer applicable should set `deleted` to `true`.
 # This will make sure the requirements are numbered consistently across
 # different document revisions.
 #deleted = true
 
+[audio.async-api]
+type = 'system'
+priority = 'must'
+description = '''
+The public audio \gls{api} supports starting audio samples asynchronously
+(i.e.~fire and forget).
+'''
+
 [audio.handle]
 type = 'system'
 priority = 'must'
 description = '''
 The public audio \gls{api} allows the game programmer to control (i.e.~play,
-pause and stop) audio samples after they are created/initialized.
+pause, resume and stop) audio samples after they are created/initialized.
 '''
 
 [audio.stream-mix]
@@ -46,6 +59,14 @@ description = '''
 The audio system supports playing multiple audio streams simultaniously.
 '''
 
+[audio.volume]
+type = 'system'
+priority = 'must'
+description = '''
+The public audio \gls{api} allows the game programmer to control the volume of
+audio samples.
+'''
+
 [aux.license]
 type = 'system'
 priority = 'must'
diff --git a/requirements.tex b/requirements.tex
index 2936272..cbaba81 100644
--- a/requirements.tex
+++ b/requirements.tex
@@ -6,6 +6,7 @@
 \projdoc@description@labelindent=0pt
 \projdoc@setdescriptionstyle
 \makeatother
+\setcounter{secnumdepth}{1}
 
 \title{Requirements}
 
diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py
index 82b0aae..ff9f3bb 100755
--- a/scripts/reqs2tex.py
+++ b/scripts/reqs2tex.py
@@ -122,7 +122,7 @@ def fmt_tex(data):
   out = ""
   for item in data:
     out += tex.join(
-      tex.cmd('subsection', item[KEY.ID]),
+      tex.cmd('subsection', f"{item[KEY.ID]}: {item[KEY.LABEL]}".upper()),
       tex.withatletter(
         tex.cmd('cref@constructprefix', 'requirement', r'\cref@result'),
         tex.pedef('@currentlabel', item[KEY.ID]),
@@ -130,12 +130,13 @@ def fmt_tex(data):
         tex.pedef('cref@currentlabel', tex.group(['requirement'], [''], [r'\cref@result']) + item[KEY.ID]),
       ),
       tex.cmd('label', ['requirement'], label2ref(item[KEY.LABEL])),
-      tex.cmd('par'),
-      tex.env('description', tex.join(
-        tex.cmd('item', ['Priority']) + item[KEY.PRIORITY].title(),
-        tex.cmd('item', ['Requirement']) + item[KEY.DESCRIPTION],
-        (tex.cmd('item', ['Definition of done']) + item[KEY.DONE] if item[KEY.DONE] is not None else ""),
-      ))
+      tex.cmd('parbox', tex.cmd('linewidth'),
+        tex.env('description', tex.join(
+          tex.cmd('item', ['Priority']) + item[KEY.PRIORITY].title(),
+          tex.cmd('item', ['Requirement']) + item[KEY.DESCRIPTION],
+          (tex.cmd('item', ['Definition of done']) + item[KEY.DONE] if item[KEY.DONE] is not None else ""),
+        )),
+      )
     )
   return out
 
diff --git a/scripts/tex.py b/scripts/tex.py
index e8fc65b..07d275a 100644
--- a/scripts/tex.py
+++ b/scripts/tex.py
@@ -69,3 +69,13 @@ def explist(*items):
       out += explist(*item)
   return out
 
+def sec(level, heading):
+  level = max(min(3, level), 0)
+  section = [
+    'section',
+    'subsection',
+    'subsubsection',
+    'paragraph',
+  ][level]
+  return cmd(section, heading)
+
-- 
cgit v1.2.3