Added FAQ

doc/chapters/2-guide.typ

@@ -0,0 +1,10 @@
+#import "/doc/util.typ": sub-file
+
+= Introduction
+#sub-file("chapters/2-guide/1-intro.typ")
+
+= Features
+#sub-file("chapters/2-guide/2-features.typ")
+
+= Frequently Asked Questions
+#sub-file("chapters/2-guide/3-faq.typ")

doc/chapters/1-intro.typ → doc/chapters/2-guide/1-intro.typ

@@ -3,7 +3,7 @@
 
 Hydra is a package which aims to query and display section elements, such as headings,legal paragraphs, documentation sections, and whatever else may semantically declare the start of a document's section.
 
-== Terminology & Semantics
+= Terminology & Semantics
 The following terms are frequently used in the remainider of this document.
 
 / primary: The element which is primarily looked for and meant to be displayed.

doc/chapters/2-features.typ → doc/chapters/2-guide/2-features.typ

@@ -1,12 +1,12 @@
 #import "/doc/util.typ": load-examples, show-examples, issue, mantys
 #import mantys: package
 
-== Contextual
+= Contextual
 Hydra will take contextual information into account to provide good defaults, such as inferring the
 reading direction and binding from the page and text styles to offer correct handling of books as
 seen in @book-mode.
 
-== Custom Elements <custom>
+= Custom Elements <custom>
 Because some documents may use custom elements of some kind to display chapters or section like
 elements, Hydra allows defining its own selectors for tight control over how elements are
 semantically related.
@@ -43,12 +43,12 @@ The usage of `custom` allows specifying an element's ancestors, to ensure the sc
 The selectors module also contains some useful default selectors.
 
 #pagebreak()
-== Redundancy Checks
+= Redundancy Checks <redundancy>
 Generally Hydra is used for heading like elements, i.e. elements which semantically describe a section of a document.
 Whenever Hydra is used in a place where its output would be redundant, it will not show any output by default.
 The following sections explain those checks more closely and will generally assume that Hydra is looking for headings for simplicity.
 
-=== Starting Page <starting-page>
+== Starting Page <starting-page>
 Given a page which starts with a primary element, it will not show anything.
 If `skip-starting` is set to `false`, it will fallback to the next element, in this case the heading at the top of the page.
 
@@ -64,7 +64,7 @@ For more complex selectors this will not correctly work if the first element on
 See #issue(8).
 
 #pagebreak()
-=== Book Mode <book-mode>
+== Book Mode <book-mode>
 Given a leading page, if `book` is set to `true`, then if the previous primary element is still
 visible on the previous (trailing) page it is also skipped.
 
@@ -77,7 +77,7 @@ visible on the previous (trailing) page it is also skipped.
 This may produce unexpected results with Hydra is used outside the header and the text direction where it is used is different to where its anchor (see @anchor) is placed.
 This can be prevented by explicitly setting its `binding` and `dir` arguments.
 
-== Anchoring <anchor>
+= Anchoring <anchor>
 To use Hydra outside of the header, an anchor must be placed to get the correct active elements.
 Hydra will always use the last anchor it finds to search, it doesn't have to be inside the header, but should generally be, otherwise the behavior may be unexpected.
 

doc/chapters/2-guide/3-faq.typ

@@ -0,0 +1,57 @@
+#import "/doc/util.typ": issues, issue
+
+The following questions and answers largely use the simple heading use case, but may apply to any custom elements and selectors.
+
+#let qna(q, a) = grid(
+  columns: 2,
+  row-gutter: 1em,
+  inset: (x: 0.5em),
+  [*Q*], strong(q),
+  [*A*], grid.vline(start: 1), a,
+)
+
+#qna[
+  I updated hydra and it doesn't work any more?
+][
+  // TODO: once released as 1.0 the second point would change
+  - If you updated to a new _major_ version make sure to read the changelog for any breaking changes.
+  - If you updated to a new _minor_ version make sure to read the changelog for any breaking changes.
+  - If you updated to a new _patch_ version and used unstable APIs then should check the changelog or source code to see if the API you used is still available. Read @api to see which APIs are stable or unstable.
+
+  If you encounter undocumented semver breakage, please report it at #issues.
+]
+
+#qna[
+  Why does hydra not show a heading where I want it to?
+][
+  Hydra will automatically detect where showing a heading would be redundant and refuse showing it.
+  See @redundancy on when that is the case, as well as how it is detected.
+]
+
+#qna[
+  Why does hydra show headings even when a page starts with a new heading?
+][
+  There are a few possible causes:
+  - If you are preparing your document and it is largely composed of empty pages with just headings, it may be caused by an introspection bug like #issue(7), this can be fixed by adding content.
+  - If you use custom selectors make sure to read @custom on how to correctly define ancestors
+  - If you have a rule which adds vertical leading spacing like `v(...)`it will change the location of the heading, this location is used to determine if a page starts with a heading or not. Make sure the location stays at the start of the element and includes the spacing, this can be done by surrounding the rule with a block or box, or by putting visible content before it.
+
+      ```typst
+      // do
+      #show heading: it => block(v(8cm) + it)
+
+      // don't
+      #show heading: it => v(8cm) + it
+      ```
+
+  - If you encounter an issue with Hydra not detecting redundant sections, please report it at #issues
+]
+
+#qna[
+  Why does hydra not show the correct heading?
+][
+  - Similar to the previous question, if your document is largely empty save for a few headings, you may encounter a bug like #issue(7) and can resolve it the same way.
+  - As before, if you use custom selectors make sure to read @custom on how to correctly define ancestors
+
+  If you encounter an issue with Hydra reporting the wrong active element, please report it at #issues.
+]

doc/chapters/3-reference.typ

@@ -7,7 +7,7 @@
   bbox(fill: yellow.lighten(50%), `unstable`)
 }
 
-== Stability
+= Stability
 The following stability guarantees are made, this package tries to adhere to semantic versioning.
 
 #table(columns: 2, gutter: 0.25em, align: (right, left), stroke: none,
@@ -19,15 +19,15 @@ The following stability guarantees are made, this package tries to adhere to sem
 )
 
 #let ref-heading(is-stable, body) = {
-  heading(depth: 3, body)
+  heading(depth: 2, body)
   place(
     right,
     dy: -2.4em,
     stable(is-stable),
   )
 }
 
-== Custom Types
+= Custom Types
 The following custom types are used to pass around information easily, they are regular Typst dictionaries with expected keys.
 
 #ref-heading(true)[queryable]
@@ -117,5 +117,5 @@ let hydra-context = (
   #tidy-module(read(path), name: name)
 ]
 
-== Modules
+= Modules
 #mods.map(x => render-module(..x)).join(pagebreak(weak: true))

doc/manual.typ

@@ -1,7 +1,10 @@
 #import "template.typ": project, raw-bg
-#import "util.typ": package, bbox, mantys
+#import "util.typ": package, bbox, mantys, issues, sub-file
+
+#import "/src/lib.typ" as hydra
 
 #show "Hydra": mantys.package
+#show link: text.with(eastern)
 
 #show: mantys.mantys.with(
   ..package,
@@ -32,15 +35,11 @@ Hydra aims to be:
 - minimal
   - it should only provide features which are specifically used for heading and section querying and display
 
-If you think its behvior is surprising, you believe you found a bug or you think its defaults or parameters are not sufficient for your use case, please open an issue at #text(eastern, link("https://github.com/tingerrr/hydra")[GitHub:tingerrr/hydra]).
+If you think its behvior is surprising, you believe you found a bug or you think its defaults or parameters are not sufficient for your use case, please open an issue at #issues.
 Contributions are also welcome!
 
 = Guide
-== Introduction
-#include "chapters/1-intro.typ"
-
-== Features
-#include "chapters/2-features.typ"
+#sub-file("chapters/2-guide.typ")
 
-= Reference
-#include "chapters/3-reference.typ"
+= Reference <api>
+#sub-file("chapters/3-reference.typ")

doc/util.typ

@@ -22,8 +22,14 @@
   grid(columns: (1fr, 1fr), gutter: 0.5em, align(center + horizon)[Binding], ..examples),
 )
 
+#let sub-file(path) = {
+  set heading(offset: path.split("/").len() - 1)
+  include path
+}
+
 #let issue(num) = link(package.repository + "/issues/" + str(num))[hydra\##num]
 
+#let issues = link(package.repository + "/issues/")[GitHub:tingerrr/hydra]
+
 #let raw-bg = gray.lighten(50%)
 #let bbox = box.with(inset: (x: 0.25em), outset: (y: 0.25em), radius: 0.25em)
-

src/lib.typ

@@ -3,7 +3,7 @@
 #import "/src/selectors.typ"
 
 /// An anchor used to search from.
-/// When using `hydra` ouside of the page header, this should be placed inside the pge header to find the correct searching hydra-context.
+/// When using `hydra` ouside of the page header, this should be placed inside the page header to find the correct searching hydra-context.
 /// `hydra` always searches from the last anchor it finds, if and only if it detects that it is outside of the top-margin.
 #let anchor() = [#metadata(()) <hydra-anchor>]