Merge branch 'main' into main

packages/preview/anti-matter/0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 tinger <me@tinger.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/preview/anti-matter/0.1.1/README.md

@@ -0,0 +1,57 @@
+# anti-matter
+This typst packages allows you to simply mark the end and start of your front matter and back matter
+to change style and value of your page number without manually setting and keeping track of inner
+and outer page counters.
+
+## Example
+```typst
+#import "@preview/anti-matter:0.1.1": anti-matter, fence, set-numbering
+
+#set page("a4", height: auto)
+#show heading.where(level: 1): it => pagebreak(weak: true) + it
+
+#show: anti-matter
+
+#set-numbering(none)
+#align(center)[My Title Page]
+#pagebreak()
+#set-numbering("I")
+
+#include "front-matter.typ"
+#fence()
+
+#include "chapters.typ"
+#fence()
+
+#include "back-matter.typ"
+```
+
+![An example outline showing the outer Roman numbering interrupted by temporary inner Arabic
+numbering][example]
+
+## Features
+- Marking the start and end of front/back matter.
+- Specifying the numbering styles for each part fo the document
+
+## FAQ
+1. Why are the pages not correctly counted?
+   - If you are setting your own page header, you must use `step`, see section II in the [manual].
+2. Why is my outline not displaying the correct numbering?
+   - If you configure your own `outline.entry`, you must use `page-number`, see section II in the
+     [manual].
+3. Why does my front/inner/back  matter numbering start on the wrong page?
+   - The fences must be on the last page of their respective part, if you have a `pagebreak`
+     forcing them on the next page it will also incorrectly label that page.
+   - Otherwise please open an issue with a minimal reproducible example.
+
+## Etymology
+The package name `anti-matter` was choosen as a word play on front/back matter.
+
+## Glossary
+- [front matter] - The first part of a thesis or book (intro, outline, etc.)
+- [back matter] - The last part of a thesis or book (bibliography, listings, acknowledgements, etc.)
+
+[front matter]: https://en.wikipedia.org/wiki/Book_design#Front_matter
+[back matter]: https://en.wikipedia.org/wiki/Book_design#Back_matter_(end_matter)
+[example]: example/example.png
+[manual]: docs/manual.pdf

packages/preview/anti-matter/0.1.1/docs/manual.typ

@@ -0,0 +1,164 @@
+#import "@preview/tidy:0.1.0"
+
+#import "template.typ": project
+#let package = toml("/typst.toml").package
+
+#show: project.with(
+    package: package,
+    date: datetime.today().display(),
+    abstract: [
+        This packages automatically numbers the front and back matter of your document separately
+        from the main content. This is commonly used for books and theses.
+    ]
+)
+
+#let codeblocks(body) = {
+    show raw.where(block: true): set block(
+        width: 100%,
+        fill: gray.lighten(50%),
+        radius: 5pt,
+        inset: 5pt
+    )
+
+    show "{{version}}": package.version
+
+    body
+}
+
+#show heading.where(level: 1): it => pagebreak(weak: true) + it
+#outline(
+    indent: auto,
+    target: heading.where(outlined: true).before(<api-ref>, inclusive: true),
+)
+
+= Introduction
+#[
+    #show: codeblocks
+
+    A document like this:
+    #raw(
+        block: true,
+        lang: "typst",
+        read("/example/main.typ").replace(
+            regex("/src/lib.typ"),
+            "@preview/anti-matter:{{version}}",
+        ),
+    )
+
+    Would generate an outline like this:
+    #block(fill: gray.lighten(50%), radius: 5pt, inset: 5pt, image("/example/example.png"))
+
+    The front matter (in this case the outlines) are numbered using `"I"`, the content starts new at
+    `"1"` and the back matter (glossary, acknowledgement, etc) are numbered `"I"` again, continuing
+    from where the front matter left off.
+]
+
+= How it works & caveats
+#[
+    #show: codeblocks
+
+    `anti-matter` keeps track of its own inner and outer counter, which are updated in the header
+    of a page. Numbering at a given location is resolved by inspecting where this location is
+    between the given fences and applying the expected numbering to it. Both `page.header` and
+    `outline.entry` need some special care if you wish to configure them. While `page.header` can
+    simply be set in `anti-matter`, if you want to set it somewhere else you need to ensure that the
+    counters are stepped. Likewise `outline.entry` or anything that displays page numbers for
+    elements needs to get the page number from `anti-matter`.
+
+    == Numbering
+    Numbering is done as usual, with a string or function, or `none`. If the numbering is set to
+    `none` then the counter is not stepped. Patterns and functions receive the current and total
+    value. Which means that `"1 / 1"` will display `"3 / 5"` on the third out of five pages. Because
+    `none` skips stepping it can be used to easily add a title page beforehand, without having to
+    reset the page counter.
+    ```typst
+    #import "@preview/anti-matter:{{version}}": anti-matter, fence, set-numbering
+    #show: anti-matter(numbering: ("I", numbering.with("1 / 1"), none))
+
+    #set-numbering(none)
+    #align(center + horizon)[Title]
+    #pagebreak()
+    #set-numbering("I")
+
+    // page numbering starts at "I"
+    // ...
+    ```
+
+    == Fences
+    For `anti-matter` to know in which part of the document it is, it needs exactly 2 fences, these
+    must be placed on the last page of the front matter and the last page of the main content. Make
+    sure to put them before your page breaks, otherwise they'll be pushed onto the next page. Fences
+    are placed with `fence()`.
+    ```typst
+    #import "@preview/anti-matter:{{version}}": anti-matter, fence
+    #show: anti-matter
+
+    // front matter
+    #lorem(1000)
+    #fence()
+
+    // content
+    #lorem(1000)
+    #fence()
+
+    // back matter
+    #lorem(1000)
+    ```
+
+    == Page header
+    `anti-matter` uses the page header to step its own counters. If you want to adjust the page
+    header sometime after the `anti-matter` show rule, you have to add `step()` before it.
+    ```typst
+    #import "@preview/hydra:0.2.0": hydra
+    #import "@preview/anti-matter:{{version}}": anti-matter, step
+    #show: anti-matter
+
+    // ...
+
+    #set page(header: step() + hydra())
+
+    // ...
+    ```
+
+    == Outline entries and querying
+    By default `outline` will use the regular page counter to resolve the page number. If you want
+    to configure the appearance of `outline` but still get the correct page numbers use
+    `page-number` with the element location.
+    ```typst
+    #import "@preview/anti-matter:{{version}}": anti-matter, page-number
+    #show: anti-matter
+
+    // render your own outline style while retaining the correct page numbering for queried elements
+    #show outline.entry: it => {
+        it.body
+        box(width: 1fr, it.fill)
+        page-number(loc: it.element.location())
+    }
+
+    // ...
+    ```
+
+    The same logic applies to other things where elemnts are queried and display their page number.
+]
+
+= API-Reference <api-ref>
+#let mods = (
+    (`anti-matter`, "/src/lib.typ", [
+        The public and stable library API intended for regular use.
+    ]),
+    (`core`, "/src/core.typ", [
+        The core API, used for querying internal state, public, but not stable.
+    ]),
+    (`rules`, "/src/rules.typ", [
+        Show and set rules which are applied in `anti-matter`, provides default versions to turn of
+        rule.
+    ]),
+)
+
+#for (title, path, descr) in mods [
+    == #title
+    #descr
+
+    #tidy.show-module(tidy.parse-module(read(path)), style: tidy.styles.default)
+    #pagebreak(weak: true)
+]

packages/preview/anti-matter/0.1.1/docs/template.typ

@@ -0,0 +1,71 @@
+// Modified version of https://github.com/Mc-Zen/tidy/blob/abedd7abbb7f072e67ef95867e3b89c0db987441/docs/template.typ
+
+// The project function defines how your document looks.
+// It takes your content and some metadata and formats it.
+// Go ahead and customize it to your liking!
+#let project(
+  package: (:),
+  subtitle: "",
+  abstract: [],
+  date: none,
+  body,
+) = {
+  // Set the document's basic properties.
+  set document(author: package.authors, title: package.name)
+  set text(font: "Linux Libertine", lang: "en")
+
+  show heading.where(level: 1): it => block(smallcaps(it), below: 1em)
+  set heading(numbering: (..args) => if args.pos().len() == 1 { numbering("I", ..args) })
+
+  // show link: set text(fill: purple.darken(30%))
+  show link: set text(fill: rgb("#1e8f6f"))
+
+  v(4em)
+
+  // Title row.
+  align(center)[
+    #block(text(weight: 700, 1.75em, package.name))
+    #block(text(1.0em, subtitle))
+    #v(4em, weak: true)
+    v#package.version #h(1.2cm) #date
+    #block(link(package.repository))
+    #v(1.5em, weak: true)
+  ]
+
+  // Author information.
+  pad(
+    top: 0.5em,
+    x: 2em,
+    grid(
+      columns: (1fr,) * calc.min(3, package.authors.len()),
+      gutter: 1em,
+      ..package.authors.map(author => align(center, strong(author))),
+    ),
+  )
+
+  v(3cm, weak: true)
+
+  // Abstract.
+  pad(
+    x: 3.8em,
+    top: 1em,
+    bottom: 1.1em,
+    align(center)[
+      #heading(
+        outlined: false,
+        numbering: none,
+        text(0.85em, smallcaps[Abstract]),
+      )
+      #abstract
+    ],
+  )
+
+  set page(numbering: "1", number-align: center)
+  counter(page).update(1)
+
+  // Main body.
+  set par(justify: true)
+  v(10em)
+
+  body
+}

packages/preview/anti-matter/0.1.1/example/back-matter.typ

@@ -0,0 +1,7 @@
+#set heading(numbering: none)
+= Glossary
+Content
+= Appendix
+Content
+= Acknowledgement
+Content

packages/preview/anti-matter/0.1.1/example/chapters.typ

@@ -0,0 +1,7 @@
+#set heading(numbering: "1.")
+= Chapter
+== Section
+=== Subsection
+= Chapter
+== Another Section
+= Chapter

packages/preview/anti-matter/0.1.1/example/front-matter.typ

@@ -0,0 +1,9 @@
+#set heading(numbering: none)
+#show outline: set heading(outlined: true)
+#outline()
+= Figures
+Content
+= Tables
+Content
+= Listings
+Content

packages/preview/anti-matter/0.1.1/example/main.typ

@@ -0,0 +1,19 @@
+#import "/src/lib.typ": anti-matter, fence, set-numbering
+
+#set page("a4", height: auto)
+#show heading.where(level: 1): it => pagebreak(weak: true) + it
+
+#show: anti-matter
+
+#set-numbering(none)
+#align(center)[My Title Page]
+#pagebreak()
+#set-numbering("I")
+
+#include "front-matter.typ"
+#fence()
+
+#include "chapters.typ"
+#fence()
+
+#include "back-matter.typ"