konevsa/typst
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Touch up docs

Browse Source
This commit is contained in:
Laurenz 2023-08-07 15:02:50 +02:00
parent 800744ed9d
commit 07c80e9a81
17 changed files with 182 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
crates/typst-library/src/compute/construct.rs
View File

@ -345,7 +345,7 @@ pub fn datetime_today(
/// #square(
/// fill: cmyk(27%, 0%, 3%, 5%)
/// )
/// ````
/// ```
///
/// Display: CMYK
/// Category: construct
@ -384,13 +384,14 @@ pub fn color_module() -> Module {
/// Create a color by mixing two or more colors.
///
/// ## Example
/// ## Example { #example }
/// ```example
/// #color.mix(red, green)
/// #color.mix(red, green, white)
/// #color.mix(red, green, space: "srgb")
/// #color.mix((red, 30%), (green, 70%))
/// ````
/// #set block(height: 20pt, width: 100%)
/// #block(fill: color.mix(red, blue))
/// #block(fill: color.mix(red, blue, space: "srgb"))
/// #block(fill: color.mix((red, 70%), (blue, 30%)))
/// #block(fill: color.mix(red, blue, white))
/// ```
///
/// _Note:_ This function must be specified as `color.mix`, not just `mix`.
/// Currently, `color` is a module, but it is designed to be forward compatible
@ -402,6 +403,9 @@ pub fn color_module() -> Module {
pub fn mix(
/// The colors, optionally with weights, specified as a pair (array of
/// length two) of color and weight (float or ratio).
///
/// The weights do not need to add to `{100%}`, they are relative to the
/// sum of all weights.
#[variadic]
colors: Vec<WeightedColor>,
/// The color space to mix in. By default, this happens in a perceptual

15
crates/typst-library/src/layout/align.rs
View File

@ -33,8 +33,8 @@ pub struct AlignElem {
/// - `horizon`
/// - `bottom`
///
/// You may use the `axis` method on a single-axis alignment to obtain
/// whether it is `{"horizontal"}` or `{"vertical"}`. You may also use the
/// You can use the `axis` method on a single-axis alignment to obtain
/// whether it is `{"horizontal"}` or `{"vertical"}`. You can also use the
/// `inv` method to obtain its inverse alignment. For example,
/// `{top.axis()}` is `{"vertical"}`, while `{top.inv()}` is equal to
/// `{bottom}`.
@ -43,12 +43,11 @@ pub struct AlignElem {
/// the `+` operator to get a `2d alignment`. For example, `top + right`
/// aligns the content to the top right corner.
///
/// For 2d alignments, you may use the `x` and `y` fields to access their
/// horizontal and vertical components, respectively. Additionally, you may
/// use the `inv` method to obtain a 2d alignment with both components
/// inverted. For instance, `{(top + right).x}` is `right`,
/// `{(top + right).y}` is `top`, and `{(top + right).inv()}` is equal to
/// `bottom + left`.
/// For 2d alignments, the `x` and `y` fields hold their horizontal and
/// vertical components, respectively. Additionally, you can use the `inv`
/// method to obtain a 2d alignment with both components inverted. For
/// instance, `{(top + right).x}` is `right`, `{(top + right).y}` is `top`,
/// and `{(top + right).inv()}` is equal to `bottom + left`.
///
/// ```example
/// #set page(height: 6cm)

4
crates/typst-library/src/layout/enum.rs
View File

@ -56,8 +56,8 @@ use super::GridLayouter;
/// numbered enumeration item.
///
/// Enumeration items can contain multiple paragraphs and other block-level
/// content. All content that is indented more than an item's plus sign or dot
/// becomes part of that item.
/// content. All content that is indented more than an item's marker becomes
/// part of that item.
///
/// Display: Numbered List
/// Category: layout

2
crates/typst-library/src/layout/list.rs
View File

@ -32,7 +32,7 @@ use super::GridLayouter;
/// This functions also has dedicated syntax: Start a line with a hyphen,
/// followed by a space to create a list item. A list item can contain multiple
/// paragraphs and other block-level content. All content that is indented
/// more than an item's hyphen becomes part of that item.
/// more than an item's marker becomes part of that item.
///
/// Display: Bullet List
/// Category: layout

10
crates/typst-library/src/layout/stack.rs
View File

@ -27,11 +27,11 @@ pub struct StackElem {
/// - `{ttb}`: Top to bottom.
/// - `{btt}`: Bottom to top.
///
/// You may use the `start` and `end` methods to obtain the initial and
/// final points (respectively) of a direction, as `alignment`. You may
/// also use the `axis` method to obtain whether a direction is
/// `{"horizontal"}` or `{"vertical"}`. Finally, the `inv` method returns
/// its inverse direction.
/// You cab use the `start` and `end` methods to obtain the initial and
/// final points (respectively) of a direction, as `alignment`. You can also
/// use the `axis` method to determine whether a direction is
/// `{"horizontal"}` or `{"vertical"}`. The `inv` method returns a
/// direction's inverse direction.
///
/// For example, `{ttb.start()}` is `top`, `{ttb.end()}` is `bottom`,
/// `{ttb.axis()}` is `{"vertical"}` and `{ttb.inv()}` is equal to `btt`.

11
crates/typst-library/src/math/class.rs
View File

@ -3,11 +3,16 @@ use super::*;
/// Forced use of a certain math class.
///
/// This is useful to treat certain symbols as if they were of a different
/// class, e.g. to make text behave like a binary operator.
/// class, e.g. to make a symbol behave like a relation.
///
/// # Example
/// ## Example { #example }
/// ```example
/// $x class("relation", "<=") 5$
/// #let loves = math.class(
/// "relation",
/// sym.suit.heart,
/// )
///
/// $x loves y and y loves 5$
/// ```
///
/// Display: Class

2
crates/typst-library/src/meta/figure.rs
View File

@ -217,7 +217,7 @@ impl Synthesize for FigureElem {
VerticalAlign(GenAlign::Specific(match self.caption_pos(styles) {
VerticalAlign(GenAlign::Specific(Align::Top)) => Align::Top,
VerticalAlign(GenAlign::Specific(Align::Bottom)) => Align::Bottom,
_ => bail!(self.span(), "caption-position can only be top or bottom"),
_ => bail!(self.span(), "caption-pos can only be top or bottom"),
}));
// Resolve the supplement.

58
crates/typst-library/src/meta/metadata.rs
View File

@ -2,19 +2,14 @@ use crate::prelude::*;
/// Exposes a value to the query system without producing visible content.
///
/// This element can be queried for with the [`query`]($func/query) function and
/// the command line `typst query` command. Its purpose is to expose an
/// arbitrary value to the introspection system. To identify a metadata value
/// among others, you can attach a [`label`]($type/label) to it and query for
/// that label.
/// This element can be retrieved with the [`query`]($func/query) function and
/// from the command with [`typst query`]($reference/meta/query/#cli-queries).
/// Its purpose is to expose an arbitrary value to the introspection system. To
/// identify a metadata value among others, you can attach a
/// [`label`]($type/label) to it and query for that label.
///
/// ```typ
/// #metadata("This is a note") <note>
/// ```
///
/// ## Within Typst: `query` function { #within-typst }
/// Metadata can be retrieved from with the [`query`]($func/query) function
/// (like other elements):
/// The `metadata` element is especially useful for command line queries because
/// it allows you to expose arbitrary values to the outside world.
///
/// ```example
/// // Put metadata somewhere.
@ -26,45 +21,6 @@ use crate::prelude::*;
/// })
/// ```
///
/// ## Outside of Typst: `typst query` command { #outside-of-typst }
/// You can also retrieve the metadata from the command line with the
/// `typst query` command. This command executes an arbitrary query on the
/// document and returns the resulting elements in serialized form.
///
/// The `metadata` element is especially useful for command line queries because
/// it allows you to expose arbitrary values to the outside world. However,
/// `typst query` also works with other elements `metadata` and complex
/// [selectors]($type/selector) like `{heading.where(level: 1)}`.
///
/// ```sh
/// $ typst query example.typ "<note>"
/// [
/// {
/// "func": "metadata",
/// "value": "This is a note",
/// "label": "<note>"
/// }
/// ]
/// ```
///
/// Frequently, you're interested in only one specific field of the resulting
/// elements. In the case of the `metadata` element, the `value` field is the
/// interesting one. You can extract just this field with the `--field`
/// argument.
///
/// ```sh
/// $ typst query example.typ "<note>" --field value
/// ["This is a note"]
/// ```
///
/// If you are interested in just a single element, you can use the `--one`
/// flag to extract just it.
///
/// ```sh
/// $ typst query example.typ "<note>" --field value --one
/// "This is a note"
/// ```
///
/// Display: Metadata
/// Category: meta
#[element(Behave, Show, Locatable)]

54
crates/typst-library/src/meta/query.rs
View File

@ -3,12 +3,9 @@ use crate::prelude::*;
/// Finds elements in the document.
///
/// The `query` functions lets you search your document for elements of a
/// particular type or with a particular label.
///
/// To use it, you first need to retrieve the current document location with the
/// [`locate`]($func/locate) function. You can then decide whether you want to
/// find all elements, just the ones before that location, or just the ones
/// after it.
/// particular type or with a particular label. To use it, you first need to
/// retrieve the current document location with the [`locate`]($func/locate)
/// function.
///
/// ## Finding elements { #finding-elements }
/// In the example below, we create a custom page header that displays the text
@ -89,12 +86,45 @@ use crate::prelude::*;
/// })
/// ```
///
/// ## Migration Hints { #migration-hints }
/// The `before` and `after` arguments have been removed in version 0.3.0. You
/// can now use flexible selector combinator methods instead. For example,
/// `query(heading, before: loc)` becomes `query(heading.before(loc), loc)`.
/// Please refer to the [selector documentation]($type/selector) for more
/// details.
/// ## Command line queries { #command-line-queries }
/// You can also perform queries from the command line with the `typst query`
/// command. This command executes an arbitrary query on the document and
/// returns the resulting elements in serialized form. Consider the following
/// `example.typ` file which contains some invisible [metadata]($func/metadata):
///
/// ```typ
/// #metadata("This is a note") <note>
/// ```
///
/// You can execute a query on it as follows using Typst's CLI:
/// ```sh
/// $ typst query example.typ "<note>"
/// [
/// {
/// "func": "metadata",
/// "value": "This is a note",
/// "label": "<note>"
/// }
/// ]
/// ```
///
/// Frequently, you're interested in only one specific field of the resulting
/// elements. In the case of the `metadata` element, the `value` field is the
/// interesting one. You can extract just this field with the `--field`
/// argument.
///
/// ```sh
/// $ typst query example.typ "<note>" --field value
/// ["This is a note"]
/// ```
///
/// If you are interested in just a single element, you can use the `--one`
/// flag to extract just it.
///
/// ```sh
/// $ typst query example.typ "<note>" --field value --one
/// "This is a note"
/// ```
///
/// Display: Query
/// Category: meta

54
crates/typst-library/src/text/mod.rs
View File

@ -265,31 +265,6 @@ pub struct TextElem {
#[default(BottomEdge::Metric(BottomEdgeMetric::Baseline))]
pub bottom_edge: BottomEdge,
/// The OpenType writing script setting.
///
/// The combination of `{script}` and `{lang}` determine how
/// font features, such as glyph substitution, are implemented.
/// Frequently the value is a modified (all-lowercase) ISO 15924 script identifier, and
/// the `math` writing script is used for features appropriate
/// for mathematical symbols.
///
/// When set to `{auto}`, the default and recommended setting,
/// an appropriate script is chosen for each block of characters
/// sharing a common Unicode script property.
///
/// ```example
/// #let scedilla = [Ş]
/// #set text(font: "Linux Libertine", size: 20pt)
/// #scedilla // S with a cedilla
///
/// #set text(script: "latn", lang: "ro")
/// #scedilla // S with a subscript comma
///
/// #set text(script: "grek", lang: "ro")
/// #scedilla // S with a cedilla
/// ```
pub script: Smart<WritingScript>,
/// An [ISO 639-1/2/3 language code.](https://en.wikipedia.org/wiki/ISO_639)
///
/// Setting the correct language affects various parts of Typst:
@ -315,6 +290,35 @@ pub struct TextElem {
/// This lets the text processing pipeline make more informed choices.
pub region: Option<Region>,
/// The OpenType writing script.
///
/// The combination of `{lang}` and `{script}` determine how font features,
/// such as glyph substitution, are implemented. Frequently the value is a
/// modified (all-lowercase) ISO 15924 script identifier, and the `math`
/// writing script is used for features appropriate for mathematical
/// symbols.
///
/// When set to `{auto}`, the default and recommended setting, an
/// appropriate script is chosen for each block of characters sharing a
/// common Unicode script property.
///
/// ```example
/// #set text(
/// font: "Linux Libertine",
/// size: 20pt,
/// )
///
/// #let scedilla = [Ş]
/// #scedilla // S with a cedilla
///
/// #set text(lang: "ro", script: "latn")
/// #scedilla // S with a subscript comma
///
/// #set text(lang: "ro", script: "grek")
/// #scedilla // S with a cedilla
/// ```
pub script: Smart<WritingScript>,
/// The dominant direction for text and inline objects. Possible values are:
///
/// - `{auto}`: Automatically infer the direction from the `lang` property.

21
crates/typst-library/src/text/raw.rs
View File

@ -135,7 +135,8 @@ pub struct RawElem {
pub align: HorizontalAlign,
/// One or multiple additional syntax definitions to load. The syntax
/// definitions should be in the `sublime-syntax` file format.
/// definitions should be in the
/// [`sublime-syntax` file format](https://www.sublimetext.com/docs/syntax.html).
///
/// ````example
/// #set raw(syntaxes: "SExpressions.sublime-syntax")
@ -161,11 +162,25 @@ pub struct RawElem {
#[fold]
pub syntaxes_data: Vec<Bytes>,
/// The theme to use for syntax highlighting. Theme files should be in the in the
/// `tmTheme` file format.
/// The theme to use for syntax highlighting. Theme files should be in the
/// in the [`tmTheme` file format](https://www.sublimetext.com/docs/color_schemes_tmtheme.html).
///
/// Applying a theme only affects the color of specifically highlighted
/// text. It does not consider the theme's foreground and background
/// properties, so that you retain control over the color of raw text. You
/// can apply the foreground color yourself with the [`text`]($func/text)
/// function and the background with a [filled block]($func/block.fill). You
/// could also use the [`xml`]($func/xml) function to extract these
/// properties from the theme.
///
/// ````example
/// #set raw(theme: "halcyon.tmTheme")
/// #show raw: it => block(
/// fill: rgb("#1d2433"),
/// inset: 8pt,
/// radius: 5pt,
/// text(fill: rgb("#a2aabc"), it)
/// )
///
/// ```typ
/// = Chapter 1

8
crates/typst-library/src/visualize/line.rs
View File

@ -69,10 +69,10 @@ pub struct LineElem {
/// the array above), and `phase` (of type [length]($type/length)),
/// which defines where in the pattern to start drawing.
///
/// Note that, for any `stroke` object, you may access any of the fields
/// mentioned in the dictionary format above. For example,
/// `{(2pt + blue).thickness}` is `{2pt}`, `{(2pt + blue).miter-limit}` is
/// `{4.0}` (the default), and so on.
/// On a `stroke` object, you can access any of the fields mentioned in the
/// dictionary format above. For example, `{(2pt + blue).thickness}` is
/// `{2pt}`, `{(2pt + blue).miter-limit}` is `{4.0}` (the default), and so
/// on.
///
/// ```example
/// #set line(length: 100%)

2
crates/typst-macros/src/element.rs
View File

@ -433,7 +433,7 @@ fn create_param_info(field: &Field) -> TokenStream {
}
}));
let ty = if *variadic {
quote! { <#ty as ::typst::eval::Variadics>::Inner }
quote! { <#ty as ::typst::eval::Container>::Inner }
} else {
quote! { #ty }
};

12
crates/typst-macros/src/func.rs
View File

@ -210,7 +210,12 @@ fn create(func: &Func, item: &syn::ItemFn) -> TokenStream {
fn create_param_info(param: &Param) -> TokenStream {
let Param { name, docs, named, variadic, ty, default, .. } = param;
let positional = !named;
let required = default.is_none();
let required = !named && default.is_none();
let ty = if *variadic || (*named && default.is_none()) {
quote! { <#ty as ::typst::eval::Container>::Inner }
} else {
quote! { #ty }
};
let default = quote_option(&default.as_ref().map(|_default| {
quote! {
|| {
@ -219,11 +224,6 @@ fn create_param_info(param: &Param) -> TokenStream {
}
}
}));
let ty = if *variadic {
quote! { <#ty as ::typst::eval::Variadics>::Inner }
} else {
quote! { #ty }
};
quote! {
::typst::eval::ParamInfo {
name: #name,

30
crates/typst/src/eval/cast.rs
View File

@ -281,13 +281,17 @@ impl Add for CastInfo {
}
}
/// A container for a variadic argument.
pub trait Variadics {
/// A container for an argument.
pub trait Container {
/// The contained type.
type Inner;
}
impl<T> Variadics for Vec<T> {
impl<T> Container for Option<T> {
type Inner = T;
}
impl<T> Container for Vec<T> {
type Inner = T;
}
@ -335,14 +339,24 @@ cast! {
MathClass::Vary => "vary",
MathClass::Special => "special",
}),
/// The default class for non-special things.
"normal" => MathClass::Normal,
"binary" => MathClass::Binary,
"closing" => MathClass::Closing,
"fence" => MathClass::Fence,
"large" => MathClass::Large,
"opening" => MathClass::Opening,
/// Punctuation, e.g. a comma.
"punctuation" => MathClass::Punctuation,
/// An opening delimiter, e.g. `(`.
"opening" => MathClass::Opening,
/// A closing delimiter, e.g. `)`.
"closing" => MathClass::Closing,
/// A delimiter that is the same on both sides, e.g. `|`.
"fence" => MathClass::Fence,
/// A large operator like `sum`.
"large" => MathClass::Large,
/// A relation like `=` or `prec`.
"relation" => MathClass::Relation,
/// A unary operator like `not`.
"unary" => MathClass::Unary,
/// A binary operator like `times`.
"binary" => MathClass::Binary,
/// An operator that can be both unary or binary like `+`.
"vary" => MathClass::Vary,
}

2
crates/typst/src/eval/mod.rs
View File

@ -43,7 +43,7 @@ pub use self::array::{array, Array};
pub use self::auto::AutoValue;
pub use self::bytes::Bytes;
pub use self::cast::{
cast, Cast, CastInfo, FromValue, IntoResult, IntoValue, Never, Reflect, Variadics,
cast, Cast, CastInfo, Container, FromValue, IntoResult, IntoValue, Never, Reflect,
};
pub use self::datetime::Datetime;
pub use self::dict::{dict, Dict};

36
docs/reference/types.md
View File

@ -87,9 +87,9 @@ Typst supports the following length units:
A length has the following fields:
- `em`: The amount of `em` units in this length, as a [float]($type/float).
- `abs`: A length with just the absolute component of the current length
(that is, excluding the `em` component).
- `em`: The amount of `em` units in this length, as a [float]($type/float).
You can multiply lengths with and divide them by integers and floats.
@ -110,38 +110,34 @@ You can multiply lengths with and divide them by integers and floats.
### pt()
Converts this length to points.
Fails with an error if this length has non-zero `em` units
(such as `5em + 2pt` instead of just `2pt`). Use the `abs`
field (such as in `(5em + 2pt).abs.pt()`) to ignore the
`em` component of the length (thus converting only its
absolute component).
Fails with an error if this length has non-zero `em` units (such as `5em + 2pt`
instead of just `2pt`). Use the `abs` field (such as in `(5em + 2pt).abs.pt()`)
to ignore the `em` component of the length (thus converting only its absolute
component).
- returns: float
### mm()
Converts this length to millimeters.
Fails with an error if this length has non-zero `em` units
(such as `5em + 2pt` instead of just `2pt`). See the
[`pt()`]($type/float.pt) method for more info.
Fails with an error if this length has non-zero `em` units (such as `5em + 2pt`
instead of just `2pt`). See the [`pt`]($type/float.pt) method for more info.
- returns: float
### cm()
Converts this length to centimeters.
Fails with an error if this length has non-zero `em` units
(such as `5em + 2pt` instead of just `2pt`). See the
[`pt()`]($type/float.pt) method for more info.
Fails with an error if this length has non-zero `em` units (such as `5em + 2pt`
instead of just `2pt`). See the [`pt`]($type/float.pt) method for more info.
- returns: float
### inches()
Converts this length to inches.
Fails with an error if this length has non-zero `em` units
(such as `5em + 2pt` instead of just `2pt`). See the
[`pt()`]($type/float.pt) method for more info.
Fails with an error if this length has non-zero `em` units (such as `5em + 2pt`
instead of just `2pt`). See the [`pt`]($type/float.pt) method for more info.
- returns: float
@ -235,7 +231,8 @@ Returns the constructor function for this color's kind
([`rgb`]($func/rgb), [`cmyk`]($func/cmyk) or [`luma`]($func/luma)).
```example
#{cmyk(1%, 2%, 3%, 4%).kind() == cmyk}
#let color = cmyk(1%, 2%, 3%, 4%)
#(color.kind() == cmyk)
```
- returns: function
@ -273,9 +270,10 @@ of [integers]($type/integer).
- returns: array
### cmyk()
Converts this color to Digital CMYK and returns its components (C, M, Y, K) as an
array of [ratio]($type/ratio). Note that this function will throw an error when
applied to an [rgb]($func/rgb) color, since its conversion to CMYK is not available.
Converts this color to Digital CMYK and returns its components (C, M, Y, K) as
an array of [ratios]($type/ratio). Note that this function will throw an error
when applied to an [rgb]($func/rgb) color, since its conversion to CMYK is not
available.
- returns: array