Never again in outer par mode: making next-generation PDFs with Quarto & typst - posit::conf(2023)
Presented by Carlos Scheidegger Quarto 1.4 will introduce support for Typst. Typst is a brand-new open-source typesetting system built from scratch to support the lessons we have learned over almost half a century of high-quality computer typesetting that TeX and LaTeX have enabled. If you've ever had to produce a PDF with Quarto and got stuck handling an inscrutable error message from LaTeX, or wanted to create a new template but were too intimated by LaTeX's arcane syntax, this talk is for you. I'll show you why we need an alternative for TeX and LaTeX , and why it will make Quarto even better. Presented at Posit Conference, between Sept 19-20 2023, Learn more at posit.co/conference. -------------------------- Talk Track: Quarto (2). Session Code: TALK-1142
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Hello everyone, I'm Carlos Scheidegger and I am going to tell you about next-generation PDFs with Quarto & typst.
I gave the title of my talk as Never Again in Outer Par Mode, and if you know what Outer Par Mode is, you know what this talk is about. If not, let me tell you.
So you're writing Quarto, you've heard this week, it's excellent, we love it. I'm a full-time developer on Quarto, I'm biased, but I really think it's quite good and we try really hard to make it even better, so if it's not good for you, we want to hear about it.
So you write your report, it's excellent, you're so ready to share it with the world, and you need to mail it to someone, so it needs to be a PDF. So you write your file and you go and hit render, or you call Quarto render, and we'll go, yes, we'll render it for you, it's PDF, we'll use LaTeX, which is the way to create beautiful PDF files.
And then it says it's updating its Pack Live Manager, but you didn't ask to update it. It's telling you, I don't want any new packages, I want my report.
And then it just says, it failed. And the reason it failed is, it's not in Outer Par Mode. And if you've ever used Quarto and PDF, unfortunately, I think you've seen this before, because it comes up all the time, and it's just a horrible error message.
So you look at it, it's like, what do I do now? It's not in Outer Par Mode, let's go look at this. See the LaTeX manual, or the LaTeX companion for explanation, or press H for help. Turns out, you get that even not in an interactive prompt, you can't press H, it's just on a file somewhere. And then it says, okay, let's go look at the index.log for more information, because it's an error. Great, they told me about the error, let's go look at it. It's 50,000 characters of error messages.
But okay, maybe it's there, so you go look at the file, and you're just like, okay, okay, okay. No, no, I'm going back to bed, I'll try this tomorrow, this is not going to be good.
And this happens all the time. This is a true story, I didn't know whether I wanted to give this talk with this title, because I thought, it doesn't come up that often. It recently has come up three separate times for me. Recently means since Saturday. Since getting here at the conference, where I'm not developing quarto, three separate times I ran into this. So no, never again in outer part mode, let's not do that.
So no, never again in outer part mode, let's not do that.
By the way, I used LaTeX for 20 years, I used to be an academic before I joined, I counted, I wrote more than 100 papers in LaTeX, and this trips me up still. I hope we don't have to sort of inflict on you this pain anymore. I want us to solve this problem so bad. LaTeX is beautiful, it was a groundbreaking system, it is still the way to generate the most beautiful PDF documents you can, but I think there's an alternative now, and this is what I want to tell you about.
Introducing Typst
So if you're ready for coffee, there's a fantastic talk coming up after mine, but if you want to sort of go back and then come back for the next talk, here's what I'm going to tell you about. Typst is a new system that Quarto uses that lets you do PDF files. I really hope it displaces LaTeX, you're going to see why, it's awesome. You can download it today, it's available in 1.4 pre-releases, but we're still going to support LaTeX forever, so if you must use LaTeX, don't despair, we're not throwing it away, we're keeping it here.
It's a little bit of extra work because it's so new, but I'll show you where the sharp edges are. So what's Typst? The first thing is it's a weird way to pronounce it, but it's on their website. I used to say typist, maybe we can convince them to change, but it's Typst. It's a new system for making PDF documents, and if you go to their website, they say that it's for rocket scientists, but it's for the rest of us, too, which is great. And what they say is it views your changes instantly, it provides clear and understandable error messages, it has a consistent styling system, and it uses familiar programming constructs. I want to tell you about all of that, because that's all true, and it's really great.
So I hope we can convince you to do that. So Quarto meets Typst. What do you have to do to get Typst working? Hopefully you don't have to do anything. If this is your Quarto document, with your YAML front matter, your title, your author, and your format, it might just be a matter of switching from format PDF to format Typst. If you're okay with a sort of standard formatted document, this works today, and you're going to get a PDF document. The advantage of that is you do not need to install TinyTek, it is bundled with Quarto, and it is much faster than LaTeX.
Demo: academic posters
So hopefully you might not have to do anything, but I'll show you what else you get if you actually want to go to the next step. So I'm going to give you four quick demos today. I'm going to show you how to make academic posters with Quarto. I don't know if Lisa is in the audience. To tell you how easy this is, I had three tiny demos to show you today, and then Lisa told me that we really need academic posters in Quarto. And we knew there was a template for Typst, and so I was like, I think we can do this. And we set it up last night in the hotel before the talk today. You can go check my GitHub repository for this talk, and you will see.
I'm going to show you how the errors are nice. I'm going to show you this really fantastic feature about how it handles fonts. And I'm going to show you a really cool, completely new design for documents that just really showcases the power of Typst.
So let's start with posters. So I'm using VS Code, which apparently, according to Nick, makes me a maniac of some kind. I apologize. I'm used to it. This is a Quarto document. It's just marked down. If you have format equals HTML and you ask it to render, we'll fire up a preview. We will run it. And you will get a preview just like you would for any website.
So you get that. It's not an academic poster, but it's your content. There's some figures. There's lists, tables, equations, images, and so on and so forth. So let's say that you needed to do an academic poster as of last night. If you switch your format from there to Typst, you see that you have to do things a little bit different. We're going to fix this in about 24 more hours. I just didn't have time to do that. We'll be using all of the metadata from Quarto. We're not right now. So it's not perfect.
And now you get a poster. I wasn't sure whether or not people were going to use it. And then this morning, someone pinged me on Mastodon saying, hey, I made a CRAN poster with this. And it worked. So there's at least one person that made it work. So trust me, this is easy.
You can see the formatting is a little bit different, right? The tables are rendered a little bit differently. The code blocks are rendered not quite the same, but they're pretty close. And we're working to make it as close as possible. You get equations. You get lists. You get other kinds of things that I hope to show you.
Error messages in Typst
So for example, here is a block of text that has a different color behind it. So this is my first opportunity to show you a little bit about how Typst actually looks like in code. Because I want to show you that this is actually really kind of simple. So here's a raw code block for Typst. So in Quarto, if you want to do something that's format specific, you use these raw blocks to get the code to do what you want. And so if you want a block that the background is this light gray that is inside eight points from the margin, and it has a radius of four, you start a block. This is the way that you call a command from Typst. You put your markdown code inside, including markdown things like lists. And then you just close your block here, right?
So there's an even easier way to do this with using divs from Pandoc, but I just wanted to show you sort of what this looks like if you were to sort of have to do the fancy sort of pure Typst thing. I don't know if you've ever had to do this in LaTeX. I promise you, this one is so much cleaner and easier to work than that.
Let's say that if you happened to type that instead of RGB, because you thought that that's how callers worked, right? Well, they don't work exactly like that. But this gives me a chance to show you error messages. So I'm running the dev version of Quarto, so I want to know exactly where the error came. You won't see this. You are going to see this part right here, where it's saying compiler poster error. I expected a caller or none, but I found a string right here.
Compare that to not in outer par mode. What error did I make that it says not in outer par mode? It's got nothing to do with my code. When Typst makes an error, it tells you what the error is, and it said it was expecting a caller, and you gave it a string, and it points you exactly in the source where that is. And it does that very consistently, and it's some of the best error messages that I've ever seen. And I spent six months working in Quarto error messages, so I care about them. These folks have done a fantastic job of their own, so I'm happy to show you that we can actually then guide you to do the right thing.
When Typst makes an error, it tells you what the error is, and it said it was expecting a caller, and you gave it a string, and it points you exactly in the source where that is.
Font support
Let me tell you about fonts. So if you've ever used PDF LaTeX from way back then, font support is not great. There's no Unicode support. It's very hard to figure out if your code is going to render the way that you want. It's just generally a mess. Lua LaTeX and ZLaTeX do a little bit better, but still, the system itself doesn't know a lot about fonts, and so it's hard for it to reason about what's possible.
So let me start with a very basic demo here. Here is font support, right? So again, I'm starting with a raw block here that says set the text to be of a particular font. But notice I'm using two fonts and not one. The other thing I'm doing is I'm putting a fenced div around that statement. And the reason I'm doing that is to show you that naturally, Typst will keep its state to the blocks around it. So this just happens by natural sort of way in which Typst work, which is not how LaTeX work. And you have to remember, does this one work in the current environment? Does this work set for the entire document? Am I going to get it wrong? In Typst, everything is scoped. If you want to keep your changes to something, you just put a block around it, and everything just works.
So here is my text. Let's render it. And now what's neat about this one is if you like avatar, you get your papyrus font. But it didn't get the papyrus font for the second one. Because the papyrus font does not have the Arabic glyphs for that. So it detects it, and it says, hey, I cannot possibly render for that one. So let me try the next font you gave me, which is the Arabic font from Google, and it renders it. And not only does it render it, I unfortunately do not know how to read Arabic. But ligatures in Arabic text are extremely important, because they actually change the meaning of the word. So they're not very readable. And so in old PDF, this is very hard to do in Typst. You just get that for free, and these are rendered properly if the font supports it. So this is something that's kind of impossible to do in LaTeX. You just get it for free in Typst. It's really nice.
Demo: newsletter template
So last quick demo for something completely different. What if you are running a small department, like an institution, and you want to have a newsletter for your college somewhere? This is a newsletter. I just want to show you how it's possible to do something that looks completely different, that almost looks like it was typeset with something like Illustrator or something of that sort. It's just another format, and this is what it looks like.
So you have two columns. You can put sort of code on one column or code on the other. You have links and so on, and you still have your code. So you can line things just like you would in your sort of R Markdown quarto inline code. They're just there. You can do sort of fancy treatments for these and cross-references, and they all work. And the content for this looks like your Markdown, and it's semantic. If you want to, say, put something on the sidebar that's an article, you just make a fence div that says article, and then the template is going to put there.
The reason I'm sharing this with you is I want to show you something real quick that might have escaped notice, just to show you how incredible Typst is as understanding graphics. Look at this part right here, where it says award-winning science. Pay attention to this line here. Looks very innocuous, right? It's just a line there. It's a little sus, right? Like it knows how to end exactly at the right spot. Is that a coincidence? What's going on there, right?
You know, if you're in a different place, maybe you don't do award-winning science. You do okay science. It's okay. It's fine. But if you want a kick-ass newsletter, we got you. And now pay attention to this. Look at where the line went. So Typst knows how to reason about font sizes right on the language. So if you want to do things like I want to take this thing and I want to stretch it so that it fits exactly at the right spot, or if this text is too big, I want it to render with a different font, you can all do this from a real programming language with scope, with variables, with error messages. So if you're a template user, this is so much better than LaTeX. I cannot tell you. If you've written any LaTeX template, you're thinking this is impossibly good. I promise it's very, very easy.
And I will show you how easy it is. Where is the template for the department news? It's right there. And this just looks like code. It's incredible. The way this works is literally you just ask for the size of the content and then you use you align it to whatever is left. You measure the image, you find the correct line width, and then you subtract it from the other one. So right in your code, you just literally say how big was this text that I was going to render? It's this much. Make the line. That's all that one.
It's a real programming language operating on text with full right-to-left support, ligature support, computation, all of that. Great error messages. It's very easy to write. You can kind of see what it's doing. It's not complicated. So I'm going to do two columns. Here's the first column. Here's the other column. It's right there. It's actually incredibly clean and well-designed.
Sharp edges and what's next
So I hope this gets you excited to actually put sort of, you know, try it out. It's actually much better than I thought. So here's SharpAddress before we're done. Rich just presented, and Rich is the table master of the universe, if you don't know. Like, GT is just mind-blowingly good, and it pains me to tell you that we don't get GT support in Typst right now. But we're going to work on it. It's possible. It's just not there yet. So some features are not there. We have callouts in Quarto. They don't quite work. They sort of render, but they're kind of not great.
So Typst has existed for about a year and a half. So it's very new. There's a lot of support out there already, but it's a little early. So you're probably going to have to do something, but we want to help you. So if this excites you as sort of an alternative for doing PDFs, that is not LaTeX, has better messages, it's kind of great, please give it a try and let us know what you find. So that's it. If you want to find more, we have documentation, links to this slide and the talks. Happy to take questions.
Q&A
First one is the obvious question. So how about equations? Is it decent enough to replace LaTeX? So there's a demo of equations right on the poster. So you can see it's very good, but it's not as good as LaTeX is right now. So you might have to do a little bit of digging, but extending it is quite simple. And they're getting better sort of every day. They do a new release every two, three weeks, and they all improve equations. So it will be there in probably three months or so. I'd say it's 90% there, but it's not 100%.
Second question. Will short codes work with Typst? Yes. If your short code emits just regular markdown, which most do, they will work with Typst. It's just another quarto feature that just should work well together, yes. We should have tested the icons, Richard. I didn't realize it. But we'll make sure it works by tonight.
Next question. What would it take to develop the document in Typst and then convert it to LaTeX to submit it to a journal, for example? What I would recommend you do is, so if you go on the repository that I had there linked, I have a document that was a paper I published as an academic that I converted to QMD. And I have it sort of compiling from quarto to LaTeX and to Typst. And that's the easiest way to do it. But if you are having a hard time, you can try to use something like Melissa suggested earlier, which is Pandoc will parse from the output back into the input if you want to try that. So I haven't tested it for Typst, but that's sort of something you can try to do. So you take the Typst output, convert it to LaTeX, and then you go. I think you should just use quarto markdown for it and target both of those because that's nice. But there might be a way to do the fancy way out.
Okay, last question. Does Typst support other output formats than PDF? Not yet. They said that they are going to support HTML, but it's not out yet. So right now they're used as a PDF engine in the same way that we use LaTeX only as a PDF engine, even though you can get more things out of LaTeX as well.
