Let's create a list. It's open for additional suggestions.

Already superseded:

• coord_flip() by inverting x/y aesthetics.
• annotation_logticks() by guide_axis_logticks().
• coord_map() and coord_quickmap() by coord_sf()

Considered for supersession:

• coord_polar() to be superseded by coord_radial()
• coord_equal() to be superseded by coord_fixed()
  • Perhaps these could even be incorporated in coord_cartesian(), they are easy to implement.
• expand_limits() should just be function to be passed to scale limits, e.g. limits = ~ range(.x, value).

Behaviour to supersede:

• options("ggplot2.continuous.colour"): use lifecycle signal superseded. Put superseded badges in documentation. Review documentation and books.

• supersede plot_env or soft-deprecate. Disentangle facet evaluation wrt plot_env. There is a related issue Drop plot_env from ggplot2 objects? #3994.

TODO: review arguments specifically.

Could expand_limits not be superseded, please? I know you can do it in the scale via the limits argument with a function, but that is quite complex for a lot of users. It is a common need (e.g. adding a zero), so it's great to have a quick, easy method to do this

The problem with expand_limits() is that it is an extragrammatical way for implicitly settings the limits. The term 'limits' would also suggest this works at the scale level, but instead it adds a blank layer. It is hack that might be easy to use, but I'd suggest you're doing users a favour in the long term by instructing on the proper way to manipulate limits.

Also, the new approach to setting colour palettes does not do entirely what the old options approach does, as you cannot set the NA value with the new approach.

Great to start the process of getting rid of the redundant functions!

Not everyone needs to learn ggplot2 to an advanced level, @teunbrand

Not everyone needs to learn ggplot2 to an advanced level, @teunbrand

I think discoverability and ability to memorize patterns are both very important for regular users. I don't even know what limits = ~ range(.x, value) does.

In general, I have found that while it's great that there are all these nifty tricks that people can in principle use to get advanced outputs in an elegant way, in practice very few people have the mental capacity to memorize all these tricks and use them in the appropriate circumstances.

Not sure how useful this is in the present context, just pointing this out as something to keep in mind.

Separate from this PR, my idea is that there will be limit helper functions in scales, e.g. r-lib/scales#490. Which has the benefits of not being circuitous and being discoverable.

I was debating whether I should bring up the scales package as an example of a repository of great helper functions that can in principle solve all sorts of issues I have and that I can never remember how to use... ;-)

Oh, those new scales helpers are really nice! +1 for UK spelling limits_centre ;)

While you're looking at supercession ideas, I just remembered this interesting post from a year ago on mastodon re xlim/ylim (& lims by association)
https://mastodon.social/@coolbutuseless@fosstodon.org/112602236033828285

@davidhodge931 We're completely off-topic now, but xlim() and ylim() should be replaced with functions that can modify the existing scale rather than adding a new scale. This is something we've talked about for a long time (#4269). We should be able to change scale properties such as limits, breaks, expansion, etc. without having to replace the existing scale. We just haven't come up with an implementation that is satisfactory.

just to fully agree with Clause's comment
"Very few people have the mental capacity to memorize all these tricks and use them in the appropriate circumstances".
(How many of those exist? :) Teun, Thomas, and ... ? even co-author like Clause find it daunting !)
Maybe Teun's plan is to teach a LLM on how to write ggplot2 code :D ! I have lost track of the various additions, newer and better ways to do things versus the original way, e.g, the dir argument to facet_wrap versus as.table, and so on.
We need a guide for "old guard" ggplot users and also
a guide for new users to adopt the newer, better and more flexible ways.

Let's be clear on what superseding means. It means that there is a new and (in our opinion) better way of doing this. Superseded behaviour is not going away in the way deprecated functionality does. So "the old guard" can continue to do what they've always done. But, if you are a new user you will gently be steered towards the new way of doing things.

Hacks are not necessarily easier to learn than the right way of doing it. It just so happen that these hacks have been internalised by some people who will then feel resistance towards learning a different way. This is not pointing fingers. It is totally understandable. But it is also a poor argument for not superseding a function