caisin/typst
1
0
Fork 0
mirror of https://github.com/typst/typst synced 2025-05-14 04:56:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

Guide for users switching from LaTeX (#1103)

Browse Source
This commit is contained in:
Martin Haug 2023-05-11 17:08:44 +02:00 committed by GitHub
parent 1a6224f566
commit d1dec299a7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 593 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

592
docs/src/general/guide-for-latex-users.md Normal file
View File

@ -0,0 +1,592 @@
---
description: |
Are you a LaTeX user? This guide explains the differences and
similarities between Typst and LaTeX so you can get started quickly.
---
# Guide for LaTeX users
This page is a good starting point if you have used LaTeX before and want to try
Typst. We will explore the main differences between these two systems from a
user perspective. Although Typst is not built upon LaTeX and has a different
syntax, you will learn how to use your LaTeX skills to get a head start.
<!-- Mention that Typst is not built upon LaTeX -->
Just like LaTeX, Typst is a markup-based typesetting system: You compose your
document in a text file and mark it up with commands and other syntax. Then, you
use a compiler to typeset the source file into a PDF. However, Typst also
differs from LaTeX in several aspects: For one, Typst uses more dedicated syntax
(like you may know from Markdown) for common tasks. Typst's commands are also
more principled: They all work the same, so unlike in LaTeX, you just need to
understand a few general concepts instead of learning different conventions for
each package. Moreover Typst compiles faster than LaTeX: Compilation usually
takes milliseconds, not seconds, so the web app and the compiler can both
provide instant previews.
In the following, we will cover some of the most common questions a user
switching from LaTeX will have when composing a document in Typst. If you prefer
a step-by-step introduction to Typst, check out our [tutorial]($tutorial).
## How do I create a new, empty document?
That's easy. You just create a new, empty text file (the file extension is
`.typ`). No boilerplate is needed to get started. Simply start by writing your
text. It will be set on an empty A4-sized page. If you are using the web app,
click "+ Empty document" to create a new project with a file and enter the
editor. [Paragraph breaks]($func/parbreak) work just as they do in LaTeX, just
use a blank line.
```example
Hey there!
Here are two paragraphs. The
output is shown to the right.
```
## How do I create a section heading, emphasis, ...?
LaTeX uses the command `\section` to create a section heading. To nest deeper,
you can use `\subsection`, `\subsubsection`, etc. Depending on your document
class, there is also `\part` or `\chapter`.
In Typst, [headings]($func/heading) are less verbose: You prefix the line with
the heading on it with an equals sign and a space to get a first-order heading:
`[= Introduction]`. If you need a second-order heading, you use two equals
signs: `[== In this paper]`. You can nest headings as deeply as you'd like by
adding more equals signs.
Emphasis (usually rendered as italic text) is expressed by enclosing text in
`[_underscores_]` and strong emphasis (usually rendered in boldface) by using
`[*stars*]` instead.
Below, there is a comparison between LaTeX commands and their Typst equivalents.
You can also check out the [full syntax cheat sheet]($syntax).
| Element | LaTeX | Typst | See |
|:-----------------|:--------------------------|:-----------------------|:-------------------------|
| Strong emphasis | `\textbf{strong}` | `[*strong*]` | [`strong`]($func/strong) |
| Emphasis | `\emph{emphasis}` | `[_emphasis_]` | [`emph`]($func/emph) |
| Monospace / code | `\texttt{print(1)}` | ``[`print(1)`]`` | [`raw`]($func/raw) |
| Link | `\url{https://typst.app}` | `[https://typst.app/]` | [`link`]($func/link) |
| Label | `\label{intro}` | `[<intro>]` | [`label`]($func/label) |
| Reference | `\ref{intro}` | `[@intro]` | [`ref`]($func/ref) |
| Citation | `\cite{humphrey97}` | `[@humphrey97]` | [`cite`]($func/cite) |
| Bullet list | `itemize` environment | `[- List]` | [`list`]($func/list) |
| Numbered list | `enumerate` environment | `[+ List]` | [`enum`]($func/enum) |
| Term list | `description` environment | `[/ Term: List]` | [`terms`]($func/terms) |
| Figure | `figure` environment | `figure` function | [`figure`]($func/figure) |
| Table | `table` environment | `table` function | [`table`]($func/table) |
| Equation | `$x$`, `align` / `equation` environments | `[$x$]`, `[$ x = y $]` | [`equation`]($func/equation) |
[Lists]($func/list) do not rely on environments in Typst. Instead, they have
lightweight syntax like headings. To create an unordered list (`itemize`),
prefix the line of the list item with a hyphen:
````example
To write this list in Typst...
```latex
\begin{itemize}
\item Fast
\item Flexible
\item Intuitive
\end{itemize}
```
...just type this:
- Fast
- Flexible
- Intuitive
````
By indenting them beyond the hyphen, you can also include multiple paragraphs or
nested lists in a single list item. If the list item's become longer, it's best
to put blank lines between the list items. This increases the spacing between
the list's items.
To get a [numbered list]($func/enum) (`enumerate`) instead, use a `+` instead of
the hyphen. For a [term list]($func/terms) (`description`), write
`[/ Term: Description]` instead.
## How do I use a command?
LaTeX heavily relies on commands (prefixed by backslashes). It uses these
_macros_ to affect the typesetting process and to insert and manipulate content.
Some commands accept arguments, most frequently they are enclosed in curly
braces: `\cite{rasmus}`.
Typst differentiates between [markup mode and code mode]($scripting/#blocks).
Markup mode is the default and where you can write text and use syntactic
constructs like `[*stars for bold text*]`. Code mode is similar to other
programming languages like Python and allows you to write code like `{1 + 2 ==
3}`.
Within Typst's markup, you can switch to code mode for a single command (or
rather, _expression_) using a hashtag (`#`). This is how you call functions and
use features like [imports]($scripting/#modules) within markup. Within these
commands and function calls, code mode applies. To embed
[_content_]($type/content) as a value, you can go back to markup mode using
square brackets:
```example
First, a rectangle:
#rect()
Let me show how to do
#underline([_underlined_ text])
We can also do some maths:
#calc.max(3, 2 * 4)
And finally a little loop:
#for x in range(3) [
Hi #x.
]
```
A function call always involves the name of the function ([`rect`]($func/rect),
[`underline`]($func/underline), [`calc.max`]($category/calc/max),
[`range`]($func/range)) and then an argument list, even if it is empty. The
argument list is enclosed in parentheses.
### Arguments
A function can have multiple arguments. Some arguments are positional, i.e. you
just provide the value: The function `[#lower("SCREAM")]` returns its argument
in all-lowercase. Many functions use named arguments instead of positional
arguments to increase legibility. For example, the dimensions and stroke of a
rectangle are defined with named arguments:
```example
#rect(
width: 2cm,
height: 1cm,
stroke: red,
)
```
You specify a named argument by first entering its name (above, it's `width`,
`height`, and `stroke`), then a colon, followed by the value (`2cm`, `1cm`,
`red`). You can find the available named arguments in the [reference
page]($reference) for each function or in the autocomplete panel when typing.
Named arguments are similar to how some LaTeX environments are configured, for
example, you would type `\begin{enumerate}[label={\alph*)}]` to start a list
with the labels `a)`, `b)`, and so on.
Often, you want to provide some [content]($type/content) to a function. For
example, the LaTeX command `\underline{Alternative A}` would translate to
`[#underline([Alternative A])]` in Typst. The square brackets indicate that a
value is content. Within these brackets, you can use normal markup. However,
that's a lot of parentheses for a pretty simple construct. This is why you can
also move trailing content arguments after the parentheses (and omit the
parentheses if they would end up empty).
```example
Typst is an #underline[alternative]
to LaTeX.
#rect(fill: aqua)[Get started here!]
```
### Data types
You likely already noticed that the arguments have distinctive data types. Typst
supports [many data types]($type). Below, there is a table with a few of the
most important ones and how to write them:
| Data type | Example |
|:-------------------------------------|:----------------------------------|
| [Content]($type/content) | `{[*fast* typesetting]}` |
| [String]($type/string) | `{"Pietro S. Author"}` |
| [Integer]($type/integer) | `{23}` |
| [Floating point number]($type/float) | `{1.459}` |
| [Absolute length]($type/length) | `{12pt}`, `{5in}`, `{0.3cm}`, ... |
| [Relative length]($type/ratio) | `{65%}` |
The difference between content and string is that content can contain markup,
including function calls, while a string really is just a sequence of
characters. You can use [operators]($scripting/#operators) like `+` for
summation and `==` for equality on these types like you would in a conventional
programming language instead of using `\addtocounter` or `\ifnum`. You can even
define [variables]($scripting/#bindings) and do computations with them.
In order to specify values of any of these types, you have to be in code mode!
### Commands to affect the remaining document
In LaTeX, some commands like `\textbf{bold text}` are passed their argument in curly
braces and only affect that argument whereas other commands like `\bfseries bold
text` act as switches and change the appearance of all following content in the
document or the current scope (denoted by a set of curly braces).
In Typst, functions can be used in both ways: With effects applying until the
end of the document or block or just to its arguments. For example,
`[#text(weight: "bold")[bold text]]` will only embolden its argument, while
`[#set text(weight: "bold")]` will embolden any text until the end of the
current block, or, if there is none, document. The effects of a function are
immediately obvious depending on if it is used in a call or a
[set rule.]($styling/#set-rules)
```example
I am starting out with small text.
#set text(14pt)
This is a bit #text(18pt)[larger,]
don't you think?
```
Set rules may appear anywhere in the document and can be though of as
pre-setting the arguments of their function:
```example
#set enum(numbering: "I.")
Good results can only be obtained by
+ following best practices
+ being aware of current results
of other researchers
+ checking the data for biases
```
The `+` is syntactic sugar (think of it as an abbreviation) for a call to the
[`{enum}`]($func/enum) function, to which we apply a set rule above. [Most
syntax is linked to a function in this way.]($syntax) If you need to style an
element beyond what its arguments enable, you can completely redefine its
appearance with a [show rule]($styling/#show-rules) (somewhat comparable to
`\renewcommand`).
## How do I load a document class?
In LaTeX, you start your main `.tex` file with the `\documentclass{article}`
command to define how your document is supposed to look. In that command, you
may have replaced `article` with another value such as `report` and `amsart` to
select a different look.
When using Typst, you style your documents with [functions]($type/function).
Typically, you use a template that provides a function that styles your whole
document. First, you import the function from a template file. Then, you apply
it to your whole document. This is accomplished with a
[show rule]($styling/#show-rules) that wraps the following document in a given
function. The following example illustrates how it works:
```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: conf.with(
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),
)
Let's get started writing this
article by putting insightful
paragraphs right here!
```
The [`{import}`]($scripting/#modules) statement makes
[functions]($type/function) (and other definitions) from another file available.
In this example, it imports the `conf` function from the `conf.typ` file. This
function formats content as a conference article. We use the show rule to apply
it to the document and also configure some metadata about the article. Finally,
we can get started writing our article below!
<div class="info-box">
Functions are Typst's "commands" and can transform their arguments to an output
value, including document _content._ Functions are "pure", which means that they
cannot have any effects beyond creating an output value / output content. This
is in stark contrast to LaTeX macros that can have arbitrary effects on your
document.
To let a function style your whole document, the show rule processes everything
that comes after it and calls the function specified after the colon with the
result as an argument. The `.with` part is a _method_ that takes the `conf`
function and pre-configures some if its arguments before passing it on to the
show rule.
</div>
In the web app, you can choose from predefined templates or even
create your own using the template wizard. You can also check out the
[`awesome-typst` repository](https://github.com/qjcg/awesome-typst) to find
templates made by the community. We plan to build a package manager to make
templates even easier to share in the future!
You can also [create you your own, custom templates.]($tutorial/making-a-template)
They are shorter and more readable than the corresponding LaTeX `.sty` files by
orders of magnitude, so give it a try!
## How do I load packages?
Most things you load packages for in LaTeX are just included in Typst, no need
to load or install anything. Below, we compiled a table with frequently loaded
packages and their corresponding Typst functions.
| LaTeX Package | Typst Alternative |
|:--------------------------------|:---------------------------------------------------------------------|
| graphicx, svg | [`image`]($func/image) function |
| tabularx | [`table`]($func/table), [`grid`]($func/grid) functions |
| fontenc, inputenc, unicode-math | Just start writing! |
| babel, polyglossia | [`text`]($func/text.lang) function: `[#set text(lang: "zh")]` |
| amsmath | [Math mode]($category/math) |
| amsfonts, amssymb | [`sym`]($category/symbols) module and [syntax]($syntax/#math) |
| geometry, fancyhdr | [`page`]($func/page) function |
| xcolor | [`text`]($func/text.fill) function: `[#set text(fill: rgb("#0178A4"))]` |
| hyperref | [`link`]($func/link) function |
| bibtex, biblatex, natbib | [`cite`]($func/cite), [`bibliography`]($func/bibliography) functions |
| lstlisting, minted | [`raw`]($func/raw) function and syntax |
| parskip | [`block`]($func/block.spacing) and [`par`]($func/par.first-line-indent) functions |
| csquotes | Type `["]` or `[']` and set the [`text`]($func/text.lang) language |
| caption | [`figure`]($func/figure) function |
| enumitem | [`list`]($func/list), [`enum`]($func/enum), [`terms`]($func/terms) functions |
If you need to load functions and variables from another file, for example to
use a template, you can use an [`import`]($scripting/#modules) statement. If you
want to include the textual content of another file instead, you can use an
[`{include}`]($scripting/#modules) statement. It will yield the content of the
included file and put it in your document.
Currently, there is no package manager for Typst, but we plan to build one so
that you can easily use packages with tools and templates from the community and
publish your own.
## How do I input maths?
To enter math mode in Typst, just enclose your equation in dollar signs. You can
enter display mode by putting spaces or newlines between the opening and closing
dollar sign and the equation.
```example
The sum of the numbers from
$1$ to $n$ is:
$ sum_(k=1)^n k = (n(n+1))/2 $
```
[Math mode]($category/math) works differently than regular markup or code mode.
Single characters and numbers with any amount of digits are displayed as
mathematical variables and values (of your equation), while multiple consecutive
non-number characters will be interpreted as Typst variables.
As you can see in the example above, Typst pre-defines a lot of useful variables
in math mode. All Greek and some Hebrew letters are resolved by their name.
Refer to the [symbol page]($func/symbol) or use the autocomplete panel to check
which symbols are available. Alternate and related forms of symbols can often be
selected by [appending a modifier]($type/symbol) after a period. For example,
`arrow.l.squiggly` inserts a squiggly left-pointing arrow. If you want to insert
multiletter text in your expression instead, enclose it in double quotes:
```example
$ delta "if" x <= 5 $
```
You can type many symbols with shorthands like `<=`, `>=`, and `->`. Similarly,
delimiters will scale automatically for their expressions, just as if `\left`
and `\right` commands were implicitly inserted in LaTeX. You can customize
delimiter behavior using the [`lr` function]($func/lr).
Typst will automatically set terms around a slash `/` as a fraction while
honoring operator precedence. All round parentheses not made redundant by the
fraction will appear in the output.
```example
$ f(x) = (x + 1) / x $
```
[Sub- and superscripts]($func/attach) work similarly in Typst and LaTeX. Typing
`{$x^2$}` will produce a superscript, `{$x_2$}` yields a subscript. If you want
to include more than one value in a sub- or superscript, enclose their contents
in parentheses: `{$x_(a -> epsilon)$}`.
Just like you can insert variables without typing a `#` or `/`, you can also use
functions "naked":
```example
$ f(x, y) := cases(
1 "if" (x dot y)/2 <= 0,
2 "if" x "is even",
3 "if" x in NN,
4 "else",
) $
```
The above example uses the [`cases` function]($func/cases) to describe f. Within
the cases function, arguments are delimited using commas and the arguments are
also interpreted as math. If you would need to interpret arguments as Typst
values instead, prefix them with a `#`:
```example
$ (a + b)^2
= a^2
+ text(fill: #maroon, 2 a b)
+ b^2 $
```
You can use all Typst functions within math mode and insert any content. If you
want them to work normally, with code mode in the argument list, you can prefix
their call with a `#`. Nobody can stop you from using rectangles or emoji as
your variables anymore:
```example
$ sum^10_(🥸=1)
#rect(width: 4mm, height: 2mm)/🥸
= 🧠 maltese $
```
If you'd like to enter your mathematical symbols directly as Unicode, that is
possible, too!
Math calls can have two-dimensional argument lists using `;` as a delimiter. The
most common use for this is the [`mat` function]($func/mat) that creates
matrices:
```example
$ mat(
1, 2, ..., 10;
2, 2, ..., 10;
dots.v, dots.v, dots.down, dots.v;
10, 10, ..., 10;
) $
```
## How do I get the "LaTeX look?"
Papers set in LaTeX have an unmistakeable look. This is mostly due to their
font, Computer Modern, justification, narrow line spacing, and wide margins.
The example below
- sets wide [margins]($func/page.margin)
- enables [justification]($func/par.justify), [tighter lines]($func/par.leading)
and [first-line-indent]($func/par.first-line-indent)
- [sets the font]($func/text.font) to "New Computer Modern", an OpenType
derivate of Computer Modern for both text and [code blocks]($func/raw)
- disables paragraph [spacing]($func/block.spacing)
- increases [spacing]($func/block.spacing) around [headings]($func/heading)
```typ
#set page(margin: 1.75in)
#set par(leading: 0.55em, first-line-indent: 1.8em, justify: true)
#set text(font: "New Computer Modern")
#show raw: set text(font: "New Computer Modern Mono")
#show par: set block(spacing: 0.55em)
#show heading: set block(above: 1.4em, below: 1em)
```
This should be a good starting point! If you want to go further, why not create
a reusable template?
## What limitations does Typst currently have compared with LaTeX?
Although Typst can be a LaTeX replacement for many today, there are still
features that Typst does not (yet) support. Here is a list of them which, where
applicable, contains possible workarounds.
- **Native charts and plots.** LaTeX users often create charts along with their
documents in PGF/TikZ. Typst does not yet include tools to draw diagrams, but
the community is stepping up with solutions such as
[`typst-canvas`](https://github.com/johannes-wolf/typst-canvas),
[`typst-plot`](https://github.com/johannes-wolf/typst-plot), and
[`circuitypst`](https://github.com/fenjalien/circuitypst). You can add those
to your document to get started with drawing diagrams.
- **Change page margins without a pagebreak.** In LaTeX, margins can always be
adjusted, even without a pagebreak. To change margins in Typst, you use the
[`page` function]($func/page) which will force a page break. If you just want
a few paragraphs to stretch into the margins, then reverting to the old
margins, you can use the [`pad` function]($func/pad) with negative padding.
- **Floating figures.** The figure command of LaTeX will smartly choose where to
place a figure, be it on the top or bottom of the page, or a dedicated figure
page. Typst's figure will always appear at the spot where they have been
inserted in the markup. While this behavior can save some headache, it is
often cumbersome to manually place figures. We will be adding this feature
soon!
- **Include PDFs as images.** In LaTeX, it has become customary to insert vector
graphics as PDF or EPS files. Typst supports neither format as an image
format, but you can easily convert both into SVG files with [online
tools](https://cloudconvert.com/pdf-to-svg) or
[Inkscape](https://inkscape.org/). We plan to add automatic conversion for
these file formats to the Typst web app, too!
- **Page break optimization.** LaTeX runs some smart algorithms to not only
optimize line but also page breaks. While Typst tries to avoid widows and
orphans, it uses less sophisticated algorithms to determine page breaks. You
can insert custom page breaks in Typst using `[#pagebreak(weak: true)]` before
submitting your document. The argument `weak` ensures that no double page
break will be created if this spot would be a natural page break
anyways. You can also use `[#v(1fr)]` to distribute space on your page. It
works quite similar to LaTeX's `\vfill`.
- **Bibliographies are not customizable.** In LaTeX, the packages `bibtex`,
`biblatex`, and `natbib` provide a wide range of reference and bibliography
formats. You can also use custom `.bbx` files to define your own styles there.
Typst only supports a small set of citation styles at the moment, but we want
to build upon this by supporting [Citation Style Language
(CSL)](https://citationstyles.org), an XML-based format backed by Zotero that
allows you to describe your own bibliography styles.

1
docs/src/lib.rs
View File

@ -56,6 +56,7 @@ pub fn provide(resolver: &dyn Resolver) -> Vec<PageModel> {
markdown_page(resolver, "/docs/", "general/overview.md").with_route("/docs/"),
tutorial_page(resolver),
reference_page(resolver),
markdown_page(resolver, "/docs/", "general/guide-for-latex-users.md"),
markdown_page(resolver, "/docs/", "general/changelog.md"),
markdown_page(resolver, "/docs/", "general/community.md"),
]