From 56a96881a54dd3784e0db22e36130eddf4e19a02 Mon Sep 17 00:00:00 2001 From: Laurenz Date: Fri, 19 May 2023 11:04:20 +0200 Subject: [PATCH] Doc links for function scopes --- docs/src/general/changelog.md | 36 +++++++------ docs/src/guides/guide-for-latex-users.md | 12 ++--- docs/src/html.rs | 32 ++++++++---- docs/src/lib.rs | 10 ++-- docs/src/reference/styling.md | 2 +- docs/src/reference/syntax.md | 66 ++++++++++++------------ docs/src/tutorial/1-writing.md | 10 ++-- library/src/meta/reference.rs | 9 ++-- 8 files changed, 97 insertions(+), 80 deletions(-) diff --git a/docs/src/general/changelog.md b/docs/src/general/changelog.md index c53d9d98b..3700121a9 100644 --- a/docs/src/general/changelog.md +++ b/docs/src/general/changelog.md @@ -9,21 +9,21 @@ description: | - **Breaking changes:** - Renamed a few symbols: What was previous `dot.op` is now just `dot` and the basic dot is `dot.basic`. The same applies to `ast` and `tilde`. - - Renamed `mod` to [`rem`]($category/calculate/rem) to more accurately reflect + - Renamed `mod` to [`rem`]($func/calc.rem) to more accurately reflect the behaviour. It will remain available as `mod` until the next update as a grace period. - A lone underscore is not a valid identifier anymore, it can now only be used in patterns - Removed `before` and `after` arguments from [`query`]($func/query). This is now handled through flexible [selectors]($type/selector) combinator methods - - Added support for [attachments]($func/attach) (sub-, superscripts) that + - Added support for [attachments]($func/math.attach) (sub-, superscripts) that precede the base symbol. The `top` and `bottom` arguments have been renamed to `t` and `b`. - New features - Added support for more complex [strokes]($func/line.stroke) (configurable caps, joins, and dash patterns) - - Added [`cancel`]($func/cancel) function for equations + - Added [`cancel`]($func/math.cancel) function for equations - Added support for [destructuring]($scripting/#bindings) in argument lists and assignments - Added [`alt`]($func/image.alt) text argument to image function @@ -106,11 +106,12 @@ description: | - Added basic i18n for a few more languages (AR, NB, CS, NN, PL, SL, ES, UA, VI) - Added a few numbering patterns (Ihora, Chinese) - - Added `sinc` [operator]($func/op) + - Added `sinc` [operator]($func/math.op) - Fixed bug where math could not be hidden with [`hide`]($func/hide) - Fixed sizing issues with box, block, and shapes - Fixed some translations - - Fixed inversion of "R" in [`cal`]($func/cal) and [`frak`]($func/frak) styles + - Fixed inversion of "R" in [`cal`]($func/math.cal) and + [`frak`]($func/math.frak) styles - Fixed some styling issues in math - Fixed supplements of references to headings - Fixed syntax highlighting of identifiers in certain scenarios @@ -202,11 +203,12 @@ description: | - Fixed build of CLI if `git` is not installed - Miscellaneous improvements - - Added support for disabling [matrix]($func/mat) and [vector]($func/vec) - delimiters. Generally with `[#set math.mat(delim: none)]` or one-off with + - Added support for disabling [matrix]($func/math.mat) and + [vector]($func/math.vec) delimiters. Generally with + `[#set math.mat(delim: none)]` or one-off with `[$mat(delim: #none, 1, 2; 3, 4)$]`. - Added [`separator`]($func/terms.separator) argument to term lists - - Added [`round`]($func/round) function for equations + - Added [`round`]($func/math.round) function for equations - Numberings now allow zeros. To reset a counter, you can write `[#counter(..).update(0)]` - Added documentation for `{page()}` and `{position()}` methods on @@ -221,7 +223,7 @@ description: | - Fixed combination of page fill and header - Fixed compiler crash if [`repeat`]($func/repeat) is used in page with automatic width - - Fixed [matrices]($func/mat) with explicit delimiter + - Fixed [matrices]($func/math.mat) with explicit delimiter - Fixed [`indent`]($func/terms.indent) property of term lists - Numerous documentation fixes - Links in bibliographies are now affected by link styling @@ -284,7 +286,7 @@ description: | - Further improvements - Added [`figure`]($func/figure) function - - Added [`numbering`]($func/equation.numbering) parameter on equation function + - Added [`numbering`]($func/math.equation.numbering) parameter on equation function - Added [`numbering`]($func/page.numbering) and [`number-align`]($func/page.number-align) parameters on page function - The page function's [`header`]($func/page.header) and @@ -297,11 +299,12 @@ description: | - Better default alignment in header and footer - Fixed Arabic vowel placement - Fixed PDF font embedding issues - - Renamed `math.formula` to [`math.equation`]($func/equation) + - Renamed `math.formula` to [`math.equation`]($func/math.equation) - Font family must be a named argument now: `[#set text(font: "..")]` - Added support for [hanging indent]($func/par.hanging-indent) - - Renamed paragraph `indent` to [`first-line-indent`]($func/par.first-line-indent) - - More accurate [logarithm]($category/calculate/log) when base is `2` or `10` + - Renamed paragraph `indent` to + [`first-line-indent`]($func/par.first-line-indent) + - More accurate [logarithm]($func/calc.log) when base is `2` or `10` - Improved some error messages - Fixed layout of [`terms`]($func/terms) list @@ -333,7 +336,8 @@ description: | the corresponding main font and the [`smallcaps`]($func/smallcaps) function - Improved default spacing for headings - Added [`panic`]($func/panic) function -- Added [`clusters`]($type/string.clusters) and [`codepoints`]($type/string.codepoints) +- Added [`clusters`]($type/string.clusters) and + [`codepoints`]($type/string.codepoints) methods for strings - Support for multiple authors in [`set document`]($func/document.author) - Fixed crash when string is accessed at a position that is not a char boundary @@ -384,8 +388,8 @@ description: | - Fixed bug where a heading show rule may not contain a pagebreak when an outline is present - Added [`baseline`]($func/box.baseline) property on [`box`]($func/box) -- Added [`tg`]($func/op) and [`ctg`]($func/op) operators in math -- Added delimiter setting for [`cases`]($func/cases) function +- Added [`tg`]($func/math.op) and [`ctg`]($func/math.op) operators in math +- Added delimiter setting for [`cases`]($func/math.cases) function - Parentheses are now included when accepting a function autocompletion ## February 2, 2023 diff --git a/docs/src/guides/guide-for-latex-users.md b/docs/src/guides/guide-for-latex-users.md index 46559f6de..da08cef24 100644 --- a/docs/src/guides/guide-for-latex-users.md +++ b/docs/src/guides/guide-for-latex-users.md @@ -74,7 +74,7 @@ You can also check out the [full syntax cheat sheet]($syntax). | Term list | `description` environment | `[/ Term: List]` | [`terms`]($func/terms) | | Figure | `figure` environment | `figure` function | [`figure`]($func/figure) | | Table | `table` environment | `table` function | [`table`]($func/table) | -| Equation | `$x$`, `align` / `equation` environments | `[$x$]`, `[$ x = y $]` | [`equation`]($func/equation) | +| Equation | `$x$`, `align` / `equation` environments | `[$x$]`, `[$ x = y $]` | [`equation`]($func/math.equation) | [Lists]($func/list) do not rely on environments in Typst. Instead, they have lightweight syntax like headings. To create an unordered list (`itemize`), @@ -144,7 +144,7 @@ And finally a little loop: ``` A function call always involves the name of the function ([`rect`]($func/rect), -[`underline`]($func/underline), [`calc.max`]($category/calc/max), +[`underline`]($func/underline), [`calc.max`]($func/calc.max), [`range`]($func/range)) and then an argument list, even if it is empty. The argument list is enclosed in parentheses. @@ -450,7 +450,7 @@ $ delta "if" x <= 5 $ You can type many symbols with shorthands like `<=`, `>=`, and `->`. Similarly, delimiters will scale automatically for their expressions, just as if `\left` and `\right` commands were implicitly inserted in LaTeX. You can customize -delimiter behavior using the [`lr` function]($func/lr). +delimiter behavior using the [`lr` function]($func/math.lr). Typst will automatically set terms around a slash `/` as a fraction while honoring operator precedence. All round parentheses not made redundant by the @@ -460,7 +460,7 @@ fraction will appear in the output. $ f(x) = (x + 1) / x $ ``` -[Sub- and superscripts]($func/attach) work similarly in Typst and LaTeX. Typing +[Sub- and superscripts]($func/math.attach) work similarly in Typst and LaTeX. Typing `{$x^2$}` will produce a superscript, `{$x_2$}` yields a subscript. If you want to include more than one value in a sub- or superscript, enclose their contents in parentheses: `{$x_(a -> epsilon)$}`. @@ -477,7 +477,7 @@ $ f(x, y) := cases( ) $ ``` -The above example uses the [`cases` function]($func/cases) to describe f. Within +The above example uses the [`cases` function]($func/math.cases) to describe f. Within the cases function, arguments are delimited using commas and the arguments are also interpreted as math. If you would need to interpret arguments as Typst values instead, prefix them with a `#`: @@ -504,7 +504,7 @@ If you'd like to enter your mathematical symbols directly as Unicode, that is possible, too! Math calls can have two-dimensional argument lists using `;` as a delimiter. The -most common use for this is the [`mat` function]($func/mat) that creates +most common use for this is the [`mat` function]($func/math.mat) that creates matrices: ```example diff --git a/docs/src/html.rs b/docs/src/html.rs index a9bbfb1c0..a3db63936 100644 --- a/docs/src/html.rs +++ b/docs/src/html.rs @@ -301,11 +301,16 @@ impl<'a> Handler<'a> { route.push_str("/#methods-"); route.push_str(method); } else if root == "$func" { - let mut parts = rest.split('.'); + let mut parts = rest.split('.').peekable(); + let mut focus = &LIBRARY.global; + while let Some(m) = parts.peek().and_then(|name| module(focus, name).ok()) { + focus = m; + parts.next(); + } + let name = parts.next()?; - let param = parts.next(); - let value = - LIBRARY.global.get(name).or_else(|_| LIBRARY.math.get(name)).ok()?; + + let value = focus.get(name).ok()?; let Value::Func(func) = value else { return None }; let info = func.info()?; route.push_str(info.category); @@ -318,18 +323,25 @@ impl<'a> Handler<'a> { route.push_str(&group.name); route.push_str("/#"); route.push_str(info.name); - if let Some(param) = param { + if let Some(param) = parts.next() { route.push_str("-parameters-"); route.push_str(param); - } else { - route.push_str("-summary"); } } else { route.push_str(name); route.push('/'); - if let Some(param) = param { - route.push_str("#parameters-"); - route.push_str(param); + if let Some(next) = parts.next() { + if info.params.iter().any(|param| param.name == next) { + route.push_str("#parameters-"); + route.push_str(next); + } else if info.scope.iter().any(|(name, _)| name == next) { + route.push('#'); + route.push_str(info.name); + route.push('-'); + route.push_str(next); + } else { + return None; + } } } } else { diff --git a/docs/src/lib.rs b/docs/src/lib.rs index a9a640f66..af786cd1f 100644 --- a/docs/src/lib.rs +++ b/docs/src/lib.rs @@ -213,7 +213,7 @@ fn category_page(resolver: &dyn Resolver, category: &str) -> PageModel { let focus = match category { "math" => &LIBRARY.math, - "calculate" => module(&LIBRARY.global, "calc"), + "calculate" => module(&LIBRARY.global, "calc").unwrap(), _ => &LIBRARY.global, }; @@ -807,7 +807,7 @@ pub struct SymbolModel { /// Create a page for symbols. fn symbol_page(resolver: &dyn Resolver, parent: &str, name: &str) -> PageModel { - let module = &module(&LIBRARY.global, name); + let module = module(&LIBRARY.global, name).unwrap(); let mut list = vec![]; for (name, value) in module.scope().iter() { @@ -873,10 +873,10 @@ struct GroupData { /// Extract a module from another module. #[track_caller] -fn module<'a>(parent: &'a Module, name: &str) -> &'a Module { +fn module<'a>(parent: &'a Module, name: &str) -> Result<&'a Module, String> { match parent.scope().get(name) { - Some(Value::Module(module)) => module, - _ => panic!("module doesn't contain module `{name}`"), + Some(Value::Module(module)) => Ok(module), + _ => Err(format!("module doesn't contain module `{name}`")), } } diff --git a/docs/src/reference/styling.md b/docs/src/reference/styling.md index d088d61dc..85095e34d 100644 --- a/docs/src/reference/styling.md +++ b/docs/src/reference/styling.md @@ -17,7 +17,7 @@ as a [function call]($type/function) to an keyword (or `[#set]` in markup). Only optional parameters of that function can be provided to the set rule. Refer to each function's documentation to see which parameters are optional. In the example below, we use two set rules to change -the [font family]($func/text.family) and +the [font family]($func/text.font) and [heading numbering]($func/heading.numbering). ```example diff --git a/docs/src/reference/syntax.md b/docs/src/reference/syntax.md index 014c56402..d0cd80d74 100644 --- a/docs/src/reference/syntax.md +++ b/docs/src/reference/syntax.md @@ -30,7 +30,7 @@ more about their syntax and usage. | Bullet list | `[- item]` | [`list`]($func/list) | | Numbered list | `[+ item]` | [`enum`]($func/enum) | | Term list | `[/ Term: description]` | [`terms`]($func/terms) | -| Math | `[$x^2$]` | [Math]($category/math) | +| Math | `[$x^2$]` | [Math]($category/math) | | Line break | `[\]` | [`linebreak`]($func/linebreak) | | Smart quote | `['single' or "double"]` | [`smartquote`]($func/smartquote) | | Symbol shorthand | `[~, ---]` | [Symbols]($category/symbols/sym) | @@ -52,7 +52,7 @@ follows: | Block-level math | `[$ x^2 $]` | [Math]($category/math) | | Bottom attachment | `[$x_1$]` | [`attach`]($category/math/attach) | | Top attachment | `[$x^2$]` | [`attach`]($category/math/attach) | -| Fraction | `[$1 + (a+b)/5$]` | [`frac`]($func/frac) | +| Fraction | `[$1 + (a+b)/5$]` | [`frac`]($func/math.frac) | | Line break | `[$x \ y$]` | [`linebreak`]($func/linebreak) | | Alignment point | `[$x &= 2 \ &= 3$]` | [Math]($category/math) | | Variable access | `[$#x$, $pi$]` | [Math]($category/math) | @@ -70,38 +70,38 @@ Within code blocks and expressions, new expressions can start without a leading `#` character. Many syntactic elements are specific to expressions. Below is a table listing all syntax that is available in code mode: -| Name | Example | See | -| ------------------------ | ----------------------------- | ---------------------------------------------------- | -| Variable access | `{x}` | [Scripting]($scripting/#blocks) | -| Any literal | `{1pt, "hey"}` | [Types]($types) | -| Code block | `{{ let x = 1; x + 2 }}` | [Scripting]($scripting/#blocks) | -| Content block | `{[*Hello*]}` | [Scripting]($scripting/#blocks) | -| Parenthesized expression | `{(1 + 2)}` | [Scripting]($scripting/#blocks) | -| Array | `{(1, 2, 3)}` | [Array]($type/array) | -| Dictionary | `{(a: "hi", b: 2)}` | [Dictionary]($type/dictionary) | -| Unary operator | `{-x}` | [Scripting]($scripting/#operators) | -| Binary operator | `{x + y}` | [Scripting]($scripting/#operators) | -| Assignment | `{x = 1}` | [Scripting]($scripting/#operators) | -| Field access | `{x.y}` | [Scripting]($scripting/#fields) | -| Method call | `{x.flatten()}` | [Scripting]($scripting/#methods) | -| Function call | `{min(x, y)}` | [Function]($type/function) | -| Unnamed function | `{(x, y) => x + y}` | [Function]($type/function) | -| Let binding | `{let x = 1}` | [Scripting]($scripting/#bindings) | -| Named function | `{let f(x) = 2 * x}` | [Function]($type/function) | -| Set rule | `{set text(14pt)}` | [Styling]($styling/#set-rules) | -| Set-if rule | `{set text(..) if .. }` | [Styling]($styling/#set-rules) | -| Show-set rule | `{show par: set block(..)}` | [Styling]($styling/#show-rules) | -| Show rule with function | `{show raw: it => {..}}` | [Styling]($styling/#show-rules) | -| Show-everything rule | `{show: columns.with(2)}` | [Styling]($styling/#show-rules) | +| Name | Example | See | +| ------------------------ | ----------------------------- | ---------------------------------- | +| Variable access | `{x}` | [Scripting]($scripting/#blocks) | +| Any literal | `{1pt, "hey"}` | [Types]($types) | +| Code block | `{{ let x = 1; x + 2 }}` | [Scripting]($scripting/#blocks) | +| Content block | `{[*Hello*]}` | [Scripting]($scripting/#blocks) | +| Parenthesized expression | `{(1 + 2)}` | [Scripting]($scripting/#blocks) | +| Array | `{(1, 2, 3)}` | [Array]($type/array) | +| Dictionary | `{(a: "hi", b: 2)}` | [Dictionary]($type/dictionary) | +| Unary operator | `{-x}` | [Scripting]($scripting/#operators) | +| Binary operator | `{x + y}` | [Scripting]($scripting/#operators) | +| Assignment | `{x = 1}` | [Scripting]($scripting/#operators) | +| Field access | `{x.y}` | [Scripting]($scripting/#fields) | +| Method call | `{x.flatten()}` | [Scripting]($scripting/#methods) | +| Function call | `{min(x, y)}` | [Function]($type/function) | +| Unnamed function | `{(x, y) => x + y}` | [Function]($type/function) | +| Let binding | `{let x = 1}` | [Scripting]($scripting/#bindings) | +| Named function | `{let f(x) = 2 * x}` | [Function]($type/function) | +| Set rule | `{set text(14pt)}` | [Styling]($styling/#set-rules) | +| Set-if rule | `{set text(..) if .. }` | [Styling]($styling/#set-rules) | +| Show-set rule | `{show par: set block(..)}` | [Styling]($styling/#show-rules) | +| Show rule with function | `{show raw: it => {..}}` | [Styling]($styling/#show-rules) | +| Show-everything rule | `{show: columns.with(2)}` | [Styling]($styling/#show-rules) | | Conditional | `{if x == 1 {..} else {..}}` | [Scripting]($scripting/#conditionals) | -| For loop | `{for x in (1, 2, 3) {..}}` | [Scripting]($scripting/#loops) | -| While loop | `{while x < 10 {..}}` | [Scripting]($scripting/#loops) | -| Loop control flow | `{break, continue}` | [Scripting]($scripting/#loops) | -| Return from function | `{return x}` | [Function]($type/function) | -| Include module | `{include "bar.typ"}` | [Scripting]($scripting/#modules) | -| Import module | `{import "bar.typ"}` | [Scripting]($scripting/#modules) | -| Import items from module | `{import "bar.typ": a, b, c}` | [Scripting]($scripting/#modules) | -| Comment | `[/* block */, // line]` | [Below](#comments) | +| For loop | `{for x in (1, 2, 3) {..}}` | [Scripting]($scripting/#loops) | +| While loop | `{while x < 10 {..}}` | [Scripting]($scripting/#loops) | +| Loop control flow | `{break, continue}` | [Scripting]($scripting/#loops) | +| Return from function | `{return x}` | [Function]($type/function) | +| Include module | `{include "bar.typ"}` | [Scripting]($scripting/#modules) | +| Import module | `{import "bar.typ"}` | [Scripting]($scripting/#modules) | +| Import items from module | `{import "bar.typ": a, b, c}` | [Scripting]($scripting/#modules) | +| Comment | `[/* block */, // line]` | [Below](#comments) | ## Comments { #comments } Comments are ignored by Typst and will not be included in the output. This diff --git a/docs/src/tutorial/1-writing.md b/docs/src/tutorial/1-writing.md index 6bb6087e8..a2a2ca650 100644 --- a/docs/src/tutorial/1-writing.md +++ b/docs/src/tutorial/1-writing.md @@ -269,17 +269,17 @@ $ 7.32 beta + Not all math constructs have special syntax. Instead, we use functions, just like the `image` function we have seen before. For example, to insert a column -vector, we can use the [`vec`]($func/vec) function. Within math mode, function -calls don't need to start with the `#` character. +vector, we can use the [`vec`]($func/math.vec) function. Within math mode, +function calls don't need to start with the `#` character. ```example $ v := vec(x_1, x_2, x_3) $ ``` Some functions are only available within math mode. For example, the -[`cal`]($func/cal) function is used to typeset calligraphic letters commonly -used for sets. The [math section of the reference]($category/math) provides a -complete list of all functions that math mode makes available. +[`cal`]($func/math.cal) function is used to typeset calligraphic letters +commonly used for sets. The [math section of the reference]($category/math) +provides a complete list of all functions that math mode makes available. One more thing: Many symbols, such as the arrow, have a lot of variants. You can select among these variants by appending a dot and a modifier name to a symbol's diff --git a/library/src/meta/reference.rs b/library/src/meta/reference.rs index 1f1f2b23d..328e6098a 100644 --- a/library/src/meta/reference.rs +++ b/library/src/meta/reference.rs @@ -11,10 +11,11 @@ use crate::text::TextElem; /// [cite]($func/cite) from a bibliography. /// /// Referenceable elements include [headings]($func/heading), -/// [figures]($func/figure), and [equations]($func/equation). To create a custom -/// referenceable element like a theorem, you can create a figure of a custom -/// [`kind`]($func/figure.kind) and write a show rule for it. In the future, -/// there might be a more direct way to define a custom referenceable element. +/// [figures]($func/figure), and [equations]($func/math.equation). To create a +/// custom referenceable element like a theorem, you can create a figure of a +/// custom [`kind`]($func/figure.kind) and write a show rule for it. In the +/// future, there might be a more direct way to define a custom referenceable +/// element. /// /// If you just want to link to a labelled element and not get an automatic /// textual reference, consider using the [`link`]($func/link) function instead.