search

Pablo-Gonzalez-Calderon / showybox-package

A Typst package for creating colorful and customizable boxes
MIT License
49 stars 5 forks source link

Add the manual source (Typst file) #15

Closed Andrew15-5 closed 11 months ago

Andrew15-5 commented 11 months ago

I've noticed that the repo has a manual PDF file, but is missing the source file (Typst). Why is that? You should probably include it.

Pablo-Gonzalez-Calderon commented 11 months ago

I've kept the manual source code private due to two main reasons:

  1. Currently, it's a mess. I set it up too fast and the file's organization inside it it's kind of crazy 😅
  2. I'm thinking to change it's appearance by using another Typst packages for creating manuals and show example code in a better way.

Due to my lack of time theese weeks (months) I've extended this tasks for a long time. Hopefully in v1.1.1 (or v1.2.0, depending on the new changes) I'll come up with a more "orthodox" and decent manual that can be understood and modified by everyone 🍀

I hope you can understand 😅

Andrew15-5 commented 11 months ago

I have already seen cetz manual with tidy package. I assume right now you use it too. It's crazy how many packages already exist. That's why I don't closely follow them. Which package do you want to use instead? I think tidy is pretty decent, but I haven't tried it myself.

Pablo-Gonzalez-Calderon commented 11 months ago

I was thinking to use tidy 😅. Currently the manual is 100% code-independent. Also I will try to use codelst for the example code.

And yeah, there're lots of packages around 🤯

Pablo-Gonzalez-Calderon commented 11 months ago

I've finally finished the first (I wish it is the last, but nobody knows 🧐) version of the new manual for v1.2.0 with "cleaner" code that is more understandable than the previous one.

I only used codelst as I didn't get really convinced by tidy for creating documentation.

I also reduced the number of examples: before was one example for each property, and now there are better examples for groups of properties.

Writing the manual helped me to see some bugs that I didn't notice before. Now the code is, in my opinion, widely tested. I'm thinking of submitting the current code as v1.2.0 in Typst package repository and fix the remaining bugs (1 or 2, related to shadows in breakable showyboxes with <100% width) in v1.2.1. What do you think? I think the code is pretty stable now for submitting it 🤔

Andrew15-5 commented 11 months ago

Writing the manual helped me to see some bugs that I didn't notice before.

The great wisdom says that in order to find bugs in your code, you have to explain everything line by line. It sure helped me a couple of times.

submitting the current code as v1.2.0 in Typst package repository and fix the remaining bugs

The issue again is that you have a stable/production ready version. This means that each new version has to be (ideally) bug-free.

Strictly speaking, you definitely have a breaking change in the config, so you have to release 2.0.0. And since you know you still have bugs, then you should fix them before rolling out a new stable version. But this mostly depends on how serious you are about semver and production. I'm pretty serious, so I said what I think. The rest is up to you.

Pablo-Gonzalez-Calderon commented 11 months ago

Hmmmm. I see. Thank you for your feedback!