pubdocrules 0.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. pubdoc/__init__.py +1 -0
  2. pubdoc/__main__.py +5 -0
  3. pubdoc/cli.py +800 -0
  4. pubdoc/compare.py +121 -0
  5. pubdoc/corpus.py +245 -0
  6. pubdoc/fonts/DejaVuSans-Bold.ttf +0 -0
  7. pubdoc/fonts/DejaVuSans.ttf +0 -0
  8. pubdoc/fonts/LICENCE-Ubuntu.txt +96 -0
  9. pubdoc/fonts/LICENSE-DejaVu.txt +78 -0
  10. pubdoc/fonts/LICENSE-Liberation.txt +130 -0
  11. pubdoc/fonts/LiberationSans-Bold.ttf +0 -0
  12. pubdoc/fonts/LiberationSans-BoldItalic.ttf +0 -0
  13. pubdoc/fonts/LiberationSans-Italic.ttf +0 -0
  14. pubdoc/fonts/LiberationSans-Regular.ttf +0 -0
  15. pubdoc/fonts/README.md +21 -0
  16. pubdoc/fonts/Ubuntu-R.ttf +0 -0
  17. pubdoc/projects.py +501 -0
  18. pubdoc/registry.py +54 -0
  19. pubdoc/schema/doc.schema.json +14 -0
  20. pubdoc/schema/project.schema.json +142 -0
  21. pubdoc/schema/pubdoc.schema.json +16 -0
  22. pubdoc/settings.py +66 -0
  23. pubdoc/storage.py +126 -0
  24. pubdoc/templates/annotations.mjs +116 -0
  25. pubdoc/templates/charged-ieee/template.typ +41 -0
  26. pubdoc/templates/charged-ieee/template.yml +28 -0
  27. pubdoc/templates/cv-sidebar/cv-sidebar.typ +113 -0
  28. pubdoc/templates/cv-sidebar/template.typ +11 -0
  29. pubdoc/templates/cv-sidebar/template.yml +23 -0
  30. pubdoc/templates/lapreprint-typst/LICENSE +21 -0
  31. pubdoc/templates/lapreprint-typst/frontmatter.typ +244 -0
  32. pubdoc/templates/lapreprint-typst/lapreprint.typ +314 -0
  33. pubdoc/templates/lapreprint-typst/template.typ +112 -0
  34. pubdoc/templates/lapreprint-typst/template.yml +82 -0
  35. pubdoc/templates/linkedin-text.mjs +127 -0
  36. pubdoc/templates/pub-plugin.mjs +117 -0
  37. pubdoc/versions.py +383 -0
  38. pubdocrules-0.5.0.dist-info/METADATA +355 -0
  39. pubdocrules-0.5.0.dist-info/RECORD +43 -0
  40. pubdocrules-0.5.0.dist-info/WHEEL +5 -0
  41. pubdocrules-0.5.0.dist-info/entry_points.txt +2 -0
  42. pubdocrules-0.5.0.dist-info/licenses/LICENSE +202 -0
  43. pubdocrules-0.5.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,142 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/Sustenaut/pubdoc/blob/main/src/pubdoc/schema/project.schema.json",
4
+ "title": "pubdoc project.yml",
5
+ "description": "A document project: the parts one purpose needs, the variants (audiences) and layouts (template or exporter, and format) each doc is rendered in, the review steps before publication, and the places it publishes to. Checker, place, template and exporter names are pubdoc's; `pubdoc check` checks them and every cross-reference.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": ["project", "purpose", "parts", "variants", "layouts"],
9
+ "properties": {
10
+ "project": {"$ref": "#/$defs/name", "description": "The project's name."},
11
+ "purpose": {"type": "string", "minLength": 1, "description": "What the project is for, in a sentence."},
12
+ "parts": {
13
+ "type": "object",
14
+ "description": "The kinds of document a doc of this project holds, by name.",
15
+ "minProperties": 1,
16
+ "propertyNames": {"$ref": "#/$defs/name"},
17
+ "additionalProperties": {
18
+ "type": "object",
19
+ "additionalProperties": false,
20
+ "required": ["required"],
21
+ "properties": {
22
+ "required": {"type": "boolean", "description": "Whether every doc must supply this part."},
23
+ "starts-from": {
24
+ "type": "string",
25
+ "pattern": "^shared/[a-z0-9][a-z0-9-]*$",
26
+ "description": "A shared part, shared/<name>/<part>.md, that a doc uses as-is when it supplies no file of its own."
27
+ }
28
+ }
29
+ }
30
+ },
31
+ "roles": {
32
+ "type": "object",
33
+ "additionalProperties": false,
34
+ "properties": {
35
+ "contributors": {"$ref": "#/$defs/logins", "description": "GitHub logins that write and edit docs."},
36
+ "reviewers": {"$ref": "#/$defs/logins", "description": "Accounts that may sign off a human review step."}
37
+ }
38
+ },
39
+ "variants": {
40
+ "type": "object",
41
+ "description": "Audiences, by name: what a doc includes and emphasises for each.",
42
+ "minProperties": 1,
43
+ "propertyNames": {"$ref": "#/$defs/name"},
44
+ "additionalProperties": {
45
+ "type": "object",
46
+ "additionalProperties": false,
47
+ "required": ["audience"],
48
+ "properties": {"audience": {"type": "string", "minLength": 1}}
49
+ }
50
+ },
51
+ "layouts": {
52
+ "type": "object",
53
+ "description": "How a part is rendered, by name: a pubdoc template or an exporter, and the format it makes.",
54
+ "minProperties": 1,
55
+ "propertyNames": {"$ref": "#/$defs/name"},
56
+ "additionalProperties": {
57
+ "type": "object",
58
+ "additionalProperties": false,
59
+ "required": ["part", "format"],
60
+ "properties": {
61
+ "part": {"$ref": "#/$defs/name"},
62
+ "template": {
63
+ "type": "string",
64
+ "pattern": "^(?:[a-z0-9][a-z0-9-]*|[^/].*/.*)$",
65
+ "description": "A template pubdoc carries, by name, or a template directory of this repository: a path relative to the project's directory, which a / marks (./templates/mine, ../templates/mine)."
66
+ },
67
+ "exporter": {"$ref": "#/$defs/name"},
68
+ "format": {"enum": ["pdf", "text", "html"]}
69
+ },
70
+ "oneOf": [
71
+ {"required": ["template"], "not": {"required": ["exporter"]}},
72
+ {"required": ["exporter"], "not": {"required": ["template"]}}
73
+ ]
74
+ }
75
+ },
76
+ "review": {"$ref": "#/$defs/review"},
77
+ "publish": {
78
+ "type": "array",
79
+ "description": "Where rendered layouts go, and who may read them there.",
80
+ "items": {"$ref": "#/$defs/publication"}
81
+ },
82
+ "storage": {"$ref": "#/$defs/storage"},
83
+ "corpus": {"$ref": "#/$defs/corpus", "description": "The corpus that signs this project's version publets, its path relative to the project's directory. The repository's pubdoc.yml gives the default."}
84
+ },
85
+ "$defs": {
86
+ "storage": {
87
+ "type": "object",
88
+ "additionalProperties": false,
89
+ "description": "Where approved renders are stored. The repository's pubdoc.yml gives the default.",
90
+ "properties": {
91
+ "tenant": {"$ref": "#/$defs/name", "description": "The storage tenant approved renders go to."},
92
+ "url": {"type": "string", "pattern": "^https?://[^/]+$", "description": "Storage's address; https://storage.sustenaut.eu by default."}
93
+ }
94
+ },
95
+ "corpus": {
96
+ "type": "object",
97
+ "additionalProperties": false,
98
+ "properties": {
99
+ "path": {"type": "string", "minLength": 1},
100
+ "key": {"type": "string", "pattern": "^pub:sha2-256:[a-z2-7]+$", "description": "The corpus's signing key: the one verify trusts."}
101
+ }
102
+ },
103
+ "name": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$"},
104
+ "names": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/name"}},
105
+ "logins": {
106
+ "type": "array",
107
+ "uniqueItems": true,
108
+ "items": {"type": "string", "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$"}
109
+ },
110
+ "review": {
111
+ "type": "array",
112
+ "description": "Ordered review steps between draft and publication. A step with both automatic checkers and human reviewers needs both to pass.",
113
+ "items": {
114
+ "type": "object",
115
+ "additionalProperties": false,
116
+ "required": ["step"],
117
+ "anyOf": [{"required": ["automatic"]}, {"required": ["human"]}],
118
+ "properties": {
119
+ "step": {"$ref": "#/$defs/name"},
120
+ "automatic": {"$ref": "#/$defs/names", "description": "Checker names from pubdoc's registry."},
121
+ "human": {
122
+ "type": "object",
123
+ "additionalProperties": false,
124
+ "required": ["reviewers"],
125
+ "properties": {"reviewers": {"type": "integer", "minimum": 1}}
126
+ }
127
+ }
128
+ }
129
+ },
130
+ "publication": {
131
+ "type": "object",
132
+ "additionalProperties": false,
133
+ "required": ["place", "layouts", "readers"],
134
+ "properties": {
135
+ "place": {"$ref": "#/$defs/name", "description": "A place name from pubdoc's registry."},
136
+ "layouts": {"$ref": "#/$defs/names"},
137
+ "variants": {"$ref": "#/$defs/names", "description": "Every variant when left out."},
138
+ "readers": {"enum": ["public", "signed-in", "named"]}
139
+ }
140
+ }
141
+ }
142
+ }
@@ -0,0 +1,16 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/Sustenaut/pubdoc/blob/main/src/pubdoc/schema/pubdoc.schema.json",
4
+ "title": "pubdoc pubdoc.yml",
5
+ "description": "Defaults for every project in a repository, at its root: the storage tenant approved renders go to, and the corpus (path relative to the root) that signs version publets. A project's own project.yml overrides each.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "properties": {
9
+ "storage": {
10
+ "$ref": "project.schema.json#/$defs/storage"
11
+ },
12
+ "corpus": {
13
+ "$ref": "project.schema.json#/$defs/corpus"
14
+ }
15
+ }
16
+ }
pubdoc/settings.py ADDED
@@ -0,0 +1,66 @@
1
+ """Where a project's versions go: its storage tenant, and the corpus that
2
+ signs its version publets.
3
+
4
+ A repository that collects several projects sets defaults in a pubdoc.yml
5
+ at its root; a project's own project.yml overrides them:
6
+
7
+ # pubdoc.yml, at the repository's root
8
+ storage: {tenant: documents}
9
+ corpus: {path: corpus, key: pub:sha2-256:...}
10
+
11
+ # <project>/project.yml
12
+ storage: {tenant: publet-design}
13
+ corpus: {path: corpus} # relative to the project: <project>/corpus
14
+
15
+ A corpus's path in pubdoc.yml is relative to the repository's root, in
16
+ project.yml to the project's directory. Without either, the corpus is
17
+ corpus/ at the repository's root. `key` is the corpus's signing key, the
18
+ one verify trusts; without it, verify says which key signed and accepts it.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ from dataclasses import dataclass
24
+ from pathlib import Path
25
+
26
+ from . import projects
27
+
28
+ ROOT_FILE = "pubdoc.yml"
29
+ STORAGE_URL = "https://storage.sustenaut.eu"
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class Settings:
34
+ root: Path
35
+ tenant: str | None
36
+ storage_url: str
37
+ corpus: Path
38
+ key: str | None
39
+
40
+
41
+ def root_config(root: Path, problems: list[projects.Problem]) -> dict:
42
+ file = root / ROOT_FILE
43
+ if not file.is_file():
44
+ return {}
45
+ data = projects.read_yaml(file, problems)
46
+ if data is None:
47
+ return {}
48
+ found = projects.schema_problems("pubdoc", data, file)
49
+ problems.extend(found)
50
+ return {} if found else data
51
+
52
+
53
+ def of(project: projects.Project) -> Settings:
54
+ """The settings `project` versions with: its own, else its repository's pubdoc.yml's."""
55
+ root = projects.repo_root(project.path).resolve()
56
+ base = root_config(root, [])
57
+ storage = {**base.get("storage", {}), **project.config.get("storage", {})}
58
+ corpus_base, corpus_own = base.get("corpus", {}), project.config.get("corpus", {})
59
+ if "path" in corpus_own:
60
+ corpus = project.path / corpus_own["path"]
61
+ else:
62
+ corpus = root / corpus_base.get("path", "corpus")
63
+ return Settings(root=root, tenant=storage.get("tenant"),
64
+ storage_url=storage.get("url", STORAGE_URL).rstrip("/"),
65
+ corpus=corpus.resolve(),
66
+ key=corpus_own.get("key", corpus_base.get("key")))
pubdoc/storage.py ADDED
@@ -0,0 +1,126 @@
1
+ """storage.sustenaut.eu's file routes, as pubdoc uses them: upload a render
2
+ to a tenant, where it is named by its SHA-256, and fetch it back.
3
+
4
+ A token is $PUBDOC_STORAGE_TOKEN, else $GITHUB_TOKEN, else `gh auth token`:
5
+ a GitHub token that may push to the tenant's repository, which an editors
6
+ tenant takes for both, or a workflow's OpenID Connect token for reading.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import hashlib
12
+ import json
13
+ import os
14
+ import posixpath
15
+ import shutil
16
+ import subprocess
17
+ import urllib.error
18
+ import urllib.parse
19
+ import urllib.request
20
+ import uuid
21
+ from importlib import metadata
22
+ from pathlib import Path
23
+
24
+
25
+ class StorageError(Exception):
26
+ pass
27
+
28
+
29
+ def token() -> str | None:
30
+ for name in ("PUBDOC_STORAGE_TOKEN", "GITHUB_TOKEN"):
31
+ if os.environ.get(name):
32
+ return os.environ[name]
33
+ gh = shutil.which("gh")
34
+ if gh:
35
+ done = subprocess.run([gh, "auth", "token"], capture_output=True, text=True)
36
+ if done.returncode == 0 and done.stdout.strip():
37
+ return done.stdout.strip()
38
+ return None
39
+
40
+
41
+ def sha256(data: bytes) -> str:
42
+ return hashlib.sha256(data).hexdigest()
43
+
44
+
45
+ class _NoRedirect(urllib.request.HTTPRedirectHandler):
46
+ """A redirect would carry the token to wherever it points: refuse it."""
47
+
48
+ def redirect_request(self, req, fp, code, msg, headers, newurl):
49
+ raise urllib.error.HTTPError(req.full_url, code, f"redirected to {newurl}, not followed", headers, fp)
50
+
51
+
52
+ def _agent() -> str:
53
+ try:
54
+ return f"pubdoc/{metadata.version('pubdocrules')}"
55
+ except metadata.PackageNotFoundError: # a checkout run without installing
56
+ return "pubdoc"
57
+
58
+
59
+ _OPENER = urllib.request.build_opener(_NoRedirect)
60
+ # Every request names pubdoc: storage's edge (Cloudflare) refuses urllib's
61
+ # own Python-urllib/<version> with a 403 (error code 1010).
62
+ _OPENER.addheaders = [("User-Agent", _agent())]
63
+
64
+
65
+ def _request(request: urllib.request.Request, auth: str | None) -> bytes:
66
+ if auth:
67
+ request.add_header("Authorization", f"Bearer {auth}")
68
+ try:
69
+ with _OPENER.open(request, timeout=120) as answer:
70
+ return answer.read()
71
+ except urllib.error.HTTPError as e:
72
+ detail = e.read().decode("utf-8", "replace")[:300]
73
+ raise StorageError(f"{request.get_method()} {request.full_url}: {e.code} {detail}") from None
74
+ except urllib.error.URLError as e:
75
+ raise StorageError(f"{request.get_method()} {request.full_url}: {e.reason}") from None
76
+
77
+
78
+ def upload(base: str, tenant: str, name: str, data: bytes, label: str) -> str:
79
+ """Store `data` in `tenant`, kept for good, and return its address.
80
+ Refuses an answer naming any other content than `data`'s."""
81
+ boundary = uuid.uuid4().hex
82
+ parts = []
83
+ for field, value in (("name", name), ("label", label[:200]), ("kept", "true")):
84
+ parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{field}"\r\n\r\n{value}\r\n'.encode())
85
+ parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="{name}"\r\n'
86
+ "Content-Type: application/octet-stream\r\n\r\n".encode() + data + b"\r\n")
87
+ parts.append(f"--{boundary}--\r\n".encode())
88
+ request = urllib.request.Request(f"{base}/{tenant}/files", data=b"".join(parts), method="POST",
89
+ headers={"Content-Type": f"multipart/form-data; boundary={boundary}"})
90
+ answer = json.loads(_request(request, token()))
91
+ if answer.get("id") != sha256(data):
92
+ raise StorageError(f"storage stored {name} as {answer.get('id')}, not as its sha256 {sha256(data)}")
93
+ return f"{base}{answer['url']}"
94
+
95
+
96
+ def within(url: str, base: str) -> bool:
97
+ """Whether `url` is under `base` (a tenant's address, such as
98
+ https://storage.sustenaut.eu/documents/): the same scheme, host and port,
99
+ no user or password, and a path that stays under base's once . and ..
100
+ are resolved. Only then does a request carry the token."""
101
+ u, b = urllib.parse.urlsplit(url), urllib.parse.urlsplit(base)
102
+ if u.username or u.password or u.query or u.fragment or "%" in u.path:
103
+ return False
104
+ if (u.scheme, u.hostname, u.port) != (b.scheme, b.hostname, b.port):
105
+ return False
106
+ path, prefix = posixpath.normpath(u.path), posixpath.normpath(b.path)
107
+ if path != u.path: # a . or .. segment, or a doubled /
108
+ return False
109
+ return path.startswith(prefix.rstrip("/") + "/")
110
+
111
+
112
+ def download(url: str, expected: str, base: str) -> bytes:
113
+ """The file at `url`, refused unless it is under `base`, the tenant the
114
+ project names (so the token goes nowhere else), and unless its SHA-256
115
+ is `expected`."""
116
+ if not within(url, base):
117
+ raise StorageError(f"{url} is not in the project's storage tenant, {base}: not fetched")
118
+ data = _request(urllib.request.Request(url), token())
119
+ if sha256(data) != expected:
120
+ raise StorageError(f"{url} is not the file recorded: its sha256 is {sha256(data)}, not {expected}")
121
+ return data
122
+
123
+
124
+ def save(url: str, expected: str, base: str, target: Path) -> Path:
125
+ target.write_bytes(download(url, expected, base))
126
+ return target
@@ -0,0 +1,116 @@
1
+ // Shared MyST plugin for the verdict-coded annotation scheme (see
2
+ // AGENTS.md, "Annotation scheme"). Referenced by any doc's myst.yml via
3
+ // `project.plugins: [../.pubdoc/templates/annotations.mjs]`.
4
+ //
5
+ // Provides four inline roles - {true}, {partial}, {false}, {neutral} -
6
+ // each taking a short, stable NAME (not a number) as their body, e.g.:
7
+ //
8
+ // The essay claims X {true}`sons-mortality`.
9
+ //
10
+ // A name can be reused anywhere in the document to mark a second mention
11
+ // of the same claim; it always resolves to the same note number. Numbers
12
+ // are assigned automatically, in the order names first appear in the
13
+ // text - never typed by hand, so inserting/removing/reordering notes
14
+ // never requires renumbering anything.
15
+ //
16
+ // Each name needs exactly one matching heading elsewhere in the document
17
+ // (normally in a "## Notes" section) labeled with `(note-<name>)=` and
18
+ // containing the literal text "Note" - the transform below rewrites that
19
+ // text to "Note <n>" using the same number, so the in-text marker and
20
+ // its target always agree:
21
+ //
22
+ // (note-sons-mortality)=
23
+ // ### Note
24
+ //
25
+ // :::{warning} Verdict: Partially true - "..."
26
+ // ...
27
+ // :::
28
+ //
29
+ // Colors match exactly what myst-imports.typ's admonition() helper uses
30
+ // for each color's own left-border stroke (color.darken(20%)) - see
31
+ // AGENTS.md for why plain Unicode symbols need this (no inherent color,
32
+ // unlike emoji) and why {raw:typst} is the only way to get real color
33
+ // with no native MyST color role.
34
+ const VERDICTS = {
35
+ true: { color: 'green', symbol: '✓' },
36
+ partial: { color: 'yellow', symbol: '◪' },
37
+ false: { color: 'red', symbol: '✗' },
38
+ neutral: { color: 'blue', symbol: '☐' },
39
+ };
40
+
41
+ function verdictRole(name) {
42
+ return {
43
+ name,
44
+ body: { type: String, required: true },
45
+ run(data) {
46
+ return [{ type: 'verdictMark', verdict: name, name: data.body }];
47
+ },
48
+ };
49
+ }
50
+
51
+ function isVerdictMark(node) {
52
+ return node && node.type === 'verdictMark';
53
+ }
54
+
55
+ function walk(node, visit) {
56
+ visit(node);
57
+ if (Array.isArray(node.children)) {
58
+ node.children.forEach((child) => walk(child, visit));
59
+ }
60
+ }
61
+
62
+ const annotationsPlugin = {
63
+ name: 'Verdict-coded annotations',
64
+ roles: Object.keys(VERDICTS).map(verdictRole),
65
+ transforms: [
66
+ {
67
+ name: 'verdict-annotations',
68
+ doc: 'Auto-number {true}/{partial}/{false}/{neutral} markers by first appearance and color-code them; sync the matching Note heading text to the same number.',
69
+ stage: 'document',
70
+ plugin: () => (tree) => {
71
+ // Pass 1: assign numbers to each unique name, in document order.
72
+ const numberByName = new Map();
73
+ walk(tree, (node) => {
74
+ if (!isVerdictMark(node)) return;
75
+ if (!numberByName.has(node.name)) {
76
+ numberByName.set(node.name, numberByName.size + 1);
77
+ }
78
+ });
79
+
80
+ // Pass 2: replace each verdictMark node in place with the
81
+ // rendered marker (mutate type/children directly - it's the
82
+ // same object reference the tree already holds).
83
+ walk(tree, (node) => {
84
+ if (!isVerdictMark(node)) return;
85
+ const n = numberByName.get(node.name);
86
+ const { color, symbol } = VERDICTS[node.verdict];
87
+ const url = `#note-${node.name}`;
88
+ const iconRaw = { type: 'raw', lang: 'typst', typst: `#text(fill: ${color}.darken(20%))[${symbol}]` };
89
+ node.type = 'link';
90
+ node.url = url;
91
+ node.children = [
92
+ { type: 'text', value: `[${n}` },
93
+ iconRaw,
94
+ { type: 'text', value: ']' },
95
+ ];
96
+ delete node.verdict;
97
+ delete node.name;
98
+ });
99
+
100
+ // Pass 3: sync each labeled "Note" heading's text to the number
101
+ // assigned to its name.
102
+ walk(tree, (node) => {
103
+ if (node.type !== 'heading') return;
104
+ const id = node.identifier || node.html_id || node.label;
105
+ if (!id || !id.startsWith('note-')) return;
106
+ const name = id.slice('note-'.length);
107
+ const n = numberByName.get(name);
108
+ if (n === undefined) return;
109
+ node.children = [{ type: 'text', value: `Note ${n}` }];
110
+ });
111
+ },
112
+ },
113
+ ],
114
+ };
115
+
116
+ export default annotationsPlugin;
@@ -0,0 +1,41 @@
1
+ // Thin jtex wrapper around the @preview/charged-ieee Typst Universe
2
+ // package. Unlike lapreprint-typst, charged-ieee isn't itself a jtex/MyST
3
+ // template - this file is what adapts it into one, so MyST/Curvenote can
4
+ // drive it from the same index.md/myst.yml as any other template.
5
+ //
6
+ // charged-ieee's `title`/`abstract` parameters are Typst *content*
7
+ // ([...]), not strings - jtex only does raw text substitution, so a
8
+ // title/abstract containing Typst markup characters (_, *, #, $) would be
9
+ // interpreted as markup here. Not an issue for plain prose titles; if
10
+ // that ever matters, escape at the source (myst.yml/index.md) instead of
11
+ // here.
12
+ #import "@preview/charged-ieee:0.1.4": ieee
13
+
14
+ #show: ieee.with(
15
+ title: [[-doc.title-]],
16
+ [# if parts.abstract #]
17
+ abstract: [
18
+ [-parts.abstract-]
19
+ ],
20
+ [# endif #]
21
+ authors: (
22
+ [# for author in doc.authors #]
23
+ (
24
+ name: "[-author.name-]",
25
+ [# if author.email #]
26
+ email: "[-author.email-]",
27
+ [# endif #]
28
+ ),
29
+ [# endfor #]
30
+ ),
31
+ [# if doc.keywords #]
32
+ index-terms: ([#- for keyword in doc.keywords -#]"[-keyword-]",[#- endfor -#]),
33
+ [# endif #]
34
+ [# if doc.bibtex #]
35
+ bibliography: bibliography("[-doc.bibtex-]"),
36
+ [# endif #]
37
+ )
38
+
39
+ [-IMPORTS-]
40
+
41
+ [-CONTENT-]
@@ -0,0 +1,28 @@
1
+ jtex: v1
2
+ kind: typst
3
+ title: Charged IEEE (local wrapper)
4
+ description: >
5
+ Thin jtex wrapper around the @preview/charged-ieee Typst Universe
6
+ package (not itself a MyST template), so MyST/Curvenote can drive it
7
+ the same way as any other jtex template. See
8
+ https://typst.app/universe/package/charged-ieee for the underlying
9
+ package's own docs.
10
+ template: template.typ
11
+ files:
12
+ - template.typ
13
+ version: 0.1.4
14
+ license: MIT
15
+ tags:
16
+ - ieee
17
+ - article
18
+ - paper
19
+ doc:
20
+ - id: title
21
+ required: true
22
+ - id: authors
23
+ required: true
24
+ - id: keywords
25
+ parts:
26
+ - id: abstract
27
+ description: The paper's abstract. Passed straight through to charged-ieee's `abstract`.
28
+ required: false
@@ -0,0 +1,113 @@
1
+ // From-scratch Typst layout replicating cv-builder's original hand-built
2
+ // CSS design: a maroon horizontal rule + rotated vertical section-label
3
+ // sidebar above each top-level heading, a maroon/pink color scheme, on
4
+ // an A4 page (confirmed via `pdfinfo` on the original weasyprint-built
5
+ // PDF - not US Letter).
6
+
7
+ #let structural-maroon = rgb(128, 0, 0) // #800000 - CSS: .section border-top, .section h1, .myname
8
+ #let link-maroon = rgb(0x72, 0, 0) // #720000 - CSS: a, a:active, a:visited (a distinct, darker shade)
9
+ #let summary-pink = rgb(0xff, 0xee, 0xee) // #FEE - CSS: .summary background-color
10
+
11
+ #let gutter = 2.4em
12
+
13
+ // Target gap between the section's rule and the label's LAST letter.
14
+ // Rendered ink ends up ~1pt further than this (glyph side-bearings);
15
+ // verified by measuring every heading in the built PDF (all within
16
+ // 8.8-9.5pt of their rule).
17
+ #let label-top-offset = 8pt
18
+
19
+ #let label-font = ("Libertinus Serif", "Noto Serif", "DejaVu Serif")
20
+ #let label-text(body, ..args) = text(
21
+ font: label-font, size: 12pt, tracking: 2pt, upper(body), ..args,
22
+ )
23
+
24
+ // The label is drawn in a zero-width box, so Typst wraps it at every
25
+ // space: the vertical extent is the LONGEST WORD, not the whole string.
26
+ // Measure exactly that, in the same font/size/tracking as the label.
27
+ #let label-length(it) = {
28
+ let words = if it.body.has("text") { it.body.text.split(" ") } else { (it.body,) }
29
+ calc.max(..words.map(w => measure(label-text(w)).width))
30
+ }
31
+
32
+ #let cv-sidebar(title: none, subtitle: none, body) = {
33
+ set page(
34
+ paper: "a4",
35
+ margin: (left: gutter + 1in, rest: 1in),
36
+ )
37
+ set text(font: ("Libertinus Serif", "Noto Serif", "DejaVu Serif"), size: 12pt, fill: rgb(51, 51, 51))
38
+ set par(justify: false, leading: 0.65em)
39
+
40
+ show link: it => text(fill: link-maroon, it)
41
+
42
+ // Each top-level heading becomes a rotated vertical label in the left
43
+ // gutter, matching CSS's `.section h1 { position:absolute; transform:
44
+ // translate(-100%,0%) rotate(-90deg); transform-origin:100% 0; }` -
45
+ // removed entirely from normal flow, not printed inline.
46
+ //
47
+ // Level 2, not 1: MyST's typst exporter maps Markdown `#` (H1) to Typst
48
+ // `==` (level 2) - it reserves level 1 (`=`) for the document title
49
+ // itself (confirmed by inspecting the generated main.typ directly).
50
+ //
51
+ // Positioning uses `place()`, not `block()`: a real `block()` (tried
52
+ // briefly, with `rotate(reflow: true, ...)` so its reported size
53
+ // matches the label's true rotated, tall-and-narrow shape) is an
54
+ // ordinary flow element - it reserves that much vertical space in the
55
+ // page's single content column before the next thing can start, even
56
+ // though the label itself is shifted out into the margin visually. For
57
+ // a long label like "Employment" that pushed the body text below it
58
+ // down by a large, unwanted gap. `place()`'d content never reserves
59
+ // flow space at all, regardless of its own size, which is what we
60
+ // actually want here: the label lives entirely in the margin and
61
+ // should never affect where body text in the main column starts.
62
+ //
63
+ // An *unaligned* `place()` (no alignment argument, just `dx`/`dy`)
64
+ // tracks the current flow position automatically and correctly, even
65
+ // with `rotate()` - but only when it is the sole content of a
66
+ // zero-size `box(width: 0pt, height: 0pt, ...)`, with nothing else
67
+ // wrapping the rotated text beyond the bare `label-text(...)` and the
68
+ // `rotate(-90deg, ...)` below (an inner box, a
69
+ // scoped show rule, `reflow: true` on the outer rotate, or extracting
70
+ // `it.body.text` all independently reintroduce a mis-tracking bug that
71
+ // silently sends the label to the wrong heading's position - keep this
72
+ // block exactly this minimal).
73
+ //
74
+ // The label reads up the page (-90deg). Its zero-width layout box
75
+ // means "origin: top + right" collapses onto the text's START, so the
76
+ // pivot is the first letter, which lands a fixed distance below the
77
+ // rule, and the label extends UPWARD from there by its own length.
78
+ // The show rule below therefore drops the label by exactly that
79
+ // length, putting the LAST letter a constant distance under the rule
80
+ // for every heading. (An earlier version scaled a gap by an estimated
81
+ // width instead - wrong for any label whose estimate differed from
82
+ // what is actually drawn, i.e. most of them.)
83
+ //
84
+ show heading.where(level: 2): it => {
85
+ v(1em, weak: true)
86
+ line(length: 100%, stroke: 0.75pt + structural-maroon)
87
+ v(0.5em, weak: true)
88
+ context {
89
+ // The rotated label's first letter lands a constant 6.7pt below the
90
+ // rule at dy: 0 (measured from the render); it then extends upward by
91
+ // its own length, so dropping it by (length + wanted offset - 6.7pt)
92
+ // puts the LAST letter `label-top-offset` below the rule.
93
+ let drop = label-length(it) + label-top-offset - 6.7pt
94
+ box(width: 0pt, height: 0pt,
95
+ place(dx: -gutter - 0.15em, dy: drop,
96
+ rotate(-90deg, origin: top + left,
97
+ label-text(it.body, fill: structural-maroon)
98
+ ),
99
+ ),
100
+ )
101
+ }
102
+ }
103
+
104
+ // Name / tagline, matching .myname (bold, maroon, 16px) / .tagline.
105
+ text(weight: "bold", fill: structural-maroon, size: 16pt, title)
106
+ if subtitle != none {
107
+ linebreak()
108
+ text(subtitle)
109
+ }
110
+ v(1em)
111
+
112
+ body
113
+ }
@@ -0,0 +1,11 @@
1
+ #import "cv-sidebar.typ": *
2
+ #show: cv-sidebar.with(
3
+ title: "[-doc.title-]",
4
+ [# if doc.subtitle #]
5
+ subtitle: "[-doc.subtitle-]",
6
+ [# endif #]
7
+ )
8
+
9
+ [-IMPORTS-]
10
+
11
+ [-CONTENT-]