Frontends#
Text in, validated IR out. Two syntaxes, one IR – which is what lets a comic script and a YAML document compile identically without anything downstream knowing there is more than one.
scenet.frontends.yaml_front#
.. py:module:: scenet.frontends.yaml_front
The YAML surface syntax: text in, validated IR out.
This is one frontend among several planned – a comic-script frontend will target the same IR. Keeping parsing separate from the IR is what makes that possible without touching anything downstream.
.. py:function:: parse_panel(text, *, source=None)
- module:
scenet.frontends.yaml_front
Parse panel source into validated IR.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.PanelIR``
.. py:function:: load_panel(path)
- module:
scenet.frontends.yaml_front
Read and validate a single-panel document from disk.
- type path:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path``
- param path:
A
*.panel.yamlfile.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.PanelIR``
- returns:
The validated scene graph. No coordinates yet – that is the solver’s job.
- raises OSError:
The file cannot be read.
- raises PanelSyntaxError:
The document is malformed or invalid. The path is included in the message.
.. py:class:: SceneDocument
- module:
scenet.frontends.yaml_front
Bases: :py:class:
objectA scene, read: its panels, and the pages they are laid out on.
.. attribute:: panels
Panel name to validated IR, in declaration order – which is reading order. A single-panel document has one, named
panel... attribute:: layout
The page format and the pages.
layout.pagesis empty for a document that lays nothing out, which is every document written before pages existed... attribute:: notes
What reading it noticed that is worth saying but is no fault, each naming its line. Only a comic script has any yet.
.. py:attribute:: SceneDocument.panels
- module:
scenet.frontends.yaml_front
- type:
dict[str, ~scenet.ir.PanelIR]
.. py:attribute:: SceneDocument.layout
- module:
scenet.frontends.yaml_front
- type:
~scenet.ir.PageLayout
.. py:attribute:: SceneDocument.notes
- module:
scenet.frontends.yaml_front
- type:
tuple[str, …]
.. py:method:: SceneDocument.init(panels, layout, notes=())
- module:
scenet.frontends.yaml_front
.. py:function:: parse_scene(text, *, source=None)
- module:
scenet.frontends.yaml_front
Parse a multi-panel document, resolving
overinheritance.A document with a top-level
panels:mapping holds a sequence; anything else is treated as a single panel named “panel”, so the two forms share one entry point and a single-panel file needs no ceremony.Panel order follows declaration order, which is reading order.
page:andpages:are read and checked, but only the panels come back: see- func:
parse_scene_document <scenet.frontends.yaml_front.parse_scene_document>.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.PanelIR`]`
.. py:function:: parse_scene_document(text, *, source=None)
- module:
scenet.frontends.yaml_front
Parse a scene and the pages it is laid out on.
page:andpages:are not panel defaults, unlike every other key besidepanels:, so they are taken out before the defaults are applied.- type text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param text:
The document source.
- type source:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path` | :py:obj:`None``
- param source:
Path it came from, used only to prefix error messages.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.frontends.yaml_front.SceneDocument``
- returns:
The panels and the layout.
- raises PanelSyntaxError:
A panel or the layout is malformed. A placement naming a panel that does not exist, or one placed twice, is rule
page-layout.- raises CompositionError:
An
over:chain is unresolvable or cyclic.
.. py:function:: load_scene(path)
- module:
scenet.frontends.yaml_front
Read and validate a multi-panel document from disk.
- type path:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path``
- param path:
A
*.scene.yamlfile. A single-panel document also works and comes back as one entry namedpanel.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.PanelIR`]`
- returns:
Panel name to scene graph, in declaration order – which is reading order.
- raises OSError:
The file cannot be read.
- raises PanelSyntaxError:
A panel is malformed or invalid.
- raises CompositionError:
An
over:chain is unresolvable or cyclic.
.. py:function:: load_scene_document(path)
- module:
scenet.frontends.yaml_front
Read a scene and the pages it is laid out on, from disk.
- type path:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path``
- param path:
A
*.scene.yamlfile, or any YAML document the frontend reads.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.frontends.yaml_front.SceneDocument``
- returns:
The panels and the layout.
- raises OSError:
The file cannot be read.
- raises PanelSyntaxError:
A panel or the layout is malformed.
- raises CompositionError:
An
over:chain is unresolvable or cyclic.
scenet.frontends.script_front#
.. py:module:: scenet.frontends.script_front
A frontend for comic script, the format writers already use.
Checked before building this: Fountain has no native panel, caption or SFX support,
and there is no standardised comic script format at all. But the informal industry
convention is stable across publishers – PANEL 1, a prose description, a character
cue in capitals, the dialogue beneath it – so that is what this parses. Dark Horse
publishes its own house format, and it is read as written: PAGE ONE (five panels),
Panel 1. with its description, CAP: and CAP/NAME, numbered lettering, Markdown
around any of it. So is a French script: PLANCHE 1, CASE 2, RÉCITATIF :, the
échelle des plans. Each PAGE heading is a page.
The honest limitation. A prose description like “Alice and Bob face each other on
a rainy street corner” cannot be compiled. Turning that into staging needs natural
language understanding, and guessing would produce panels that are confidently wrong
– far worse than refusing. So descriptions are preserved but not interpreted, and
anything the compiler must know is declared explicitly: cast and staging in a
front-matter block, per-panel settings as @ directives.
---
cast:
ALICE: {reference: alice, at: left_third}
BOB: {reference: bob, at: right_third}
staging:
- ALICE left_of BOB
---
PANEL 1
@shot: full_shot
CAPTION: Midnight. The docks.
Alice and Bob face each other on a rainy street corner.
ALICE
You forgot your umbrella!
BOB (whisper)
I know.
.. py:class:: ScriptNote
- module:
scenet.frontends.script_front
Bases: :py:class:
objectSomething the script frontend noticed that is worth saying but is not a fault.
.. attribute:: rule
Catalogue identifier, a rule whose level is
note... attribute:: message
What was noticed, phrased for whoever wrote the script.
.. attribute:: line
One-based line it is on.
.. attribute:: path
Where it is, structurally, so a finding’s fingerprint survives an edit above it: the panel’s name and what in it, or the page’s.
.. py:attribute:: ScriptNote.rule
- module:
scenet.frontends.script_front
- type:
str
.. py:attribute:: ScriptNote.message
- module:
scenet.frontends.script_front
- type:
str
.. py:attribute:: ScriptNote.line
- module:
scenet.frontends.script_front
- type:
int
.. py:attribute:: ScriptNote.path
- module:
scenet.frontends.script_front
- type:
tuple[str | int, …]
.. py:method:: ScriptNote.init(rule, message, line, path=())
- module:
scenet.frontends.script_front
.. py:function:: default_tiers(count)
- module:
scenet.frontends.script_front
How many panels each tier of a page holds, when the script does not say.
Dark Horse leaves “exact panel layout” to the artist, and the compiler is the artist, so it follows a fixed rule: three tiers at most up to nine panels – the lettering height of a page assumes three – with an odd panel in a tier of its own in the middle, and beyond nine, rows of three with the extras in the earlier tiers.
.. admonition:: Example
[default_tiers(count) for count in (1, 4, 5, 7, 10)] [[1], [2, 2], [2, 1, 2], [2, 3, 2], [3, 3, 2, 2]]
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\list`\ \[:py:class:`int`]`
.. py:function:: normalise_text(text)
- module:
scenet.frontends.script_front
A script as it is read, whatever the editor that saved it did.
Line endings become line feeds. Python’s text mode does this silently when reading a file, which is why it took a browser to notice: the playground hands over the bytes it was given, and a script saved by a Windows editor – or pasted from one – arrives with CRLF. The front-matter pattern then does not match, the
---fence is read as prose, and the whole document is rejected for having content before the first PANEL heading.A byte-order mark is dropped. Some Windows editors still write one, and it hid the front matter in exactly the same way.
Text is composed (NFC). A macOS editor may store
ÉasEand a combining accent, and a name typed that way in a cue is the same name the front matter composed; compared as stored, the cue named nobody.
.. admonition:: Example
normalise_text(“\ufeffZOE\u0308\r\n”) == “ZO\u00cb\n” True
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
.. py:class:: PanelLines
- module:
scenet.frontends.script_front
Bases: :py:class:
objectWhere a script panel was written, for a finding about it to point at.
.. attribute:: heading
The line of its PANEL heading.
.. attribute:: events
The line each entry of its
scriptwas written on, in order: a speech’s cue, a caption’s or a sound effect’s own line... py:attribute:: PanelLines.heading
- module:
scenet.frontends.script_front
- type:
int
.. py:attribute:: PanelLines.events
- module:
scenet.frontends.script_front
- type:
tuple[int, …]
.. py:method:: PanelLines.init(heading, events)
- module:
scenet.frontends.script_front
.. py:class:: ScriptDocument
- module:
scenet.frontends.script_front
Bases: :py:class:
objectA comic script, read and validated, and where each of its panels was written.
.. attribute:: panels
Panel name to scene graph, in the order the panels appear.
.. attribute:: lines
Panel name to the lines it was written on.
.. attribute:: notes
What reading it noticed that is worth saying but is not a fault – a cue with nothing said under it, a page whose count its panels do not match.
.. attribute:: descriptions
Panel name to its prose, which is kept and never interpreted.
.. attribute:: title_page
The prose before the first heading: Dark Horse’s format opens with the writer’s name and address.
.. attribute:: page_notes
Page to the prose between its heading and its first panel.
.. attribute:: layout
The pages its PAGE headings lay its panels out on; none without them.
.. py:attribute:: ScriptDocument.panels
- module:
scenet.frontends.script_front
- type:
dict[str, ~scenet.ir.PanelIR]
.. py:attribute:: ScriptDocument.lines
- module:
scenet.frontends.script_front
- type:
dict[str, ~scenet.frontends.script_front.PanelLines]
.. py:attribute:: ScriptDocument.notes
- module:
scenet.frontends.script_front
- type:
tuple[~scenet.frontends.script_front.ScriptNote, …]
.. py:attribute:: ScriptDocument.descriptions
- module:
scenet.frontends.script_front
- type:
dict[str, tuple[str, …]]
.. py:attribute:: ScriptDocument.title_page
- module:
scenet.frontends.script_front
- type:
tuple[str, …]
.. py:attribute:: ScriptDocument.page_notes
- module:
scenet.frontends.script_front
- type:
dict[str, tuple[str, …]]
.. py:attribute:: ScriptDocument.layout
- module:
scenet.frontends.script_front
- type:
~scenet.ir.PageLayout
.. py:method:: ScriptDocument.init(panels, lines, notes=(), descriptions=
, title_page=(), page_notes= , layout= ) - module:
scenet.frontends.script_front
.. py:function:: parse_script_document(text, *, source=None)
- module:
scenet.frontends.script_front
Parse comic script, keeping the line each panel and each of its events is on.
parse_scriptis this, less the lines. A checker reporting a fault in a panel that did validate – a balloon over the word limit, say – needs to know where it is... admonition:: Example
document = parse_script_document( … “—\ncast: {A: {reference: alice}}\n—\nPANEL 1\nA\nHi.\n” … ) document.lines[“1”] PanelLines(heading=4, events=(5,))
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.frontends.script_front.ScriptDocument``
.. py:function:: parse_script(text, *, source=None)
- module:
scenet.frontends.script_front
Parse comic script into one validated panel per PANEL heading.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.PanelIR`]`
.. py:function:: load_script(path)
- module:
scenet.frontends.script_front
Read and validate a comic script from disk.
- type path:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path``
- param path:
A
*.scriptfile in the comic-script format writers already use.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.PanelIR`]`
- returns:
Panel name to scene graph, in the order the panels appear.
- raises OSError:
The file cannot be read.
- raises ScriptSyntaxError:
The script cannot be parsed – dialogue before the first
PANELheading, or noPANELheadings at all.