diff options
Diffstat (limited to 'docs/tutorial')
| -rw-r--r-- | docs/tutorial/1-writing.md | 15 | ||||
| -rw-r--r-- | docs/tutorial/2-formatting.md | 61 | ||||
| -rw-r--r-- | docs/tutorial/3-advanced.md | 41 | ||||
| -rw-r--r-- | docs/tutorial/4-template.md | 22 |
4 files changed, 68 insertions, 71 deletions
diff --git a/docs/tutorial/1-writing.md b/docs/tutorial/1-writing.md index de2af62f..5a9fdd4f 100644 --- a/docs/tutorial/1-writing.md +++ b/docs/tutorial/1-writing.md @@ -85,7 +85,7 @@ 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`]($image) function. +show up on the page, we use Typst's [`image`] function. ```example #image("glacier.jpg") @@ -116,9 +116,9 @@ 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]($figure) function. This function takes the figure's contents as a -positional argument and an optional caption as a named argument. +default. It's also lacking a caption. Let's fix that by using the [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 now have to remove the hash before the image function call. @@ -178,8 +178,8 @@ valid kind of content. ## 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`]($bibliography) -function. This function expects a path to a bibliography file. +add a bibliography to your document with the [`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), @@ -300,8 +300,7 @@ 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]($table), [shapes]($category/visualize), and [code blocks]($raw). You -can peruse the [reference]($reference) to learn more about these and other -features. +can peruse the [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 diff --git a/docs/tutorial/2-formatting.md b/docs/tutorial/2-formatting.md index 58095f94..e51f96e7 100644 --- a/docs/tutorial/2-formatting.md +++ b/docs/tutorial/2-formatting.md @@ -11,11 +11,10 @@ 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`]($image) function) and others that _manipulate_ -content that they received as arguments (e.g. the [`align`]($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. +content (e.g. the [`image`] function) and others that _manipulate_ content that +they received as arguments (e.g. the [`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)[ @@ -38,9 +37,9 @@ 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`]($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. +As seen above, that works. The [`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 @@ -89,13 +88,12 @@ 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`]($text) to set font family, size, color, and other properties of text -- [`page`]($page) to set the page size, margins, headers, enable columns, and - footers -- [`par`]($par) to justify paragraphs, set line spacing, and more -- [`heading`]($heading) to set the appearance of headings and enable numbering -- [`document`]($document) to set the metadata contained in the PDF output, such - as title and author +- [`text`] to set font family, size, color, and other properties of text +- [`page`] to set the page size, margins, headers, enable columns, and footers +- [`par`] to justify paragraphs, set line spacing, and more +- [`heading`] to set the appearance of headings and enable numbering +- [`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 @@ -149,24 +147,24 @@ behaviour of these natural structures. There are a few things of note here. -First is the [`page`]($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,]($page.paper) but you can also specify a custom page -size. The margins are specified as a [dictionary.]($dictionary) Dictionaries are -a collection of key-value pairs. In this case, the keys are `x` and `y`, and the +First is the [`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,]($page.paper) but you can also specify a custom page size. The +margins are specified as a [dictionary.]($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`]($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. +Next is the set [`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]($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}`). +a [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 @@ -174,8 +172,7 @@ center alignment. Vertical and horizontal alignments can be combined with the ## 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`]($heading) -function. +can do this by setting the `numbering` parameter of the [`heading`] function. ```example >>> #set text(font: "New Computer Modern") @@ -210,9 +207,9 @@ for our headings: #lorem(15) ``` -This example also uses the [`lorem`]($lorem) function to generate some -placeholder text. This function takes a number as an argument and generates that -many words of _Lorem Ipsum_ text. +This example also uses the [`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"> diff --git a/docs/tutorial/3-advanced.md b/docs/tutorial/3-advanced.md index 2393a474..57b3dc0d 100644 --- a/docs/tutorial/3-advanced.md +++ b/docs/tutorial/3-advanced.md @@ -125,17 +125,17 @@ supervisor, we'll add our own and their name. ) ``` -The two author blocks are laid out next to each other. We use the -[`grid`]($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]($relative) or -[fractions]($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. +The two author blocks are laid out next to each other. We use the [`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]($relative) or [fractions]($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. @@ -248,11 +248,10 @@ 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`]($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. +some headings and switch our paper to a two-column layout. The [`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 @@ -386,8 +385,7 @@ 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`]($smallcaps) function to render the heading's title in small -capitals. +[`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 @@ -479,7 +477,8 @@ Let's review the conference's style guide: - 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 ✓ +- 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 @@ -496,7 +495,9 @@ the conference! The finished paper looks like this: ## 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`]($grid) function and how to write show rules for individual functions, and the whole document. You also learned how to use the +scopes to locally override styles, how to create more complex layouts with the +[`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 diff --git a/docs/tutorial/4-template.md b/docs/tutorial/4-template.md index 3b745db5..a96e7c0a 100644 --- a/docs/tutorial/4-template.md +++ b/docs/tutorial/4-template.md @@ -195,17 +195,17 @@ 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]($array) of -[dictionaries]($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()`]($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). +The new `authors` parameter expects an [array] of [dictionaries]($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()`]($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]($array.map) comes in handy. It takes a function as an |