From fad53bed06801c59c3f24ecdf2075b45b607a8a8 Mon Sep 17 00:00:00 2001
From: Carl Suster <carl@contraflo.ws>
Date: Wed, 11 Dec 2024 09:41:54 +1100
Subject: [PATCH 1/2] Explain how to fix fill guide for points with filled
 shapes

---
 R/geom-point.R              | 7 +++++++
 man/geom_point.Rd           | 7 +++++++
 vignettes/ggplot2-specs.Rmd | 2 ++
 3 files changed, 16 insertions(+)

diff --git a/R/geom-point.R b/R/geom-point.R
index 3efa394c31..600547bb66 100644
--- a/R/geom-point.R
+++ b/R/geom-point.R
@@ -85,6 +85,13 @@
 #' ggplot(mtcars, aes(wt, mpg)) +
 #'   geom_point(shape = 21, colour = "black", fill = "white", size = 5, stroke = 5)
 #'
+#' # The default shape used in legends is not filled, so you will need to
+#' # override it in the guide in order to see the fill reflected in the legend
+#' ggplot(mtcars, aes(wt, mpg, fill = factor(carb), shape = factor(cyl), colour = factor(vs))) +
+#'   geom_point(size = 5, stroke = 1) +
+#'   scale_shape_manual(values = 21:25) +
+#'   scale_fill_ordinal(guide = guide_legend(override.aes = list(shape = 21)))
+#'
 #' \donttest{
 #' # You can create interesting shapes by layering multiple points of
 #' # different sizes
diff --git a/man/geom_point.Rd b/man/geom_point.Rd
index 56264c0a36..ade53f0061 100644
--- a/man/geom_point.Rd
+++ b/man/geom_point.Rd
@@ -182,6 +182,13 @@ d + geom_point(alpha = 1/100)
 ggplot(mtcars, aes(wt, mpg)) +
   geom_point(shape = 21, colour = "black", fill = "white", size = 5, stroke = 5)
 
+# The default shape used in legends is not filled, so you will need to
+# override it in the guide in order to see the fill reflected in the legend
+ggplot(mtcars, aes(wt, mpg, fill = factor(carb), shape = factor(cyl), colour = factor(vs))) +
+  geom_point(size = 5, stroke = 1) +
+  scale_shape_manual(values = 21:25) +
+  scale_fill_ordinal(guide = guide_legend(override.aes = list(shape = 21)))
+
 \donttest{
 # You can create interesting shapes by layering multiple points of
 # different sizes
diff --git a/vignettes/ggplot2-specs.Rmd b/vignettes/ggplot2-specs.Rmd
index 79c6f29d01..04350405aa 100644
--- a/vignettes/ggplot2-specs.Rmd
+++ b/vignettes/ggplot2-specs.Rmd
@@ -251,6 +251,8 @@ ggplot(sizes, aes(size, stroke, size = size, stroke = stroke)) +
   scale_size_identity()
 ```
 
+Because most shapes are not filled, mapping the `fill` aesthetic of points is considered an advanced feature. Additional steps may be required to produce sensible results, such as overriding the shape used in the `fill` guide (refer to `geom_point()` for an example of this).
+
 ## Text
 
 ### Font family

From f2c10f598c508985f66610b04271b644c004347f Mon Sep 17 00:00:00 2001
From: Carl Suster <carl@contraflo.ws>
Date: Fri, 13 Dec 2024 15:43:18 +1100
Subject: [PATCH 2/2] Refine filled point example in docs

---
 R/geom-point.R              | 6 +++---
 man/geom_point.Rd           | 6 +++---
 vignettes/ggplot2-specs.Rmd | 2 +-
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/R/geom-point.R b/R/geom-point.R
index 600547bb66..bf73cf8749 100644
--- a/R/geom-point.R
+++ b/R/geom-point.R
@@ -85,9 +85,9 @@
 #' ggplot(mtcars, aes(wt, mpg)) +
 #'   geom_point(shape = 21, colour = "black", fill = "white", size = 5, stroke = 5)
 #'
-#' # The default shape used in legends is not filled, so you will need to
-#' # override it in the guide in order to see the fill reflected in the legend
-#' ggplot(mtcars, aes(wt, mpg, fill = factor(carb), shape = factor(cyl), colour = factor(vs))) +
+#' # The default shape in legends is not filled, but you can override the shape
+#' # in the guide to reflect the fill in the legend
+#' ggplot(mtcars, aes(wt, mpg, fill = factor(carb), shape = factor(cyl))) +
 #'   geom_point(size = 5, stroke = 1) +
 #'   scale_shape_manual(values = 21:25) +
 #'   scale_fill_ordinal(guide = guide_legend(override.aes = list(shape = 21)))
diff --git a/man/geom_point.Rd b/man/geom_point.Rd
index ade53f0061..ccf615e007 100644
--- a/man/geom_point.Rd
+++ b/man/geom_point.Rd
@@ -182,9 +182,9 @@ d + geom_point(alpha = 1/100)
 ggplot(mtcars, aes(wt, mpg)) +
   geom_point(shape = 21, colour = "black", fill = "white", size = 5, stroke = 5)
 
-# The default shape used in legends is not filled, so you will need to
-# override it in the guide in order to see the fill reflected in the legend
-ggplot(mtcars, aes(wt, mpg, fill = factor(carb), shape = factor(cyl), colour = factor(vs))) +
+# The default shape in legends is not filled, but you can override the shape
+# in the guide to reflect the fill in the legend
+ggplot(mtcars, aes(wt, mpg, fill = factor(carb), shape = factor(cyl))) +
   geom_point(size = 5, stroke = 1) +
   scale_shape_manual(values = 21:25) +
   scale_fill_ordinal(guide = guide_legend(override.aes = list(shape = 21)))
diff --git a/vignettes/ggplot2-specs.Rmd b/vignettes/ggplot2-specs.Rmd
index 04350405aa..21d90e12af 100644
--- a/vignettes/ggplot2-specs.Rmd
+++ b/vignettes/ggplot2-specs.Rmd
@@ -251,7 +251,7 @@ ggplot(sizes, aes(size, stroke, size = size, stroke = stroke)) +
   scale_size_identity()
 ```
 
-Because most shapes are not filled, mapping the `fill` aesthetic of points is considered an advanced feature. Additional steps may be required to produce sensible results, such as overriding the shape used in the `fill` guide (refer to `geom_point()` for an example of this).
+Because points are not typically filled, you may need to change some default settings when using these shapes and mapping `fill`. In particular, discrete `fill` guides will be drawn with an unfilled shape unless overridden (refer to `geom_point()` for an example of this).
 
 ## Text