Skip to content

Commit

Permalink
Remove FAQ vlines and use mty.codesnippet
Browse files Browse the repository at this point in the history
  • Loading branch information
tingerrr committed May 1, 2024
1 parent 6720f95 commit edb8cf2
Show file tree
Hide file tree
Showing 6 changed files with 110 additions and 81 deletions.
36 changes: 20 additions & 16 deletions doc/chapters/2-guide/1-intro.typ
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
#import "/doc/util.typ": mantys
#import mantys: package
#import mantys: *

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.

Expand All @@ -18,21 +18,25 @@ The following terms are frequently used in the remainider of this document.
The search for a primary element is always bounded to its scope.
For the following simplified document:

```typst
= Chapter 1
== Section 1.1
= Chapter 2
=== Subsection 2.0.1
#hydra(2)
```
```txt
Chapter 1
└ Section 1.1
Chapter 2
└ <none>
└ Subsection 2.0.1
```
#codesnippet[
```typst
= Chapter 1
== Section 1.1
= Chapter 2
=== Subsection 2.0.1
#hydra(2)
```
]
#codesnippet[
```txt
Chapter 1
└ Section 1.1
Chapter 2
└ <none>
└ Subsection 2.0.1
```
]

HYDRA will only search within its current chapter as it is looking for active sections.
In this case HYDRA would not find a suitable candidate.
Expand Down
64 changes: 35 additions & 29 deletions doc/chapters/2-guide/2-features.typ
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
#import "/doc/util.typ": load-examples, show-examples, issue, mantys
#import mantys: package
#import mantys: *

= Contextual
HYDRA will take contextual information into account to provide good defaults, such as inferring the
Expand All @@ -12,32 +12,36 @@ elements, HYDRA allows defining its own selectors for tight control over how ele
semantically related.

Given a custom element like so:
```typst
#let chapter = figure.with(kind: "chapter", supplement: [Chapter])
// ... show rules and additional setup
#chapter[Introduction]
#chapter[Main]
= Section 1.1
== Subsection 1.1.1
= Section 1.2
#chapter[Annex]
```
#codesnippet[
```typst
#let chapter = figure.with(kind: "chapter", supplement: [Chapter])
// ... show rules and additional setup
#chapter[Introduction]
#chapter[Main]
= Section 1.1
== Subsection 1.1.1
= Section 1.2
#chapter[Annex]
```
]

A user my want to query for the current chapter and section respectively:
```typst
#import "@preview/hydra:{{VERSION}}": hydra, selectors
#import selectors: custom
#let chap = figure.where(kind: "chapter")
#let sect = custom(heading.where(level: 1), ancestor: chap)
#set page(header: context if calc.odd(here().page()) {
align(left, hydra(chap))
} else {
align(right, hydra(sect))
})
```
#codesnippet[
```typst
#import "@preview/hydra:{{VERSION}}": hydra, selectors
#import selectors: custom
#let chap = figure.where(kind: "chapter")
#let sect = custom(heading.where(level: 1), ancestor: chap)
#set page(header: context if calc.odd(here().page()) {
align(left, hydra(chap))
} else {
align(right, hydra(sect))
})
```
]

The usage of `custom` allows specifying an element's ancestors, to ensure the scope is correctly defined.
The selectors module also contains some useful default selectors.
Expand Down Expand Up @@ -81,7 +85,9 @@ This can be prevented by explicitly setting its `binding` and `dir` arguments.
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.

```typst
#import "@preview/hydra:{{VERSION}}": hydra, anchor
#set page(header: anchor(), footer: context hydra())
```
#codesnippet[
```typst
#import "@preview/hydra:{{VERSION}}": hydra, anchor
#set page(header: anchor(), footer: context hydra())
```
]
2 changes: 1 addition & 1 deletion doc/chapters/2-guide/3-faq.typ
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ The following questions and answers largely use the simple heading use case, but
row-gutter: 1em,
inset: (x: 0.5em),
[*Q*], strong(q),
[*A*], grid.vline(start: 1), a,
[*A*], a,
)

#qna[
Expand Down
78 changes: 44 additions & 34 deletions doc/chapters/3-reference.typ
Original file line number Diff line number Diff line change
Expand Up @@ -47,57 +47,67 @@ The following type definitions are used to simplify the documentation. The type
#type-def(true)[queryable]
Any type which can be used in `query`, `function` refers to the subset of element functions which are locatable.

```typc
let queryable = label | function | selector
```
#codesnippet[
```typc
let queryable = label | function | selector
```
]

#type-def(true, color: lime)[hydra-selector]
Defines a selector for an ancestor or primary element.

```typc
let hydra-selector = (
target: queryable,
filter: ((hydra-context, candidates) => bool) | none,
)
```
#codesnippet[
```typc
let hydra-selector = (
target: queryable,
filter: ((hydra-context, candidates) => bool) | none,
)
```
]

#type-def(true, color: lime)[full-selector]
Defines a pair of primary and ancestor element selectors.

```typc
let full-selector = (
primary: hydra-selector,
ancestors: hydra-selector | none,
)
```
#codesnippet[
```typc
let full-selector = (
primary: hydra-selector,
ancestors: hydra-selector | none,
)
```
]

#type-def(true, color: lime)[candidates]
Defines the candidates that have been found in a specific context.

```typc
let candidates = (
primary: (prev: content | none, next: content | none),
ancestor: (prev: content | none, next: content | none),
)
```
#codesnippet[
```typc
let candidates = (
primary: (prev: content | none, next: content | none),
ancestor: (prev: content | none, next: content | none),
)
```
]

#type-def(false, color: lime)[hydra-context]
Defines the options passed to HYDRA and resolved contextual information needed for querying and
displaying.

```typc
let hydra-context = (
prev-filter: (hydra-context, candidates) => bool,
next-filter: (hydra-context, candidates) => bool,
display: (hydra-context, content) => content,
skip-starting: bool,
book: bool,
anchor: label | none,
anchor-loc: location,
primary: hydra-selector,
ancestors: hydra-selector,
)
```
#codesnippet[
```typc
let hydra-context = (
prev-filter: (hydra-context, candidates) => bool,
next-filter: (hydra-context, candidates) => bool,
display: (hydra-context, content) => content,
skip-starting: bool,
book: bool,
anchor: label | none,
anchor-loc: location,
primary: hydra-selector,
ancestors: hydra-selector,
)
```
]

#pagebreak()

Expand Down
Binary file modified doc/manual.pdf
Binary file not shown.
11 changes: 10 additions & 1 deletion doc/manual.typ
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,20 @@
],
)

#show raw: it => {
#show raw.line: it => {
show "{{VERSION}}": package.version
it
}

#show terms: it => table(
columns: 2,
gutter: 0.25em,
align: (right, left),
stroke: none,
table.vline(x: 1),
..it.children.map(i => (strong(i.term), i.description)).flatten(),
)

= Manifest
HYDRA aims to be:
- simple to use
Expand Down

0 comments on commit edb8cf2

Please sign in to comment.