From 340119e5ead41df091fc644671226e4b23ea5294 Mon Sep 17 00:00:00 2001
From: Alexey Stukalov <astukalol@seer.bio>
Date: Thu, 12 Dec 2024 14:59:53 -0800
Subject: [PATCH] update savefig docs

---
 docs/src/manipulating_plots.md | 82 ++++++++++++++--------------------
 1 file changed, 34 insertions(+), 48 deletions(-)

diff --git a/docs/src/manipulating_plots.md b/docs/src/manipulating_plots.md
index e85fa64..27f6ef1 100644
--- a/docs/src/manipulating_plots.md
+++ b/docs/src/manipulating_plots.md
@@ -138,70 +138,56 @@ More examples are being worked on at this time (2021-07-14), but for now you can
 
 ## Saving figures
 
-
-Figures can be saved in a variety of formats using the `savefig` function.
+Figures can be saved in a variety of formats using the [`savefig`](@ref) function.
 
 !!! note
-   Note that the docs below are shown for the `PlotlyBase.Plot` type, but are also defined for `PlotlyJS.SyncPlot`. Thus, you can use these methods after calling either `plot` or `Plot`.
-
-This function has a few methods:
+   Note that the docs below are shown for the `PlotlyBase.Plot` type, but are also defined for `PlotlyJS.SyncPlot`.
+   Thus, you can use these methods after calling either `plot` or `Plot`.
 
-**1**
+The `savefig` function can be called in a few ways:
 
-```@docs
-savefig(::Union{PlotlyBase.Plot}, ::String)
-```
-
-When using this method the format of the file is inferred based on the extension
-of the second argument. The examples below show the possible export formats:
-
-```julia
-savefig(p::Union{Plot,SyncPlot}, "output_filename.pdf")
-savefig(p::Union{Plot,SyncPlot}, "output_filename.html")
-savefig(p::Union{Plot,SyncPlot}, "output_filename.json")
-savefig(p::Union{Plot,SyncPlot}, "output_filename.png")
-savefig(p::Union{Plot,SyncPlot}, "output_filename.svg")
-savefig(p::Union{Plot,SyncPlot}, "output_filename.jpeg")
-savefig(p::Union{Plot,SyncPlot}, "output_filename.webp")
-```
+**Save into a file**
 
-**2**
+`savefig(p, filename)` saves the plot `p` into `filename`.
+Unless explicitly specified, the format of the file is inferred from the `filename` extension.
+The examples demonstrate the supported formats:
 
 ```julia
-savefig(
-    io::IO,
-    p::Plot;
-    width::Union{Nothing,Int}=nothing,
-    height::Union{Nothing,Int}=nothing,
-    scale::Union{Nothing,Real}=nothing,
-    format::String="png"
-)
+savefig(p, "output_filename.pdf")
+savefig(p, "output_filename.html")
+savefig(p, "output_filename.json")
+savefig(p, "output_filename.png")
+savefig(p, "output_filename.svg")
+savefig(p, "output_filename.jpeg")
+savefig(p, "output_filename.webp")
 ```
 
-This method allows you to save a plot directly to an open IO stream.
+**Save into a stream**
 
-See the [`savefig(::IO, ::PlotlyBase.Plot)`](@ref) API docs for more information.
+`savefig(io, p)` saves the plot `p` into the open `io` stream.
+The figure format could be specified with the `format` keyword, the default format is *PNG*.
 
-**3**
+**Display on the screen**
 
+*PlotlyJS.jl* overloads the `Base.show` method to hook into Julia's rich display system:
 ```julia
-Base.show(::IO, ::MIME, ::Union{PlotlyBase.Plot})
+Base.show(io::IO, ::MIME, p::Union{PlotlyBase.Plot})
 ```
+Internally, this `Base.show` implementation calls `savefig(io, p)`,
+and the `MIME` argument allows to specify the output format.
+
+The following MIME formats are supported:
+    * `::MIME"application/pdf`
+    * `::MIME"image/png`
+    * `::MIME"image/svg+xml`
+    * `::MIME"image/eps`
+    * `::MIME"image/jpeg`
+    * `::MIME"application/json"`
+    * `::MIME"application/json; charset=UTF-8"`
 
-This method hooks into Julia's rich display system.
-
-Possible arguments for the second argument are shown in the examples below:
-
-```julia
-savefig(io::IO, ::MIME"application/pdf", p::Union{Plot,SyncPlot})
-savefig(io::IO, ::MIME"image/png", p::Union{Plot,SyncPlot})
-savefig(io::IO, ::MIME"image/svg+xml", p::Union{Plot,SyncPlot})
-savefig(io::IO, ::MIME"image/eps", p::Union{Plot,SyncPlot})
-savefig(io::IO, ::MIME"image/jpeg", p::Union{Plot,SyncPlot})
-savefig(io::IO, ::MIME"application/json", p::Union{Plot,SyncPlot})
-savefig(io::IO, ::MIME"application/json; charset=UTF-8", p::Union{Plot,SyncPlot})
+```@docs
+savefig
 ```
-
 !!! note
     You can also save the json for a figure by calling
     `savejson(p::Union{Plot,SyncPlot}, filename::String)`.