wip

README.md

@@ -21,7 +21,7 @@ Stroustrup.
 If you are familiar with the concept of open multi-methods, or if you prefer
 to learn by reading code, go directly to [the
 synopsis](examples/synopsis.cpp). The [reference is
-here](reference/README.md)
+here](reference/reference.md)
 
 ## Open Methods in a Nutshell
 

dev/md2md

@@ -9,13 +9,22 @@ import mdgen
 
 out_path = Path(sys.argv[2]).absolute()
 
+repo = Path(__file__).absolute()
+while not (repo / ".git").exists():
+    repo = repo.parent
+
+trail = str(out_path).replace(str(repo), "").split("/")
+trail.pop(0)
+trail.pop()
+
+with open(sys.argv[1]) as rh:
+    text = rh.read()
+
 with contextlib.suppress(FileNotFoundError):
     out_path.chmod(0o600)
 
-
-with open(sys.argv[1]) as rh, open(out_path, "w") as wh:
-    for text in rh.readlines():
-        text = mdgen.replace_md(text)
-        print(text, file=wh, end="")
+with open(out_path, "w") as wh:
+    text = mdgen.replace_md(text, trail=trail)
+    print(text, file=wh, end="")
 
 out_path.chmod(0o400)

dev/mdgen.py

@@ -5,17 +5,19 @@
 import sys
 
 
-def split_list(text):
-    return re.split(" *, *", text)
+def split_list(text, sep=","):
+    return list(map(str.strip, text.split(sep)))
 
 
 hrefs = {"home": "/README.md", "reference": "/reference/README.md"}
 in_path = Path(__file__).parent.parent / "reference.in"
 in_files = list(
     Path(ref_str)
     for ref_str in sorted(
-    glob.glob("**/*.md", root_dir=in_path, recursive=True)
-    + glob.glob("**/*.cpp", root_dir=in_path, recursive=True), key=str.lower)
+        glob.glob("**/*.md", root_dir=in_path, recursive=True)
+        + glob.glob("**/*.cpp", root_dir=in_path, recursive=True),
+        key=str.lower,
+    )
 )
 
 for ref in in_files:
@@ -38,6 +40,7 @@ def split_list(text):
 with open(".hrefs", "w", encoding="ascii") as fh:
     json.dump(hrefs, fh, indent=4)
 
+
 def replace_links(text):
     def sub(m):
         path = m.group(2)
@@ -50,7 +53,7 @@ def sub(m):
     return re.sub(r"->(`?)([/:\w_\-]+)(`?)", sub, text)
 
 
-def replace_md(text):
+def replace_md(text: str, trail: list[str] = None):
     text = re.sub(
         r"^entry: *(.*)",
         lambda m: ", ".join([f"**{entry}**" for entry in split_list(m[1])]) + "<br>",
@@ -89,6 +92,39 @@ def headers(m):
         flags=re.MULTILINE,
     )
 
+    def location(m):
+        locations = split_list(m[1], ";")
+        assert len(locations) <= 2
+
+        namespace = "yorel::yomm2"
+        if len(locations) == 2:
+            namespace = f"{namespace}::{locations.pop(0)}"
+
+        locations = split_list(locations.pop())
+
+        segments = [f"defined in {namespace} by <{locations.pop()}>"]
+
+        if len(locations) > 0:
+            segments.append(", also provided by ")
+            segments.append(", ".join([f"<{header}>" for header in locations]))
+
+        return "".join(("<sub>", *segments, "</sub>", "\n"))
+
+    text = re.sub(
+        r"^location: *(.*)",
+        location,
+        text,
+        flags=re.MULTILINE,
+    )
+
+    if trail is not None and "->home" not in text:
+        trailer = ["[home](/README.md)"]
+        for i, node in enumerate(trail):
+            path = "/".join(trail[:i + 1])
+            trailer.append(f"[{node}](/{path}.md)")
+
+        text = f"<sub>{trailer}</sub><br>\n" + text
+
     text = replace_links(text)
 
     return text

reference.boilerplate/class.md

@@ -1,7 +1,7 @@
 <sub>/ ->home / ->reference / ->CLASS </sub>
 
 # yorel::yomm2::**CLASS**
-<br><small>Defined in header yorel/yomm2/core.hpp</small>
+location:yorel/yomm2/core.hpp
 ```
 template<class TP>
 struct CLASS;

reference.in/error_handler.md

@@ -1,7 +1,5 @@
-<sub>/ [home](/reference//README.md) / [reference](/reference//reference/README.md) </sub>
-
-**yorel::yomm2::error_handler**<br>
-<sub>defined in <yorel/yomm2/core.hpp>, also provided by<yorel/yomm2/keywords.hpp></sub>
+**error_handler**<br>
+location: policy;yorel/yomm2/core.hpp,yorel/yomm2/keywords.hpp
 
 ---
 ```
@@ -21,7 +19,7 @@ can prevent program termination by throwing an exception.
 | ------------------------ | ----------------- |
 | [error](#register_vptrs) | handle ther error |
 
-### Implementations of `external_vptr`
+### Implementations of `error_handler`
 
 |                  |                                 |
 | ---------------- | ------------------------------- |

reference.in/vectored_error.md

@@ -1,7 +1,7 @@
 <sub>/ ->home / ->reference / ->vectored_error </sub>
 
-# yorel::yomm2::**vectored_error**
-<small>Defined in header yorel/yomm2/core.hpp</small>
+# **vectored_error**
+location: policy;yorel/yomm2/core.hpp,yorel/yomm2/keywords.hpp
 ```
 template<class Policy>
 struct vectored_error;

reference.in/vectored_error/default_error_handler.md

@@ -1,18 +1,16 @@
-<sub>/ ->home / ->reference / ->vectored_error / ->vectored_error/default_error_handler </sub>
-
 # vectored_error<Policy>::**default_error_handler**
-
+location: policy;yorel/yomm2/core.hpp, yorel/yomm2/keywords.hpp
 ---
 ```
-static void default_error_handler(const error_type& err);
+static void default_error_handler(const error_type& error);
 ```
 
 If ->`error_output` is available in `Policy`, use it to print a description of
-`err`. Return normally, causing the program to be aborted by the caller.
+`error`. Return normally, causing the program to be aborted by the caller.
 
 **Parameters**
 
-**err** - the variant containing the error.
+**error** - a variant containing the error.
 
 **Return value**