"announcement" notation

[damaxwell]

Description

Syntax sugar to apply a function and an optional label to extended content.

Use Case

Background

Typst offers trailing content block notation to conveniently pass content to a function:

#alert(fill:red)[
  Printer lp0 is on fire.
]

is syntax sugar for

#alert(fill:red, [
  Printer lp0 is on fire.
])

This feature allows for styling and customization of larger content blocks

#theorem(alt: [Smith's Lemma])[
    Let $a$, $b$, and $c$ be integers. ...
]

It only applies, however, to a trailing content block, delimited by [ ]. Notably, it does not apply to mathematics, which is delimited by $ $, and hence notation such as

#customized_eq$
    ...
$

is not available. Instead, we have

#customized_eq[$
    ...
$]

but the trailing ] is less than convenient. Adding or removing styling of a displayed equation requires visiting both the beginning and the ending of the display, despite the fact that it is already well delimited by its dollar signs. Nevertheless, there is not uniform support for extending trailing content block notation to mathematics, #1856. Part of the hesitancy toward #1856 stems from the lack of visual appeal of trailing material delimited by fence-like $s instead of proper asymmetric delimiters.

Because math.equation only offers a few features at the moment, there is limited need for styling and customization. Nevertheless, the number of knobs will grow in time as line numbering and additional control of alignment are added. Even today, turning on/off numbering for a single equation has friction. Probably something like

#let nonumber(body) = {set math.equation(numbering: none); body}

#nonumber($
y = x^2 - 2x + 5
$)

is the best we have. It works, but is a mild hassle and is visually less than ideal.

Proposal

This feature request is a proposal to add "annoncement" syntax, inspired by some of the conversation surrounding #1856, to apply a function and an optional label to extended content. The examples below illustrate its use, and the rules are laid out concretely after the examples.

#nonumber:
$
y = x^2 - 2x + 5
$

#amsmath.align(line-height: 110%):
$
a & = b & c &= d\
  & < e &   &< f
$

#theorem(alt: [Fermat]): <fermat-little>
[
    Suppose $p$ is prime.  Then ...
    ...
    ...
]

The proposed rules (which are meant to be very restrictive, and which could be loosened now or in the future if desired):

• The notation is only available in markup mode (not in math, and not in code).
• It is signified by a function call that is immediately followed by a colon. Arguments to the function, delimited by ( ), are permitted, in which case the colon follows the ). Otherwise, the colon immediately follows the function name.
• Leaving aside the optional label for the moment, following the colon there is an arbitrary amount of whitespace followed by either a content block in a [ ] pair or a mathematics block in a $ $ pair.
• The notation is de-sugared during parsing. Its sole purpose is to aid authors writing their literal content.
• Whitespace following the colon and up to the [ or $ is interpreted in the code sense: it is not significant.
• The notation

  #foo: $ bar $
  

  is simply syntax sugar for #foo($ bar $). Similarly,

  #foo(baz): $ bar $
  

  is #foo(baz, $ bar $).
• Standard trailing content block notation is not permitted in combination with announcement notation, so#foo[bar]: is the same as #foo([bar])\:. This restriction is inessential and could be relaxed.
• Unlike trailing content block notation, which permits an arbitrary number of trailing block arguments (#foo[bar][baz][blat]), only a single trailing argument is available in announcment notation. This restriction is essential.
• A label, preceeded and followed by arbitrary non-significant whitespace, can appear between the colon and the content/math block.
• The notation #foo(fill: red) <bar> [baz] is syntax sugar for #foo(fill: red, [baz])<bar>.

Although the notation is intended to be used for a large trailing block, and is ideally started on a line by itself with the announced content on the following line, none of this is enforced.

The optional label part of the proposal is motivated by the primary use case of a large trailing block. Although final labels mesh well with headings and other short labeled content, they are less convenient for extended content (theorem statements, large equations) where all customization occurs at the beginning with the sole exeption of the label, which can be a paragraph or two away at the end.

[PgBiel]

Worth mentioning that it seems that AsciiDoc, which apparently inspired part of Typst's syntax, has something similar, which we could take inspiration from: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#admonitions

[Jollywatt]

This looks quite similar to this idea: #530 (reply in thread)

Basic idea is “why stop at just content and math blocks?” You could use colons to signify what follows is the final argument. In particular, this could be composed, like so:

// current
align(center, box(stroke: 1pt, text(size: 14pt, [Lorem Ipsum])))
// proposed
align(center):
    box(stroke: 1pt):
        text(size: 14pt)[Lorem Ipsum]

[wrzian]

I believe the original issue is now solved by the release of the wrap-indent package! (typst/packages#602) which lets you write the following:

#import "@preview/wrap-indent:0.1.0": wrap-in, allow-wrapping
#show terms.item: allow-wrapping

#set page(height: auto, width: auto, margin: 0.25in)

/ #wrap-in(rect):
  A *custom block* using the `wrap-in` function

  with indented text
  over multiple lines
And un-indented text exits the block.

However, it might be good to keep this issue open to discuss the implications (good and bad) of implementing this as native Typst syntax.

You can see some more thoughts on that in my write-up here: https://typst.app/project/r5ogFas7lj7E48iHw_M4yh