From 3a979e88da7be6240821ba8acfdd376b7f4e0f09 Mon Sep 17 00:00:00 2001 From: Laurenz Date: Mon, 11 Sep 2023 15:53:20 +0200 Subject: Docs generation for types --- docs/tutorial/1-writing.md | 41 ++++++++++---------- docs/tutorial/2-formatting.md | 88 +++++++++++++++++++++---------------------- docs/tutorial/3-advanced.md | 29 +++++++------- docs/tutorial/4-template.md | 38 +++++++++---------- 4 files changed, 97 insertions(+), 99 deletions(-) (limited to 'docs/tutorial') diff --git a/docs/tutorial/1-writing.md b/docs/tutorial/1-writing.md index a2a2ca65..6a458e44 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`]($func/image) function. +show up on the page, we use Typst's [`image`]($image) function. ```example #image("glacier.jpg") @@ -98,8 +98,8 @@ result (the function's _return value_) into the document. In our case, the 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. +Our file path is a short [string of text]($str), 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 @@ -110,14 +110,14 @@ they are separated by commas, so we first need to put a comma behind the path. #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 +The `width` argument is a [relative length]($relative). 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 +[figure]($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. @@ -176,9 +176,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`]($func/bibliography) function. This function expects a path -to a bibliography file. +add a bibliography to your document with the [`bibliography`]($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), @@ -190,7 +189,7 @@ 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. +[reference]($bibliography.style) for more details. ```example = Methods @@ -200,7 +199,7 @@ established in @glacier-melt. #bibliography("works.bib") ``` -## Maths { #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 @@ -269,17 +268,17 @@ $ 7.32 beta + 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. +vector, we can use the [`vec`]($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. +[`cal`]($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 @@ -293,14 +292,14 @@ 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 } +## 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. +as [tables]($table), [shapes]($category/visualize), and [code blocks]($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 diff --git a/docs/tutorial/2-formatting.md b/docs/tutorial/2-formatting.md index c231b878..7eb82710 100644 --- a/docs/tutorial/2-formatting.md +++ b/docs/tutorial/2-formatting.md @@ -9,13 +9,13 @@ 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 } +## 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. +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. ```example #par(justify: true)[ @@ -38,9 +38,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`]($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. +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. 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,15 +89,13 @@ 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 +- [`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 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 @@ -151,23 +149,22 @@ behavior of these natural structures. 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. +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 +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. 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 +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}`). @@ -177,8 +174,8 @@ 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`]($func/heading) function. +can do this by setting the `numbering` parameter of the [`heading`]($heading) +function. ```example >>> #set text(font: "New Computer Modern") @@ -196,8 +193,8 @@ can do this by setting the `numbering` parameter of the 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: +each level. We can also use [letters, roman numerals, and symbols]($numbering) +for our headings: ```example >>> #set text(font: "New Computer Modern") @@ -213,7 +210,7 @@ each level. We can also use #lorem(15) ``` -This example also uses the [`lorem`]($func/lorem) function to generate some +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. @@ -222,13 +219,13 @@ many words of _Lorem Ipsum_ text. 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. +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. -## Show rules { #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. @@ -236,7 +233,8 @@ 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: +[define a custom function]($function/#defining-functions) 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. @@ -272,7 +270,7 @@ 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 } +## 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 diff --git a/docs/tutorial/3-advanced.md b/docs/tutorial/3-advanced.md index bb0362ef..2393a474 100644 --- a/docs/tutorial/3-advanced.md +++ b/docs/tutorial/3-advanced.md @@ -78,7 +78,7 @@ 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 +[numbering pattern]($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 @@ -126,16 +126,16 @@ supervisor, we'll add our own and their name. ``` 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 +[`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]($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. +`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. @@ -249,7 +249,7 @@ 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 +[`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. @@ -386,7 +386,8 @@ 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. +[`smallcaps`]($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 @@ -493,9 +494,9 @@ the conference! The finished paper looks like this: style="box-shadow: 0 4px 12px rgb(89 85 101 / 20%); width: 500px; max-width: 100%; display: block; margin: 24px auto;" > -## Review { #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 +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 [`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 320f82b2..3b745db5 100644 --- a/docs/tutorial/4-template.md +++ b/docs/tutorial/4-template.md @@ -195,26 +195,26 @@ 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). +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). 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 array's [`map` method]($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]($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: @@ -365,7 +365,7 @@ conference! Why not share it on [Typst's Discord server](https://discord.gg/2uDybryKPe) so that others can use it too? -## Review { #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 -- cgit v1.2.3