show don't tell

Author: huettenhain

tutorials/notebooks/tbr-files.v0x0b.flare.on.12.ipynb

@@ -180,14 +180,8 @@
     "We have to reverse engineer a packed Python script.\n",
     "The first layer is a sequence of zlib-decompression and unmarshaling;\n",
     "here's a [peek][] at the code without the useless comments;\n",
-    "It first uses [resplit][] to split the input at line breaks, and then filters out all lines that contain a comment using [iffx][] within the [frame][]. The unit [sep][] re-inserts line breaks before fusing the lines at the end of that frame, and [trim][] strips all surrounding whitespace of the document.\n",
     "\n",
-    "[resplit]: https://binref.github.io/#refinery.resplit\n",
-    "[iffx]: https://binref.github.io/#refinery.iffx\n",
-    "[sep]: https://binref.github.io/#refinery.sep\n",
-    "[trim]: https://binref.github.io/#refinery.trim\n",
-    "[peek]: https://binref.github.io/#refinery.peek\n",
-    "[frame]: https://binref.github.io/lib/frame.html"
+    "[peek]: https://binref.github.io/#refinery.peek"
    ]
   },
   {
@@ -220,15 +214,26 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We use [csd][], another shortcut for [carve][], which includes both the `-s` and `-d` switches.\n",
-    "The former means to carve the single largest buffer, while `-d` instructs the unit to decode the buffer.\n",
-    "For a string literal, this means to remove the surrounding quotes and resolve any escape sequences.\n",
+    "*(This pipeline first uses [resplit][] to split the input at line breaks, and then filters out all lines that contain a comment using [iffx][] within the [frame][]. The unit [sep][] re-inserts line breaks before fusing the lines at the end of that frame, and [trim][] strips all surrounding whitespace of the document.)*\n",
+    "\n",
+    "[resplit]: https://binref.github.io/#refinery.resplit\n",
+    "[iffx]: https://binref.github.io/#refinery.iffx\n",
+    "[sep]: https://binref.github.io/#refinery.sep\n",
+    "[trim]: https://binref.github.io/#refinery.trim\n",
+    "[peek]: https://binref.github.io/#refinery.peek\n",
+    "[frame]: https://binref.github.io/lib/frame.html"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We next use [esc][], which decodes string literals and resolves backslash escape sequences.\n",
     "Then, we use [zl][] to decompress the buffer.\n",
-    "There is also a refinery unit [pym][] for unmarshaling which attempts to dump code objects with the correct magic.\n",
+    "Finally, there is a unit [pym][] for unmarshaling which attempts to dump code objects with the correct magic.\n",
     "This doesn't always work well, but after tweaking the unit during Flare On, it should definitely continue to work for this specific sample as I'm adding a regression test for it:\n",
     "\n",
-    "\n",
-    "[csd]: https://binref.github.io/#refinery.csd\n",
+    "[esc]: https://binref.github.io/#refinery.esc\n",
     "[carve]: https://binref.github.io/#refinery.carve\n",
     "[pym]: https://binref.github.io/#refinery.pym\n",
     "[zl]: https://binref.github.io/#refinery.zl"
@@ -240,7 +245,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%emit project_chimera.py | csd str | zl | pym | dump stage1.pyc"
+    "%emit project_chimera.py | csb str | esc | zl | pym | dump stage1.pyc"
    ]
   },
   {