Clarify grid.column-gutter docs

[tingerrr]

Description

The documentation for grid states that the default value for grid.column-gutter is (), yet when setting it explicitly, it changes the behavior of grid.

#grid(
  columns: 2,
  gutter: 1em,
  box(stroke: red)[A],
  box(stroke: red)[B],
)

#grid(
  columns: 2,
  gutter: 1em,
  column-gutter: (),
  box(stroke: red)[A],
  box(stroke: red)[B],
)

My understanding is that, passing the default value myself should not change how the gird behaves.

Reproduction URL

No response

Operating system

No response

Typst version

• I am using the latest version of Typst

[laurmaedje]

The gutter variable overrides the column-gutter. Basically gutter: X is equivalent to passing column-gutter: X, row-gutter: X. So a desugared version of your example is

#grid(
  columns: 2,
  column-gutter: 1em,
  row-gutter: 1em,
  box(stroke: red)[A],
  box(stroke: red)[B],
)

#grid(
  columns: 2,
  column-gutter: (),
  row-gutter: 1em,
  box(stroke: red)[A],
  box(stroke: red)[B],
)

And if you now remove column-gutter: () in the second example, nothing happens, as expected.

[tingerrr]

The docs ought to be clear about that then. When providing wrapper functions that don't use argument sinks, this is surprising.

[laurmaedje]

The docs ought to be clear about that then.

How do you think we should word it? Right now it says "Takes precedence over gutter." for column-gutter.

When providing wrapper functions that don't use argument sinks, this is surprising.

Can you provide an example?

[tingerrr]

How do you think we should word it? Right now it says "Takes precedence over gutter." for column-gutter.

I think it should be noted on gutter and {column,row}-gutter that gutter is a shorthand passing the specific ones both, such that auto is not a fallback to gutter, maybe. At least that's what I initially assumed.

Can you provide an example?

Simplified, because this is a for a library, it is important for both tidy and argument validation to not use a sink here:

#let subfigure-grid(
  // figure arguments with defaults
  // ...

  // grid arguments with defaults
  // ...

  // figures
  // ...
) = {
  // arg validation with explicit arguments
  // passing all arguments straight through with their default values
}

[laurmaedje]

We can reword the docs. I'll reopen to track this.