`inline-note` example doesn't work without all imports

[sitandr]

There is almost no current package documentation, and the one that is there is very hard to read.

I tried using your example code from docs/main.typ, but failed. The minimal reproducible example is

#import "@preview/drafting:0.1.1": *

#let (l-margin, r-margin) = (1in, 2in)
#set page(
  margin: (left: l-margin, right: r-margin, rest: 0.1in),
)
#set-page-properties(margin-left: l-margin, margin-right: r-margin)

#inline-note(par-break: false, stroke: (paint: orange, dash: "dashed"))[
  But you can specify `par-break: false` to prevent this
]

(taken from line 113 in docs/main.typ)

That produces that very hard to fix error on Typst 0.9.0:

error: cannot divide auto by integer
    ┌─ @preview/drafting:0.1.1\drafting.typ:379:14
    │
379 │       let t = s.thickness / 2
    │               ^^^^^^^^^^^^^^^

If you add thickness argument to stroke, it will fail with similiar error in some other place.

Anyway, I think that package really needs better documentation (there is even no "how to import package from @preview" code snippet in README.md, as requested by Typst Packages repo).

[ntjess]

I agree, I wish I had more time to clarify the documentation and add more use cases. I've attempted to flesh out the function docstrings a bit more, and fixed the compilation error you pointed out. Both should be available on the main branch; I might make a new release soon based on this fix.

In the future, it would be more constructive for you to note specifically which portions of the library are most difficult to understand and would most benefit from added documentation, rather than a blanket statement of disapproval -- this is hard to fix in a targeted manner with the limited amount of free time I have available.

I would be happy to merge a PR if you want to add the "how to import package" instructions to the readme.

Thanks for your feedback!

[sitandr]

Thank you for your work!

Sorry about bad feedback. I admire of your package and wanted to add the examples of this package usage to the Typst Examples Book I'm writing. This is not the first package I have problems demonstrating, partly because of guidelines not being followed. Unfortunately, I've really a little amount of spare time too, so I didn't want to make a PR to every package in Typst Packages. Maybe in future, when I will have more time. I hope for your understanding.

About the documentation improvements. Right now there are literally no docs available in Github repo. One has to compile manual.typ themselves to get basic docs. I strongly suggest adding compiled version to repo and giving a reference from README.md.

Also, ideally, I believe, above each example there should be a source code you can copy-paste to your document. That could be achieved either using codeblocks in markdown and lots of small documents, or one large document with both source and compiled versions. But that is not that necessary. Reading current example document is hard, but possible.

Again, the package itself is great, I just want to say that improving documentation is a very important thing that would allow more people to use the package.

[ntjess]

No problem, I appreciate you including this repo in your book!

The readme mentions main.pdf with copy-able examples, hopefully this meets some of the needs in the meantime. However, I see the value of also pushing manual.pdf -- Once I get the formatting a little nicer, I include that as well. The code blocks are intentionally hidden on the homepage since I didn't want the document to appear too bloated, but do you think it would be better to show them? I am open to the idea. Here is what it would look like:

[sitandr]

(Sorry for the delay)

There are multiple ways to create a good document for Typst package. Unfortunately, there is no standard one yet.

I like how it is done in cetz (multiple examples with links to the source in README, tons of inline examples in manual), polulyx (mdbook with examples and images, certainly an overkill for this case, but still good) and tablex (lots of separate examples, each one with code above and rendered image below). The last one seems to be the most popular abd arguably the easiest to work with.

So my suggestion would be splitting this large example into several separate small. Of course, you can still leave it as is, just add the codeblocks like in image you attached.

Explicit codeblocks are really handy, despite taking some space.

[ntjess]

Error fixed in 5364c8a659a7cd342577b8f086dd46585d51f57f and documentation addressed in adfb1bd79cbfe3dc4d027b834779a7b79e385caf / c3c7172aee9bf66f26730ef21aed64bdafe971ef. Improved documentation will be an ongoing effort, but I think it is safe to close this issue for the time being.