Merge remote-tracking branch 'origin/master'

alshan · alshan · commit 72953acf5242 · 2024-12-16T17:12:09.000-05:00
# Conflicts:
#	build.gradle.kts
diff --git a/Writerside/images/Python4DS.png b/Writerside/images/Python4DS.png
diff --git a/Writerside/images/coding_for_economists.png b/Writerside/images/coding_for_economists.png
diff --git a/Writerside/images/previews/square-legend_theme.png b/Writerside/images/previews/square-legend_theme.png
diff --git a/Writerside/images/previews/square-theme_legend_scheme.png b/Writerside/images/previews/square-theme_legend_scheme.png
diff --git a/Writerside/images/screenshots/text_geoms.png b/Writerside/images/screenshots/text_geoms.png
diff --git a/Writerside/topics/annotations.md b/Writerside/topics/annotations.md
@@ -1,6 +1,7 @@
 # Annotating Charts
 
 You can customize the content of annotations for pie and bar charts by using the parameter `labels` of the corresponding functions.
+The parameter takes as value the result of the [`layerLabels()`](%api_annotations%/layer-labels/index.html) function call.
 
 [Learn more (datalore link)](%nbp-annotations%).
 
diff --git a/Writerside/topics/charts.md b/Writerside/topics/charts.md
@@ -218,4 +218,18 @@ Examples:
 Examples:
 
 - [Flipped coordinates](%nb-coord_flip%)
-- [Polar coordinate system](%nb-coord_polar%)
+- [Polar coordinate system](%nb-coord_polar%)
+
+
+## Legends and Guides
+
+[`guideLegend()`](%api_scale%/guide-legend.html),
+[`guideColorbar()`](%api_scale%/guide-colorbar.html),
+[`guides()`](%api_scale%/guides.html),
+[`layerKey()`](%api_scale%/layer-key.html)
+
+Examples:
+
+- [Legend customization](%nb-legend%)
+- [Manual legend](%nb-manual_legend%)
+- [Customize legend appearance](%nb-legend_theme%)
diff --git a/Writerside/topics/formats.md b/Writerside/topics/formats.md
@@ -78,6 +78,10 @@ The numeric format strings are used to format common numeric types. The general
   - `Z` - zetta, 10²¹
   - `Y` - yotta, 10²⁴
 
+<note>
+  These formatting rules are compatible with formatting from the d3 library, so you can find out more about the options listed above by visiting <a href="https://d3js.org/d3-format">this page</a>.
+</note>
+
 ### Number Format Examples
 
 Let's format the number `1024`:
@@ -107,12 +111,20 @@ Some other examples:
 ```
 format   number        result
 .1f      0.42          "0.4"
-.3g      0.4449        "0.445"
-,.12g    -4200000      "-4,200,000" 
-0,.2f    1234567.449   "1,234,567.45"
+0,.1f    1234567.89    "1,234,567.9"
 +$,.2f   1e4           "+$10,000.00"
++$,.2~f  1e4           "+$10,000"
+~g       0.0000042     "0.0000042"
+~g       0.00000042    "4.2e-7"
+~g       420000        "420000"
+~g       4200000       "4.2e+6"
+,.2g     -4231         "-4,2e+3"
+,.6g     -4231         "-4,231.00"
+,.6~g    -4231         "-4,231"
 ```
 
+See more examples <a href="https://observablehq.com/@d3/d3-format">here</a>.
+
 ## String Template
 
 The number format can be used in a template to create a string with variable substitution.
@@ -220,5 +232,5 @@ You can format text in annotations, see: [Annotating Charts](annotations.md).
 ## Demo Notebooks
 
 - [Formatting labels on plots](%nb-formatting_axes_etc%)
-- [The `label_format` parameter in `geom_text()`](%nb-label_format%)
+- [Text geoms](%nb-text_geoms%)
 - [Exponent format in Lets-Plot](%nb-superscript_exponent%)
diff --git a/Writerside/topics/gallery.md b/Writerside/topics/gallery.md
@@ -2,8 +2,8 @@
 
 <list columns="3">
     <li>
-        <a href="%nb-legend_theme%">
-            <img alt="Customize legend appearance" src="square-legend_theme.png"/>
+        <a href="%nb-theme_legend_scheme%">
+            <img alt="Theme legend scheme" src="square-theme_legend_scheme.png"/>
         </a>
     </li>
     <li>
diff --git a/Writerside/topics/geospatial_charts.md b/Writerside/topics/geospatial_charts.md
@@ -106,6 +106,6 @@ When declaring additional GeoTools dependencies, check the compatible version in
   <img src="projection_provided.png" alt="Using exotic map projections" height="339"/>
 
 - Label geometry:
-  [geom_label.ipynb](%nb-geom_label%)
+  [text_geoms.ipynb](%nb-text_geoms%)
 
-  <img src="geom_label.png" alt="Label geometry" width="480"/>
+  <img src="text_geoms.png" alt="Text geoms" width="480"/>
diff --git a/Writerside/topics/presentation_options.md b/Writerside/topics/presentation_options.md
@@ -12,6 +12,28 @@
 [`guideColorbar()`](%api_scale%/guide-colorbar.html),
 [`guides()`](%api_scale%/guides.html)
 
+### Examples
+
+- [Themes overview](%nb-themes%)
+- [Default theme](%nb-default_theme%)
+- [Applying common theme to a plot group](%nb-gggrid_theme%)
+- [Plot margins](%nb-theme_plot_margin%)
+- [Option to show/hide plot messages](%nb-theme_plot_message%)
+- [Justification for text elements](%nb-hjust_vjust%)
+- [Margins](%nb-margins%)
+- [`margin` parameter of `elementText()`](%nb-text_margins%)
+- [Panel border](%nb-panel_border%)
+- [Tooltip properties in `theme()`](%nb-tooltips_theme%)
+- [Plot title, subtitle and caption](%nb-title_subtitle_caption%)
+- [Theme colors for geometries](%nb-geom_theme_colors%)
+- [Customize legend appearance](%nb-legend_theme%)
+- [Tooltip customization](%nb-tooltip_config%)
+- [Set font faces](%nb-set_font_faces%)
+- [Set font size and family](%nb-font_size_and_family%)
+- [Rotation of axis labels](%nb-axis_text_angle%)
+- [Exponent format in Lets-Plot](%nb-superscript_exponent%)
+- [Annotation labels on pie-chart](%nb-annotations_for_pie%)
+
 ## Predefined Themes
 
 [`minimal2`](%api_theme%/theme-minimal2.html),
@@ -27,6 +49,17 @@
     <img alt="All predefined themes" src="complete_themes.png" style="block"/>
 </a>
 
+### Predefined Themes Examples
+
+- [Default theme](%nb-default_theme%)
+- [Theme flavors](%nb-theme_flavors%)
+- [Applying common theme to a plot group](%nb-gggrid_theme%)
+- [Margins](%nb-margins%)
+- [`margin` parameter of `elementText()`](%nb-text_margins%)
+- [Theme colors for geometries](%nb-geom_theme_colors%)
+- [Axis position](%nb-axis_position%)
+- [Exponent format in Lets-Plot](%nb-superscript_exponent%)
+
 ## Color Schemes (Flavors)
 
 [`darcula`](%api_theme%/flavor-darcula.html),
@@ -39,26 +72,9 @@
     <img alt="Theme colors for geometries" src="flavors.png" style="block"/>
 </a>
 
-## Examples
+### Flavors Examples
 
-- [Default theme](%nb-default_theme%)
-- [Themes overview](%nb-themes%)
+- [Theme flavors](%nb-theme_flavors%)
 - [Applying common theme to a plot group](%nb-gggrid_theme%)
-- [Plot margins](%nb-theme_plot_margin%)
-- [Option to show/hide plot messages](%nb-theme_plot_message%)
-- [Justification for text elements](%nb-hjust_vjust%)
-- [Margins](%nb-margins%)
-- [`margin` parameter of `elementText()`](%nb-text_margins%)
-- [Panel border](%nb-panel_border%)
-- [Tooltip properties in `theme()`](%nb-tooltips_theme%)
-- [Plot title, subtitle and caption](%nb-title_subtitle_caption%)
 - [Theme colors for geometries](%nb-geom_theme_colors%)
-- [Theme flavors](%nb-theme_flavors%)
-- [Customizing the legend](%nb-legend%)
-- [Tooltip customization](%nb-tooltip_config%)
-- [Set font faces](%nb-set_font_faces%)
-- [Set font size and family](%nb-font_size_and_family%)
-- [Axis position](%nb-axis_position%)
-- [Rotation of axis labels](%nb-axis_text_angle%)
-- [Exponent format in Lets-Plot](%nb-superscript_exponent%)
 - [Annotation labels on pie-chart](%nb-annotations_for_pie%)
diff --git a/Writerside/topics/tooltips.md b/Writerside/topics/tooltips.md
@@ -1,6 +1,7 @@
 # Tooltip Customization
 
-You can customize the content, values formatting and appearance of tooltip for any geometry layer in your plot.
+You can customize the content, values formatting and appearance of tooltip for any geometry layer by using the parameter `tooltips`.
+The parameter takes as value the result of the [`layerToltips()`](%api_tooltips%/layer-tooltips/index.html) function call.
 
 [Learn more (datalore link)](%nbp-tooltips%).
 
diff --git a/Writerside/v.list b/Writerside/v.list
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE vars SYSTEM "https://resources.jetbrains.com/writerside/1.0/vars.dtd">
 <vars>
-    <var name="version" value="4.8.0"/>
+    <var name="version" value="4.9.2"/>
     <var name="current_year" value="2024"/>
     <var name="web_root" value="https://lets-plot.org"/>
 
@@ -33,13 +33,13 @@
     <!-- Gallery -->
     <var name="nb-geotools_naturalearth" value="%nbviewer_demo%/geotools_naturalearth.ipynb"/>
     <var name="nb-interact_pan_zoom" value="%nbviewer_demo%/interact_pan_zoom.ipynb"/>
-    <var name="nb-legend_theme" value="%nbviewer_cookbook%/legend_theme.ipynb"/>
     <var name="nb-lp_verse" value="%nbviewer_demo%/lp_verse.ipynb"/>
     <var name="nb-mpg_daisy" value="%nbviewer_demo%/mpg_daisy.ipynb"/>
     <var name="nb-palmer_penguins" value="%nbviewer_demo%/palmer_penguins.ipynb"/>
     <var name="nb-pushkin" value="%nbviewer_demo%/pushkin.ipynb"/>
     <var name="nb-spatialdataset_kotlin_isl" value="%nbviewer_demo%/spatialdataset_kotlin_isl.ipynb"/>
     <var name="nb-sunshine_hours" value="%nbviewer_demo%/sunshine_hours.ipynb"/>
+    <var name="nb-theme_legend_scheme" value="%nbviewer_demo%/theme_legend_scheme.ipynb"/>
     <var name="nb-us_unemployment" value="%nbviewer_demo%/us_unemployment.ipynb"/>
     <var name="nb-wind_rose" value="%nbviewer_demo%/wind_rose.ipynb"/>
     <!-- Cookbooks -->
@@ -72,12 +72,10 @@
     <var name="nb-geom_dotplot" value="%nbviewer_cookbook%/geom_dotplot.ipynb"/>
     <var name="nb-geom_function" value="%nbviewer_cookbook%/geom_function.ipynb"/>
     <var name="nb-geom_histogram_threshold" value="%nbviewer_cookbook%/geom_histogram_threshold.ipynb"/>
-    <var name="nb-geom_label" value="%nbviewer_cookbook%/geom_label.ipynb"/>
     <var name="nb-geom_lollipop" value="%nbviewer_cookbook%/geom_lollipop.ipynb"/>
     <var name="nb-geom_pie" value="%nbviewer_cookbook%/geom_pie.ipynb"/>
     <var name="nb-geom_smooth" value="%nbviewer_cookbook%/geom_smooth.ipynb"/>
     <var name="nb-geom_spoke" value="%nbviewer_cookbook%/geom_spoke.ipynb"/>
-    <var name="nb-geom_text_and_label_new_features" value="%nbviewer_cookbook%/geom_text_and_label_new_features.ipynb"/>
     <var name="nb-geom_theme_colors" value="%nbviewer_cookbook%/geom_theme_colors.ipynb"/>
     <var name="nb-geom_violin" value="%nbviewer_cookbook%/geom_violin.ipynb"/>
     <var name="nb-geom_ydotplot" value="%nbviewer_cookbook%/geom_ydotplot.ipynb"/>
@@ -94,9 +92,9 @@
     <var name="nb-image_grayscale" value="%nbviewer_cookbook%/image_grayscale.ipynb"/>
     <var name="nb-jittered_points" value="%nbviewer_cookbook%/jittered_points.ipynb"/>
     <var name="nb-joint_plot" value="%nbviewer_cookbook%/joint_plot.ipynb"/>
-    <var name="nb-label_format" value="%nbviewer_cookbook%/label_format.ipynb"/>
     <var name="nb-latex_support" value="%nbviewer_cookbook%/latex_support.ipynb"/>
     <var name="nb-legend" value="%nbviewer_cookbook%/legend.ipynb"/>
+    <var name="nb-legend_theme" value="%nbviewer_cookbook%/legend_theme.ipynb"/>
     <var name="nb-lines" value="%nbviewer_cookbook%/lines.ipynb"/>
     <var name="nb-manual_legend" value="%nbviewer_cookbook%/manual_legend.ipynb"/>
     <var name="nb-marginal_layers" value="%nbviewer_cookbook%/marginal_layers.ipynb"/>
@@ -126,6 +124,7 @@
     <var name="nb-stat_summary" value="%nbviewer_cookbook%/stat_summary.ipynb"/>
     <var name="nb-stat_summary_bin" value="%nbviewer_cookbook%/stat_summary_bin.ipynb"/>
     <var name="nb-superscript_exponent" value="%nbviewer_cookbook%/superscript_exponent.ipynb"/>
+    <var name="nb-text_geoms" value="https://datalore.jetbrains.com/report/static/HZqq77cegYd.E7get_WnChZ/Lb69ZPTQWq3XbupPxnQ4Rh"/>
     <var name="nb-text_margins" value="%nbviewer_cookbook%/text_margins.ipynb"/>
     <var name="nb-theme_flavors" value="%nbviewer_cookbook%/theme_flavors.ipynb"/>
     <var name="nb-theme_plot_margin" value="%nbviewer_cookbook%/theme_plot_margin.ipynb"/>
diff --git a/docs/dokka/source/packages.md b/docs/dokka/source/packages.md
@@ -96,9 +96,7 @@ letsPlot(data) +
 
 - `geomTile()`, `geomContour()`, `geomPolygon()` (`Stat.contour()`), `geomContourFilled()`: [contours.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/contours.ipynb)
 
-- `geomText()`: [label_format.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/label_format.ipynb)
-
-- `geomLabel()`: [geom_label.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/geom_label.ipynb)
+- `geomText()`, `geomLabel()`: [text_geoms.ipynb](https://datalore.jetbrains.com/report/static/HZqq77cegYd.E7get_WnChZ/Lb69ZPTQWq3XbupPxnQ4Rh)
 
 - `geomQQ()`, `geomQQLine()`, `geomQQ2()`, `geomQQ2Line()`, `qqPlot()`: [qq_plots.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/qq_plots.ipynb)
 
diff --git a/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_label.kt b/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_label.kt
@@ -24,9 +24,7 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  *
  * ## Examples
  *
- * - [geom_label.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/geom_label.ipynb)
- *
- * - [geom_label_alpha_stroke.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/geom_label_alpha_stroke.ipynb)
+ * - [text_geoms.ipynb](https://datalore.jetbrains.com/report/static/HZqq77cegYd.E7get_WnChZ/Lb69ZPTQWq3XbupPxnQ4Rh)
  *
  * @param data The data to be displayed in this layer. If null, the default, the data
  *  is inherited from the plot data as specified in the call to [letsPlot][org.jetbrains.letsPlot.letsPlot].
diff --git a/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_text.kt b/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_text.kt
@@ -23,7 +23,7 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  *
  * ## Examples
  *
- * - [label_format.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/label_format.ipynb)
+ * - [text_geoms.ipynb](https://datalore.jetbrains.com/report/static/HZqq77cegYd.E7get_WnChZ/Lb69ZPTQWq3XbupPxnQ4Rh)
  *
  * - [formatting_axes_etc.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/formatting_axes_etc.ipynb)
  *
