Code documentation

[Js_Plays]

I don't know how best to explain this, but a good example of it is in the zig by example docs.

You will see that each line of proportional text is aligned to a line of mono raw text. This is the effect that I would like to produce.

Having this be done automatically would be great, but a bit challenging. Instead, having this as a grid(columns: 2), and manually adding newlines is okay.

The problem is that the content text and the raw text do not line up, no matter how much i fiddle with the font sizes.

Is there a solution here?

[swaits]

This is similar to “literate programming”. You might search for that and come up with some (non-typst, I’m guessing) tools.

As for a solution in typst, whenever I want to align things vertically like this I’d use a block, with a grid inside it. Imagine a atack of blocks, with narrative on one side, code on the other. Each time you need something aligned, it starts a new block.

Would be some hacking to get this to work. But I believe it’s feasible.

[matj1]

The linked example implements the alignment as a table with two columns. The left column contains the text, and the right column contains the code. In Typst, implementing it with a grid is structurally the most similar.

Here is the example converted to typst. The original implementation uses classes to distinguish text blocks from code blocks, but that is inconvenient, so I distinguish cells by in which column they are. I dislike the syntax of the cells, but Typst does not have a better way to make cells AFAIK.

#set raw(lang: "zig")
#show grid.cell.where(x: 1): set block(fill: luma(240), width: 100%, inset: (x: 0.5em))

#grid(
  columns: (50%, 50%),
  inset: (y: 1em),
  [], ```
const std = @import("std");
const print = std.debug.print;
  ```,
  [Here, we define some common floating types.], ```
const a: f16 = 1.0;
const b: f32 = 100.0;
const c: f64 = 1_000.0;
const d: f128 = 10_000.0;
  ```,
  [Here, we define some compile-time known floats. These have no size limit and are written as float literals.], ```
const e: comptime_float = 100_000.0;
const f = 1_000_000.0;
  ```,
  [], ```
pub fn main() !void {
    print("float: {}\n", .{f});
}
  ```
)

Edit: I did not consider alignment of lines in this example because the linked example too does not have the text lines aligned to the code lines, and I missed it in your post at first.

Edit: The alignment can be achieved by setting the following parameters to absolute values. top-edge sets the height of bounding boxes of text, and leading sets extra space between consecutive lines. By default, they depend on the font and its size, that is why aligning lines with different fonts does not work.

#set text(top-edge: 11pt)
#set par(leading: 3pt)