diff --git a/docs/src/lib.rs b/docs/src/lib.rs index 2a7b7c5f1..a9a640f66 100644 --- a/docs/src/lib.rs +++ b/docs/src/lib.rs @@ -492,6 +492,7 @@ pub struct ParamModel { pub example: Option, pub types: Vec<&'static str>, pub strings: Vec, + pub default: Option, pub positional: bool, pub named: bool, pub required: bool, @@ -532,6 +533,10 @@ fn param_model(resolver: &dyn Resolver, info: &ParamInfo) -> ParamModel { example: example.map(|md| Html::markdown(resolver, md)), types, strings, + default: info.default.map(|default| { + let node = typst::syntax::parse_code(&default().repr()); + Html::new(typst::ide::highlight_html(&node)) + }), positional: info.positional, named: info.named, required: info.required, @@ -721,6 +726,7 @@ fn method_model(resolver: &dyn Resolver, part: &'static str) -> MethodModel { example: None, types, strings: vec![], + default: None, positional, named, required, diff --git a/library/src/compute/calc.rs b/library/src/compute/calc.rs index 6008828c6..bd673c542 100644 --- a/library/src/compute/calc.rs +++ b/library/src/compute/calc.rs @@ -412,7 +412,7 @@ pub fn tanh( pub fn log( /// The number whose logarithm to calculate. Must be strictly positive. value: Spanned, - /// The base of the logarithm. Defaults to `{10}` and may not be zero. + /// The base of the logarithm. May not be zero. #[named] #[default(Spanned::new(10.0, Span::detached()))] base: Spanned, diff --git a/library/src/compute/construct.rs b/library/src/compute/construct.rs index 1c5775e59..d39b69dd0 100644 --- a/library/src/compute/construct.rs +++ b/library/src/compute/construct.rs @@ -135,23 +135,18 @@ pub fn rgb( /// ] /// ``` #[external] - #[default] hex: EcoString, /// The red component. #[external] - #[default] red: Component, /// The green component. #[external] - #[default] green: Component, /// The blue component. #[external] - #[default] blue: Component, /// The alpha component. #[external] - #[default] alpha: Component, ) -> Value { Value::Color(if let Some(string) = args.find::>()? { diff --git a/library/src/compute/data.rs b/library/src/compute/data.rs index d97a3782c..90ac03c98 100644 --- a/library/src/compute/data.rs +++ b/library/src/compute/data.rs @@ -58,7 +58,6 @@ pub fn csv( path: Spanned, /// The delimiter that separates columns in the CSV file. /// Must be a single ASCII character. - /// Defaults to a comma. #[named] #[default] delimiter: Delimiter, @@ -69,7 +68,7 @@ pub fn csv( let mut builder = csv::ReaderBuilder::new(); builder.has_headers(false); - builder.delimiter(delimiter.0); + builder.delimiter(delimiter.0 as u8); let mut reader = builder.from_reader(data.as_slice()); let mut array = Array::new(); @@ -87,7 +86,7 @@ pub fn csv( } /// The delimiter to use when parsing CSV files. -struct Delimiter(u8); +struct Delimiter(char); cast_from_value! { Delimiter, @@ -102,13 +101,17 @@ cast_from_value! { Err("delimiter must be an ASCII character")? } - Self(first as u8) + Self(first) }, } +cast_to_value! { + v: Delimiter => v.0.into() +} + impl Default for Delimiter { fn default() -> Self { - Self(b',') + Self(',') } } @@ -313,7 +316,9 @@ fn format_toml_error(error: toml::de::Error) -> EcoString { /// } /// } /// -/// #bookshelf(yaml("scifi-authors.yaml")) +/// #bookshelf( +/// yaml("scifi-authors.yaml") +/// ) /// ``` /// /// Display: YAML @@ -386,15 +391,15 @@ fn format_yaml_error(error: serde_yaml::Error) -> EcoString { /// /// ## Example { #example } /// ```example -/// #let findChild(elem, tag) = { +/// #let find-child(elem, tag) = { /// elem.children /// .find(e => "tag" in e and e.tag == tag) /// } /// /// #let article(elem) = { -/// let title = findChild(elem, "title") -/// let author = findChild(elem, "author") -/// let pars = findChild(elem, "content") +/// let title = find-child(elem, "title") +/// let author = find-child(elem, "author") +/// let pars = find-child(elem, "content") /// /// heading(title.children.first()) /// text(10pt, weight: "medium")[ @@ -411,9 +416,9 @@ fn format_yaml_error(error: serde_yaml::Error) -> EcoString { /// } /// /// #let data = xml("example.xml") -/// #for child in data.first().children { -/// if (type(child) == "dictionary") { -/// article(child) +/// #for elem in data.first().children { +/// if (type(elem) == "dictionary") { +/// article(elem) /// } /// } /// ``` diff --git a/library/src/layout/container.rs b/library/src/layout/container.rs index 04c58075e..b7d0ba2fb 100644 --- a/library/src/layout/container.rs +++ b/library/src/layout/container.rs @@ -229,7 +229,6 @@ pub struct BlockElem { /// Whether the block can be broken and continue on the next page. /// - /// Defaults to `{true}`. /// ```example /// #set page(height: 80pt) /// The following block will @@ -282,13 +281,16 @@ pub struct BlockElem { /// A second paragraph. /// ``` #[external] + #[default(Em::new(1.2).into())] pub spacing: Spacing, /// The spacing between this block and its predecessor. Takes precedence /// over `spacing`. Can be used in combination with a show rule to adjust /// the spacing around arbitrary block-level elements. - /// - /// The default value is `{1.2em}`. + #[external] + #[default(Em::new(1.2).into())] + pub above: Spacing, + #[internal] #[parse( let spacing = args.named("spacing")?; args.named("above")? @@ -300,8 +302,10 @@ pub struct BlockElem { /// The spacing between this block and its successor. Takes precedence /// over `spacing`. - /// - /// The default value is `{1.2em}`. + #[external] + #[default(Em::new(1.2).into())] + pub below: Spacing, + #[internal] #[parse( args.named("below")? .map(VElem::block_around) diff --git a/library/src/layout/enum.rs b/library/src/layout/enum.rs index f7117574b..0fd0ebb2b 100644 --- a/library/src/layout/enum.rs +++ b/library/src/layout/enum.rs @@ -121,7 +121,6 @@ pub struct EnumElem { /// Whether to display the full numbering, including the numbers of /// all parent enumerations. /// - /// Defaults to `{false}`. /// /// ```example /// #set enum(numbering: "1.a)", full: true) diff --git a/library/src/layout/list.rs b/library/src/layout/list.rs index 75fc7c3a4..1e42d51b5 100644 --- a/library/src/layout/list.rs +++ b/library/src/layout/list.rs @@ -66,8 +66,6 @@ pub struct ListElem { /// control, you may pass a function that maps the list's nesting depth /// (starting from `{0}`) to a desired marker. /// - /// Default: `•` - /// /// ```example /// #set list(marker: [--]) /// - A more classic list @@ -79,7 +77,7 @@ pub struct ListElem { /// - Items /// - Items /// ``` - #[default(ListMarker::Content(vec![]))] + #[default(ListMarker::Content(vec![TextElem::packed('•')]))] pub marker: ListMarker, /// The indent of each item. @@ -192,11 +190,9 @@ impl ListMarker { /// Resolve the marker for the given depth. fn resolve(&self, vt: &mut Vt, depth: usize) -> SourceResult { Ok(match self { - Self::Content(list) => list - .get(depth) - .or(list.last()) - .cloned() - .unwrap_or_else(|| TextElem::packed('•')), + Self::Content(list) => { + list.get(depth).or(list.last()).cloned().unwrap_or_default() + } Self::Func(func) => func.call_vt(vt, [Value::Int(depth as i64)])?.display(), }) } @@ -216,7 +212,11 @@ cast_from_value! { cast_to_value! { v: ListMarker => match v { - ListMarker::Content(vec) => vec.into(), + ListMarker::Content(vec) => if vec.len() == 1 { + vec.into_iter().next().unwrap().into() + } else { + vec.into() + }, ListMarker::Func(func) => func.into(), } } diff --git a/library/src/layout/page.rs b/library/src/layout/page.rs index cb0ed7dc7..cfddc446f 100644 --- a/library/src/layout/page.rs +++ b/library/src/layout/page.rs @@ -26,9 +26,9 @@ use crate::prelude::*; /// Category: layout #[element] pub struct PageElem { - /// A standard paper size to set width and height. When this is not - /// specified, Typst defaults to `{"a4"}` paper. + /// A standard paper size to set width and height. #[external] + #[default(Paper::A4)] pub paper: Paper, /// The width of the page. @@ -470,6 +470,8 @@ cast_to_value! { /// Specification of a paper. #[derive(Debug, Copy, Clone, Hash)] pub struct Paper { + /// The name of the paper. + name: &'static str, /// The width of the paper in millimeters. width: Scalar, /// The height of the paper in millimeters. @@ -490,12 +492,13 @@ impl Paper { /// Defines paper constants and a paper parsing implementation. macro_rules! papers { - ($(($var:ident: $width:expr, $height: expr, $pat:literal))*) => { + ($(($var:ident: $width:expr, $height: expr, $name:literal))*) => { /// Predefined papers. /// /// Each paper is parsable from its name in kebab-case. impl Paper { $(pub const $var: Self = Self { + name: $name, width: Scalar($width), height: Scalar($height), };)* @@ -506,7 +509,7 @@ macro_rules! papers { fn from_str(name: &str) -> Result { match name.to_lowercase().as_str() { - $($pat => Ok(Self::$var),)* + $($name => Ok(Self::$var),)* _ => Err("unknown paper size"), } } @@ -516,9 +519,13 @@ macro_rules! papers { Paper, $( /// Produces a paper of the respective size. - $pat => Self::$var, + $name => Self::$var, )* } + + cast_to_value! { + v: Paper => v.name.into() + } }; } diff --git a/library/src/layout/par.rs b/library/src/layout/par.rs index f8df63f47..f0dcbb11f 100644 --- a/library/src/layout/par.rs +++ b/library/src/layout/par.rs @@ -20,8 +20,11 @@ use crate::text::{ /// /// ## Example { #example } /// ```example -/// #set par(first-line-indent: 1em, justify: true) /// #show par: set block(spacing: 0.65em) +/// #set par( +/// first-line-indent: 1em, +/// justify: true, +/// ) /// /// We proceed by contradiction. /// Suppose that there exists a set @@ -40,8 +43,6 @@ use crate::text::{ #[element(Construct)] pub struct ParElem { /// The spacing between lines. - /// - /// The default value is `{0.65em}`. #[resolve] #[default(Em::new(0.65).into())] pub leading: Length, @@ -102,6 +103,7 @@ pub struct ParElem { /// The contents of the paragraph. #[external] + #[required] pub body: Content, /// The paragraph's children. diff --git a/library/src/layout/table.rs b/library/src/layout/table.rs index bb24bd7c2..fb4e4a3b1 100644 --- a/library/src/layout/table.rs +++ b/library/src/layout/table.rs @@ -104,16 +104,18 @@ pub struct TableElem { /// How to stroke the cells. /// - /// This can be a color, a stroke width, both, or `{none}` to disable - /// the stroke. + /// See the [line's documentation]($func/line.stroke) for more details. + /// Strokes can be disabled by setting this to `{none}`. + /// + /// _Note:_ Richer stroke customization for individual cells is not yet + /// implemented, but will be in the future. In the meantime, you can use + /// the third-party [tablex library](https://github.com/PgBiel/typst-tablex/). #[resolve] #[fold] #[default(Some(PartialStroke::default()))] pub stroke: Option, /// How much to pad the cells's content. - /// - /// The default value is `{5pt}`. #[default(Abs::pt(5.0).into())] pub inset: Rel, diff --git a/library/src/layout/transform.rs b/library/src/layout/transform.rs index e3622ac5c..f1f1e94af 100644 --- a/library/src/layout/transform.rs +++ b/library/src/layout/transform.rs @@ -83,10 +83,9 @@ pub struct RotateElem { /// The origin of the rotation. /// - /// By default, the origin is the center of the rotated element. If, - /// however, you wanted the bottom left corner of the rotated element to - /// stay aligned with the baseline, you would set the origin to `bottom + - /// left`. + /// If, for instance, you wanted the bottom left corner of the rotated + /// element to stay aligned with the baseline, you would set it to `bottom + + /// left` instead. /// /// ```example /// #set text(spacing: 8pt) @@ -98,6 +97,8 @@ pub struct RotateElem { /// #box(rotate(30deg, origin: bottom + right, square())) /// ``` #[resolve] + #[fold] + #[default(Align::CENTER_HORIZON)] pub origin: Axes>, /// The content to rotate. @@ -115,8 +116,8 @@ impl Layout for RotateElem { ) -> SourceResult { let pod = Regions::one(regions.base(), Axes::splat(false)); let mut frame = self.body().layout(vt, styles, pod)?.into_frame(); - let origin = self.origin(styles).unwrap_or(Align::CENTER_HORIZON); - let Axes { x, y } = origin.zip(frame.size()).map(|(o, s)| o.position(s)); + let Axes { x, y } = + self.origin(styles).zip(frame.size()).map(|(o, s)| o.position(s)); let ts = Transform::translate(x, y) .pre_concat(Transform::rotate(self.angle(styles))) .pre_concat(Transform::translate(-x, -y)); @@ -160,13 +161,13 @@ pub struct ScaleElem { /// The origin of the transformation. /// - /// By default, the origin is the center of the scaled element. - /// /// ```example /// A#box(scale(75%)[A])A \ /// B#box(scale(75%, origin: bottom + left)[B])B /// ``` #[resolve] + #[fold] + #[default(Align::CENTER_HORIZON)] pub origin: Axes>, /// The content to scale. @@ -184,8 +185,8 @@ impl Layout for ScaleElem { ) -> SourceResult { let pod = Regions::one(regions.base(), Axes::splat(false)); let mut frame = self.body().layout(vt, styles, pod)?.into_frame(); - let origin = self.origin(styles).unwrap_or(Align::CENTER_HORIZON); - let Axes { x, y } = origin.zip(frame.size()).map(|(o, s)| o.position(s)); + let Axes { x, y } = + self.origin(styles).zip(frame.size()).map(|(o, s)| o.position(s)); let transform = Transform::translate(x, y) .pre_concat(Transform::scale(self.x(styles), self.y(styles))) .pre_concat(Transform::translate(-x, -y)); diff --git a/library/src/math/cancel.rs b/library/src/math/cancel.rs index 9a0ffb7a5..643eb9eb4 100644 --- a/library/src/math/cancel.rs +++ b/library/src/math/cancel.rs @@ -24,8 +24,6 @@ pub struct CancelElem { /// the whole element being "cancelled". A value of `{100%}` would then have /// the line span precisely the element's diagonal. /// - /// Defaults to `{100% + 3pt}`. - /// /// ```example /// >>> #set page(width: 140pt) /// $ a + cancel(x, length: #200%) @@ -37,8 +35,6 @@ pub struct CancelElem { /// If the cancel line should be inverted (pointing to the top left instead /// of top right). /// - /// Defaults to `{false}`. - /// /// ```example /// >>> #set page(width: 140pt) /// $ (a cancel((b + c), inverted: #true)) / @@ -50,8 +46,6 @@ pub struct CancelElem { /// If two opposing cancel lines should be drawn, forming a cross over the /// element. Overrides `inverted`. /// - /// Defaults to `{false}`. - /// /// ```example /// >>> #set page(width: 140pt) /// $ cancel(Pi, cross: #true) $ @@ -85,6 +79,11 @@ pub struct CancelElem { /// ``` #[resolve] #[fold] + #[default(PartialStroke { + // Default stroke has 0.5pt for better visuals. + thickness: Smart::Custom(Abs::pt(0.5)), + ..Default::default() + })] pub stroke: PartialStroke, } @@ -100,10 +99,8 @@ impl LayoutMath for CancelElem { let span = self.span(); let length = self.length(styles).resolve(styles); - // Default stroke has 0.5pt for better visuals. let stroke = self.stroke(styles).unwrap_or(Stroke { paint: TextElem::fill_in(styles), - thickness: Abs::pt(0.5), ..Default::default() }); diff --git a/library/src/math/delimited.rs b/library/src/math/delimited.rs index a4639de6f..403f79227 100644 --- a/library/src/math/delimited.rs +++ b/library/src/math/delimited.rs @@ -19,8 +19,6 @@ pub(super) const DELIM_SHORT_FALL: Em = Em::new(0.1); #[element(LayoutMath)] pub struct LrElem { /// The size of the brackets, relative to the height of the wrapped content. - /// - /// Defaults to `{100%}`. pub size: Smart>, /// The delimited content, including the delimiters. diff --git a/library/src/math/op.rs b/library/src/math/op.rs index 1a3acaa32..cc57eb614 100644 --- a/library/src/math/op.rs +++ b/library/src/math/op.rs @@ -27,8 +27,6 @@ pub struct OpElem { pub text: EcoString, /// Whether the operator should force attachments to display as limits. - /// - /// Defaults to `{false}`. #[default(false)] pub limits: bool, } diff --git a/library/src/meta/figure.rs b/library/src/meta/figure.rs index f23cbacc3..5476b3675 100644 --- a/library/src/meta/figure.rs +++ b/library/src/meta/figure.rs @@ -144,8 +144,6 @@ pub struct FigureElem { /// How to number the figure. Accepts a /// [numbering pattern or function]($func/numbering). - /// - /// Defaults to `{"1"}`. #[default(Some(NumberingPattern::from_str("1").unwrap().into()))] pub numbering: Option, @@ -155,8 +153,6 @@ pub struct FigureElem { /// Whether the figure should appear in an [`outline`]($func/outline) /// of figures. - /// - /// Defaults to `{true}`. #[default(true)] pub outlined: bool, diff --git a/library/src/meta/outline.rs b/library/src/meta/outline.rs index a45b2a346..3114aa380 100644 --- a/library/src/meta/outline.rs +++ b/library/src/meta/outline.rs @@ -127,7 +127,7 @@ pub struct OutlineElem { pub indent: bool, /// Content to fill the space between the title and the page number. Can be - /// set to `none` to disable filling. The default is `{repeat[.]}`. + /// set to `none` to disable filling. /// /// ```example /// #outline(fill: line(length: 100%)) diff --git a/library/src/meta/query.rs b/library/src/meta/query.rs index ca4304b52..ad7274f12 100644 --- a/library/src/meta/query.rs +++ b/library/src/meta/query.rs @@ -98,7 +98,7 @@ use crate::prelude::*; /// /// Display: Query /// Category: meta -/// Returns: content +/// Returns: array #[func] pub fn query( /// Can be an element function like a `heading` or `figure`, a `{