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.yaml file.

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:object

A 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.pages is 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 over inheritance.

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: and pages: 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: and pages: are not panel defaults, unlike every other key beside panels:, 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.yaml file. A single-panel document also works and comes back as one entry named panel.

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.yaml file, 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:object

Something 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 É as E and 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:object

Where 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 script was 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:object

A 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_script is 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 *.script file 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 PANEL heading, or no PANEL headings at all.