2.1 Notation
Getting Started provides many examples of Rhombus notation. Here, we recap the main points.
The rhombus/scribble language is like the rhombus language, but with three key differences:
A #lang rhombus/scribble module body starts in text mode as if inside @{} (see At-Notation Using @), which means that @ escapes must be used to write Rhombus definitions or expressions for implementing a document.
Since it starts in text mode, the body of a #lang rhombus/scribble module produces a mixture of string literals and other forms. Those results are gathered together and decoded as described in Decoding Parts, Flow Blocks, and Content to construct a document representation as described in Document Structure.
The rhombus/scribble module provides all of the binding of rhombus plus a group of bindings for writing documents. Those bindings are described in Core Scribble. The rhombus/scribble/manual module provides even more bindings as described in Documentation Scribble.
Functions and forms added by rhombus/scribble to rhombus are primarily intended to be used with @ notation. For example, the italic function could be called as italic(["Hello"]), but the intended use syntax is @italic{Hello}.
Some functions accept extra arguments, especially keyword-based optional arguments, and those can be supplied in parentheses before a final text argument written with {}. For example,
@hyperlink("https://rhombus-lang.org", ~underline: #true){Rhombus}
supplies a string argument and an ~underline keyword argument to hyperlink, while ["Rhombus"] (as written in {} with @ notation) is provided as the text of the hyperlink.
The text content of a function like italic or hyperlink is represented by an argument with the PreContent annotation, which allows a mixture of strings, Element results as produced by nested calls to functions like italic and hyperlink, lists of PreContent values, and a few other kinds of values. The “Pre” part of PreContent refers to the fact that string arguments are lightly decoded, turning --- into an em dash and `` into curly open quotes, for example.
The PreContent annotation roughly corresponds to a paragraph in output. Functions like nested or item take PreFlow arguments, because they accept with multiple paragraphs of text. Functions like nested and item are still mean to be used with @ notation and {}, but part of the decoding of a PreFlow is recognizing two newlines in a row (possibly with whitespace in between) to create a break between paragraphs. The immediate, non-definition content of a #lang rhombus/scribble module is implicitly a PreFlow.
Some functions, such as secref, do not have text-content arguments with an immediate PreContent or PreFlow annotation, and so they are not meant to be used with {} arguments. The tabular function is another example that is normally used without {}, because it works in terms of a list of list of PreFlows.