As you can see, they are still on version 0.x, which is exactly the time for breaking stuff.
Julia, too was known for some significant breakage before version 1.0.
6 Likes
What save me most of the time are the error messages which are clear enough to allow for quick fixes.
This is partly due to the fact that the language feels natural. I would add that you have several solutions to solve your problems : fill an issue on the repo of the package, open a topic on discord or on the Typst forum. But I guess you already know that 
4 Likes
Exactly. Note that I am not disparaging Typst when I say it is not mature enough for a general audience, it is a normal stage of software development which all software underwent at some point.
It may be perfectly fine for early adopters, especially if someone is willing to put up with the occasional inconvenience.
I also fully understand why the developers may prioritize features which allows them to make money from it. Clearly, having offline docs in a commonly used searchable format is not one of those since they want to channel people to the online interface.
But as long as Typst is not documented with a FOSS-licensed manual, it not really a LaTeX replacement for many people. I am one of those.
(Cf Julia, which had nice docs in the repo from almost the very beginning. The difference in approach is apparent.)
3 Likes
Really? The whole typst repo, including the docs, has the Apache 2 licence, which is FOSS.
Part of the manual is generated from that docs repo, but the eg “library” section isn’t. Sure, one can read the docstrings in the source code, but it is far from ideal.
Also, I don’t want a FOSS-licensed source for the manual. I want the manual itself Cf
1 Like
But the code to generate the docs is all there right? So you can build it yourself? Is the situation materially any different from say the majority of Julia packages which pretty much only have online HTML docs?
A manual isn’t software, so FOSS licenses don’t really apply anyway.
Apparently not. There was a PR to do it but it was closed, and one reason cited was that it used closed source code from the website that was needed to build the manual.
Some argue that they might not be ideal, but they apply nevertheless (in case you are not aware: Julia’s own docs are in an MIT-licensed repo).
Again, I understand that for some people, docs with a free license are not an issue. For me it is.
4 Likes
Fair enough, but I’m curious - can you say why?
Looks like open-source docs will come along after HTML export.
Secondly, we want to use Typst’s HTML export once it is there to power the docs and do not want to spend time and effort twice in porting things over to a new system.
1 Like
From your discussions, I have had the feeling that they (who build Typst) are not quite open, or they don’t want to be too open.
2 Likes
I agree that they aren’t 100% open, given their closed-source documentation code and paid tiers on the web-app. However, they are otherwise pretty open and communicative. The primary codebase, and multiple additional repositories, are open-source. Many development discussions, led by one of the founders, are held in their Discord server. I also enjoyed attending one of their community calls!
My impression is that they don’t want to release something they aren’t proud of. Typst v0.1 was impressive enough to quickly grab many people’s attention. It seems like the documentation source-code will be given the same treatment; that is, done well and better than the alternative.
6 Likes
I think that Typst has a vibrant user community full of people who are eager to contribute.
I don’t see how not releasing the docs in a format that allows them to do so helps.
3 Likes
Otherwise what you say sounds nice, but I’m not sure that “development discussions are held on Discord” is an argument in favor of Typst being open. Julia’s triage meetings on Slack at least have written summaries sometimes, though, perhaps Typst also does something like that.
3 Likes
I’m not sure about whether they made a written summary, otherwise, it is a matter of platform. Regardless of whether one prefers to talk on GitHub, Slack, Discourse, Discord, etc, these platforms are available to the public. They have a Discourse too.
That is a fair point. Even though it seems like they plan to publicly release the docs, it would have been and will be substantially helpful to do so earlier rather than some unknown date in the future when HTML is “ready enough”.
2 Likes
They don’t have something like triage meetings. Instead each development topic like math, performance, types, fonts, etc. has a “forge” (like a room) on discord where all the history can be read. They did start to publish summaries of the community calls, see here and here (though I could only find those links on discord).
It’s fair to complain that there’s no local documentation, though they mention that it’s planned. I see this as a matter of priorities, and I can imagine that different kinds of languages must set different priorities. I mean Typst is easier to program than LaTeX but the audience is still much less programmy than the Julia audience. For their audience I understand that the website has higher priority.
1 Like
Not all of those.
My main point is that “on discord” and “where all the history can be read” are arguably in conflict. Discord is:
-
Meant for ephemeral discussion and not well suited to anything that will have to be referenced in the future.
-
Not available on the Web openly.
-
Only available to be used for registered users.
-
Only available to be used through approved/official clients. Many ignore this, some get banned.
-
Closed source.
-
Owned by a (for-profit) company whose goals necessarily conflict with the goals of the open-source community using it as a host.
2 Likes
I think that the website is prioritized by the Typst developers, not the audience.
Generating docs is not rocket science. Established workflows exist in almost all modern languages. If they wanted to do it, I guess they could have it already with relatively little effort.
I wonder if not making the full docs available in some convenient format under a FOSS license is an indication that they want to channel users to the web app. I get it that it they want to make money to support the development, but striking the light balance in these matters is quite delicate and IMO this just sends the wrong message.
1 Like
@nsajko yeah discord sucks in these regards but at least it’s better than slack. You can search the history and link to old messages.
In the previously linked issue comment the devs talk of the technical difficulty and state clearly that they want to do it.
You can read here a developer’s answer to someone who made a similar suggestion (that the website was “hiding” the existence of the open-source command-line tool for commercial reasons). If you don’t have a discord account and don’t what to create one the executive summary is “We don’t believe that hiding the CLI or hiding Tinymist or anything like that helps us in any way.”
Of course the commercial side with the startup is going to influence decisions, but it’s also providing a lot of resources. I think even for the open source side it’s a net win. We can always speculate about hidden motives but at some point it gets rather uncharitable… They open sourced the compiler and are very engaged with the community in developing the language. I’ll take their word for it when they say local docs are a bit tricky to do properly but are coming.
3 Likes
The tinymist plugin is excellent and was easy to find. I exclusively use typst in vs code (though tinymist is apparently available for other editors, such as emacs). Documentation is available on hovering, and I assume there would something for more keyboard-centric workflows as well.
2 Likes
Yes, I linked that before.
Note that it is a PR, and not an issue. Someone actually did implement this functionality.
The shot it down as it used some closed source from their website. This is of course legally within their rights, but does not strike me as being eager to do this.
1 Like