Code demonstrates, never computes

A code pane shows a procedure. Its output is authored — nothing it contains produces canvas content.

#The rule

A code pane demonstrates a procedure. It never produces content. Nothing written in a canvas.code pane runs to make a plot, feed a graph, or generate data.

#What this buys

It is the line between a document medium and a compute notebook, and holding it is what keeps an internote free of kernels, environments, package versions and execution state. A reader opening a five-year-old internote sees what its author saw. A reader opening a five-year-old notebook sees whatever their environment does today, which is usually an error.

It also keeps authorship honest in the same way Honest numbers does, from the other direction: a graph is authored in Chalk and says what the author meant it to say, rather than being whatever a script happened to emit.

#Authoring the output

Where the reader should see a result, write it — as a comment, or as a later chunk that states what an interpreter would print. It is authored content, exactly like the prose, and it carries the same obligation to be true.

canvas.code{
    lines{
        z, log_c = np.polyfit(log_area, log_species, 1)
    }
    cue.type{
        lines{
            print(z)   # 0.34
        }
    }(
        in: 1
    )
}(
    language: python
)

#Keeping code and canvas in agreement

Since neither half computes the other, they agree only because you made them. Two things help. Splice shared values in with {{ }} so the code and the canvas read from one source — a @data column reaches a literal code body exactly as it reaches prose. And where a number in the code is also a number in the argument, prefer a @let constant over typing it twice.

@data#survey:galapagos-plants-1973.csv

canvas.code{
    lines{
        area = np.array([{{#survey.area}}])
    }
}(
    language: python
)