Release: 0.3.0

tingerrr · Jan 8, 2024 · eabba30 · eabba30
2 parents 10127b1 + d1c3a9a
commit eabba30
Show file tree

Hide file tree

Showing 107 changed files with 1,350 additions and 484 deletions.
diff --git a/README.md b/README.md
@@ -1,18 +1,14 @@
 # hydra
-Hydra is a [typst] package allowing you to easily display the current section anywhere in your
-document. In short it will show you the current section only when you need to know it, that is
-when the last section still has remainig text but it's heading is nowhere to be seen.
+Hydra is a [typst] package allowing you to easily display the heading like elements anywhere in your
+document. In short, it will show you the currently active element only when it is not visible.
 
-By default hydra also assumes that you use `a4` page size and margin, see its named parameters
-to adjust this.
-
-## Note on API
-The current API is subject to change in the next version when new features for general handling of
-headings is added.
+Some of hydra's features rely on the size of the top-margin, if you use a different page size than
+`a4` or a custom top margin for your pages, make sure to configure hydra, otherwise those cheks may
+not work.
 
 ## Example
 ```typst
-#import "@preview/hydra:0.2.0": hydra
+#import "@preview/hydra:0.3.0": hydra
 
 #set page(header: hydra() + line(length: 100%))
 #set heading(numbering: "1.1")
@@ -39,60 +35,33 @@ headings is added.
 ![ex5]
 
 ## Documentation
-Changing the default behavior can be done using the various named parameters:
-```typst
-#let hydra(
-  sel: heading,                     // the elements to consider
-  prev-filter: (ctx, p, n) => true, // check if the last element is eligible
-  next-filter: (ctx, p, n) => true, // check if the next element is eligible
-  display: core.display,            // displays the eligible element
-  fallback-next: false,             // fallback to the next heading if necessary
-  binding: none,                    // whether the redundancy check should be book binding aware
-  paper: "a4",                      // the paper size to use
-  page-size: auto,                  // the smaller page size if set
-  top-margin: auto,                 // the top margin is set
-  loc: none,                        // a location from which to search
-) = {
-  ...
-}
+For a more in-depth description of hydra's functionality and the reference read its [manual].
+
+## Contribution
+### Testing
+This package serves as my real-world test for [`typst-test`][typst-test], it is not required for
+contributions, but encouraged as it speeds up the review process.
+
+Other than that tests can be run using the following command structure for each test:
+```bsh
+test=...
+typst --root . "tests/typ/${test}.typ" "tests/out/${test}/{n}.png"
+# some command to compare images in tests/ref/${test} and tests/out/${test}
 ```
 
-`sel` can be a `selector`/`element`, or a tuple of (`selector`/`element`, `function`), where the
-function is used in querying this is mainly useful for selecting ranges of headings without building
-a complicated selector `(heading, (ctx, h) => h.level in (1, 2, 3))`. This function is executed for
-each matching element in your document.
-
-`loc` can be used in contexts where location is already known, this avoids a call to `locate`,
-allowing you to inspect the result of `display` directly.
-
-`prev-filter` and `next-filter` are used to check if an element is eligible for being displayed.
-They receive the `context`, the previous and next element relative to the given `loc`, the element
-that is checked for is not `none`, but the other may be. These functions are executed at most once.
-
-If `binding` is set to `left`/`right`, it will not display the element if it is visible on the
-previous open page. This means for a book with `left` binding, if hydra is used on the right page
-while the previous section is visible on the left page, it will display nothing. Does nothing on
-`none`.
-
-To display the current section even if it's right at the top of the page, set `fallback-next` to
-`true`, this will, if no previous section is eligible, display the next one if it is.
-
-Of `paper`, `page-size` and `top-margin` exactly one must be given. `paper` and `page-size` are for
-convenience and will be used to calculate the `top-margin` for you. Use them as follows:
-
-1. If you use a custom top margin, pass it to `top-margin`
-2. If you use no custom top margin but a custom page size, pass the *smaller* page size to
-   `page-size`
-3. If you use no custom top margin or page size, but a custom paper, pass it `paper`
-
-### Anywhere but the header
-To use the hydra function out side of the header of your doc while retaining its behavior, place the
-`hydra-anchor()` in the header of your document, it'll use this to search as if it was used in the
-header itself.
+## Examples and manual
+Furthermore, I use [`just`][just] and [`nushell`][nushell] to run common commands. It's once again
+not required, as I'll generate those myself if you don't on a PR, but if you already use both you
+can run the example and manual generation using `just gen`.
 
 [ex1]: examples/example1.png
 [ex2]: examples/example2.png
 [ex3]: examples/example3.png
 [ex4]: examples/example4.png
 [ex5]: examples/example5.png
+[manual]: docs/manual.pdf
+
 [typst]: https://github.com/typst/typst
+[typst-test]: https://github.com/tingerrr/typst-test
+[just]: https://just.systems/
+[nushell]: https://www.nushell.sh/
diff --git a/docs/examples/book/a.typ b/docs/examples/book/a.typ
@@ -0,0 +1,3 @@
+#import "/docs/examples/template.typ": example
+#show: example.with(book: false)
+#include "content.typ"
diff --git a/docs/examples/book/b.typ b/docs/examples/book/b.typ
@@ -0,0 +1,3 @@
+#import "/docs/examples/template.typ": example
+#show: example.with(book: true)
+#include "content.typ"
diff --git a/docs/examples/book/content.typ b/docs/examples/book/content.typ
@@ -0,0 +1,5 @@
+= Chapter A
+#lorem(20)
+
+= Chapter B
+#lorem(50)
diff --git a/docs/examples/book/out.toml b/docs/examples/book/out.toml
@@ -0,0 +1 @@
+pages = 3
diff --git a/docs/examples/book/out/a1.png b/docs/examples/book/out/a1.png
diff --git a/docs/examples/book/out/a2.png b/docs/examples/book/out/a2.png
diff --git a/docs/examples/book/out/a3.png b/docs/examples/book/out/a3.png
diff --git a/docs/examples/book/out/b1.png b/docs/examples/book/out/b1.png
diff --git a/docs/examples/book/out/b2.png b/docs/examples/book/out/b2.png
diff --git a/docs/examples/book/out/b3.png b/docs/examples/book/out/b3.png
diff --git a/docs/examples/skip/a.typ b/docs/examples/skip/a.typ
@@ -0,0 +1,3 @@
+#import "/docs/examples/template.typ": example
+#show: example.with(skip-starting: true)
+#include "content.typ"
diff --git a/docs/examples/skip/b.typ b/docs/examples/skip/b.typ
@@ -0,0 +1,3 @@
+#import "/docs/examples/template.typ": example
+#show: example.with(skip-starting: false)
+#include "content.typ"
diff --git a/docs/examples/skip/content.typ b/docs/examples/skip/content.typ
@@ -0,0 +1,5 @@
+= Chapter A
+#lorem(50)
+
+= Chapter B
+#lorem(20)
diff --git a/docs/examples/skip/out.toml b/docs/examples/skip/out.toml
@@ -0,0 +1 @@
+pages = 3
diff --git a/docs/examples/skip/out/a1.png b/docs/examples/skip/out/a1.png
diff --git a/docs/examples/skip/out/a2.png b/docs/examples/skip/out/a2.png
diff --git a/docs/examples/skip/out/a3.png b/docs/examples/skip/out/a3.png
diff --git a/docs/examples/skip/out/b1.png b/docs/examples/skip/out/b1.png
diff --git a/docs/examples/skip/out/b2.png b/docs/examples/skip/out/b2.png
diff --git a/docs/examples/skip/out/b3.png b/docs/examples/skip/out/b3.png
diff --git a/docs/examples/template.typ b/docs/examples/template.typ
@@ -0,0 +1,8 @@
+#import "/src/lib.typ": hydra
+
+#let example(..args, body) = {
+  set page(paper: "a8", header: hydra(..args, paper: "a8"))
+  show heading.where(level: 1): it => pagebreak(weak: true) + it
+  set par(justify: true)
+  body
+}
diff --git a/docs/manual.pdf b/docs/manual.pdf