More flexible splitting of the bibliography

docs/manual.typ

@@ -21,7 +21,14 @@
 
 = Introduction
 
-_Alexandria_ allows adding multiple bibliographies to the same document. Its two main functions are #ref-fn("alexandria()") and #ref-fn("bibliographyx()"). Typical usage would look something like this:
+_Alexandria_ enables multiple bibliographies within the same Typst document.
+
+With _Alexandria_, each citation citation is associated with a _prefix_.
+To specify the prefix, one can explicitly prepend it to the bibliograhic key (e.g. `@x-quark` or `#cite(<y-arggh>)`)
+or set the default prefix with this #ref-fn("alexandria-prefix()") function.
+#ref-fn("bibliographyx()") allows generating a bibliography limited to the citations with a specific prefix.
+
+Typical usage would look something like this:
 
 #context crudo.join(
   main: -1,
@@ -32,14 +39,30 @@ _Alexandria_ allows adding multiple bibliographies to the same document. Its two
     line => line.replace("PACKAGE", package-import-spec()),
   ),
   ```typ
-  #show: alexandria(prefix: "x-", read: path => read(path))
+  #show: alexandria("bibliography.bib", reader: path => read(path))
 
+  ...
+  My text that references @x-quark and @x-netwok.
   ...
 
   #bibliographyx(
-    "bibliography.bib",
-    // title: auto is not yet supported so it needs to be specified
-    title: "Bibliography",
+    prefix: "x",
+    title: "X Bibliography",
+  )
+
+  ...
+
+  Lets use `y-` prefix by default for the rest of the document.
+
+  #alexandria-prefix("y")
+
+  ...
+  Here we are referencing @arggh and @y-distress.
+  ...
+
+  #bibliographyx(
+    prefix: "y",
+    title: "Y Bibliography",
   )
   ```
 )
@@ -52,11 +75,18 @@ Some known limitations:
 - Native bibliographies have `numbering: none` applied to its title, while Alexandrias' haven't. ```typc show bibliography: set heading(...)``` also won't work on them.
 - Citations that are shown as footnotes are not supported yet -- see #link("https://github.com/SillyFreak/typst-alexandria/issues/11")[issue \#11].
 
-The example on the next page demonstrates some of these. If you find additional limitations or other issues, please report them at https://github.com/SillyFreak/typst-alexandria/issues.
+If you find additional limitations or other issues, please report them at https://github.com/SillyFreak/typst-alexandria/issues.
 
 #pagebreak(weak: true)
 
-= Example -- native Typst version (APA) <ex-native>
+= Example: Separate bibliographies for document sections
+
+Below we demonstrate how to create separate bibliographies with independent numbering for different sections of a document:
+- @ex-native[Example] uses the native Typst bibliography
+- @ex-apa[Example] uses explicit prefix specification (`x`) for Alexandria bibliography with APA-style references
+- @ex-ieee[Example] shows how #ref-fn("alexandria-prefix()") could be used to specify the default prefix (`y`) and generate the IEEE-style bibliography.
+
+== Native Typst (APA) <ex-native>
 
 #[
   For further information on pirate and quark organizations, see @arrgh @quark.
@@ -75,61 +105,58 @@ The example on the next page demonstrates some of these. If you find additional
   )
 ]
 
-= Example -- Alexandria version (APA) <ex-apa>
-
 #[
+
+== Alexandria (APA) <ex-apa>
+
   #import alexandria: *
-  #show: alexandria(prefix: "x-", read: path => read(path))
+  #show: alexandria("bibliography.bib", reader: path => read(path))
 
-  For further information on pirate and quark organizations, see #citegroup(prefix: "x-")[@x-arrgh @x-quark].
+  For further information on pirate and quark organizations, see #citegroup[@x-arrgh @x-quark].
   #cite(<x-distress>, form: "author") discusses bibliographical distress.
 
   #text(lang: "de")[
     Über den "Netzwok" ist in der Arbeit von #cite(<x-netwok>, form: "prose", style: "ieee") zu lesen.
   ]
 
-  #set heading(offset: 1)
   #bibliographyx(
-    "bibliography.bib",
-    prefix: "x-",
+    prefix: "x",
     title: "Bibliography",
-    full: true,
+    //full: true,
     style: "apa",
   )
-]
 
-= Example -- Alexandria version (IEEE) <ex-ieee>
+== Alexandria (IEEE) <ex-ieee>
 
-#[
-  #import alexandria: *
-  #show: alexandria(prefix: "y-", read: path => read(path))
+  #alexandria-prefix("y")
 
-  For further information on pirate and quark organizations, see #citegroup(prefix: "y-")[@y-arrgh @y-quark].
-  #cite(<y-distress>, form: "author") discusses bibliographical distress.
+  For further information on pirate and quark organizations, see #citegroup[@arrgh @quark].
+  #cite(<distress>, form: "author") discusses bibliographical distress.
 
   #text(lang: "de")[
-    Über den "Netzwok" ist in der Arbeit von #cite(<y-netwok>, form: "prose", style: "apa") zu lesen.
+    Über den "Netzwok" ist in der Arbeit von #cite(<netwok>, form: "prose", style: "apa") zu lesen.
   ]
 
-  #set heading(offset: 1)
   #bibliographyx(
-    "bibliography.bib",
-    prefix: "y-",
+    prefix: "y",
     title: "Bibliography",
-    full: true,
+    //full: true,
     style: "ieee",
   )
 ]
 
 #pagebreak(weak: true)
 
-= Splitting bibliographies
-
-The previous three examples showed using Alexandria to render three separate bibliographies for different parts of a document: @ex-native[Example] used the native bibliography, @ex-apa[Example] used Alexandria to show APA style references, and @ex-ieee[Example] showed IEEE style. Particularly, with IEEE, all references are numbered and multiple separate Alexandria bibliographies would reuse the same 1-based numbering.
+= Splitting bibliographies <ex-split>
 
-This approach is thus not suitable for multiple bibliographies that serve the same regions of a document. For this purpose, Alexandria also supports splitting the _loading_ and _rendering_ of a bibliography, giving you the opportunity to preprocess the bibliography entries. Instead of calling #ref-fn("bibliographyx()") directly, you'd use #ref-fn("load-bibliography()") followed by #ref-fn("get-bibliography()") and #ref-fn("render-bibliography()").
+In the previous example, the bibliographies we created for separate parts of a document, and each had its own independent numbering.
+This approach will not work when multiple bibliographies have to serve the same region of the document, because with overlapping numbers the citations become ambiguous.
+For this scenario, Alexandria allows decoupling _collection_ of the references from their _rendering_.
+Instead of a single #ref-fn("bibliographyx()") call:
+- #ref-fn("collect-citations()") assembles the combined list of all bibliographical entries with prefixes that match the user-specified criteria
+- #ref-fn("render-bibliography()") renders the subset of this list, further filtering its entries by the prefix or other properties. #ref-fn("render-bibliography()") could be called multiple times, each time with a different filter.
 
-An example could look like this:
+An example Typst code could look like this:
 
 #context crudo.join(
   main: -1,
@@ -140,78 +167,60 @@ An example could look like this:
     line => line.replace("PACKAGE", package-import-spec()),
   ),
   ```typ
-  #show: alexandria(prefix: "x-", read: path => read(path))
+  #show: alexandria("bibliography.bib", reader: path => read(path))
 
   ...
 
-  // load the bibliography so that the data is available to citations and rendering
-  #load-bibliography("bibliography.bib")
-
-  #context {
-    // get the bibliography items
-    let (references, ..rest) =  get-bibliography("x-")
-
-    // render the bibliography
-    render-bibliography(
-      title: [Bibliography],
-      (
-        // instead of giving it all references, only consider non-book references
-        references: references.filter(x => x.details.type != "book"),
-        // `render-bibliography()` also needs the non-reference information
-        // that was returned by `get-bibliography()`
-        ..rest,
-      ),
-    )
-
-    // render the rest of the bibliography
-    // (this could also be somewhere else in the document)
-    render-bibliography(
-      title: [Books],
-      (
-        references: references.filter(x => x.details.type == "book"),
-        ..rest,
-      ),
-    )
-  }
-  ```
-)
+  #collect-citations("a_and_b", prefix-filter: ("a", "b"))
 
-= Example -- Splitting a bibliography <ex-split>
+  #render-bibliography("a_and_b",
+    filter: ref => ref.prefixes.contains("a"),
+    title: "A Bibliography",
+  )
 
-Here is a rendered example of using this approach. You can see how the single call to #ref-fn("load-bibliography()") results in the entries using distinct numbers.
+  #render-bibliography("a_and_b",
+    filter: ref => ref.prefixes.contains("b") and ref.details.type != "book",
+    title: "B Articles",
+  )
 
-Note how all references are rendered once, although in a different presentation from usual. This is generally a requirement for citations being able to refer to their corresponding reference's label. In this particular case, this is not a concern since there are no citations and references were rendered due to the #ref-fn("load-bibliography.full") option, but in general this is a concern.
+  #render-bibliography("a_and_b",
+    filter: ref => ref.prefixes.contains("b") and ref.details.type == "book",
+    title: "B Books",
+  )
+  ```
+)
+
+Here's the rendered output:
 
 #[
   #import alexandria: *
-  #show: alexandria(prefix: "z-", read: path => read(path))
+  #show: alexandria("bibliography.bib", reader: path => read(path))
+  #alexandria-prefix("a")
 
-  #load-bibliography(
-    "bibliography.bib",
-    prefix: "z-",
-    full: true,
+  For further information on pirate and quark organizations, see #citegroup[@arrgh @quark].
+  #cite(<b-distress>, form: "author") discusses bibliographical distress in @b-distress,
+  and @b-psychology25 is a hefty volume on various aspects of psychology.
+
+  #text(lang: "de")[
+    Über den "Netzwok" ist in der Arbeit von #cite(<b-netwok>, form: "prose", style: "apa") zu lesen.
+  ]
+
+  #collect-citations("a_and_b", prefix-filter: ("a", "b"))
+
+  #render-bibliography("a_and_b",
+    filter: ref => ref.prefixes.contains("a"),
+    title: "A Bibliography",
   )
 
-  #set heading(offset: 1)
-  #context {
-    let (references, ..rest) =  get-bibliography("z-")
-
-    render-bibliography(
-      title: [Bibliography],
-      (
-        references: references.filter(x => x.details.type != "book"),
-        ..rest,
-      ),
-    )
-
-    render-bibliography(
-      title: [Books],
-      (
-        references: references.filter(x => x.details.type == "book"),
-        ..rest,
-      ),
-    )
-  }
+  #render-bibliography("a_and_b",
+    filter: ref => ref.prefixes.contains("b") and ref.details.type != "book",
+    title: "B Articles",
+  )
+
+  #render-bibliography("a_and_b",
+    filter: ref => ref.prefixes.contains("b") and ref.details.type == "book",
+    title: "B Books",
+  )
 ]
 
 #pagebreak(weak: true)

gallery/example.typ

@@ -1,27 +1,30 @@
-#import "@preview/alexandria:0.2.0": *
+#import "@local/alexandria:0.3.0": *
 
 #set document(date: none)
 #set page(height: auto, margin: 8mm)
 
-#show: alexandria(prefix: "x-", read: path => read(path))
-#show: alexandria(prefix: "y-", read: path => read(path))
+#show: alexandria("bibliography.bib", reader: path => read(path))
 
 = Section 1
 
-For further information, see #cite(<x-netwok>, form: "prose").
+#alexandria-prefix("x")
 
-#bibliographyx(
-  "bibliography.bib",
-  prefix: "x-",
-  title: "Bibliography",
-)
+For further information, see #cite(<netwok>, form: "prose").
+
+#bibliographyx(prefix: "x", title: "Bibliography")
 
 = Section 2
 
-We will now look at pirate organizations. @y-arrgh
+#alexandria-prefix("y")
+
+We will now look at pirate and quark organizations @arrgh@y-quark.
+
+#bibliographyx(prefix: "y", title: "Bibliography")
+
+= Section 3
+
+#alexandria-prefix("z")
+
+A bit of psychology #citegroup([@mcintosh_anxiety @psychology25]).
 
-#bibliographyx(
-  "bibliography.bib",
-  prefix: "y-",
-  title: "Bibliography",
-)
+#bibliographyx(prefix: "z", title: "Bibliography")

plugin/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "alexandria"
-version = "0.1.0"
+version = "0.3.0"
 edition = "2021"
 
 [lib]