caisin/typst
1
0
Fork 0
mirror of https://github.com/typst/typst synced 2025-05-13 20:46:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

A few tutorial improvements

Browse Source
This commit is contained in:
Laurenz 2023-03-21 00:41:20 +01:00
parent 2d16f9434f
commit c8b0be21f5
5 changed files with 114 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
assets/files/works.bib
View File

@ -30,3 +30,14 @@
title={An Insight into Bibliographical Distress}, title={An Insight into Bibliographical Distress},
author={Aldrin, Buzz} author={Aldrin, Buzz}
} }
@article{glacier-melt,
author = {Regine Hock},
title ={Glacier melt: a review of processes and their modelling},
journal = {Progress in Physical Geography: Earth and Environment},
volume = {29},
number = {3},
pages = {362-391},
year = {2005},
doi = {10.1191/0309133305pp453ra},
}

124
docs/src/tutorial/1-writing.md
View File

@ -55,9 +55,9 @@ items.
+ The geology + The geology
``` ```
If we wanted to add a bulleted list, we would use the `-` character instead of the If we wanted to add a bulleted list, we would use the `-` character instead of
`+` character. We can also nest lists: For example, we can add a sub-list to the the `+` character. We can also nest lists: For example, we can add a sub-list to
first item of the list above by indenting it. the first item of the list above by indenting it.
```example ```example
+ The climate + The climate
@ -67,7 +67,7 @@ first item of the list above by indenting it.
+ The geology + The geology
``` ```
## Adding images ## Adding a figure
You think that your report would benefit from a figure. Let's add one. Typst 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 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 your project, first open the _file panel_ by clicking the box icon in the left
@ -83,9 +83,9 @@ We have seen before that specific symbols (called _markup_) have specific
meaning in Typst. We can use `=`, `-`, `+`, and `_` to create headings, lists meaning in Typst. We can use `=`, `-`, `+`, and `_` to create headings, lists
and emphasized text, respectively. However, having a special symbol for and emphasized text, respectively. However, having a special symbol for
everything we want to insert into our document would soon become cryptic and 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 unwieldy. For this reason, Typst reserves markup symbols only for the most
things. Everything else is inserted with _functions._ For our image to show up common things. Everything else is inserted with _functions._ For our image to
on the page, we use Typst's [`image`]($func/image) function. show up on the page, we use Typst's [`image`]($func/image) function.
```example ```example
#image("glacier.jpg") #image("glacier.jpg")
@ -95,11 +95,11 @@ 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 _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 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 `image` function takes one argument: The path to the image file. To call a
function, we first need to type the `#` character, immediately followed by the function in markup, we first need to type the `#` character, immediately
name of the function. Then, we enclose the arguments in parentheses. Typst followed by the name of the function. Then, we enclose the arguments in
recognizes many different data types within argument lists. Our file path is a parentheses. Typst recognizes many different data types within argument lists.
short [string of text]($type/string), so we need to enclose it Our file path is a short [string of text]($type/string), so we need to enclose
in double quotes. it in double quotes.
The inserted image uses the whole width of the page. To change that, pass the 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 `width` argument to the `image` function. This is a _named_ argument and
@ -110,40 +110,52 @@ they are separated by commas, so we first need to put a comma behind the path.
#image("glacier.jpg", width: 70%) #image("glacier.jpg", width: 70%)
``` ```
The `width` argument is a The `width` argument is a [relative length]($type/relative-length). In our case,
[relative length]($type/relative-length). In our case, we specified a we specified a percentage, determining that the image shall take up `{70%}` of
percentage, determining that the image shall take up `{70%}` of the page's the page's width. We also could have specified an absolute value like `{1cm}` or
width. We also could have specified an absolute value like `{1cm}` or `{0.7in}`. `{0.7in}`.
Just like text, the image is aligned at the left side of the page by default. Just like text, the image is now aligned at the left side of the page by
That looks a bit awkward. Let's center it and add a caption. We achieve this by default. It's also lacking a caption. Let's fix that by using the
using the [`align`]($func/align) function. This function takes an `alignment` as [figure]($func/figure) function. This function takes the figure's contents as a
its first argument and then the content that we want to align as the second positional argument and an optional caption as a named argument.
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 ```example
#align(center)[ #figure(
#image("glacier.jpg", width: 70%) image("glacier.jpg", width: 70%),
caption: [
_Glaciers form an important _Glaciers_ form an important part
part of the earth's climate of the earth's climate system.
system._ ],
] )
``` ```
Did you spot the closing bracket `]` at the end of the example? Both the You continue to write your report and now want to reference the figure. To do
argument and the caption are enclosed in the same square brackets. Therefore, that, first attach a label to figure. A label uniquely identifies an element in
the `align` function centers both of them. 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 referencable.
But wait, shouldn't the arguments of a function be specified within parentheses? ```example
Why is there a second set of square brackets with the aligned content after the Glaciers as the one shown in
parentheses? @glaciers will cease to exist if
we don't take action soon!
The answer is that, as passing content to a function is such a common thing #figure(
to do in Typst, there is special syntax for it: Instead of putting the content image("glacier.jpg", width: 70%),
inside of the argument list, you can write it in square brackets directly after caption: [
the normal arguments, saving on punctuation. We call markup in square brackets _Glaciers_ form an important part
a _content block._ of the earth's climate system.
],
) <glaciers>
```
<div class="info-box"> <div class="info-box">
@ -159,11 +171,37 @@ 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 a another image as It would not make sense to pass, e.g., a paragraph of text or a another image as
the image's path parameter. That's why only strings are allowed here. 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 On the contrary, strings work wherever content is expected because text is a
kind of valid content. valid kind of content.
</div> </div>
## Adding a 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 final 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 introduction, you move on to the meat of the document: 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 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 math notation. Let's start with a simple equation. We wrap it in `[$]` signs
to let Typst know it should expect a mathematical expression: to let Typst know it should expect a mathematical expression:
@ -194,8 +232,8 @@ If you want to have a variable that consists of multiple letters, you can
enclose it in quotes: enclose it in quotes:
```example ```example
The flow rate of a glacier is given by The flow rate of a glacier is given
the following equation: by the following equation:
$ Q = rho A v + "time offset" $ $ Q = rho A v + "time offset" $
``` ```

14
docs/src/tutorial/2-formatting.md
View File

@ -31,6 +31,13 @@ complete document in it.
] ]
``` ```
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 As seen above, that works. The [`par`]($func/par) function justifies all
paragraphs within it. However, wrapping the document in countless functions and paragraphs within it. However, wrapping the document in countless functions and
applying styles selectively and in-situ can quickly become cumbersome. applying styles selectively and in-situ can quickly become cumbersome.
@ -100,9 +107,12 @@ 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. font. For the purposes of the example, we'll also set another page size.
```example ```example
#set text(font: "New Computer Modern", 10pt) #set text(
font: "New Computer Modern",
size: 10pt
)
#set page( #set page(
"a6", paper: "a6",
margin: (x: 1.8cm, y: 1.5cm), margin: (x: 1.8cm, y: 1.5cm),
) )
#set par( #set par(

8
docs/src/tutorial/3-advanced.md
View File

@ -50,9 +50,6 @@ to learn some new tricks.
Let's start by writing some set rules for the document. Let's start by writing some set rules for the document.
```example ```example
#set text(font: "Linux Libertine", 11pt)
#set par(justify: true)
#set page( #set page(
>>> margin: auto, >>> margin: auto,
paper: "us-letter", paper: "us-letter",
@ -62,6 +59,11 @@ Let's start by writing some set rules for the document.
], ],
numbering: "1", numbering: "1",
) )
#set par(justify: true)
#set text(
font: "Linux Libertine",
size: 11pt,
)
#lorem(600) #lorem(600)
``` ```

8
docs/src/tutorial/4-template.md
View File

@ -86,8 +86,6 @@ previous chapter.
```example ```example
#let conf(title, doc) = { #let conf(title, doc) = {
set text(font: "Linux Libertine", 11pt)
set par(justify: true)
set page( set page(
paper: "us-letter", paper: "us-letter",
>>> margin: auto, >>> margin: auto,
@ -97,6 +95,11 @@ previous chapter.
), ),
<<< ... <<< ...
) )
set par(justify: true)
set text(
font: "Linux Libertine",
size: 11pt,
)
// Heading show rules. // Heading show rules.
<<< ... <<< ...
@ -324,7 +327,6 @@ path of the file after the `{from}` keyword.
>>> columns(2, doc) >>> columns(2, doc)
>>>} >>>}
<<< #import "conf.typ": conf <<< #import "conf.typ": conf
#show: doc => conf( #show: doc => conf(
title: [ title: [
Towards Improved Modelling Towards Improved Modelling