diff options
Diffstat (limited to 'docs/tutorial/1-writing.md')
| -rw-r--r-- | docs/tutorial/1-writing.md | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/docs/tutorial/1-writing.md b/docs/tutorial/1-writing.md new file mode 100644 index 00000000..a2a2ca65 --- /dev/null +++ b/docs/tutorial/1-writing.md @@ -0,0 +1,308 @@ +--- +description: Typst's tutorial. +--- + +# Writing in Typst +Let's get started! Suppose you got assigned to write a technical report for +university. It will contain prose, maths, headings, and figures. To get started, +you create a new project on the Typst app. You'll be taken to the editor where +you see two panels: A source panel where you compose your document and a +preview panel where you see the rendered document. + + + +You already have a good angle for your report in mind. So let's start by writing +the introduction. Enter some text in the editor panel. You'll notice that the +text immediately appears on the previewed page. + +```example +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. +``` + +_Throughout this tutorial, we'll show code examples like this one. Just like in the app, the first panel contains markup and the second panel shows a preview. We shrunk the page to fit the examples so you can see what's going on._ + +The next step is to add a heading and emphasize some text. Typst uses simple +markup for the most common formatting tasks. To add a heading, enter the `=` +character and to emphasize some text with italics, enclose it in +`[_underscores_]`. + +```example += 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. +``` + +That was easy! To add a new paragraph, just add a blank line in between two +lines of text. If that paragraph needs a subheading, produce it by typing `==` +instead of `=`. The number of `=` characters determines the nesting level of the +heading. + +Now we want to list a few of the circumstances that influence glacier dynamics. +To do that, we use a numbered list. For each item of the list, we type a `+` +character at the beginning of the line. Typst will automatically number the +items. + +```example ++ The climate ++ The topography ++ The geology +``` + +If we wanted to add a bulleted list, we would use the `-` character instead of +the `+` character. We can also nest lists: For example, we can add a sub-list to +the first item of the list above by indenting it. + +```example ++ The climate + - Temperature + - Precipitation ++ The topography ++ The geology +``` + +## Adding a figure { #figure } +You think that your report would benefit from a figure. Let's add one. Typst +supports images in the formats PNG, JPEG, GIF, and SVG. To add an image file to +your project, first open the _file panel_ by clicking the box icon in the left +sidebar. Here, you can see a list of all files in your project. Currently, there +is only one: The main Typst file you are writing in. To upload another file, +click the button with the arrow in the top-right corner. This opens the upload +dialog, in which you can pick files to upload from your computer. Select an +image file for your report. + + + +We have seen before that specific symbols (called _markup_) have specific +meaning in Typst. We can use `=`, `-`, `+`, and `_` to create headings, lists +and emphasized text, respectively. However, having a special symbol for +everything we want to insert into our document would soon become cryptic and +unwieldy. For this reason, Typst reserves markup symbols only for the most +common things. Everything else is inserted with _functions._ For our image to +show up on the page, we use Typst's [`image`]($func/image) function. + +```example +#image("glacier.jpg") +``` + +In general, a function produces some output for a set of _arguments_. When you +_call_ a function within markup, you provide the arguments and Typst inserts the +result (the function's _return value_) into the document. In our case, the +`image` function takes one argument: The path to the image file. To call a +function in markup, we first need to type the `#` character, immediately +followed by the name of the function. Then, we enclose the arguments in +parentheses. Typst recognizes many different data types within argument lists. +Our file path is a short [string of text]($type/string), so we need to enclose +it in double quotes. + +The inserted image uses the whole width of the page. To change that, pass the +`width` argument to the `image` function. This is a _named_ argument and +therefore specified as a `name: value` pair. If there are multiple arguments, +they are separated by commas, so we first need to put a comma behind the path. + +```example +#image("glacier.jpg", width: 70%) +``` + +The `width` argument is a [relative length]($type/relative-length). In our case, +we specified a percentage, determining that the image shall take up `{70%}` of +the page's width. We also could have specified an absolute value like `{1cm}` or +`{0.7in}`. + +Just like text, the image is now aligned at the left side of the page by +default. It's also lacking a caption. Let's fix that by using the +[figure]($func/figure) function. This function takes the figure's contents as a +positional argument and an optional caption as a named argument. + +Within the argument list of the `figure` function, Typst is already in code mode. This means, you can now remove the hashtag before the image function call. +The hashtag is only needed directly in markup (to disambiguate text from function calls). + +The caption consists of arbitrary markup. To give markup to a function, we +enclose it in square brackets. This construct is called a _content block._ + +```example +#figure( + image("glacier.jpg", width: 70%), + caption: [ + _Glaciers_ form an important part + of the earth's climate system. + ], +) +``` + +You continue to write your report and now want to reference the figure. To do +that, first attach a label to figure. A label uniquely identifies an element in +your document. Add one after the figure by enclosing some name in angle +brackets. You can then reference the figure in your text by writing an `[@]` +symbol followed by that name. Headings and equations can also be labelled to +make them referenceable. + +```example +Glaciers as the one shown in +@glaciers will cease to exist if +we don't take action soon! + +#figure( + image("glacier.jpg", width: 70%), + caption: [ + _Glaciers_ form an important part + of the earth's climate system. + ], +) <glaciers> +``` + +<div class="info-box"> + +So far, we've passed content blocks (markup in square brackets) and strings +(text in double quotes) to our functions. Both seem to contain text. What's the +difference? + +A content block can contain text, but also any other kind of markup, function +calls, and more, whereas a string is really just a _sequence of characters_ and +nothing else. + +For example, the image function expects a path to an image file. +It would not make sense to pass, e.g., a paragraph of text or another image as +the image's path parameter. That's why only strings are allowed here. +On the contrary, strings work wherever content is expected because text is a +valid kind of content. +</div> + +## Adding a bibliography { #bibliography } +As you write up your report, you need to back up some of your claims. You can +add a bibliography to your document with the +[`bibliography`]($func/bibliography) function. This function expects a path +to a bibliography file. + +Typst's native bibliography format is +[Hayagriva](https://github.com/typst/hayagriva/blob/main/docs/file-format.md), +but for compatibility you can also use BibLaTeX files. As your classmate has +already done a literature survey and sent you a `.bib` file, you'll use that +one. Upload the file through the file panel to access it in Typst. + +Once the document contains a bibliography, you can start citing from it. +Citations use the same syntax as references to a label. As soon as you cite a +source for the first time, it will appear in the bibliography section of your +document. Typst supports different citation and bibliography styles. Consult the +[reference]($func/bibliography.style) for more details. + +```example += Methods +We follow the glacier melting models +established in @glacier-melt. + +#bibliography("works.bib") +``` + +## Maths { #maths } +After fleshing out the methods section, you move on to the meat of the document: +Your equations. Typst has built-in mathematical typesetting and uses its own +math notation. Let's start with a simple equation. We wrap it in `[$]` signs +to let Typst know it should expect a mathematical expression: + +```example +The equation $Q = rho A v + C$ +defines the glacial flow rate. +``` + +The equation is typeset inline, on the same line as the surrounding text. If you +want to have it on its own line instead, you should insert a single space at its +start and end: + +```example +The flow rate of a glacier is +defined by the following equation: + +$ Q = rho A v + C $ +``` + +We can see that Typst displayed the single letters `Q`, `A`, `v`, and `C` as-is, +while it translated `rho` into a Greek letter. Math mode will always show single +letters verbatim. Multiple letters, however, are interpreted as symbols, +variables, or function names. To imply a multiplication between single letters, +put spaces between them. + +If you want to have a variable that consists of multiple letters, you can +enclose it in quotes: + +```example +The flow rate of a glacier is given +by the following equation: + +$ Q = rho A v + "time offset" $ +``` + +You'll also need a sum formula in your paper. We can use the `sum` symbol and +then specify the range of the summation in sub- and superscripts: + +```example +Total displaced soil by glacial flow: + +$ 7.32 beta + + sum_(i=0)^nabla Q_i / 2 $ +``` + +To add a subscript to a symbol or variable, type a `_` character and then the +subscript. Similarly, use the `^` character for a superscript. If your +sub- or superscript consists of multiple things, you must enclose them +in round parentheses. + +The above example also showed us how to insert fractions: Simply put a `/` +character between the numerator and the denominator and Typst will automatically +turn it into a fraction. Parentheses are smartly resolved, so you can enter your +expression as you would into a calculator and Typst will replace parenthesized +sub-expressions with the appropriate notation. + +```example +Total displaced soil by glacial flow: + +$ 7.32 beta + + sum_(i=0)^nabla + (Q_i (a_i - epsilon)) / 2 $ +``` + +Not all math constructs have special syntax. Instead, we use functions, just +like the `image` function we have seen before. For example, to insert a column +vector, we can use the [`vec`]($func/math.vec) function. Within math mode, +function calls don't need to start with the `#` character. + +```example +$ v := vec(x_1, x_2, x_3) $ +``` + +Some functions are only available within math mode. For example, the +[`cal`]($func/math.cal) function is used to typeset calligraphic letters +commonly used for sets. The [math section of the reference]($category/math) +provides a complete list of all functions that math mode makes available. + +One more thing: Many symbols, such as the arrow, have a lot of variants. You can +select among these variants by appending a dot and a modifier name to a symbol's +name: + +```example +$ a arrow.squiggly b $ +``` + +This notation is also available in markup mode, but the symbol name must be +preceded with `#sym.` there. See the [symbols section]($category/symbols/sym) +for a list of all available symbols. + +## Review { #review } +You have now seen how to write a basic document in Typst. You learned how to +emphasize text, write lists, insert images, align content, and typeset +mathematical expressions. You also learned about Typst's functions. There are +many more kinds of content that Typst lets you insert into your document, such +as [tables]($func/table), [shapes]($category/visualize), and +[code blocks]($func/raw). You can peruse the [reference]($reference) to learn +more about these and other features. + +For the moment, you have completed writing your report. You have already saved a +PDF by clicking on the download button in the top right corner. However, you +think the report could look a bit less plain. In the next section, we'll learn +how to customize the look of our document. |