diff options
Diffstat (limited to 'docs/src/tutorial')
| -rw-r--r-- | docs/src/tutorial/1-writing.md | 308 | ||||
| -rw-r--r-- | docs/src/tutorial/2-formatting.md | 283 | ||||
| -rw-r--r-- | docs/src/tutorial/3-advanced.md | 509 | ||||
| -rw-r--r-- | docs/src/tutorial/4-template.md | 380 | ||||
| -rw-r--r-- | docs/src/tutorial/welcome.md | 44 |
5 files changed, 0 insertions, 1524 deletions
diff --git a/docs/src/tutorial/1-writing.md b/docs/src/tutorial/1-writing.md deleted file mode 100644 index a2a2ca65..00000000 --- a/docs/src/tutorial/1-writing.md +++ /dev/null @@ -1,308 +0,0 @@ ---- -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. diff --git a/docs/src/tutorial/2-formatting.md b/docs/src/tutorial/2-formatting.md deleted file mode 100644 index c231b878..00000000 --- a/docs/src/tutorial/2-formatting.md +++ /dev/null @@ -1,283 +0,0 @@ ---- -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 { #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). -] -``` - -Wait, shouldn't all arguments of a function be specified within parentheses? Why -is there a second set of square brackets with content _after_ the parentheses? -The answer is that, as passing content to a function is such a common thing to -do in Typst, there is special syntax for it: Instead of putting the content -inside of the argument list, you can write it in square brackets directly after -the normal arguments, saving on punctuation. - -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 { #autocomplete } -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 { #page-setup } -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( - font: "New Computer Modern", - size: 10pt -) -#set page( - paper: "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 `{"New Computer Modern"}`. 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 { #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(font: "New Computer Modern") -#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(font: "New Computer Modern") -#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 { #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 { #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. diff --git a/docs/src/tutorial/3-advanced.md b/docs/src/tutorial/3-advanced.md deleted file mode 100644 index 42a810fd..00000000 --- a/docs/src/tutorial/3-advanced.md +++ /dev/null @@ -1,509 +0,0 @@ ---- -description: Typst's tutorial. ---- - -# Advanced Styling -In the previous two chapters of this tutorial, you have learned how to write a -document in Typst and how to change its formatting. The report you wrote -throughout the last two chapters got a straight A and your supervisor wants to -base a conference paper on it! The report will of course have to comply with the -conference's style guide. Let's see how we can achieve that. - -Before we start, let's create a team, invite your supervisor and add them to the -team. You can do this by going back to the app dashboard with the four-circles -icon in the top left corner of the editor. Then, choose the plus icon in the -left toolbar and create a team. Finally, click on the new team and go to its -settings by clicking 'manage team' next to the team name. Now you can invite -your supervisor by email. - - - -Next, move your project into the team: Open it, going to its settings by -choosing the gear icon in the left toolbar and selecting your new team from the -owners dropdown. Don't forget to save your changes! - -Now, your supervisor can also edit the project and you can both see the changes -in real time. You can join our [Discord server](https://discord.gg/2uDybryKPe) -to find others with preview access and try teams with them! - -## The conference guidelines { #guidelines } -The layout guidelines are available on the conference website. Let's take a look -at them: - -- The font should be an 11pt serif font -- The title should be in 17pt and bold -- The paper contains a single-column abstract and two-column main text -- The abstract should be centered -- The main text should be justified -- First level section headings should be 13pt, centered, and rendered in small - capitals -- Second level headings are run-ins, italicized and have the same size as the - body text -- Finally, the pages should be US letter sized, numbered in the center of the - footer and the top left corner of each page should contain the title of the - paper - -We already know how to do many of these things, but for some of them, we'll need -to learn some new tricks. - -## Writing the right set rules { #set-rules } -Let's start by writing some set rules for the document. - -```example -#set page( ->>> margin: auto, - paper: "us-letter", - header: align(right)[ - A fluid dynamic model for - glacier flow - ], - numbering: "1", -) -#set par(justify: true) -#set text( - font: "Linux Libertine", - size: 11pt, -) - -#lorem(600) -``` - -You are already familiar with most of what is going on here. We set the text -size to `{11pt}` and the font to Linux Libertine. We also enable paragraph -justification and set the page size to US letter. - -The `header` argument is new: With it, we can provide content to fill the top -margin of every page. In the header, we specify our paper's title as requested -by the conference style guide. We use the `align` function to align the text to -the right. - -Last but not least is the `numbering` argument. Here, we can provide a -[numbering pattern]($func/numbering) that defines how to number the pages. By -setting into to `{"1"}`, Typst only displays the bare page number. Setting it to -`{"(1/1)"}` would have displayed the current page and total number of pages -surrounded by parentheses. And we could even have provided a completely custom -function here to format things to our liking. - -## Creating a title and abstract { #title-and-abstract } -Now, let's add a title and an abstract. We'll start with the title. We center -align it and increase its font weight by enclosing it in `[*stars*]`. - -```example ->>> #set page(width: 300pt, margin: 30pt) ->>> #set text(font: "Linux Libertine", 11pt) -#align(center, text(17pt)[ - *A fluid dynamic model - for glacier flow* -]) -``` - -This looks right. We used the `text` function to override the previous text -set rule locally, increasing the size to 17pt for the function's argument. Let's -also add the author list: Since we are writing this paper together with our -supervisor, we'll add our own and their name. - -```example ->>> #set page(width: 300pt, margin: 30pt) ->>> #set text(font: "Linux Libertine", 11pt) ->>> ->>> #align(center, text(17pt)[ ->>> *A fluid dynamic model ->>> for glacier flow* ->>> ]) -#grid( - columns: (1fr, 1fr), - align(center)[ - Therese Tungsten \ - Artos Institute \ - #link("mailto:tung@artos.edu") - ], - align(center)[ - Dr. John Doe \ - Artos Institute \ - #link("mailto:doe@artos.edu") - ] -) -``` - -The two author blocks are laid out next to each other. We use the -[`grid`]($func/grid) function to create this layout. With a grid, we can control -exactly how large each column is and which content goes into which cell. The -`columns` argument takes an array of [relative lengths]($type/relative-length) -or [fractions]($type/fraction). In this case, we passed it two equal fractional -sizes, telling it to split the available space into two equal columns. We then -passed two content arguments to the grid function. The first with our own -details, and the second with our supervisors'. We again use the `align` function -to center the content within the column. The grid takes an arbitrary number of -content arguments specifying the cells. Rows are added automatically, but they -can also be manually sized with the `rows` argument. - -Now, let's add the abstract. Remember that the conference wants the abstract to -be set ragged and centered. - -```example:0,0,612,317.5 ->>> #set text(font: "Linux Libertine", 11pt) ->>> #set par(justify: true) ->>> #set page( ->>> "us-letter", ->>> margin: auto, ->>> header: align(right + horizon)[ ->>> A fluid dynamic model for ->>> glacier flow ->>> ], ->>> numbering: "1", ->>> ) ->>> ->>> #align(center, text(17pt)[ ->>> *A fluid dynamic model ->>> for glacier flow* ->>> ]) ->>> ->>> #grid( ->>> columns: (1fr, 1fr), ->>> align(center)[ ->>> Therese Tungsten \ ->>> Artos Institute \ ->>> #link("mailto:tung@artos.edu") ->>> ], ->>> align(center)[ ->>> Dr. John Doe \ ->>> Artos Institute \ ->>> #link("mailto:doe@artos.edu") ->>> ] ->>> ) ->>> -<<< ... - -#align(center)[ - #set par(justify: false) - *Abstract* \ - #lorem(80) -] ->>> #lorem(600) -``` - -Well done! One notable thing is that we used a set rule within the content -argument of `align` to turn off justification for the abstract. This does not -affect the remainder of the document even though it was specified after the -first set rule because content blocks _scope_ styling. Anything set within a -content block will only affect the content within that block. - -Another tweak could be to save the paper title in a variable, so that we do not -have to type it twice, for header and title. We can do that with the `{let}` -keyword: - -```example:single -#let title = [ - A fluid dynamic model - for glacier flow -] - -<<< ... - ->>> #set text(font: "Linux Libertine", 11pt) ->>> #set par(justify: true) -#set page( ->>> "us-letter", ->>> margin: auto, - header: align( - right + horizon, - title - ), -<<< ... ->>> numbering: "1", -) - -#align(center, text(17pt)[ - *#title* -]) - -<<< ... - ->>> #grid( ->>> columns: (1fr, 1fr), ->>> align(center)[ ->>> Therese Tungsten \ ->>> Artos Institute \ ->>> #link("mailto:tung@artos.edu") ->>> ], ->>> align(center)[ ->>> Dr. John Doe \ ->>> Artos Institute \ ->>> #link("mailto:doe@artos.edu") ->>> ] ->>> ) ->>> ->>> #align(center)[ ->>> #set par(justify: false) ->>> *Abstract* \ ->>> #lorem(80) ->>> ] ->>> ->>> #lorem(600) -``` - -After we bound the content to the `title` variable, we can use it in functions -and also within markup (prefixed by `#`, like functions). This way, if we decide -on another title, we can easily change it in one place. - -## Adding columns and headings { #columns-and-headings } -The paper above unfortunately looks like a wall of lead. To fix that, let's add -some headings and switch our paper to a two-column layout. The -[`columns`]($func/columns) function takes a number and content, and layouts the -content into the specified number of columns. Since we want everything after the -abstract to be in two columns, we need to apply the column function to our whole -document. - -Instead of wrapping the whole document in a giant function call, we can use an -"everything" show rule. To write such a show rule, put a colon directly behind -the show keyword and then provide a function. This function is given the rest of -the document as a parameter. We have called the parameter `rest` here, but you -are free to choose any name. The function can then do anything with this -content. In our case, it passes it on to the `columns` function. - -```example:single ->>> #let title = [ ->>> A fluid dynamic model ->>> for glacier flow ->>> ] ->>> ->>> #set text(font: "Linux Libertine", 11pt) ->>> #set par(justify: true) ->>> #set page( ->>> "us-letter", ->>> margin: auto, ->>> header: align( ->>> right + horizon, ->>> title ->>> ), ->>> numbering: "1", ->>> ) ->>> ->>> #align(center, text( ->>> 17pt, ->>> weight: "bold", ->>> title, ->>> )) ->>> ->>> #grid( ->>> columns: (1fr, 1fr), ->>> align(center)[ ->>> Therese Tungsten \ ->>> Artos Institute \ ->>> #link("mailto:tung@artos.edu") ->>> ], ->>> align(center)[ ->>> Dr. John Doe \ ->>> Artos Institute \ ->>> #link("mailto:doe@artos.edu") ->>> ] ->>> ) ->>> ->>> #align(center)[ ->>> #set par(justify: false) ->>> *Abstract* \ ->>> #lorem(80) ->>> ] ->>> #v(4mm) -<<< ... - -#show: rest => columns(2, rest) - -= Introduction -#lorem(300) - -= Related Work -#lorem(200) -``` - -Now there is only one thing left to do: Style our headings. We need to make them -centered and use small capitals. Because the `heading` function does not offer -a way to set any of that, we need to write our own heading show rule. - -```example:50,250,265,270 ->>> #let title = [ ->>> A fluid dynamic model ->>> for glacier flow ->>> ] ->>> ->>> #set text(font: "Linux Libertine", 11pt) ->>> #set par(justify: true) ->>> #set page( ->>> "us-letter", ->>> margin: auto, ->>> header: align( ->>> right + horizon, ->>> title ->>> ), ->>> numbering: "1", ->>> ) -#show heading: it => [ - #set align(center) - #set text(12pt, weight: "regular") - #block(smallcaps(it.body)) -] - -<<< ... ->>> ->>> #align(center, text( ->>> 17pt, ->>> weight: "bold", ->>> title, ->>> )) ->>> ->>> #grid( ->>> columns: (1fr, 1fr), ->>> align(center)[ ->>> Therese Tungsten \ ->>> Artos Institute \ ->>> #link("mailto:tung@artos.edu") ->>> ], ->>> align(center)[ ->>> Dr. John Doe \ ->>> Artos Institute \ ->>> #link("mailto:doe@artos.edu") ->>> ] ->>> ) ->>> ->>> #align(center)[ ->>> #set par(justify: false) ->>> *Abstract* \ ->>> #lorem(80) ->>> ] ->>> ->>> #v(4mm) ->>> #show: rest => columns(2, rest) ->>> ->>> = Introduction ->>> #lorem(35) ->>> ->>> == Motivation ->>> #lorem(45) -``` - -This looks great! We used a show rule that applies to all headings. We give it a -function that gets passed the heading as a parameter. That parameter can be used -as content but it also has some fields like `title`, `numbers`, and `level` from -which we can compose a custom look. Here, we are center-aligning, setting the -font weight to `{"regular"}` because headings are bold by default, and use the -[`smallcaps`]($func/smallcaps) function to render the heading's title in small capitals. - -The only remaining problem is that all headings look the same now. The -"Motivation" and "Problem Statement" subsections ought to be italic run in -headers, but right now, they look indistinguishable from the section headings. We -can fix that by using a `where` selector on our set rule: This is a -[method]($scripting/#methods) we can call on headings (and other -elements) that allows us to filter them by their level. We can use it to -differentiate between section and subsection headings: - -```example:50,250,265,245 ->>> #let title = [ ->>> A fluid dynamic model ->>> for glacier flow ->>> ] ->>> ->>> #set text(font: "Linux Libertine", 11pt) ->>> #set par(justify: true) ->>> #set page( ->>> "us-letter", ->>> margin: auto, ->>> header: align( ->>> right + horizon, ->>> title ->>> ), ->>> numbering: "1", ->>> ) ->>> -#show heading.where( - level: 1 -): it => block(width: 100%)[ - #set align(center) - #set text(12pt, weight: "regular") - #smallcaps(it.body) -] - -#show heading.where( - level: 2 -): it => text( - size: 11pt, - weight: "regular", - style: "italic", - it.body + [.], -) ->>> ->>> #align(center, text( ->>> 17pt, ->>> weight: "bold", ->>> title, ->>> )) ->>> ->>> #grid( ->>> columns: (1fr, 1fr), ->>> align(center)[ ->>> Therese Tungsten \ ->>> Artos Institute \ ->>> #link("mailto:tung@artos.edu") ->>> ], ->>> align(center)[ ->>> Dr. John Doe \ ->>> Artos Institute \ ->>> #link("mailto:doe@artos.edu") ->>> ] ->>> ) ->>> ->>> #align(center)[ ->>> #set par(justify: false) ->>> *Abstract* \ ->>> #lorem(80) ->>> ] ->>> ->>> #v(4mm) ->>> #show: rest => columns(2, rest) ->>> ->>> = Introduction ->>> #lorem(35) ->>> ->>> == Motivation ->>> #lorem(45) -``` - -This looks great! We wrote two show rules that each selectively apply to the -first and second level headings. We used a `where` selector to filter the -headings by their level. We then rendered the subsection headings as run-ins. We -also automatically add a period to the end of the subsection headings. - -Let's review the conference's style guide: -- The font should be an 11pt serif font ✓ -- The title should be in 17pt and bold ✓ -- The paper contains a single-column abstract and two-column main text ✓ -- The abstract should be centered ✓ -- The main text should be justified ✓ -- First level section headings should be centered, rendered in small caps and in 13pt ✓ -- Second level headings are run-ins, italicized and have the same size as the - body text ✓ -- Finally, the pages should be US letter sized, numbered in the center and the - top left corner of each page should contain the title of the paper ✓ - -We are now in compliance with all of these styles and can submit the paper to -the conference! The finished paper looks like this: - -<img - src="3-advanced-paper.png" - alt="The finished paper" - style="box-shadow: 0 4px 12px rgb(89 85 101 / 20%); width: 500px; max-width: 100%; display: block; margin: 24px auto;" -> - -## Review { #review } -You have now learned how to create headers and footers, how to use functions and -scopes to locally override styles, how to create more complex layouts with the [`grid`]($func/grid) function and how to write show rules for individual functions, and the whole document. You also learned how to use the -[`where` selector]($styling/#show-rules) to filter the headings by their level. - -The paper was a great success! You've met a lot of like-minded researchers at -the conference and are planning a project which you hope to publish at the same -venue next year. You'll need to write a new paper using the same style guide -though, so maybe now you want to create a time-saving template for you and your -team? - -In the next section, we will learn how to create templates that can be reused in -multiple documents. This is a more advanced topic, so feel free to come back -to it later if you don't feel up to it right now. diff --git a/docs/src/tutorial/4-template.md b/docs/src/tutorial/4-template.md deleted file mode 100644 index 320f82b2..00000000 --- a/docs/src/tutorial/4-template.md +++ /dev/null @@ -1,380 +0,0 @@ ---- -description: Typst's tutorial. ---- - -# Making a Template -In the previous three chapters of this tutorial, you have learned how to write a -document in Typst, apply basic styles, and customize its appearance in-depth to -comply with a publisher's style guide. Because the paper you wrote in the -previous chapter was a tremendous success, you have been asked to write a -follow-up article for the same conference. This time, you want to take the style -you created in the previous chapter and turn it into a reusable template. In -this chapter you will learn how to create a template that you and your team can -use with just one show rule. Let's get started! - -## A toy template { #toy-template } -In Typst, templates are functions in which you can wrap your whole document. To -learn how to do that, let's first review how to write your very own functions. -They can do anything you want them to, so why not go a bit crazy? - -```example -#let amazed(term) = box[✨ #term ✨] - -You are #amazed[beautiful]! -``` - -This function takes a single argument, `term`, and returns a content block with -the `term` surrounded by sparkles. We also put the whole thing in a box so that -the term we are amazed by cannot be separated from its sparkles by a line break. - -Many functions that come with Typst have optional named parameters. Our -functions can also have them. Let's add a parameter to our function that lets us -choose the color of the text. We need to provide a default color in case the -parameter isn't given. - -```example -#let amazed(term, color: blue) = { - text(color, box[✨ #term ✨]) -} - -You are #amazed[beautiful]! -I am #amazed(color: purple)[amazed]! -``` - -Templates now work by using an "everything" show rule that applies the custom -function to our whole document. Let's do that with our `amazed` function. - -```example ->>> #let amazed(term, color: blue) = { ->>> text(color, box[✨ #term ✨]) ->>> } -#show: amazed -I choose to focus on the good -in my life and let go of any -negative thoughts or beliefs. -In fact, I am amazing! -``` - -Our whole document will now be passed to the `amazed` function, as if we -wrapped it around it. This is not especially useful with this particular -function, but when combined with set rules and named arguments, it can be very -powerful. - -## Embedding set and show rules { #set-and-show-rules } -To apply some set and show rules to our template, we can use `set` and `show` -within a content block in our function and then insert the document into -that content block. - -```example -#let template(doc) = [ - #set text(font: "Inria Serif") - #show "something cool": [Typst] - #doc -] - -#show: template -I am learning something cool today. -It's going great so far! -``` - -Just like we already discovered in the previous chapter, set rules will apply to -everything within their content block. Since the everything show rule passes our -whole document to the `template` function, the text set rule and string show -rule in our template will apply to the whole document. Let's use this knowledge -to create a template that reproduces the body style of the paper we wrote in the -previous chapter. - -```example -#let conf(title, doc) = { - set page( - paper: "us-letter", ->>> margin: auto, - header: align( - right + horizon, - title - ), -<<< ... - ) - set par(justify: true) - set text( - font: "Linux Libertine", - size: 11pt, - ) - - // Heading show rules. -<<< ... ->>> show heading.where( ->>> level: 1 ->>> ): it => block( ->>> align(center, ->>> text( ->>> 13pt, ->>> weight: "regular", ->>> smallcaps(it.body), ->>> ) ->>> ), ->>> ) ->>> show heading.where( ->>> level: 2 ->>> ): it => box( ->>> text( ->>> 11pt, ->>> weight: "regular", ->>> style: "italic", ->>> it.body + [.], ->>> ) ->>> ) - - columns(2, doc) -} - -#show: doc => conf( - [Paper title], - doc, -) - -= Introduction -#lorem(90) - -<<< ... ->>> == Motivation ->>> #lorem(140) ->>> ->>> == Problem Statement ->>> #lorem(50) ->>> ->>> = Related Work ->>> #lorem(200) -``` - -We copy-pasted most of that code from the previous chapter. The only two -differences are that we wrapped everything in the function `conf` and are -calling the columns function directly on the `doc` argument as it already -contains the content of the document. Moreover, we used a curly-braced code -block instead of a content block. This way, we don't need to prefix all set -rules and function calls with a `#`. In exchange, we cannot write markup -directly into it anymore. - -Also note where the title comes from: We previously had it inside of a variable. -Now, we are receiving it as the first parameter of the template function. -Thus, we must specify it in the show rule where we call the template. - -## Templates with named arguments { #named-arguments } -Our paper in the previous chapter had a title and an author list. Let's add these -things to our template. In addition to the title, we want our template to accept -a list of authors with their affiliations and the paper's abstract. To keep -things readable, we'll add those as named arguments. In the end, we want it to -work like this: - -```typ -#show: doc => conf( - title: [Towards Improved Modelling], - authors: ( - ( - name: "Theresa Tungsten", - affiliation: "Artos Institute", - email: "tung@artos.edu", - ), - ( - name: "Eugene Deklan", - affiliation: "Honduras State", - email: "e.deklan@hstate.hn", - ), - ), - abstract: lorem(80), - doc, -) - -... -``` - -Let's build this new template function. First, we add a default value to the -`title` argument. This way, we can call the template without specifying a title. -We also add the named `authors` and `abstract` parameters with empty defaults. -Next, we copy the code that generates title, abstract and authors from the -previous chapter into the template, replacing the fixed details with the -parameters. - -The new `authors` parameter expects an [array]($type/array) of -[dictionaries]($type/dictionary) with the keys `name`, `affiliation` and -`email`. Because we can have an arbitrary number of authors, we dynamically -determine if we need one, two or three columns for the author list. First, we -determine the number of authors using the [`.len()`]($type/array.len) method on -the `authors` array. Then, we set the number of columns as the minimum of this -count and three, so that we never create more than three columns. If there are -more than three authors, a new row will be inserted instead. For this purpose, -we have also added a `row-gutter` parameter to the `grid` function. Otherwise, -the rows would be too close together. To extract the details about the authors -from the dictionary, we use the [field access syntax]($scripting/#fields). - -We still have to provide an argument to the grid for each author: Here is where -the array's [`map` method]($type/array.map) comes in handy. It takes a function -as an argument that gets called with each item of the array. We pass it a -function that formats the details for each author and returns a new array -containing content values. We've now got one array of values that we'd like to -use as multiple arguments for the grid. We can do that by using the [`spread` -operator]($type/arguments). It takes an array and applies each of its items as a -separate argument to the function. - -The resulting template function looks like this: - -```typ -#let conf( - title: none, - authors: (), - abstract: [], - doc, -) = { - // Set and show rules from before. -<<< ... - - set align(center) - text(17pt, title) - - let count = authors.len() - let ncols = calc.min(count, 3) - grid( - columns: (1fr,) * ncols, - row-gutter: 24pt, - ..authors.map(author => [ - #author.name \ - #author.affiliation \ - #link("mailto:" + author.email) - ]), - ) - - par(justify: false)[ - *Abstract* \ - #abstract - ] - - set align(left) - columns(2, doc) -} -``` - -## A separate file { #separate-file } -Most of the time, a template is specified in a different file and then imported -into the document. This way, the main file you write in is kept clutter free and -your template is easily reused. Create a new text file in the file panel by -clicking the plus button and name it `conf.typ`. Move the `conf` function -definition inside of that new file. Now you can access it from your main file by -adding an import before the show rule. Specify the path of the file between the -`{import}` keyword and a colon, then name the function that you -want to import. - -```example:single ->>> #let conf( ->>> title: none, ->>> authors: (), ->>> abstract: [], ->>> doc, ->>> ) = { ->>> set text(font: "Linux Libertine", 11pt) ->>> set par(justify: true) ->>> set page( ->>> "us-letter", ->>> margin: auto, ->>> header: align( ->>> right + horizon, ->>> title ->>> ), ->>> numbering: "1", ->>> ) ->>> ->>> show heading.where( ->>> level: 1 ->>> ): it => block( ->>> align(center, ->>> text( ->>> 13pt, ->>> weight: "regular", ->>> smallcaps(it.body), ->>> ) ->>> ), ->>> ) ->>> show heading.where( ->>> level: 2 ->>> ): it => box( ->>> text( ->>> 11pt, ->>> weight: "regular", ->>> style: "italic", ->>> it.body + [.], ->>> ) ->>> ) ->>> ->>> set align(center) ->>> text(17pt, title) ->>> ->>> let count = calc.min(authors.len(), 3) ->>> grid( ->>> columns: (1fr,) * count, ->>> row-gutter: 24pt, ->>> ..authors.map(author => [ ->>> #author.name \ ->>> #author.affiliation \ ->>> #link("mailto:" + author.email) ->>> ]), ->>> ) ->>> ->>> par(justify: false)[ ->>> *Abstract* \ ->>> #abstract ->>> ] ->>> ->>> set align(left) ->>> columns(2, doc) ->>>} -<<< #import "conf.typ": conf -#show: doc => conf( - title: [ - Towards Improved Modelling - ], - authors: ( - ( - name: "Theresa Tungsten", - affiliation: "Artos Institute", - email: "tung@artos.edu", - ), - ( - name: "Eugene Deklan", - affiliation: "Honduras State", - email: "e.deklan@hstate.hn", - ), - ), - abstract: lorem(80), - doc, -) - -= Introduction -#lorem(90) - -== Motivation -#lorem(140) - -== Problem Statement -#lorem(50) - -= Related Work -#lorem(200) -``` - -We have now converted the conference paper into a reusable template for that -conference! Why not share it on -[Typst's Discord server](https://discord.gg/2uDybryKPe) so that others can use -it too? - -## Review { #review } -Congratulations, you have completed Typst's Tutorial! In this section, you have -learned how to define your own functions and how to create and apply templates -that define reusable document styles. You've made it far and learned a lot. You -can now use Typst to write your own documents and share them with others. - -We are still a super young project and are looking for feedback. If you have any -questions, suggestions or you found a bug, please let us know on -[Typst's Discord server](https://discord.gg/2uDybryKPe), on our -[contact form](https://typst.app/contact), or on -[social media.](https://twitter.com/typstapp) - -So what are you waiting for? [Sign up](https://typst.app) and write something! diff --git a/docs/src/tutorial/welcome.md b/docs/src/tutorial/welcome.md deleted file mode 100644 index 530336cb..00000000 --- a/docs/src/tutorial/welcome.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -description: Typst's tutorial. ---- - -# Tutorial -Welcome to Typst's tutorial! In this tutorial, you will learn how to write and -format documents in Typst. We will start with everyday tasks and gradually -introduce more advanced features. This tutorial does not assume prior knowledge -of Typst, other Markup languages, or programming. We do assume that you know how -to edit a text file. - -The best way to start is to sign up to the Typst app for free and follow along -with the steps below. The app gives you instant preview, syntax highlighting and -helpful autocompletions. Alternatively, you can follow along in your local text -editor with the [open-source CLI](https://github.com/typst/typst). - -## When to use Typst { #when-typst } -Before we get started, let's check what Typst is and when to use it. Typst is a -markup language for typesetting documents. It is designed to be easy to learn, -fast, and versatile. Typst takes text files with markup in them and outputs -PDFs. - -Typst is a good choice for writing any long form text such as essays, articles, -scientific papers, books, reports, and homework assignments. Moreover, Typst is -a great fit for any documents containing mathematical notation, such as papers -in the math, physics, and engineering fields. Finally, due to its strong styling -and automation features, it is an excellent choice for any set of documents that -share a common style, such as a book series. - -## What you will learn { #learnings } -This tutorial has four chapters. Each chapter builds on the previous one. Here -is what you will learn in each of them: - -1. [Writing in Typst:]($tutorial/writing-in-typst) Learn how to write text and - insert images, equations, and other elements. -2. [Formatting:]($tutorial/formatting) Learn how to adjust the formatting - of your document, including font size, heading styles, and more. -3. [Advanced Styling:]($tutorial/advanced-styling) Create a complex page - layout for a scientific paper with typographic features such as an author - list and run-in headings. -4. [Making a Template:]($tutorial/making-a-template) Build a reusable template - from the paper you created in the previous chapter. - -We hope you'll enjoy Typst! |