Clarify stuff

takimata · takimata · commit a68b7f437bb4 · 2021-07-18T12:28:51.000+02:00
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -679,7 +679,6 @@ def set_sketch_params(self, scale=None, length=None, randomness=None):
 
         Requires the following preamble when using the PGF backend:
 
-            \\usepackage{pgf}
             \\usepgfmodule{decorations}
             \\usepgflibrary{decorations.pathmorphing}
 
diff --git a/lib/matplotlib/backends/backend_pgf.py b/lib/matplotlib/backends/backend_pgf.py
@@ -603,10 +603,13 @@ def _print_pgf_path(self, gc, path, transform, rgbFace=None):
         # apply pgf decorators
         sketch_params = gc.get_sketch_params() if gc else None
         if sketch_params is not None:
-            # Only "length" directly maps to "segment length" in PGF's API
-            # The others are combined in "amplitude" -> Use "randomness" as
-            # PRNG seed to allow the user to force the same shape on multiple
-            # sketched lines
+            # Only "length" directly maps to "segment length" in PGF's API.
+            # PGF uses "amplitude" to pass the combined deviation in both x-
+            # and y-direction, while matplotlib only varies the length of the
+            # wiggle along the line ("randomness" and "length" parameters)
+            # and has a separate "scale" argument for the amplitude.
+            # -> Use "randomness" as PRNG seed to allow the user to force the
+            # same shape on multiple sketched lines
             scale, length, randomness = sketch_params
             if scale is not None:
                 writeln(self.fh, r"\pgfkeys{/pgf/decoration/.cd, "
diff --git a/lib/matplotlib/tests/test_backend_pgf.py b/lib/matplotlib/tests/test_backend_pgf.py
@@ -341,34 +341,24 @@ def test_minus_signs_with_tex(fig_test, fig_ref, texsystem):
 
 @pytest.mark.backend("pgf")
 def test_sketch_params():
-    fig, ax = plt.subplots(figsize=[3, 3])
+    fig, ax = plt.subplots(figsize=(3, 3))
     ax.set_xticks([])
     ax.set_yticks([])
     ax.set_frame_on(False)
-    handle = ax.plot([0, 1])[0]
+    handle, = ax.plot([0, 1])
     handle.set_sketch_params(scale=5, length=30, randomness=42)
 
     with BytesIO() as fd:
         fig.savefig(fd, format='pgf')
         buf = fd.getvalue().decode()
 
-    baseline = r"""\begin{pgfscope}%
-\pgfpathrectangle{\pgfqpoint{0.375000in}{0.300000in}}""" \
-    r"""{\pgfqpoint{2.325000in}{2.400000in}}%
-\pgfusepath{clip}%
-\pgfsetrectcap%
-\pgfsetroundjoin%
-\pgfsetlinewidth{1.003750pt}%
-\definecolor{currentstroke}{rgb}{0.000000,0.000000,1.000000}%
-\pgfsetstrokecolor{currentstroke}%
-\pgfsetdash{}{0pt}%
-\pgfpathmoveto{\pgfqpoint{0.375000in}{0.300000in}}%
+    baseline = r"""\pgfpathmoveto{\pgfqpoint{0.375000in}{0.300000in}}%
 \pgfpathlineto{\pgfqpoint{2.700000in}{2.700000in}}%
 \pgfkeys{/pgf/decoration/.cd, """ \
     r"""segment length = 0.300000in, amplitude = 0.050000in}%
 \pgfmathsetseed{42}%
 \pgfdecoratecurrentpath{random steps}%
-\pgfusepath{stroke}%
-\end{pgfscope}%"""
-    # check that \pgfkeys{/pgf/decoration/.cd, ...} is in path definition
+\pgfusepath{stroke}%"""
+    # \pgfdecoratecurrentpath must be after the path definition and before the
+    # path is used (\pgfusepath)
     assert baseline in buf
