# Internote — Chalk manual > Chalk is the language internotes are written in: prose first, with a canvas beside it. The manual is its reference — every construct, the value types its attributes take — and the guides to writing an internote well. Each link below is one page as Markdown. The whole manual is one file at https://internote.co/manual/llms-full.txt. ## Indexes - [Value types](https://internote.co/manual/types.md): Every value type an attribute parses its text as, and what each accepts. - [Packs](https://internote.co/manual/packs.md): Every pack, with the constructs and datasets it exports. ## Syntax - [Grammar](https://internote.co/manual/guide/grammar.md): How a line is read as prose or a construct: the head and its three sections, marker spellings, escapes and sigils. - [Body & detail](https://internote.co/manual/guide/body-and-detail.md): The { } and [ ] slots: which constructs take each, what a slot accepts, what a scene keeps to each side, and inline content in attributes. - [Attributes](https://internote.co/manual/guide/attributes.md): Writing the attribute group, the implicit :value and bare booleans, how names and aliases match, how a value is parsed by its type, maps, and defaults set for several constructs at once. - [Comments](https://internote.co/manual/guide/comments.md): // for a line and @ignore for a block, and the literal bodies where // is kept as text. - [@ignore](https://internote.co/manual/directives/ignore.md): A block comment. The body is dropped without being read, so what is inside need not compile, but its braces must balance. Like any directive it begins its own line, and it may stand between scenes, in a scene's body or in an environment. In the middle of prose it ends the paragraph before it. It takes no attributes and no `:value`. ## Language features - [References](https://internote.co/manual/guide/references.md): Naming a construct with #id, reaching what an id names by a binding or an expression, member access, and the derived attributes a construct publishes as it renders. - [Expressions](https://internote.co/manual/guide/expressions.md): Computing a value in {{…}}: its values and operators, the names it reads — @let constants among them — and when it is worked out, as the document compiles or as the page renders. - [@let](https://internote.co/manual/directives/let.md): Declares named constants, read back with `{{name}}`. - [Canvas expressions](https://internote.co/manual/guide/canvas-expressions.md): The maths written bare in a canvas attribute — a curve’s expression, a point’s coordinates — its variables, the parameters controls set, and its function set. - [Control structures](https://internote.co/manual/guide/control-structures.md): Chalk’s two control structures, decided as the document compiles: @for repeats source — a count, a range or each row of a dataset — and @if keeps or drops it. - [@for](https://internote.co/manual/directives/for.md): Repeats its body a number of times, over a range, or once per row of a dataset. - [@if](https://internote.co/manual/directives/if.md): Keeps its body when its condition holds, and its detail, if it has one, when it fails. - [Modularity](https://internote.co/manual/guide/modularity.md): Pieces written once and used again: templates with @define, attribute defaults with @preset, packs of ready-made constructs and datasets with @use, and .part.chalk files of your own with @include. - [@define](https://internote.co/manual/directives/define.md): Defines a template: a new construct whose uses expand to the Chalk written in its body. - [@preset](https://internote.co/manual/directives/preset.md): Declares a group of attribute values that constructs take by type or by name. - [@use](https://internote.co/manual/directives/use.md): Imports a pack, whose constructs and datasets are then called under the pack's name. - [@include](https://internote.co/manual/directives/include.md): Splices an attached partial, a `.part.chalk` file, into the document where the directive is written. - [Datasets](https://internote.co/manual/guide/datasets.md): Declaring a dataset with @data, and reaching it whole, by column, row by row, over time, joined to regions and from packs. - [@data](https://internote.co/manual/directives/data.md): Declares a dataset under an `#id`: a table of values written inline, attached as a `.csv` or read from a URL, or boundaries attached as a `.geojson`. ## The document - [Document header](https://internote.co/manual/header.md): The starred attribute group that opens an internote and names it. - [Scenes & steps](https://internote.co/manual/guide/scenes-and-steps.md): A scene’s narrative and canvas, the steps it is divided into, and what belongs to the whole scene. - [scene](https://internote.co/manual/elements/scene.md): A body of narrative and an optional detail that declares its canvas. - [step](https://internote.co/manual/elements/step.md): A step marker: `===` on a line of its own in a scene's narrative, where the scene's next step begins. - [Citations](https://internote.co/manual/guide/citations.md): Declaring a source with cite, citing it in prose with !cite, and the reference list built from both. - [cite](https://internote.co/manual/elements/cite.md): One source the internote draws on, declared beside the scenes. - [!cite](https://internote.co/manual/inline/cite.md): A citation in prose: a numbered badge that opens the internote's reference drawer at the source it names. - [Maps](https://internote.co/manual/guide/maps.md): A collection of internotes drawn as a graph of the references between them: making one, how references become its edges, and the six ways to arrange it. - [internote](https://internote.co/manual/elements/internote.md): A reference to another internote, written as a block on a line of its own. - [!internote](https://internote.co/manual/inline/internote.md): A reference to another internote, written inline inside a sentence. ## Text - [divider](https://internote.co/manual/elements/divider.md): A horizontal rule between passages of a scene's narrative, written `---` on a line of its own. - [h1](https://internote.co/manual/elements/h1.md): The first of four heading levels, written `# ` at the start of a line. - [h2](https://internote.co/manual/elements/h2.md): The second heading level, written `## ` at the start of a line. - [h3](https://internote.co/manual/elements/h3.md): The third heading level, written `### ` at the start of a line. - [h4](https://internote.co/manual/elements/h4.md): The fourth and smallest heading level, written `#### ` at the start of a line. - [list](https://internote.co/manual/elements/list.md): A bulleted or numbered list, one item per line. - [paragraph](https://internote.co/manual/elements/paragraph.md): A block of prose, written bare. - [equation](https://internote.co/manual/elements/equation.md): Display maths: a block of LaTeX on a line of its own, centred and typeset with KaTeX. - [!latex](https://internote.co/manual/inline/latex.md): Maths inside a sentence: LaTeX between single dollar signs, typeset with KaTeX. - [definition](https://internote.co/manual/elements/definition.md): A callout defining a term. - [example](https://internote.co/manual/elements/example.md): A callout holding a worked example. - [note](https://internote.co/manual/elements/note.md): A callout for an aside from the main line of argument. - [panel](https://internote.co/manual/elements/panel.md): A callout with no label or number of its own, in a colour the author chooses. - [task](https://internote.co/manual/elements/task.md): A callout setting the reader an exercise. - [theorem](https://internote.co/manual/elements/theorem.md): A callout stating a formal result, with its proof held back in the detail. - [warning](https://internote.co/manual/elements/warning.md): A callout warning of a hazard: what goes wrong if the reader gets a step wrong, and what it costs. - [!bold](https://internote.co/manual/inline/bold.md): Bold text, written between double asterisks: **text**. - [!footnote](https://internote.co/manual/inline/footnote.md): An aside attached to a run of prose. - [!inline-code](https://internote.co/manual/inline/inline-code.md): A run of text in the monospace face, written between backticks. - [!italic](https://internote.co/manual/inline/italic.md): Italic text, written between single asterisks: *text*. - [!link](https://internote.co/manual/inline/link.md): A hyperlink on a run of text. ## Canvas - [Layout & content](https://internote.co/manual/guide/layout-and-content.md): What a scene’s canvas holds, two environments side by side, a grid of them, and the tables and images that stand outside any environment. - [grid](https://internote.co/manual/elements/grid.md): A layout of a scene's canvas environments in rows and columns, up to three by three. - [image](https://internote.co/manual/elements/image.md): An image on the canvas, with an optional caption. - [table](https://internote.co/manual/elements/table.md): A table on the canvas, its rows written in the body or bound from an `@data` dataset. - [Colours](https://internote.co/manual/guide/colours.md): The micronodes only canvas text takes: the nine colours, highlight and symbol. - [!blue](https://internote.co/manual/families/text-colours.md): Nine micronodes that colour a run of text on a scene's canvas, one per hue: !red{…}, !orange{…}, !yellow{…}, !green{…}, !teal{…}, !blue{…}, !purple{…}, !pink{…} and !grey{…}. Each takes an inline body and no attributes. Canvas-only: one anywhere in a scene's narrative is a compile error. - [!highlight](https://internote.co/manual/inline/highlight.md): A tinted band behind a run of canvas text. - [!symbol](https://internote.co/manual/inline/symbol.md): A glyph in a run of canvas text, sitting on the line like a letter. - [Styling marks from data](https://internote.co/manual/guide/styling-from-data.md): A mark’s colour, size, shape, width and opacity from its data: each a style attribute, holding a look, a list of looks, or a reading applied with -> to a map, a ramp or an expression. - [circuit](https://internote.co/manual/elements/circuit.md): A canvas environment holding a direct-current circuit the reader operates: components in `series` and `parallel`, or placed by hand on a grid. - [ammeter](https://internote.co/manual/elements/ammeter.md): An ideal ammeter: it takes no voltage, and shows the current through it beneath its label. - [battery](https://internote.co/manual/elements/battery.md): Cells joined end to end, drawn as two: a cell whose `emf:` is the whole battery's. - [breaker](https://internote.co/manual/elements/breaker.md): A switch the reader opens and closes by clicking it, drawn as a blade that swings onto its contact. - [bulb](https://internote.co/manual/elements/bulb.md): A filament lamp, drawn as a circle crossed through, that glows by the power it takes. - [capacitor](https://internote.co/manual/elements/capacitor.md): Two plates that store charge, charging and discharging through what is joined to them. - [cell](https://internote.co/manual/elements/cell.md): A single cell that drives a current round a circuit, drawn as its long plate and short one. - [lead](https://internote.co/manual/elements/lead.md): A bare wire between two grid points, in a circuit placed by hand. - [parallel](https://internote.co/manual/elements/parallel.md): Branches joined between the same two points, drawn as rungs between two rails. - [resistor](https://internote.co/manual/elements/resistor.md): A resistor, drawn as the IEC box, lit while a current runs through it. - [series](https://internote.co/manual/elements/series.md): Components joined end to end, each to the next: a branch of a `parallel` that holds more than one. - [voltmeter](https://internote.co/manual/elements/voltmeter.md): An ideal voltmeter: no current flows through it, and it shows the voltage across it beneath its label. - [code](https://internote.co/manual/elements/code.md): A canvas environment that shows code, written as `lines` chunks joined into one file. - [lines](https://internote.co/manual/elements/lines.md): A chunk of code inside a `code` environment. - [flowchart](https://internote.co/manual/elements/flowchart.md): A canvas environment that draws a flowchart, a tree or an entity–relationship diagram from boxes and the arrows between them. - [arrow](https://internote.co/manual/elements/arrow.md): A relation between two boxes in a flowchart, drawn as a line the environment routes. - [box](https://internote.co/manual/elements/box.md): A thing in a flowchart, drawn as a shape holding its text. - [graph](https://internote.co/manual/elements/graph.md): A plotting environment, its head naming the plane: `x`, `xy` (the default), `argand`, `polar` or `xyz`. - [axis.band](https://internote.co/manual/elements/axis.band.md): A shaded interval of an axis, across the whole plot. - [axis.brace](https://internote.co/manual/elements/axis.brace.md): A curly brace naming an interval on an axis, drawn beyond the tick numbers. - [axis.break](https://internote.co/manual/elements/axis.break.md): A cut that removes an interval from an axis and closes the axis up around it. - [axis.label](https://internote.co/manual/elements/axis.label.md): A name for a value on an axis, set in place of its tick number. - [area](https://internote.co/manual/elements/area.md): A series filled down to the baseline, or to a second series: the amount under the readings, with its top edge stroked. - [bar](https://internote.co/manual/elements/bar.md): Bars standing at the names of one axis, each reaching to its value along the other. - [boxplot](https://internote.co/manual/elements/boxplot.md): A sample drawn as its five-number summary: a box across the quartiles, the median ruled across it, and whiskers. - [density](https://internote.co/manual/elements/density.md): A Gaussian kernel density estimate of a sample, drawn as one curve. - [fit](https://internote.co/manual/elements/fit.md): The least-squares polynomial through the readings of one `scatter`; in space, the regression surface. - [heatmap](https://internote.co/manual/elements/heatmap.md): A grid of cells, one value each, painted from a ramp. - [histogram](https://internote.co/manual/elements/histogram.md): A sample counted into bins and drawn as bars, each as tall as its count. - [pictograph](https://internote.co/manual/elements/pictograph.md): A quantity drawn as repeated glyphs, each standing for `per` of it: a bar chart counted out in glyphs on the plane, or a hemicycle on the polar plane. - [lollipop](https://internote.co/manual/elements/lollipop.md): A value drawn as a stem from the baseline with a dot at its end. - [scatter](https://internote.co/manual/elements/scatter.md): A set of readings drawn as markers. - [violin](https://internote.co/manual/elements/violin.md): A Gaussian kernel density estimate of a sample, mirrored about the line it stands on. - [contour](https://internote.co/manual/elements/contour.md): The level sets of a function of the plane. - [curve](https://internote.co/manual/elements/curve.md): A curve on a graph: a function, an equation, or a position in t. - [field](https://internote.co/manual/elements/field.md): A differential equation drawn as the directions it gives, with the solutions that follow them. - [integral](https://internote.co/manual/elements/integral.md): The region under a function, shaded, with its signed area; in space, the solid under a surface, with its volume. - [surface](https://internote.co/manual/elements/surface.md): A function of the plane, shaded; in space, the surface itself. - [angle](https://internote.co/manual/elements/angle.md): The angle at a vertex, marked with an arc or a right-angle square, and measured. - [brace](https://internote.co/manual/elements/brace.md): A curly brace spanning from one point to another, with its label at the tip. - [line](https://internote.co/manual/elements/line.md): A path through readings in the order written. - [point](https://internote.co/manual/elements/point.md): A single point. - [polygon](https://internote.co/manual/elements/polygon.md): A closed shape whose outline is its vertex series. - [segment](https://internote.co/manual/elements/segment.md): A straight line between two points, stopping at both. - [text](https://internote.co/manual/elements/text.md): Freestanding text at a position: a mark that is nothing but its label. - [vector](https://internote.co/manual/elements/vector.md): An arrow from a tail along a displacement. - [Shapes](https://internote.co/manual/families/shapes.md): Closed shape marks for a graph environment. They are positioned the same way, take the same attributes and animate identically — the outline is the only difference. - [circle](https://internote.co/manual/elements/circle.md): A circle centred at a position on a graph. - [diamond](https://internote.co/manual/elements/diamond.md): A diamond centred at a position on a graph. - [hexagon](https://internote.co/manual/elements/hexagon.md): A hexagon centred at a position on a graph. - [rectangle](https://internote.co/manual/elements/rectangle.md): A rectangle centred at a position on a graph. - [square](https://internote.co/manual/elements/square.md): A square centred at a position on a graph. - [star](https://internote.co/manual/elements/star.md): A five-pointed star centred at a position on a graph. - [triangle](https://internote.co/manual/elements/triangle.md): A triangle centred at a position on a graph. - [polyhedron](https://internote.co/manual/elements/polyhedron.md): A solid with flat faces: the convex hull of its vertices, or one of the five regular solids by name. - [revolution](https://internote.co/manual/elements/revolution.md): The solid swept out by turning the region under y = f(x) about an axis. - [section](https://internote.co/manual/elements/section.md): A cross-section of an `integral`'s solid or a `revolution`, where a plane x = c or y = c cuts it. - [shell](https://internote.co/manual/elements/shell.md): The cylindrical shell at radius r of a `revolution` about y, as tall as the profile there. - [logic](https://internote.co/manual/elements/logic.md): A canvas environment holding a logic circuit the reader operates: parts and the `wire`s between them. - [alu](https://internote.co/manual/elements/alu.md): An arithmetic logic unit, drawn for a datapath and computing nothing. - [clock](https://internote.co/manual/elements/clock.md): An input to a logic circuit that flips itself, as a square wave. - [flipflop](https://internote.co/manual/elements/flipflop.md): A D flip-flop: on each rising edge of its `clock`, its output `q` takes the level at its `d` and holds it until the next. - [gate](https://internote.co/manual/elements/gate.md): A logic gate, drawn as its schematic symbol turned to the flow. - [lamp](https://internote.co/manual/elements/lamp.md): An output of a logic circuit, drawn as an indicator lamp that lights when its wire carries 1. - [mux](https://internote.co/manual/elements/mux.md): A multiplexer: its output is whichever data input its select lines choose. - [switch](https://internote.co/manual/elements/switch.md): An input to a logic circuit that the reader flips by clicking it. - [wire](https://internote.co/manual/elements/wire.md): A connection from one part's output to another's input in a logic circuit. - [network](https://internote.co/manual/elements/network.md): A canvas environment that draws a network: a graph in the discrete-maths sense, such as a social or citation network or a causal diagram. - [edge](https://internote.co/manual/elements/edge.md): A relation between two vertices in a network. - [edges](https://internote.co/manual/elements/edges.md): An edge list bound from `@data`, one edge per row. - [path](https://internote.co/manual/elements/path.md): A route through a network, named by the vertices or the edges it passes. - [vertex](https://internote.co/manual/elements/vertex.md): A point in a network. - [vertices](https://internote.co/manual/elements/vertices.md): A table of vertices bound from `@data`, one vertex per row. - [region](https://internote.co/manual/elements/region.md): A canvas environment that draws a map: boundaries, and the overlays set over them. - [arc](https://internote.co/manual/elements/arc.md): The great-circle route between two places on a `region` map, the shortest way over the earth. - [choropleth](https://internote.co/manual/elements/choropleth.md): A dataset column joined onto a map's regions and shaded by value. - [marker](https://internote.co/manual/elements/marker.md): A point on the earth, placed singly or one per row of a dataset. ## Motion & interaction - [Motion](https://internote.co/manual/guide/motion.md): A scene’s clock, the anchors that place a change on it, the wrapping cues and the cues on a value, and how each step plays. - [cue](https://internote.co/manual/elements/cue.md): Presence on the timeline: what it wraps fades in at `in:` and out at `out:`. - [cue.draw](https://internote.co/manual/elements/cue.draw.md): Presence drawn rather than faded: what it wraps is drawn in along its strokes. - [cue.highlight](https://internote.co/manual/elements/cue.highlight.md): A cue that draws attention to what it wraps with rings pushed out from its edge. - [!cue.highlight](https://internote.co/manual/inline/cue.highlight.md): A wash drawn across a run of canvas words from one anchor to another. - [cue.spotlight](https://internote.co/manual/elements/cue.spotlight.md): A cue that dims everything else in the environment and leaves what it wraps lit. On a graph the grid and the rules `axis.label` draws dim with the unlit marks, and the axes, their numbers, captions and the named values themselves stay: they are what the lit marks are read against. - [cue.trace](https://internote.co/manual/elements/cue.trace.md): A cue that carries its content along a path on a graph. - [cue.write](https://internote.co/manual/elements/cue.write.md): A cue that writes its content in, in reading order. - [!cue.to](https://internote.co/manual/cues/cue.to.md): A cue written after an animatable attribute's value that moves the attribute to a new value. - [!cue.zoom](https://internote.co/manual/cues/cue.zoom.md): A cue that moves a graph's window after outlining where it is going. - [Controls](https://internote.co/manual/guide/controls.md): The controls that set a scene’s parameters — moved by the reader, or by the scene through a cue control — where their stops come from, and how their values read. - [slider](https://internote.co/manual/elements/slider.md): A control that declares a parameter and gives the reader a track to move it along, as a row in the scene's footer. - [cue.slider](https://internote.co/manual/elements/cue.slider.md): A `slider` the scene moves along its range. - [selector](https://internote.co/manual/elements/selector.md): A control that declares a parameter whose stops are written out with `options:` or taken from a column with `column:`. - [cue.selector](https://internote.co/manual/elements/cue.selector.md): A `selector` the scene steps through, one choice at a time. - [Questions](https://internote.co/manual/guide/questions.md): Asking the reader: where a question goes, text, choice and maths answers, how an answer is checked, quizzes, and reading the result in prose. - [question](https://internote.co/manual/elements/question.md): A question the reader answers, written in a scene's detail. - [option](https://internote.co/manual/elements/option.md): One answer a `choice` question offers. - [quiz](https://internote.co/manual/elements/quiz.md): A run of questions the reader is shown one at a time, written in a scene's detail. ## Writing internotes - [What a document covers](https://internote.co/manual/guide/document-scope.md): One topic, named by the title, with the constructs and the length that topic needs. - [Scenes and what each shows](https://internote.co/manual/guide/what-a-scene-shows.md): A canvas makes one point at a time, a second idea is a second scene, and a detail is optional. - [Prose & canvas state](https://internote.co/manual/guide/narrative-contract.md): Prose describes the state the canvas is in and names what it shows, never the controls or where things sit. - [Prose & headings](https://internote.co/manual/guide/writing-prose.md): What the narrative carries that the picture cannot, headings a reader can navigate by, and maths as LaTeX. - [Callouts](https://internote.co/manual/guide/callouts.md): Prose around every callout, one job each, a definition written to stand in a glossary, and which callout a result, a hazard or a set-apart panel takes. - [Reading computed values in prose](https://internote.co/manual/guide/honest-numbers.md): A number the canvas computes is read from the construct with a {{…}} expression, and rounded for the claim. - [Selecting canvas content](https://internote.co/manual/guide/earning-a-place.md): A mark belongs on the canvas when seeing it changes what the reader understands, and the detail holds as a picture on its own. - [Framing a readable graph](https://internote.co/manual/guide/readable-graphs.md): When to write a domain, the defaults left alone, naming a series, the ticks the prose reads, and one meaning per hue. - [Steps, timers, sweeps & parameters](https://internote.co/manual/guide/steps-and-parameters.md): New content on the step that introduces it, timers for timed motion, sweeps for a change the prose describes, and parameters where one sentence holds across the range. - [Questions & tasks](https://internote.co/manual/guide/questions-and-tasks.md): A question beside only what it needs, opposite the task that sets it, after the reasoning rather than the answer. - [Shaping a map from its subject](https://internote.co/manual/guide/shaping-a-map.md): A map takes its shape from the dependencies between the ideas it covers, not from a template of counts. - [One home for each result and term](https://internote.co/manual/guide/one-home-per-result.md): Across a map, each worked result is derived in one internote and each term defined in one; the rest quote and link. - [Checking a document's claims](https://internote.co/manual/guide/checked-claims.md): Every other number worked out, every output quoted from a run, every dataset read and attached whole, every external fact checked and cited, or cut. - [Source style](https://internote.co/manual/guide/source-style.md): The conventions that keep a .chalk file legible to the next person editing it by hand. - [Writing for print](https://internote.co/manual/guide/writing-for-print.md): How an internote is set as a printed document — its designs, canvases as figures, citations, pages and contents — and how to write one that reads well both ways. - [The final pass](https://internote.co/manual/guide/final-pass.md): What the compiler checks, with its diagnostics, and the judgements nothing checks, each linked to its reason.