diff options
Diffstat (limited to 'docs/src/tutorial/2-formatting.md')
| -rw-r--r-- | docs/src/tutorial/2-formatting.md | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/docs/src/tutorial/2-formatting.md b/docs/src/tutorial/2-formatting.md new file mode 100644 index 00000000..dd0352bd --- /dev/null +++ b/docs/src/tutorial/2-formatting.md @@ -0,0 +1,273 @@ +--- +description: Typst's tutorial. +--- + +# Formatting +So far, you have written a report with some text, a few equations and images. +However, it still looks very plain. Your teaching assistant does not yet know +that you are using a new typesetting system, and you want your report to fit in +with the other student's submissions. In this chapter, we will see how to format +your report using Typst's styling system. + +## Set rules +As we have seen in the previous chapter, Typst has functions that _insert_ +content (e.g. the [`image`]($func/image) function) and others that _manipulate_ +content that they received as arguments (e.g. the [`align`]($func/align) +function). The first impulse you might have when you want, for example, to +justify the report, could be to look for a function that does that and wrap the +complete document in it. + +```example +#par(justify: true)[ + = Background + In the case of glaciers, fluid + dynamics principles can be used + to understand how the movement + and behavior of the ice is + influenced by factors such as + temperature, pressure, and the + presence of other fluids (such as + water). +] +``` + +As seen above, that works. The [`par`]($func/par) function justifies all +paragraphs within it. However, wrapping the document in countless functions and +applying styles selectively and in-situ can quickly become cumbersome. + +Fortunately, Typst has a more elegant solution. With _set rules,_ you can apply +style properties to all occurrences of some kind of content. You write a set +rule by entering the `{set}` keyword, followed by the name of the function whose +properties you want to set, and a list of arguments in parentheses. + +```example +#set par(justify: true) + += Background +In the case of glaciers, fluid +dynamics principles can be used +to understand how the movement +and behavior of the ice is +influenced by factors such as +temperature, pressure, and the +presence of other fluids (such as +water). +``` + +<div class="info-box"> + +Want to know in more technical terms what is happening here? + +Set rules can be conceptualized as setting default values +for some of the parameters of a function for all future +uses of that function. +</div> + +## The autocomplete panel +If you followed along and tried a few things in the app, you might have noticed +that always after you enter a `#` character, a panel pops up to show you the +available functions, and, within an argument list, the available parameters. +That's the autocomplete panel. It can be very useful while you are writing your +document: You can apply its suggestions by hitting the Return key or navigate to +the desired completion with the arrow keys. The panel can be dismissed by +hitting the Escape key and opened again by typing `#` or hitting +<kbd>Ctrl</kbd> + <kbd>Space</kbd>. Use the autocomplete panel to discover the +right arguments for functions. Most suggestions come with a small description of +what they do. + + + +## Set up the page +Back to set rules: When writing a rule, you choose the function depending on +what type of element you want to style. Here is a list of some functions that +are commonly used in set rules: + +- [`text`]($func/text) to set font family, size, color, and other properties of + text +- [`page`]($func/page) to set the page size, margins, headers, enable columns, + and footers +- [`par`]($func/par) to justify paragraphs, set line spacing, and more +- [`heading`]($func/heading) to set the appearance of headings and enable + numbering +- [`document`]($func/document) to set the metadata contained in the PDF output, + such as title and author + +Not all function parameters can be set. In general, only parameters that tell +a function _how_ to do something can be set, not those that tell it _what_ to +do it with. The function reference pages indicate which parameters are settable. + +Let's add a few more styles to our document. We want larger margins and a serif +font. For the purposes of the example, we'll also set another page size. + +```example +#set text(10pt, "Latin Modern Roman") +#set page( + "a6", + margin: (x: 1.8cm, y: 1.5cm), +) +#set par( + justify: true, + leading: 0.52em, +) + += Introduction +In this report, we will explore the +various factors that influence fluid +dynamics in glaciers and how they +contribute to the formation and +behavior of these natural structures. + +>>> Glacier displacement is influenced +>>> by a number of factors, including +>>> + The climate +>>> + The topography +>>> + The geology +>>> +>>> This report will present a physical +>>> model of glacier displacement and +>>> dynamics, and will explore the +>>> influence of these factors on the +>>> movement of large bodies of ice. +<<< ... + +#align(center + bottom)[ + #image("glacier.jpg", width: 70%) + + *Glaciers form an important + part of the earth's climate + system.* +] +``` + +There are a few things of note here. + +First is the [`page`]($func/page) set rule. It receives two arguments: the page +size and margins for the page. The page size is a string. Typst accepts +[many standard page sizes,]($func/page.paper) but you can also specify a custom +page size. The margins are specified as a [dictionary.]($type/dictionary) +Dictionaries are a collection of key-value pairs. In this case, the keys are `x` +and `y`, and the values are the horizontal and vertical margins, respectively. +We could also have specified separate margins for each side by passing a +dictionary with the keys `{left}`, `{right}`, `{top}`, and `{bottom}`. + +Next is the set [`text`]($func/text) set rule. Here, we set the font size to +`{10pt}` and font family to `{"Latin Modern Roman"}`. The Typst app comes with +many fonts that you can try for your document. When you are in the text +function's argument list, you can discover the available fonts in the +autocomplete panel. + +We have also set the spacing between lines (a.k.a. leading): It is specified as +a [length]($type/length) value, and we used the `em` unit to specify the leading +relative to the size of the font: `{1em}` is equivalent to the current font size +(which defaults to `{11pt}`). + +Finally, we have bottom aligned our image by adding a vertical alignment to our +center alignment. Vertical and horizontal alignments can be combined with the +`{+}` operator to yield a 2D alignment. + +## A hint of sophistication +To structure our document more clearly, we now want to number our headings. We +can do this by setting the `numbering` parameter of the +[`heading`]($func/heading) function. + +```example +>>> #set text("Latin Modern Roman") +#set heading(numbering: "1.") + += Introduction +#lorem(10) + +== Background +#lorem(12) + +== Methods +#lorem(15) +``` + +We specified the string `{"1."}` as the numbering parameter. This tells Typst to +number the headings with arabic numerals and to put a dot between the number of +each level. We can also use +[letters, roman numerals, and symbols]($func/numbering) for our headings: + +```example +>>> #set text("Latin Modern Roman") +#set heading(numbering: "1.a") + += Introduction +#lorem(10) + +== Background +#lorem(12) + +== Methods +#lorem(15) +``` + +This example also uses the [`lorem`]($func/lorem) function to generate some +placeholder text. This function takes a number as an argument and generates that +many words of _Lorem Ipsum_ text. + +<div class="info-box"> + +Did you wonder why the headings and text set rules apply to all text and headings, +even if they are not produced with the respective functions? + +Typst internally calls the `heading` function every time you write `[= Conclusion]`. +In fact, the function call `[#heading[Conclusion]]` is equivalent to the heading +markup above. Other markup elements work similarly, they are only +_syntax sugar_ for the corresponding function calls. +</div> + +## Show rules +You are already pretty happy with how this turned out. But one last thing needs +to be fixed: The report you are writing is intended for a larger project and +that project's name should always be accompanied by a logo, even in prose. + +You consider your options. You could add an `[#image("logo.svg")]` call before +every instance of the logo using search and replace. That sounds very tedious. +Instead, you could maybe +[define a custom function]($type/function/#definitions) that always yields the logo with its image. However, there is an even easier way: + +With show rules, you can redefine how Typst displays certain elements. You +specify which elements Typst should show differently and how they should look. +Show rules can be applied to instances of text, many functions, and even the +whole document. + +```example +#show "ArtosFlow": name => box[ + #box(image( + "logo.svg", + height: 0.7em, + )) + #name +] + +This report is embedded in the +ArtosFlow project. ArtosFlow is a +project of the Artos Institute. +``` + +There is a lot of new syntax in this example: We write the `{show}` keyword, +followed by a string of text we want to show differently and a colon. Then, we +write a function that takes the content that shall be shown as an argument. +Here, we called that argument `name`. We can now use the `name` variable in the +function's body to print the ArtosFlow name. Our show rule adds the logo image +in front of the name and puts the result into a box to prevent linebreaks from +occurring between logo and name. The image is also put inside of a box, so that +it does not appear in its own paragraph. + +The calls to the first box function and the image function did not require a +leading `#` because they were not embedded directly in markup. When Typst +expects code instead of markup, the leading `#` is not needed to access +functions, keywords, and variables. This can be observed in parameter lists, +function definitions, and [code blocks]($scripting). + +## Review +You now know how to apply basic formatting to your Typst documents. You learned +how to set the font, justify your paragraphs, change the page dimensions, and +add numbering to your headings with set rules. You also learned how to use a +basic show rule to change how text appears throughout your document. + +You have handed in your report. Your supervisor was so happy with it that they +want to adapt it into a conference paper! In the next section, we will learn how +to format your document as a paper using more advanced show rules and functions. |