I am hoping one day to be sufficiently fluent in Typst that I do not need to ask regular questions on a forum (and/or frequently consult ChatGPT, once it has ingested the contents of this forum and the documentation.)
One thing that would help is if there could be a few examples of each item in the documentation, including at least one very straightforward example.
As an example of the phenomenon I am referring to, I wanted to find more about raw so I look at the documentation and I see that it takes an argument called text. I want to get a bit more information about this argument so I expand it and rather than finding an example like raw("Hello World") or finding out whether I can use raw([Hello World]) or raw(Hello World), I instead learn that I can hack together a domain specific language using the functionalities of raw together with #show rules.
I think your problem is that you are not familiar with existing types. The documentation clearly states that the text parameter is required (i.e., you can’t call the constructor without providing this parameter) and is positional (i.e., you have to directly provide a value and not text: some-value, which is different from a named/settable parameter). There is also a tooltip available:
And the type is onlystr, which means you can only pass a string and no other type.
With above information (which is present in the documentation) in mind, you can use raw() like raw("Hello World"), but you can’t use raw([Hello World]) (or raw[Hello World]), because [] is of type content. And raw(Hello World) is simply not a valid syntax, because you didn’t define Hello and World plus there is a space between those two tokens. If you want to get creative, you can do:
#let Hello = "Hello"
#let World = " World"
// #raw(Hello+World) // Not very readable, but you just replace ` ` with `+`.
#raw(Hello + World)
Thank you - yes I assumed it would need a string passed in but the purpose of documentation (in particular the examples) is to help people who are new to the language rather than as a record for people who are already accomplished. And for all a newcomer knows, there is some automatic string conversation that takes place - for instance this happens whenever you put something in back ticks, you are not required to put quotation marks as well.
I have posted this in “General” rather than “Questions” as I think this is a general issue in the documentation which should be considered.
It might, however, be that the maintainers and authors are keen to keep a higher barrier to entry, but I want that to be an explicit choice rather than the result of an oversight.
If you go to https://typst.app/docs/ you will see that there is a “Step-by-step guide to help you get started” in addition to the reference. Have you read through the tutorial? There are plenty of simple examples specifically made for newcomers. There is Syntax – Typst Documentation page that goes over all of the syntax that Typst has. If after reading through all of those pages, you still have some difficulties understanding the fundamentals of Typst syntax, let me know.
After the first read, you are highly unlikely to read them again (in the future). This is because you can learn fundamentals very quickly. What you will be returning to in the documentation is the “Library” section:
It has a ton of functions, which isn’t something that you can memorize overnight (e.g., I don’t remember all of the math functions because I simply don’t use them). I still open it from time to time because some things just don’t stick around as the time goes by.
There are indeed lots of great starting points and I have looked at some of them. My initial request was for the documentation to include straightforward examples, but it could be that I am unusual in wanting this and that most users would prefer to click on the example for “raw” and find out that you can design a domain specific language like the one linked above.
I would be interested to hear from others, too, because it might just be that the culture of typst community is different from other programming communities I have been part of.
Writing documentation is not trivial, so I’m sure there is room for improvement. Often, feedback from the actual users of documentation is the only thing that can reveal weaknesses there, so thank you.
The central problem is that it’s both. Most of the documentation for specific functions/types/features is in the “Reference” part, and one goal of a reference is to be easy to look up when looking for a specific thing. That doesn’t mean that it should be harder to access for someone not already deep into Typst, but I think it illustrates the conflict.
These examples are usually on the general section of each page. For example, at the top of the raw page are examples that show
single and triple backtick syntax,
block and inline raw code,
specifying the language for inline and block code.
These examples are really simple and, at least as far as I’m concerned, show what usual users would want to do without overcomplicating the scenario. The syntax section below that describes in more detail how the backtick syntax works (I wonder if it’s easy enough to read – if not, that’s partially my fault, I helped with that…)
What’s not shown there, and that’s something that should probably be improved, is just using #raw() as a function. It’s rare that you have to do it, but it really does feel like an oversight.
And that raw is not often called as a function is probably also a reason why the text parameter example is so complicated: there is simply not much to show for the text parameter that has not already been shown. When do you need to refer to text? Basically only in a show rule, so that’s the way the example goes. It may not have been the best choice, but I think that’s how that choice was made.
I’m not on the team but that’s definitely not it. If the barrier of entry was no concern, then LaTeX would have been enough I think we’re all thankful for this feedback; it’s hard to see this from inside. If you’re motivated to do so, I would ask the following:
look at the weak spots you identified again with the expectation that the simplest examples are not listed with the parameters, but in the general sections
report the specific functions/features/parameters that you still think need improvement
if you have ideas for good examples, put them in the issue, or if you are proficient enough in Rust & Git, open a pull request modifying the relevant doc comments. Improving (I hope) the raw docs was actually my first contribution to Typst.
Thanks @SillyFreak for this reply. I see what you’re saying about potentially doing the pull request and making suggested changes etc.; I’m afraid that is beyond me at the moment.
I still find it strange that the initial documentation does not have an example without the backtick syntactic sugar, e.g. to say that `Hello World` is equivalent to raw("Hello World").
The reason that I noticed this was that I wanted to do some simple string interpolation within some raw text, e.g. to put in some variable into my raw text.
#let name = "John"
`Hello #name` // doesn't work
#raw("Hello " + name) // does work
This example feels like a more logical reason why you might want to call #raw explicitly (although if there is a way using the backticks, I would also be interested in that.)
It’s a fact that the current documentation is not great for beginners and we’re aware of it. We want to put greater focus on creating better introductory-level material in the near-ish future.
We’ve noticed that some people love the docs and some don’t like them at all and the distinction is typically whether they are experienced programmers or not. That’s something we need to improve on: In part with tweaks to the reference, but primarily with better tutorial and guide-style documentation.
Thank you for saying this. I think one other thing that people sometimes forget is that regular users do not always diligently work their way through all the tutorials, but instead might just glean enough to get started on the actual problem they are trying to solve.
This means that they can be left with incomplete mental models, and ideally, other parts of the documentation could help fill in those gaps. Not by repeating everything, but if the example for raw had said that `Hello World` is converted to #raw("Hello World") then that reinforces the idea that there is syntax sugar but the actual raw function operates on strings.
The challenge with any of this, of course, is that the people doing the documentation already have very complete mental models of how the whole system works, and are unlikely to know the types of misconceptions that a newcomer might have formed.
Hopefully this forum helps with this problem though!
Right now I’m still fully occupied with the release preparations, but once I’ve thought a bit more about it, after the release, I might get back to this.
I think we’re all thankful for this feedback; it’s hard to see this from inside. If you’re motivated to do so, I would ask the following: