staves:0.1.0

[mdavis-xyz]

I am submitting

• a new package
• an update for a package

Description: This Typst package is used to draw musical scales. It draws 5 lines, clefs, key signatures, and then a series of notes. The series can be predefined (e.g. B flat major), or a custom scale.

I have read and followed the submission guidelines and, in particular, I

• selected a name that isn't the most obvious or canonical name for what the package does
• added a typst.toml file with all required keys
• added a README.md with documentation for my package
• have chosen a license and added a LICENSE file or linked one in my README.md
• tested my package locally on my system and it worked
• excluded PDFs or README images, if any, but not the LICENSE

My repo is: https://github.com/mdavis-xyz/staves-typst

Packaging

I am confident in the functionality of the package itself. However I have really struggled to understand how to package it to submit to this repo. I found the instructions to be spread out over too many different places, lacking crucial details. I read all the instructions I could find multiple times, but I'm still confused. So consider this a draft, and please tell me what to do.

How do I configure the imports? /src/core.typ or ./src/core.typ or @preview/staves:0.1.0/core or what? I have no idea. I checked documentation.md, resources.md and tips.md. None of those mention how to do imports. One mentions that in the README you should import from @preview in code blocks shown to the user.

However I tried running typst-package-check check. It throws an error for my import of cetz: #import "@preview/cetz:0.3.4" . "failed to download package (All packages are supposed to be present in the packages repository, or in the local cache.)" It's not clear what this error is for. The code compiles fine with typst watch docs/docs.typ docs/docs.pdf --root $(pwd) and typst watch src/test.typ src/test.pdf --root $(pwd). So it seems the typst compiler can download cetz, but typst-package-check says it can't. I think there's just something big I'm not understanding about what the local cache is. (Was I supposed to checkout my mdavis-xyz/staves-typst repo into ~/.local/share?) I do not understand what "present in the packages repository" is referring to. My understanding is that I'm supposed to have two git repos cloned to my machine. One with my code mdavis-xyz/staves-typst, and then also this repo (typst/packages). But if I'm compiling code in staves-typst, how does typst-package-check know which other folder on my laptop is the clone of typst/packages?

I ran typos on this as suggested by the tips, but it flags every import as a typo, because the .typ file extension is considered a typo of "typo". (A recent PR is still open

I tried running showman but that didn't work. It seems like an issue with how showman is installed by pip.

I tried reading the docs from showman, to figure out what my README should look like. In particular, how to link to images, and where to save images. It's not clear. For now my README.md is a stub. The real docs are in docs/docs.typ. Once the showman bug is solved, I'll update this pull request with a README.md that matches docs/docs.typ. In the mean time, please tell me what to do with my imports.

Sorry for the long rant. I'm just trying to communicate how difficult it was for me as a newcomer to understand what is required of me. In particular, the way that each instruction markdown file branches off into several others made it easy to get lost, miss stuff, and read things in the wrong order. It was hard to see the big picture. If there was just a single markdown file to read from top to bottom to follow the 'golden path', that would be much easier.

Additionally, I was also confused for a long time about the overall approach to packaging. I was expecting something like pypi, where you have only one git repo for your package, and you upload a zip of code files somewhere. Typst uses a different approach. My understanding now is that it is one monorepo, plus a second per-package repo, joined with append-only copy-pasting a subset of files, without pull requests between the two repos, nor a common commit tree. I'm sure there are good reasons for that. It's just not clear for a newcomer that this is the approach. The way it's phrased in the top README.md describes this approach, but in a way that I only find clear in hindsight.
Once I've got a better idea of how this process works, I'm happy to rearrange and add to the documentation, if you want.

[elegaanz]

Hello, and thank you for your feedback. We recently revamped the docs to include more information, and it's very valuable to get some comments from someone making a Typst package for the first time. I'll try to answer everything.

How do I configure the imports? /src/core.typ or ./src/core.typ or @preview/staves:0.1.0/core or what? I have no idea. I checked documentation.md, resources.md and tips.md. None of those mention how to do imports. One mentions that in the README you should import from @Preview in code blocks shown to the user.

It's true that this could be more explicit. I think the section on imports in docs/typst.md could be extended.

However I tried running typst-package-check check. It throws an error for my import of cetz: #import "@preview/cetz:0.3.4" . "failed to download package (All packages are supposed to be present in the packages repository, or in the local cache.)" It's not clear what this error is for. The code compiles fine with typst watch docs/docs.typ docs/docs.pdf --root $(pwd) and typst watch src/test.typ src/test.pdf --root $(pwd). So it seems the typst compiler can download cetz, but typst-package-check says it can't.

This is a technical limitation in typst-package-check. I can take some time to try to see if I can find any workaround, but last time I checked it was just too complex to be fixed. At least the error message it gives could be improved to give more details.

I think there's just something big I'm not understanding about what the local cache is. (Was I supposed to checkout my mdavis-xyz/staves-typst repo into ~/.local/share?) I do not understand what "present in the packages repository" is referring to. My understanding is that I'm supposed to have two git repos cloned to my machine. One with my code mdavis-xyz/staves-typst, and then also this repo (typst/packages). But if I'm compiling code in staves-typst, how does typst-package-check know which other folder on my laptop is the clone of typst/packages?

You are indeed supposed to have these two git repositories on your machine.
If you are running typst-package-check in the typst-staves directory, it will look for external packages in the package cache (~/.local/share/...), but can't download them by itself because of the aforementioned limitation. So you have to make sure the necessary packages are already present there (by compiling a document that imports them with typst compile for example).
If you are running typst-package-check in typst/packages/packages, it will try to find the dependency in the preview directory here first, using the package cache as a last resort.

I ran typos on this as suggested by the tips, but it flags every import as a typo, because the .typ file extension is considered a typo of "typo". (A recent PR is crate-ci/typos#1328

That's a bit unfortunate :( Let's hope this PR will get merged soon.

I tried running showman but ntjess/showman#3. It seems like an issue with how showman is installed by pip.

I tried reading the docs from showman, to figure out what my README should look like. In particular, how to link to images, and where to save images. It's not clear. For now my README.md is a stub. The real docs are in docs/docs.typ. Once the ntjess/showman#3 bug is solved, I'll update this pull request with a README.md that matches docs/docs.typ. In the mean time, please tell me what to do with my imports.

I can't really help here, as I have never used showman personally. I would advise you to open specific issues on the dedicated repository to discuss these points.

Sorry for the long rant. I'm just trying to communicate how difficult it was for me as a newcomer to understand what is required of me. In particular, the way that each instruction markdown file branches off into several others made it easy to get lost, miss stuff, and read things in the wrong order. It was hard to see the big picture. If there was just a single markdown file to read from top to bottom to follow the 'golden path', that would be much easier.

The motivation for splitting the docs into multiple files was that there was just to much information for it to be put linearly in a single document, that some of it was not really depending on any particular reading order, and that some pieces of information are more extra tips to make your life easier than requirements. We still wanted to list to most important aspects of package authoring in the docs/README.md file, so that you can just read that if you want to do the bare minimum, and let people "explore" other files if they needed more details.
But apparently, this doesn't work too well. If you have any suggestion on how this could be improved, without merging everything into a single giant file, I would be happy to discuss it with you.

Additionally, I was also confused for a long time about the overall approach to packaging. I was expecting something like pypi, where you have only one git repo for your package, and you upload a zip of code files somewhere. Typst uses a different approach. My understanding now is that it is one monorepo, plus a second per-package repo, joined with append-only copy-pasting a subset of files, without pull requests between the two repos, nor a common commit tree. I'm sure there are good reasons for that. It's just not clear for a newcomer that this is the approach. The way it's phrased in the top README.md describes this approach, but in a way that I only find clear in hindsight.

Yes, this is the approach for Typst packages. I think you might be biased by other packaging systems you already knew here. However, it may be worth it to be a bit more explicit about the expected submission process in the docs.

[mdavis-xyz]

I think a way to make it clear would to be to have some examples, as code files, not code snippets.
A simple, medium, and complex example.

Simple: A folder (e.g. docs/example/simple/) which contains just lib.typ and typst.toml, LICENSE.txt, README.md, showing the bare minimum needed for a package. Include instructions on how to locally test the package, prior to it existing in @preview.

Medium: A folder with at least two .typ files (showing how to make something 'private', and showing how to import one .typ file from another`), and an asset (e.g. png, svg).

Complex: Just point to a real package, e.g. Cetz, as you already do.

The key thing here is that a user should be able to see wholistically all the files they need, and all the steps they need.

e.g. I still can't figure out how to actually install a package locally. The README says:

• Store a package in ~/.local/share/typst/packages/local/mypkg/1.0.0
• Import from it with #import "@local/mypkg:1.0.0": *

But when I do that, I get "package not found". Is there something missing from the instructions? Note that ~/.local/share/typst did not exist until I manually created it. So is ~/.local/share/typst no longer the correct location? (typst is installed as a Snap on my machine.)

(venv) matthew@zenbook:~/Documents/Projects/software/typst-staves/staves/showman$ typst compile test.typ test.pdf
error: package not found (searched for @local/staves:0.1.0)
  ┌─ test.typ:1:8
  │
1 │ #import "@local/staves:0.1.0": *
  │         ^^^^^^^^^^^^^^^^^^^^^

(venv) matthew@zenbook:~/Documents/Projects/software/typst-staves/staves/showman$ tree ~/.local/share/typst/
/home/matthew/.local/share/typst/
└── packages
    └── local
        └── staves
            └── 0.1.0 -> /home/matthew/Documents/Projects/software/typst-staves/staves/

5 directories, 0 files
(venv) matthew@zenbook:~/Documents/Projects/software/typst-staves/staves/showman$ tree /home/matthew/Documents/Projects/software/typst-staves/staves/
/home/matthew/Documents/Projects/software/typst-staves/staves/

├── LICENSE.txt
├── README.md
├── src
│   ├── core.typ
│   ├── data.typ
│   ├── lib.typ
│   ├── README.md
│   ├── test.typ
│   └── utils.typ
└── typst.toml

How do I install my package locally to test it? What have I done wrong? Why did ~/.local/share/typst not already exist? (I have previously compiled documents that import from @preview, so I expected them to be cached there.)

I'm also still confused about the import syntax. Can you confirm that it is:

• #import "something.typ": * inside the content of the library, if both .typ are in the same folder, even if they're not the root folder
• #import "../somedir/something.typ": * inside the content of the library, if the .typ is in another folder. (Or is it #import /somedir?)
• #import "@preview/mypackage:0.1.0": * inside the README documentation for my package, even though this actually won't work (i.e. is untestable) until after the PR is merged.

For images, will #image("/assets/clefs/...") still work once this package is merged? Or should I use ../ instead of /?

[elegaanz]

Having the three example packages as you suggested sound like a good idea, thanks.

But when I do that, I get "package not found". Is there something missing from the instructions? Note that ~/.local/share/typst did not exist until I manually created it. So is ~/.local/share/typst no longer the correct location? (typst is installed as a Snap on my machine.)

This is a known issue when using Snap, access to the local package directory doesn't work as expected.

How do I install my package locally to test it? What have I done wrong? Why did ~/.local/share/typst not already exist? (I have previously compiled documents that import from @Preview, so I expected them to be cached there.)

It is normal that you had to create that directory: the package cache (~/.cache/typst/packages) and local packages (~/.local/share/typst/packages) directory are different. The former is supposed to be reserved to the compiler, and only exists to not re-download a package on each compilation. The later should be created and populated by users if they want to use local packages, without publishing them to Typst Universe.

Regarding the import syntax: it works just like in the terminal (or most other programming languages), paths starting with a / are absolute, paths without that prefix are relative (to the current file). The only difference is that the root directory is not the root of your filesystem, but the root of your Typst project (either the directory in which you call typst compile or another directory you specified using the --root flag). TL;DR: you got it right.

For the @preview/my-package:0.1.0 imports, you can test them locally by making a copy (or symlink) of your package to ~/.local/share/typst/packages/preview/my-package/0.1.0.

[mdavis-xyz]

For the @preview/my-package:0.1.0 imports, you can test them locally by making a copy (or symlink) of your package to ~/.local/share/typst/packages/preview/my-package/0.1.0.

That's not working for me. What am I doing wrong?

My terminal output from earlier was about doing that for @local. Now I've tried doing that for @preview. Typst tries to download the package. It doesn't notice there's a copy in that local cache.

(venv) matthew@zenbook:~/.local/share/typst/packages/preview/staves$ ls -lh
total 4,0K
lrwxrwxrwx 1 matthew matthew 62 juil.  1 09:14 0.1.0 -> /home/matthew/Documents/Projects/software/typst-staves/staves/

(venv) matthew@zenbook:~/.local/share/typst/packages/preview/staves/0.1.0$ ls
assets  docs  examples  LICENSE.txt  README.md  showman  src  typst.toml

(venv) matthew@zenbook:~/Documents/Projects/software/typst-staves/staves/showman$ typst compile test.typ  test.pdf
downloading @preview/staves:0.1.0
error: package not found (searched for @preview/staves:0.1.0)
  ┌─ test.typ:1:8
  │
1 │ #import "@preview/staves:0.1.0": *
  │         ^^^^^^^^^^^^^^^^^^^^^^^

[elegaanz]

The bug with the Snap package affects the whole ~/.local/share/typst directory, not only the @local subdirectory, so Typst can't read your local package archive correctly. You should install Typst using another method if you want to use this feature for now.

[mdavis-xyz]

Ah yes, of course. You did say that, I missed it. Sorry.

I'll try installing with cargo.

[mdavis-xyz]

I'm still working on this. Since documentation needs to be in markdown, but I want to use variables within the library to write the docs, I'm writing my own implementation of showman.

I've also found some bugs in the core functionality that I need to fix.

I don't have much time at the moment to work on this. It might be another month or two until I'm ready.
Either we can leave this PR here, or I can close it and open another one later.

[elegaanz]

Thank you for the update. We generally try to only keep active PRs open in this repository, so if you don't see yourself finishing it in less than one or two weeks, it would be better to close it for now, yes.