Merge branch 'raimo/stdlib/gen_statem-dev/OTP-14015'

* raimo/stdlib/gen_statem-dev/OTP-14015:
  Fix after feedback
  Improve pointer to User's Guide
  Fix after feedback on 'When to use'
  Add a 'When to use' section
  Fix timeout parsing and doc feedback
  Improve doc, change images to .svg
  erl_docgen: Implement width in image tag
  Update User's Guide and pointers to it
  Improve error reasons from state enter call

8 files changed, 1267 insertions, 519 deletions

diff --git a/system/doc/design_principles/Makefile b/system/doc/design_principles/Makefile
index 611ab6da99..41d2d1208f 100644
--- a/system/doc/design_principles/Makefile
+++ b/system/doc/design_principles/Makefile
@@ -1,7 +1,7 @@
 #
 # %CopyrightBegin%
 #
-# Copyright Ericsson AB 1997-2016. All Rights Reserved.
+# Copyright Ericsson AB 1997-2018. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -60,11 +60,11 @@ GIF_FILES = \
 	sup5.gif \
 	sup6.gif
 
-PNG_FILES = \
-	code_lock.png \
-	code_lock_2.png
+SVG_FILES = \
+	code_lock.svg \
+	code_lock_2.svg
 
-IMAGE_FILES = $(GIF_FILES) $(PNG_FILES)
+IMAGE_FILES = $(GIF_FILES) $(SVG_FILES)
 
 XML_FILES = \
 	$(BOOK_FILES) $(XML_CHAPTER_FILES) \
@@ -93,7 +93,7 @@ _create_dirs := $(shell mkdir -p $(HTMLDIR))
 $(HTMLDIR)/%.gif: %.gif
 	$(INSTALL_DATA) $< $@
 
-$(HTMLDIR)/%.png: %.png
+$(HTMLDIR)/%.svg: %.svg
 	$(INSTALL_DATA) $< $@
 
 docs: html
diff --git a/system/doc/design_principles/code_lock.dia b/system/doc/design_principles/code_lock.dia
index eaa2aca5b0..fe43d6da2c 100644
--- a/system/doc/design_principles/code_lock.dia
+++ b/system/doc/design_principles/code_lock.dia
diff --git a/system/doc/design_principles/code_lock.png b/system/doc/design_principles/code_lock.png
deleted file mode 100644
index 40bd35fc74..0000000000
--- a/system/doc/design_principles/code_lock.png
+++ /dev/null
diff --git a/system/doc/design_principles/code_lock.svg b/system/doc/design_principles/code_lock.svg
new file mode 100644
index 0000000000..223e121486
--- /dev/null
+++ b/system/doc/design_principles/code_lock.svg
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="41cm" height="52cm" viewBox="-2 -2 806 1023" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="492.782,860 600,860 600,900 "/>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="380,900 380,900 380,931.6 "/>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="640,560 640,580 640,580 640,600 "/>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="492.782,300 640,300 640,340 "/>
+  <g>
+    <path style="fill: #d5d5f7" d="M 289.774 260 L 470.226,260 C 492.782,276 500,284 500,300 C 500,316 492.782,324 470.226,340 L 289.774,340 C 267.218,324 260,316 260,300 C 260,284 267.218,276 289.774,260z"/>
+    <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 289.774 260 L 470.226,260 C 492.782,276 500,284 500,300 C 500,316 492.782,324 470.226,340 L 289.774,340 C 267.218,324 260,316 260,300 C 260,284 267.218,276 289.774,260"/>
+    <text font-size="27.0933" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="380" y="308.467">
+      <tspan x="380" y="308.467">locked</tspan>
+    </text>
+  </g>
+  <g>
+    <path style="fill: #d5d5f7" d="M 289.774 820 L 470.226,820 C 492.782,836 500,844 500,860 C 500,876 492.782,884 470.226,900 L 289.774,900 C 267.218,884 260,876 260,860 C 260,844 267.218,836 289.774,820z"/>
+    <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 289.774 820 L 470.226,820 C 492.782,836 500,844 500,860 C 500,876 492.782,884 470.226,900 L 289.774,900 C 267.218,884 260,876 260,860 C 260,844 267.218,836 289.774,820"/>
+    <text font-size="27.0933" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="380" y="868.467">
+      <tspan x="380" y="868.467">open</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #aad7aa" points="520,340 760,340 736,360 760,380 520,380 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="520,340 760,340 736,360 760,380 520,380 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:italic;font-weight:normal" x="546" y="366.35">
+      <tspan x="546" y="366.35">{button,Button}</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #f3cccc" points="640,480 800,520 640,560 480,520 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="640,480 800,520 640,560 480,520 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="643.2" y="527.15">
+      <tspan x="643.2" y="527.15">Correct Code?</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #ffff8f" points="0,940 160,940 160,980 0,980 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="0,940 160,940 160,980 0,980 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="80" y="966.35">
+      <tspan x="80" y="966.35">do_lock()</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #aad7aa" points="280,931.6 480,931.6 460,960 480,988.4 280,988.4 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="280,931.6 480,931.6 460,960 480,988.4 280,988.4 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:italic;font-weight:normal" x="380" y="966.35">
+      <tspan x="380" y="966.35">state_timeout</tspan>
+    </text>
+  </g>
+  <g>
+    <ellipse style="fill: #d5d5f7" cx="380" cy="40" rx="40" ry="40"/>
+    <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="380" cy="40" rx="40" ry="40"/>
+    <text font-size="27.0933" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="380" y="48.4667">
+      <tspan x="380" y="48.4667">init</tspan>
+    </text>
+  </g>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="380.719" y1="180" x2="380.087" y2="250.264"/>
+    <polygon style="fill: #000000" points="380.02,257.764 375.11,247.72 380.087,250.264 385.11,247.809 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="380.02,257.764 375.11,247.72 380.087,250.264 385.11,247.809 "/>
+  </g>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="640.438" y1="440" x2="640.106" y2="470.265"/>
+    <polygon style="fill: #000000" points="640.024,477.764 635.134,467.71 640.106,470.265 645.134,467.819 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="640.024,477.764 635.134,467.71 640.106,470.265 645.134,467.819 "/>
+  </g>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="640,700 640,740 380,740 380,740 "/>
+  <text font-size="20.32" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="640" y="578.9">
+    <tspan x="640" y="578.9">Y</tspan>
+  </text>
+  <text font-size="20.32" style="fill: #000000;text-anchor:end;font-family:sans-serif;font-style:normal;font-weight:normal" x="480" y="538.9">
+    <tspan x="480" y="538.9">N</tspan>
+  </text>
+  <g>
+    <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="80,940 80,220 370.623,220 "/>
+    <polygon style="fill: #000000" points="378.123,220 368.123,225 370.623,220 368.123,215 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="378.123,220 368.123,225 370.623,220 368.123,215 "/>
+  </g>
+  <g>
+    <polygon style="fill: #aad7aa" points="500,900 700,900 680,920 700,940 500,940 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="500,900 700,900 680,920 700,940 500,940 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:italic;font-weight:normal" x="522" y="926.35">
+      <tspan x="522" y="926.35">{button,Digit}</tspan>
+    </text>
+  </g>
+  <g>
+    <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="600,940 600,980 760,980 760,780 389.736,780 "/>
+    <polygon style="fill: #000000" points="382.236,780 392.236,775 389.736,780 392.236,785 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="382.236,780 392.236,775 389.736,780 392.236,785 "/>
+  </g>
+  <g>
+    <polygon style="fill: #ffff8f" points="260,120 501.438,120 501.438,180 260,180 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="260,120 501.438,120 501.438,180 260,180 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="286.144" y="143.65">
+      <tspan x="286.144" y="143.65">do_lock()</tspan>
+      <tspan x="286.144" y="169.05">Clear Buttons</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #ffff8f" points="500,600 780,600 780,700 500,700 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="500,600 780,600 780,700 500,700 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="530" y="630.95">
+      <tspan x="530" y="630.95">do_unlock()</tspan>
+      <tspan x="530" y="656.35">Clear Buttons</tspan>
+      <tspan x="530" y="681.75">state_timeout 10 s</tspan>
+    </text>
+  </g>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="380" y1="80" x2="380.544" y2="110.266"/>
+    <polygon style="fill: #000000" points="380.679,117.764 375.5,107.856 380.544,110.266 385.498,107.676 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="380.679,117.764 375.5,107.856 380.544,110.266 385.498,107.676 "/>
+  </g>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="380" y1="740" x2="380" y2="810.264"/>
+    <polygon style="fill: #000000" points="380,817.764 375,807.764 380,810.264 385,807.764 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="380,817.764 375,807.764 380,810.264 385,807.764 "/>
+  </g>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="380,988.4 380,1020 80,1020 80,980 "/>
+  <g>
+    <polygon style="fill: #ffff8f" points="540,400 740.875,400 740.875,440 540,440 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="540,400 740.875,400 740.875,440 540,440 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="640.438" y="426.35">
+      <tspan x="640.438" y="426.35">Collect Buttons</tspan>
+    </text>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="640" y1="380" x2="640.438" y2="400"/>
+  <g>
+    <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="480,520 380,520 380,351 "/>
+    <polygon style="fill: #000000" points="385,351 380,341 375,351 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="385,351 380,341 375,351 "/>
+  </g>
+</svg>
diff --git a/system/doc/design_principles/code_lock_2.dia b/system/doc/design_principles/code_lock_2.dia
index 3b9ba554d8..31eb0fb6eb 100644
--- a/system/doc/design_principles/code_lock_2.dia
+++ b/system/doc/design_principles/code_lock_2.dia
diff --git a/system/doc/design_principles/code_lock_2.png b/system/doc/design_principles/code_lock_2.png
deleted file mode 100644
index 3aca9dd5aa..0000000000
--- a/system/doc/design_principles/code_lock_2.png
+++ /dev/null
diff --git a/system/doc/design_principles/code_lock_2.svg b/system/doc/design_principles/code_lock_2.svg
new file mode 100644
index 0000000000..d3e15e7577
--- /dev/null
+++ b/system/doc/design_principles/code_lock_2.svg
@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="41cm" height="52cm" viewBox="-1 0 806 1021" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="380,300.55 380,300 140,300 140,360 "/>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="412.782,900 412.782,900 560,900 560,940 "/>
+  <g>
+    <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="560,980 560,1020 0,1020 0,120.55 370.264,120.55 "/>
+    <polygon style="fill: #000000" points="377.764,120.55 367.764,125.55 370.264,120.55 367.764,115.55 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="377.764,120.55 367.764,125.55 370.264,120.55 367.764,115.55 "/>
+  </g>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="640,680 640,720 300,720 300,760 "/>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="492.782,300.55 492.782,300 640,300 640,360 "/>
+  <g>
+    <path style="fill: #d5d5f7" d="M 289.774 261.1 L 470.226,261.1 C 492.782,276.88 500,284.77 500,300.55 C 500,316.33 492.782,324.22 470.226,340 L 289.774,340 C 267.218,324.22 260,316.33 260,300.55 C 260,284.77 267.218,276.88 289.774,261.1z"/>
+    <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 289.774 261.1 L 470.226,261.1 C 492.782,276.88 500,284.77 500,300.55 C 500,316.33 492.782,324.22 470.226,340 L 289.774,340 C 267.218,324.22 260,316.33 260,300.55 C 260,284.77 267.218,276.88 289.774,261.1"/>
+    <text font-size="27.0933" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="380" y="309.017">
+      <tspan x="380" y="309.017">locked</tspan>
+    </text>
+  </g>
+  <g>
+    <path style="fill: #d5d5f7" d="M 209.774 860 L 390.226,860 C 412.782,876 420,884 420,900 C 420,916 412.782,924 390.226,940 L 209.774,940 C 187.218,924 180,916 180,900 C 180,884 187.218,876 209.774,860z"/>
+    <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 209.774 860 L 390.226,860 C 412.782,876 420,884 420,900 C 420,916 412.782,924 390.226,940 L 209.774,940 C 187.218,924 180,916 180,900 C 180,884 187.218,876 209.774,860"/>
+    <text font-size="27.0933" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="300" y="908.467">
+      <tspan x="300" y="908.467">open</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #aad7aa" points="520,360 760,360 736,380 760,400 520,400 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="520,360 760,360 736,380 760,400 520,400 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:italic;font-weight:normal" x="546" y="386.35">
+      <tspan x="546" y="386.35">{button,Button}</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #ffff8f" points="140,760 460,760 460,816.8 140,816.8 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="140,760 460,760 460,816.8 140,816.8 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="174" y="782.05">
+      <tspan x="174" y="782.05">do_unlock()</tspan>
+      <tspan x="174" y="807.45">state_timeout 10 s</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #ffff8f" points="260,160 500,160 500,222.2 260,222.2 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="260,160 500,160 500,222.2 260,222.2 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="380" y="184.75">
+      <tspan x="380" y="184.75">do_lock()</tspan>
+      <tspan x="380" y="210.15">Clear Buttons</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #aad7aa" points="460,940 660,940 640,960 660,980 460,980 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="460,940 660,940 640,960 660,980 460,980 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:italic;font-weight:normal" x="560" y="966.35">
+      <tspan x="560" y="966.35">state_timeout</tspan>
+    </text>
+  </g>
+  <g>
+    <ellipse style="fill: #d5d5f7" cx="380" cy="41.1" rx="40" ry="40"/>
+    <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="380" cy="41.1" rx="40" ry="40"/>
+    <text font-size="27.0933" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="380" y="49.5667">
+      <tspan x="380" y="49.5667">init</tspan>
+    </text>
+  </g>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="380" y1="81.1" x2="380" y2="150.264"/>
+    <polygon style="fill: #000000" points="380,157.764 375,147.764 380,150.264 385,147.764 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="380,157.764 375,147.764 380,150.264 385,147.764 "/>
+  </g>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="380" y1="222.2" x2="380" y2="251.364"/>
+    <polygon style="fill: #000000" points="380,258.864 375,248.864 380,251.364 385,248.864 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="380,258.864 375,248.864 380,251.364 385,248.864 "/>
+  </g>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="300" y1="816.8" x2="300" y2="850.264"/>
+    <polygon style="fill: #000000" points="300,857.764 295,847.764 300,850.264 305,847.764 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="300,857.764 295,847.764 300,850.264 305,847.764 "/>
+  </g>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="380" y1="560" x2="380" y2="349.736"/>
+    <polygon style="fill: #000000" points="380,342.236 385,352.236 380,349.736 375,352.236 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="380,342.236 385,352.236 380,349.736 375,352.236 "/>
+  </g>
+  <g>
+    <polygon style="fill: #ffff8f" points="240,560 520,560 520,600 240,600 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="240,560 520,560 520,600 240,600 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="380" y="586.35">
+      <tspan x="380" y="586.35">state_timeout 30 s</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #aad7aa" points="40,360 240,360 220,380 240,400 40,400 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="40,360 240,360 220,380 240,400 40,400 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:italic;font-weight:normal" x="62" y="386.35">
+      <tspan x="62" y="386.35">state_timeout</tspan>
+    </text>
+  </g>
+  <g>
+    <polygon style="fill: #ffff8f" points="540,440 741.438,440 741.438,480 540,480 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="540,440 741.438,440 741.438,480 540,480 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="640.719" y="466.35">
+      <tspan x="640.719" y="466.35">Collect Buttons</tspan>
+    </text>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="640" y1="400" x2="640.719" y2="440"/>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="640.611" y1="480.995" x2="640.056" y2="589"/>
+    <polygon style="fill: #000000" points="635.057,588.974 640.005,599 645.056,589.026 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="635.057,588.974 640.005,599 645.056,589.026 "/>
+  </g>
+  <g>
+    <polygon style="fill: #ffff8f" points="40,440 240,440 240,480 40,480 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="40,440 240,440 240,480 40,480 "/>
+    <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="140" y="466.35">
+      <tspan x="140" y="466.35">Clear Buttons</tspan>
+    </text>
+  </g>
+  <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="480,640 380,640 380,600 "/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="140" y1="400" x2="140" y2="440"/>
+  <g>
+    <g>
+      <polygon style="fill: #f3cccc" points="640,600 800,640 640,680 480,640 "/>
+      <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="640,600 800,640 640,680 480,640 "/>
+      <text font-size="20.32" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="643.2" y="647.15">
+        <tspan x="643.2" y="647.15">Correct Code?</tspan>
+      </text>
+    </g>
+    <text font-size="20.32" style="fill: #000000;text-anchor:end;font-family:sans-serif;font-style:normal;font-weight:normal" x="480" y="658.9">
+      <tspan x="480" y="658.9">N</tspan>
+    </text>
+    <text font-size="20.32" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="640" y="698.9">
+      <tspan x="640" y="698.9">Y</tspan>
+    </text>
+  </g>
+  <g>
+    <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="140,480 140,516 369,516 "/>
+    <polygon style="fill: #000000" points="369,521 379,516 369,511 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="369,521 379,516 369,511 "/>
+  </g>
+</svg>
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index 5be2981f62..80ee9c992f 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -36,16 +36,6 @@
     manual page in STDLIB, where all interface functions and callback
     functions are described in detail.
   </p>
-  <note>
-    <p>
-      This is a new behavior in Erlang/OTP 19.0.
-      It has been thoroughly reviewed, is stable enough
-      to be used by at least two heavy OTP applications, and is here to stay.
-      Depending on user feedback, we do not expect
-      but can find it necessary to make minor
-      not backward compatible changes into Erlang/OTP 20.0.
-    </p>
-  </note>
 
 <!-- =================================================================== -->
 
@@ -72,13 +62,14 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
     <p>These relations are interpreted as follows:
       if we are in state <c>S</c> and event <c>E</c> occurs, we
       are to perform actions <c>A</c> and make a transition to
-      state <c>S'</c>. Notice that <c>S'</c> can be equal to <c>S</c>.
+      state <c>S'</c>. Notice that <c>S'</c> can be equal to <c>S</c>
+      and that <c>A</c> can be empty.
     </p>
     <p>
       As <c>A</c> and <c>S'</c> depend only on
       <c>S</c> and <c>E</c>, the kind of state machine described
-      here is a Mealy Machine
-      (see, for example, the corresponding Wikipedia article).
+      here is a Mealy machine
+      (see, for example, the Wikipedia article "Mealy machine").
     </p>
     <p>
       Like most <c>gen_</c> behaviors, <c>gen_statem</c> keeps
@@ -88,7 +79,95 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       or on the number of distinct input events,
       a state machine implemented with this behavior
       is in fact Turing complete.
-      But it feels mostly like an Event-Driven Mealy Machine.
+      But it feels mostly like an Event-Driven Mealy machine.
+    </p>
+  </section>
+
+<!-- =================================================================== -->
+
+  <section>
+    <marker id="When to use gen_statem" />
+    <title>When to use gen_statem</title>
+    <p>
+      If your process logic is convenient to describe as a state machine,
+      and you want any of these <c>gen_statem</c> key features:
+    </p>
+    <list type="bulleted">
+      <item>
+	Co-located callback code for each state,
+	regardless of
+	<seealso marker="#Event Types">Event Type</seealso>
+	(such as <em>call</em>, <em>cast</em> and <em>info</em>)
+      </item>
+      <item>
+	<seealso marker="#Postponing Events">
+	  Postponing Events
+	</seealso>
+	(a substitute for selective receive)
+      </item>
+      <item>
+	<seealso marker="#Inserted Events">
+	  Inserted Events
+	</seealso>
+	that is: events from the state machine to itself
+	(in particular purely internal events)
+      </item>
+      <item>
+	<seealso marker="#State Enter Calls">
+	  State Enter Calls
+	</seealso>
+	(callback on state entry co-located with the rest
+	of each state's callback code)
+      </item>
+      <item>
+	Easy-to-use timeouts
+	(<seealso marker="#State Time-Outs">State Time-Outs</seealso>,
+	<seealso marker="#Event Time-Outs">Event Time-Outs</seealso>
+	and
+	<seealso marker="#Generic Time-Outs">Generic Time-outs</seealso>
+	(named time-outs))
+      </item>
+    </list>
+    <p>
+      If so, or if possibly needed in future versions,
+      then you should consider using <c>gen_statem</c> over
+      <seealso marker="stdlib:gen_server"><c>gen_server</c></seealso>.
+    </p>
+    <p>
+      For simple state machines not needing these features
+      <seealso marker="stdlib:gen_server"><c>gen_server</c></seealso>
+      works just fine.
+      It also has got smaller call overhead,
+      but we are talking about something like 2 vs 3.3 microseconds
+      call roundtrip time here, so if the server callback
+      does just a little bit more than just replying,
+      or if the call is not extremely frequent,
+      that difference will be hard to notice.
+    </p>
+  </section>
+
+<!-- =================================================================== -->
+
+  <section>
+    <marker id="Callback Module" />
+    <title>Callback Module</title>
+    <p>
+      The callback module contains functions that implement
+      the state machine.
+      When an event occurs,
+      the <c>gen_statem</c> behaviour engine
+      calls a function in the callback module with the event,
+      current state and server data.
+      This function performs the actions for this event,
+      and returns the new state and server data
+      and also actions to be performed by the behaviour engine.
+    </p>
+    <p>
+      The behaviour engine holds the state machine state,
+      server data, timer references, a queue of posponed messages
+      and other metadata.  It receives all process messages,
+      handles the system messages, and calls the callback module
+      with machine specific events.
     </p>
   </section>
 
@@ -100,61 +179,72 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
     <p>
       The <c>gen_statem</c> behavior supports two callback modes:
     </p>
-    <list type="bulleted">
+    <taglist>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-callback_mode">
+	  <c>state_functions</c>
+	</seealso>
+      </tag>
       <item>
         <p>
-          In mode
-	  <seealso marker="stdlib:gen_statem#type-callback_mode"><c>state_functions</c></seealso>,
-          the state transition rules are written as some Erlang
-          functions, which conform to the following convention:
-        </p>
-        <pre>
-StateName(EventType, EventContent, Data) ->
-    ... code for actions here ...
-    {next_state, NewStateName, NewData}.
-	</pre>
-	<p>
-	  This form is used in most examples here for example in section
-	  <seealso marker="#Example">Example</seealso>.
+	  Events are handled by one callback function per state.
 	</p>
       </item>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-callback_mode">
+	  <c>handle_event_function</c>
+	  </seealso>
+      </tag>
       <item>
         <p>
-          In mode
-	  <seealso marker="stdlib:gen_statem#type-callback_mode"><c>handle_event_function</c></seealso>,
-          only one Erlang function provides all state transition rules:
-        </p>
-        <pre>
-handle_event(EventType, EventContent, State, Data) ->
-    ... code for actions here ...
-    {next_state, NewState, NewData}
-	</pre>
-	<p>
-	  See section
-	  <seealso marker="#One Event Handler">One Event Handler</seealso>
-	  for an example.
+	  Events are handled by one single callback function.
 	</p>
       </item>
-    </list>
+    </taglist>
     <p>
-      Both these modes allow other return tuples; see
-      <seealso marker="stdlib:gen_statem#Module:StateName/3"><c>Module:StateName/3</c></seealso>
-      in the <c>gen_statem</c> manual page.
-      These other return tuples can, for example, stop the machine,
-      execute state transition actions on the machine engine itself,
-      and send replies.
+      The callback mode is selected at server start
+      and may be changed with a code upgrade/downgrade.
+    </p>
+    <p>
+      See the section
+      <seealso marker="#Event Handler">Event Handler</seealso>
+      that describes the event handling callback function(s).
+    </p>
+    <p>
+      The callback mode is selected by implementing
+      a mandatory callback function
+      <seealso marker="stdlib:gen_statem#Module:callback_mode/0">
+	<c>Module:callback_mode()</c>
+      </seealso>
+      that returns one of the callback modes.
+    </p>
+    <p>
+      The
+      <seealso marker="stdlib:gen_statem#Module:callback_mode/0">
+	<c>Module:callback_mode()</c>
+      </seealso>
+      function may also return a list containing the callback mode
+      and the atom <c>state_enter</c> in which case
+      <seealso marker="#State Enter Calls">State Enter Calls</seealso>
+      are activated for the callback mode.
     </p>
 
     <section>
       <marker id="Choosing the Callback Mode" />
       <title>Choosing the Callback Mode</title>
       <p>
+	The short version: choose <c>state_functions</c> -
+	it is the one most like <c>gen_fsm</c>.
+	But if you do not want the restriction that the state
+	must be an atom, or if you do not want to write
+	one event handler function per state; please read on...
+      </p>
+      <p>
 	The two
-	<seealso marker="#Callback Modes">callback modes</seealso>
-	give different possibilities
-	and restrictions, but one goal remains:
-	you want to handle all possible combinations of
-	events and states.
+	<seealso marker="#Callback Modes">Callback Modes</seealso>
+	give different possibilities and restrictions,
+	with one common goal:
+	to handle all possible combinations of events and states.
       </p>
       <p>
 	This can be done, for example, by focusing on one state at the time
@@ -167,7 +257,7 @@ handle_event(EventType, EventContent, State, Data) ->
 	With <c>state_functions</c>, you are restricted to use
 	atom-only states, and the <c>gen_statem</c> engine
 	branches depending on state name for you.
-	This encourages the callback module to gather
+	This encourages the callback module to co-locate
 	the implementation of all event actions particular
 	to one state in the same place in the code,
 	hence to focus on one state at the time.
@@ -186,13 +276,17 @@ handle_event(EventType, EventContent, State, Data) ->
 	This mode works equally well when you want to focus on
 	one event at the time or on
 	one state at the time, but function
-	<seealso marker="stdlib:gen_statem#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>
+	<seealso marker="stdlib:gen_statem#Module:handle_event/4">
+	  <c>Module:handle_event/4</c>
+	</seealso>
 	quickly grows too large to handle without branching to
 	helper functions.
       </p>
       <p>
 	The mode enables the use of non-atom states, for example,
 	complex states or even hierarchical states.
+	See section
+	<seealso marker="#Complex State">Complex State</seealso>.
 	If, for example, a state diagram is largely alike
 	for the client side and the server side of a protocol,
 	you can have a state <c>{StateName,server}</c> or
@@ -208,43 +302,180 @@ handle_event(EventType, EventContent, State, Data) ->
 <!-- =================================================================== -->
 
   <section>
-    <marker id="State Enter Calls" />
-    <title>State Enter Calls</title>
+    <marker id="Event Handler" />
+    <title>Event Handler</title>
     <p>
-      The <c>gen_statem</c> behavior can regardless of callback mode
-      automatically
-      <seealso marker="stdlib:gen_statem#type-state_enter">
-	call the state callback
-      </seealso>
-      with special arguments whenever the state changes
-      so you can write state entry actions
-      near the rest of the state transition rules.
-      It typically looks like this:
+      Which callback function that handles an event
+      depends on the callback mode:
     </p>
-    <pre>
-StateName(enter, _OldState, Data) ->
-    ... code for state entry actions here ...
-    {keep_state, NewData};
-StateName(EventType, EventContent, Data) ->
-    ... code for actions here ...
-    {next_state, NewStateName, NewData}.</pre>
+    <taglist>
+      <tag><c>state_functions</c></tag>
+      <item>
+	The event is handled by:<br />
+	<seealso marker="stdlib:gen_statem#Module:StateName/3">
+	  <c>Module:StateName(EventType, EventContent, Data)</c>
+	</seealso>
+	<p>
+	  This form is the one mostly used in the
+	  <seealso marker="#Example">Example</seealso>
+	  section.
+	</p>
+      </item>
+      <tag><c>handle_event_function</c></tag>
+      <item>
+	The event is handled by:<br />
+	<seealso marker="stdlib:gen_statem#Module:handle_event/4">
+	  <c>Module:handle_event(EventType, EventContent, State, Data)</c>
+	</seealso>
+	<p>
+	  See section
+	  <seealso marker="#One Event Handler">One Event Handler</seealso>
+	  for an example.
+	</p>
+      </item>
+    </taglist>
     <p>
-      Depending on how your state machine is specified,
-      this can be a very useful feature,
-      but it forces you to handle the state enter calls in all states.
-      See also the
-      <seealso marker="#State Entry Actions">
-	State Entry Actions
+      The state is either the name of the function itself or an argument to it.
+      The other arguments are the <c>EventType</c> described in section
+      <seealso marker="#Event Types">Event Types</seealso>,
+      the event dependent <c>EventContent</c>, and the current server <c>Data</c>.
+    </p>
+    <p>
+      State enter calls are also handled by the event handler and have
+      slightly different arguments. See the section
+      <seealso marker="#State Enter Calls">State Enter Calls</seealso>.
+    </p>
+    <p>
+      The event handler return values are defined in the description of
+      <seealso marker="stdlib:gen_statem#Module:StateName/3">
+	<c>Module:StateName/3</c>
       </seealso>
-      chapter.
+      in the <c>gen_statem</c> manual page, but here is
+      a more readable list:
     </p>
+    <taglist>
+      <tag>
+	<c>{next_state, NextState, NewData, Actions}</c><br />
+	<c>{next_state, NextState, NewData}</c>
+      </tag>
+      <item>
+	<p>
+	  Set next state and update the server data.
+	  If the <c>Actions</c> field is used, execute state transition actions.
+	  An empty <c>Actions</c> list is equivalent to not returning the field.
+	</p>
+	<p>
+	  See section
+	  <seealso marker="#State Transition Actions">
+	    State Transition Actions
+	  </seealso>
+	  for a list of possible
+	  state transition actions.
+	</p>
+	<p>
+	  If <c>NextState =/= State</c> the state machine changes
+	  to a new state.  A
+	  <seealso marker="#State Enter Calls">state enter call</seealso>
+	  is performed if enabled and all
+	  <seealso marker="#Postponing Events">postponed events</seealso>
+	  are retried.
+	</p>
+      </item>
+      <tag>
+	<c>{keep_state, NewData, Actions}</c><br />
+	<c>{keep_state, NewData}</c>
+      </tag>
+      <item>
+	<p>
+	  Same as the <c>next_state</c> values with
+	  <c>NextState =:= State</c>, that is, no state change.
+	</p>
+      </item>
+      <tag>
+	<c>{keep_state_and_data, Actions}</c><br />
+	<c>keep_state_and_data</c>
+      </tag>
+      <item>
+	<p>
+	  Same as the <c>keep_state</c> values with
+	  <c>NextData =:= Data</c>, that is, no change in server data.
+	</p>
+      </item>
+      <tag>
+	<c>{repeat_state, NewData, Actions}</c><br />
+	<c>{repeat_state, NewData}</c><br />
+	<c>{repeat_state_and_data, Actions}</c><br />
+	<c>repeat_state_and_data</c>
+      </tag>
+      <item>
+	<p>
+	  Same as the <c>keep_state</c> or <c>keep_state_and_data</c> values,
+	  and if
+	  <seealso marker="#State Enter Calls">
+	    State Enter Calls
+	  </seealso>
+	  are enabled, repeat the state enter call
+	  as if this state was entered again.
+	</p>
+      </item>
+      <tag>
+	<c>{stop, Reason, NewData}</c><br />
+	<c>{stop, Reason}</c>
+      </tag>
+      <item>
+	<p>
+	  Stop the server with reason <c>Reason</c>.
+	  If the <c>NewData</c> field is used, first update the server data.
+	</p>
+      </item>
+      <tag>
+	<c>{stop_and_reply, Reason, NewData, ReplyActions}</c><br />
+	<c>{stop_and_reply, Reason, ReplyActions}</c>
+      </tag>
+      <item>
+	<p>
+	  Same as the <c>stop</c> values, but first execute the given
+	  state transition actions that may only be reply actions.
+	</p>
+      </item>
+    </taglist>
+
+    <section>
+      <marker id="The First State" />
+      <title>The First State</title>
+      <p>
+	To decide the first state the
+	<seealso marker="stdlib:gen_statem#Module:init/1">
+	  <c>Module:init(Args)</c>
+	</seealso>
+	callback function is called before any
+	<seealso marker="#Event Handler">Event Handler</seealso>
+	is called.  This function behaves like an event handler
+	function, but gets its only argument <c>Args</c> from 
+	the <c>gen_statem</c>
+	<seealso marker="stdlib:gen_statem#start/3">
+	  <c>start/3,4</c>
+	</seealso>
+	or
+	<seealso marker="stdlib:gen_statem#start_link/3">
+	  <c>start_link/3,4</c>
+	</seealso>
+	function, and returns <c>{ok, State, Data}</c>
+	or <c>{ok, State, Data, Actions}</c>.
+	If you use the
+	<seealso marker="#Postponing Events"><c>postpone</c></seealso>
+	action from this function, that action is ignored,
+	since there is no event	to postpone.
+      </p>
+    </section>
+
   </section>
 
 <!-- =================================================================== -->
 
   <section>
-    <marker id="Actions" />
-    <title>Actions</title>
+    <marker id="State Transition Actions" />
+    <title>State Transition Actions</title>
     <p>
       In the first section
       <seealso marker="#Event-Driven State Machines">
@@ -259,77 +490,102 @@ StateName(EventType, EventContent, Data) ->
     </p>
     <p>
       There are more specific state-transition actions
-      that a callback function can order the <c>gen_statem</c>
+      that a callback function can command the <c>gen_statem</c>
       engine to do after the callback function return.
-      These are ordered by returning a list of
+      These are commanded by returning a list of
       <seealso marker="stdlib:gen_statem#type-action">actions</seealso>
       in the
-      <seealso marker="stdlib:gen_statem#type-state_callback_result">return tuple</seealso>
+      <seealso marker="stdlib:gen_statem#type-state_callback_result">
+	return value
+      </seealso>
       from the
       <seealso marker="stdlib:gen_statem#Module:StateName/3">callback function</seealso>.
-      These state transition actions affect the <c>gen_statem</c>
-      engine itself and can do the following:
+      These are the possible state transition actions:
     </p>
-    <list type="bulleted">
-      <item>
+    <taglist>
+      <tag>
 	<seealso marker="stdlib:gen_statem#type-postpone">
-	  Postpone
+	  <c>postpone</c>
 	</seealso>
-	the current event, see section
+	<br />
+	<c>{postpone, Boolean}</c>
+      </tag>
+      <item>
+	If set postpone the current event, see section
 	<seealso marker="#Postponing Events">Postponing Events</seealso>
       </item>
-      <item>
+      <tag>
 	<seealso marker="stdlib:gen_statem#type-hibernate">
-	  Hibernate
+	  <c>hibernate</c>
 	</seealso>
-	the <c>gen_statem</c>, treated in
+	<br />
+	<c>{hibernate, Boolean}</c>
+      </tag>
+      <item>
+	If set hibernate the <c>gen_statem</c>, treated in section
 	<seealso marker="#Hibernation">Hibernation</seealso>
       </item>
-      <item>
-	Start a
+      <tag>
 	<seealso marker="stdlib:gen_statem#type-state_timeout">
-	  state time-out</seealso>,
-	  read more in section
+	  <c>{state_timeout, Time}</c>
+	</seealso>
+	<br />
+	<c>{state_timeout, Time, Opts}</c>
+      </tag>
+      <item>
+	Start a state time-out, read more in section
 	<seealso marker="#State Time-Outs">State Time-Outs</seealso>
       </item>
-      <item>
-	Start a
+      <tag>
 	<seealso marker="stdlib:gen_statem#type-generic_timeout">
-	  generic time-out</seealso>,
-	  read more in section
+	  <c>{{timeout, Name}, Time}</c>
+	</seealso>
+	<br />
+	<c>{{timeout, Name}, Time, Opts}</c>
+      </tag>
+      <item>
+	Start a generic time-out, read more in section
 	<seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>
       </item>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-event_timeout">
+	  <c>{timeout, Time}</c>
+	</seealso>
+	<br />
+	<c>{timeout, Time, Opts}</c><br />
+	<c>Time</c>
+      </tag>
       <item>
-	Start an
-	<seealso marker="stdlib:gen_statem#type-event_timeout">event time-out</seealso>,
-	see more in section
+	Start an event time-out, see more in section
 	<seealso marker="#Event Time-Outs">Event Time-Outs</seealso>
       </item>
-      <item>
+      <tag>
 	<seealso marker="stdlib:gen_statem#type-reply_action">
-	  Reply
+	  <c>{reply, From, Reply}</c>
 	</seealso>
-	to a caller, mentioned at the end of section
+      </tag>
+      <item>
+	Reply to a caller, mentioned at the end of section
 	<seealso marker="#All State Events">All State Events</seealso>
       </item>
-      <item>
-	Generate the
+      <tag>
 	<seealso marker="stdlib:gen_statem#type-action">
-	  next event
+	  <c>{next_event, EventType, EventContent}</c>
 	</seealso>
-	to handle, see section 
-	<seealso marker="#Self-Generated Events">Self-Generated Events</seealso>
+      </tag>
+      <item>
+	Generate the next event to handle, see section 
+	<seealso marker="#Inserted Events">Inserted Events</seealso>
       </item>
-    </list>
+    </taglist>
     <p>
-      For details, see the
-      <seealso marker="stdlib:gen_statem#type-action">
-	<c>gen_statem(3)</c>
-      </seealso>
-      manual page.
+      For details, see the <c>gen_statem(3)</c>
+      manual page for type
+      <seealso marker="stdlib:gen_statem#type-action"><c>action()</c></seealso>.
       You can, for example, reply to many callers,
       generate multiple next events,
-      and set time-outs to relative or absolute times.
+      and set a time-out to use absolute instead of relative time
+      (using the <c>Opts</c> field).
     </p>
   </section>
 
@@ -341,8 +597,8 @@ StateName(EventType, EventContent, Data) ->
     <p>
       Events are categorized in different
       <seealso marker="stdlib:gen_statem#type-event_type">event types</seealso>.
-      Events of all types are handled in the same callback function,
-      for a given state, and the function gets
+      Events of all types are for a given state
+      handled in the same callback function, and that function gets
       <c>EventType</c> and <c>EventContent</c> as arguments.
     </p>
     <p>
@@ -350,12 +606,20 @@ StateName(EventType, EventContent, Data) ->
       they come from:
     </p>
     <taglist>
-      <tag><c>cast</c></tag>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-external_event_type">
+	  <c>cast</c>
+	</seealso>
+      </tag>
       <item>
 	Generated by
 	<seealso marker="stdlib:gen_statem#cast/2"><c>gen_statem:cast</c></seealso>.
       </item>
-      <tag><c>{call,From}</c></tag>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-external_event_type">
+	  <c>{call,From}</c>
+	</seealso>
+      </tag>
       <item>
 	Generated by
 	<seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call</c></seealso>,
@@ -364,12 +628,20 @@ StateName(EventType, EventContent, Data) ->
 	<c>{reply,From,Msg}</c> or by calling
 	<seealso marker="stdlib:gen_statem#reply/1"><c>gen_statem:reply</c></seealso>.
       </item>
-      <tag><c>info</c></tag>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-external_event_type">
+	  <c>info</c>
+	</seealso>
+      </tag>
       <item>
 	Generated by any regular process message sent to
 	the <c>gen_statem</c> process.
       </item>
-      <tag><c>state_timeout</c></tag>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-timeout_event_type">
+	  <c>state_timeout</c>
+	</seealso>
+      </tag>
       <item>
 	Generated by state transition action
 	<seealso marker="stdlib:gen_statem#type-state_timeout">
@@ -377,7 +649,11 @@ StateName(EventType, EventContent, Data) ->
 	</seealso>
 	state timer timing out.
       </item>
-      <tag><c>{timeout,Name}</c></tag>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-timeout_event_type">
+	  <c>{timeout,Name}</c>
+	</seealso>
+      </tag>
       <item>
 	Generated by state transition action
 	<seealso marker="stdlib:gen_statem#type-generic_timeout">
@@ -385,7 +661,11 @@ StateName(EventType, EventContent, Data) ->
 	</seealso>
 	generic timer timing out.
       </item>
-      <tag><c>timeout</c></tag>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-timeout_event_type">
+	  <c>timeout</c>
+	</seealso>
+      </tag>
       <item>
 	Generated by state transition action
 	<seealso marker="stdlib:gen_statem#type-event_timeout">
@@ -394,7 +674,11 @@ StateName(EventType, EventContent, Data) ->
 	(or its short form <c>Time</c>)
 	event timer timing out.
       </item>
-      <tag><c>internal</c></tag>
+      <tag>
+	<seealso marker="stdlib:gen_statem#type-event_type">
+	  <c>internal</c>
+	</seealso>
+      </tag>
       <item>
 	Generated by state transition
 	<seealso marker="stdlib:gen_statem#type-action">action</seealso>
@@ -408,19 +692,75 @@ StateName(EventType, EventContent, Data) ->
 <!-- =================================================================== -->
 
   <section>
+    <marker id="State Enter Calls" />
+    <title>State Enter Calls</title>
+    <p>
+      The <c>gen_statem</c> behavior can if this is enabled,
+      regardless of callback mode,
+      automatically
+      <seealso marker="stdlib:gen_statem#type-state_enter">
+	call the state callback
+      </seealso>
+      with special arguments whenever the state changes
+      so you can write state enter actions
+      near the rest of the state transition rules.
+      It typically looks like this:
+    </p>
+    <pre>
+StateName(enter, OldState, Data) ->
+    ... code for state enter actions here ...
+    {keep_state, NewData};
+StateName(EventType, EventContent, Data) ->
+    ... code for actions here ...
+    {next_state, NewStateName, NewData}.</pre>
+    <p>
+      Since the state enter call is not an event there are restrictions
+      on the allowed return value and
+      <seealso marker="#State Transition Actions">State Transition Actions</seealso>.
+      You may not change the state,
+      <seealso marker="#Postponing Events">postpone</seealso>
+      this non-event, or
+      <seealso marker="#Inserted Events">insert events</seealso>.
+    </p>
+    <p>
+      The first state that is entered will get a state enter call
+      with <c>OldState</c> equal to the current state.
+    </p>
+    <p>
+      You may repeat the state enter call using the <c>{repeat_state,...}</c>
+      return value from the 
+      <seealso marker="#Event Handler">Event Handler</seealso>.
+      In this case <c>OldState</c> will also be equal to the current state.
+    </p>
+    <p>
+      Depending on how your state machine is specified,
+      this can be a very useful feature,
+      but it forces you to handle the state enter calls in all states.
+      See also the
+      <seealso marker="#State Enter Actions">
+	State Enter Actions
+      </seealso>
+      chapter.
+    </p>
+  </section>
+
+<!-- =================================================================== -->
+
+  <section>
     <marker id="Example" />
     <title>Example</title>
     <p>
       A door with a code lock can be seen as a state machine.
       Initially, the door is locked. When someone presses a button,
       an event is generated.
-      Depending on what buttons have been pressed before,
-      the sequence so far can be correct, incomplete, or wrong.
-      If correct, the door is unlocked for 10 seconds (10,000 milliseconds).
-      If incomplete, we wait for another button to be pressed. If
-      wrong, we start all over, waiting for a new button sequence.
-    </p>
-    <image file="../design_principles/code_lock.png">
+      The pressed buttons are collected, up to the number of buttons
+      in the correct code.
+      If correct, the door is unlocked for 10 seconds.
+      If not correct, we wait for a new button to be pressed.
+    </p>
+    <!-- The image is edited with dia in a .dia file,
+	 then exported to Scalable Vector Graphics. -->
+    <image file="../design_principles/code_lock.svg" width="80%">
       <icaption>Code Lock State Diagram</icaption>
     </image>
     <p>
@@ -434,43 +774,51 @@ StateName(EventType, EventContent, Data) ->
 
 -export([start_link/1]).
 -export([button/1]).
--export([init/1,callback_mode/0,terminate/3,code_change/4]).
+-export([init/1,callback_mode/0,terminate/3]).
 -export([locked/3,open/3]).
 
 start_link(Code) ->
     gen_statem:start_link({local,?NAME}, ?MODULE, Code, []).
 
-button(Digit) ->
-    gen_statem:cast(?NAME, {button,Digit}).
+button(Button) ->
+    gen_statem:cast(?NAME, {button,Button}).
 
 init(Code) ->
     do_lock(),
-    Data = #{code => Code, remaining => Code},
+    Data = #{code => Code, length => length(Code), buttons => []},
     {ok, locked, Data}.
 
 callback_mode() ->
     state_functions.
-
+    ]]></code>
+    <code type="erl"><![CDATA[
 locked(
-  cast, {button,Digit},
-  #{code := Code, remaining := Remaining} = Data) ->
-    case Remaining of
-        [Digit] ->
+  cast, {button,Button},
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
+    NewButtons =
+        if
+            length(Buttons) < Length ->
+                Buttons;
+            true ->
+                tl(Buttons)
+        end ++ [Button],
+    if
+        NewButtons =:= Code -> % Correct
 	    do_unlock(),
-            {next_state, open, Data#{remaining := Code},
-             [{state_timeout,10000,lock}]};
-        [Digit|Rest] -> % Incomplete
-            {next_state, locked, Data#{remaining := Rest}};
-        _Wrong ->
-            {next_state, locked, Data#{remaining := Code}}
+            {next_state, open, Data#{buttons := []},
+             [{state_timeout,10000,lock}]}; % Time in milliseconds
+	true -> % Incomplete | Incorrect
+            {next_state, locked, Data#{buttons := NewButtons}}
     end.
-
+    ]]></code>
+    <code type="erl"><![CDATA[
 open(state_timeout, lock,  Data) ->
     do_lock(),
     {next_state, locked, Data};
 open(cast, {button,_}, Data) ->
     {next_state, open, Data}.
-
+    ]]></code>
+    <code type="erl"><![CDATA[
 do_lock() ->
     io:format("Lock~n", []).
 do_unlock() ->
@@ -479,8 +827,6 @@ do_unlock() ->
 terminate(_Reason, State, _Data) ->
     State =/= locked andalso do_lock(),
     ok.
-code_change(_Vsn, State, Data, _Extra) ->
-    {ok, State, Data}.
     ]]></code>
     <p>The code is explained in the next sections.</p>
   </section>
@@ -556,17 +902,17 @@ start_link(Code) ->
       in this case <c>locked</c>; assuming that the door is locked to begin
       with. <c>Data</c> is the internal server data of the <c>gen_statem</c>.
       Here the server data is a <seealso marker="stdlib:maps">map</seealso>
-      with key <c>code</c> that stores
-      the correct button sequence, and key <c>remaining</c>
-      that stores the remaining correct button sequence
-      (the same as the <c>code</c> to begin with).
+      with key <c>code</c> that stores the correct button sequence,
+      key <c>length</c> store its length,
+      and key <c>buttons</c> that stores the collected buttons
+      up to the same length.
     </p>
 
     <code type="erl"><![CDATA[
 init(Code) ->
     do_lock(),
-    Data = #{code => Code, remaining => Code},
-    {ok,locked,Data}.
+    Data = #{code => Code, length => length(Code), buttons => []},
+    {ok, locked, Data}.
     ]]></code>
     <p>Function
       <seealso marker="stdlib:gen_statem#start_link/3"><c>gen_statem:start_link</c></seealso>
@@ -584,10 +930,6 @@ init(Code) ->
       a <c>gen_statem</c> that is not part of a supervision tree.
     </p>
 
-    <code type="erl"><![CDATA[
-callback_mode() ->
-    state_functions.
-    ]]></code>
     <p>
       Function
       <seealso marker="stdlib:gen_statem#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>
@@ -595,8 +937,12 @@ callback_mode() ->
       <seealso marker="#Callback Modes"><c>CallbackMode</c></seealso>
       for the callback module, in this case
       <seealso marker="stdlib:gen_statem#type-callback_mode"><c>state_functions</c></seealso>.
-      That is, each state has got its own handler function.
+      That is, each state has got its own handler function:
     </p>
+    <code type="erl"><![CDATA[
+callback_mode() ->
+    state_functions.
+    ]]></code>
 
   </section>
 
@@ -620,7 +966,7 @@ button(Digit) ->
       <c>{button,Digit}</c> is the event content.
     </p>
     <p>
-      The event is made into a message and sent to the <c>gen_statem</c>.
+      The event is sent to the <c>gen_statem</c>.
       When the event is received, the <c>gen_statem</c> calls
       <c>StateName(cast, Event, Data)</c>, which is expected to
       return a tuple <c>{next_state, NewStateName, NewData}</c>,
@@ -629,44 +975,48 @@ button(Digit) ->
       <c>NewStateName</c> is the name of the next state to go to.
       <c>NewData</c> is a new value for the server data of
       the <c>gen_statem</c>, and <c>Actions</c> is a list of
-      actions on the <c>gen_statem</c> engine.
+      actions to be performed by the <c>gen_statem</c> engine.
     </p>
+
     <code type="erl"><![CDATA[
 locked(
-  cast, {button,Digit},
-  #{code := Code, remaining := Remaining} = Data) ->
-    case Remaining of
-        [Digit] -> % Complete
+  cast, {button,Button},
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
+    NewButtons =
+        if
+            length(Buttons) < Length ->
+                Buttons;
+            true ->
+                tl(Buttons)
+        end ++ [Button],
+    if
+        NewButtons =:= Code -> % Correct
 	    do_unlock(),
-            {next_state, open, Data#{remaining := Code},
-             [{state_timeout,10000,lock}]};
-        [Digit|Rest] -> % Incomplete
-            {next_state, locked, Data#{remaining := Rest}};
-        [_|_] -> % Wrong
-            {next_state, locked, Data#{remaining := Code}}
+            {next_state, open, Data#{buttons := []},
+             [{state_timeout,10000,lock}]}; % Time in milliseconds
+	true -> % Incomplete | Incorrect
+            {next_state, locked, Data#{buttons := NewButtons}}
     end.
-
-open(state_timeout, lock, Data) ->
-    do_lock(),
-    {next_state, locked, Data};
-open(cast, {button,_}, Data) ->
-    {next_state, open, Data}.
     ]]></code>
     <p>
-      If the door is locked and a button is pressed, the pressed
-      button is compared with the next correct button.
+      In state <c>locked</c>, when a button is pressed,
+      it is collected with the last pressed buttons
+      up to the length of the correct code,
+      and compared with the correct code.
       Depending on the result, the door is either unlocked
       and the <c>gen_statem</c> goes to state <c>open</c>,
       or the door remains in state <c>locked</c>.
     </p>
     <p>
-      If the pressed button is incorrect, the server data
-      restarts from the start of the code sequence.
-    </p>
-    <p>
-      If the whole code is correct, the server changes states
-      to <c>open</c>.
+      When changing to state <c>open</c>, the collected
+      buttons are reset, the lock unlocked, and a state timer
+      for 10 s is started.
     </p>
+
+    <code type="erl"><![CDATA[
+open(cast, {button,_}, Data) ->
+    {next_state, open, Data}.
+    ]]></code>
     <p>
       In state <c>open</c>, a button event is ignored
       by staying in the same state.  This can also be done
@@ -684,9 +1034,9 @@ open(cast, {button,_}, Data) ->
       the following tuple is returned from <c>locked/2</c>:
     </p>
     <code type="erl"><![CDATA[
-{next_state, open, Data#{remaining := Code},
- [{state_timeout,10000,lock}]};
-    ]]></code>
+{next_state, open, Data#{buttons := []},
+ [{state_timeout,10000,lock}]}; % Time in milliseconds
+ ]]></code>
     <p>
       10,000 is a time-out value in milliseconds.
       After this time (10 seconds), a time-out occurs.
@@ -721,10 +1071,9 @@ open(state_timeout, lock,  Data) ->
     </p>
     <p>
       Consider a <c>code_length/0</c> function that returns
-      the length of the correct code
-      (that should not be sensitive to reveal).
+      the length of the correct code.
       We dispatch all events that are not state-specific
-      to the common function <c>handle_event/3</c>:
+      to the common function <c>handle_common/3</c>:
     </p>
     <code type="erl"><![CDATA[
 ...
@@ -737,16 +1086,46 @@ code_length() ->
 ...
 locked(...) -> ... ;
 locked(EventType, EventContent, Data) ->
-    handle_event(EventType, EventContent, Data).
+    handle_common(EventType, EventContent, Data).
 
 ...
 open(...) -> ... ;
 open(EventType, EventContent, Data) ->
-    handle_event(EventType, EventContent, Data).
+    handle_common(EventType, EventContent, Data).
 
-handle_event({call,From}, code_length, #{code := Code} = Data) ->
-    {keep_state, Data, [{reply,From,length(Code)}]}.
+handle_common({call,From}, code_length, #{code := Code} = Data) ->
+    {keep_state, Data,
+     [{reply,From,length(Code)}]}.
     ]]></code>
+
+    <p>
+      Another way to do it is through a convenience macro
+      <c>?HANDLE_COMMON/0</c>:
+    </p>
+    <code type="erl"><![CDATA[
+...
+-export([button/1,code_length/0]).
+...
+
+code_length() ->
+    gen_statem:call(?NAME, code_length).
+
+-define(HANDLE_COMMON,
+    ?FUNCTION_NAME(T, C, D) -> handle_common(T, C, D)).
+%%
+handle_common({call,From}, code_length, #{code := Code} = Data) ->
+    {keep_state, Data,
+     [{reply,From,length(Code)}]}.
+
+...
+locked(...) -> ... ;
+?HANDLE_COMMON.
+
+...
+open(...) -> ... ;
+?HANDLE_COMMON.
+]]></code>
+
     <p>
       This example uses
       <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call/2</c></seealso>,
@@ -757,6 +1136,14 @@ handle_event({call,From}, code_length, #{code := Code} = Data) ->
       when you want to stay in the current state but do not know or
       care about what it is.
     </p>
+    <p>
+      If the common event handler needs to know the current state
+      a function <c>handle_common/4</c> can be used instead:
+    </p>
+    <code type="erl"><![CDATA[
+-define(HANDLE_COMMON,
+    ?FUNCTION_NAME(T, C, D) -> handle_common(T, C, ?FUNCTION_NAME, D)).
+    ]]></code>
   </section>
 
 <!-- =================================================================== -->
@@ -765,7 +1152,11 @@ handle_event({call,From}, code_length, #{code := Code} = Data) ->
     <marker id="One Event Handler" />
     <title>One Event Handler</title>
     <p>
-      If mode <c>handle_event_function</c> is used,
+      If
+      <seealso marker="#Callback Modes">
+	Callback Mode
+      </seealso>
+      <c>handle_event_function</c> is used,
       all events are handled in
       <seealso marker="stdlib:gen_statem#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>
       and we can (but do not have to) use an event-centered approach
@@ -783,25 +1174,35 @@ callback_mode() ->
 handle_event(cast, {button,Digit}, State, #{code := Code} = Data) ->
     case State of
 	locked ->
-	    case maps:get(remaining, Data) of
-		[Digit] -> % Complete
-		    do_unlock(),
-		    {next_state, open, Data#{remaining := Code},
-                     [{state_timeout,10000,lock}]};
-		[Digit|Rest] -> % Incomplete
-		    {keep_state, Data#{remaining := Rest}};
-		[_|_] -> % Wrong
-		    {keep_state, Data#{remaining := Code}}
-	    end;
+            #{length := Length, buttons := Buttons} = Data,
+            NewButtons =
+                if
+                    length(Buttons) < Length ->
+                        Buttons;
+                    true ->
+                        tl(Buttons)
+                end ++ [Button],
+            if
+                NewButtons =:= Code -> % Correct
+                    do_unlock(),
+                    {next_state, open, Data#{buttons := []},
+                     [{state_timeout,10000,lock}]}; % Time in milliseconds
+                true -> % Incomplete | Incorrect
+                    {keep_state, Data#{buttons := NewButtons}}
+            end;
 	open ->
             keep_state_and_data
     end;
 handle_event(state_timeout, lock, open, Data) ->
     do_lock(),
-    {next_state, locked, Data}.
+    {next_state, locked, Data};
+handle_event(
+  {call,From}, code_length, _State, #{code := Code} = Data) ->
+    {keep_state, Data,
+     [{reply,From,length(Code)}]}.
 
 ...
-    ]]></code>
+]]></code>
   </section>
 
 <!-- =================================================================== -->
@@ -833,7 +1234,7 @@ init(Args) ->
     process_flag(trap_exit, true),
     do_lock(),
     ...
-      ]]></code>
+    ]]></code>
       <p>
 	When ordered to shut down, the <c>gen_statem</c> then calls
 	callback function <c>terminate(shutdown, State, Data)</c>.
@@ -847,7 +1248,7 @@ init(Args) ->
 terminate(_Reason, State, _Data) ->
     State =/= locked andalso do_lock(),
     ok.
-      ]]></code>
+    ]]></code>
     </section>
 
     <section>
@@ -866,7 +1267,7 @@ terminate(_Reason, State, _Data) ->
 ...
 stop() ->
     gen_statem:stop(?NAME).
-      ]]></code>
+    ]]></code>
       <p>
 	This makes the <c>gen_statem</c> call callback function
 	<c>terminate/3</c> just like for a supervised server
@@ -889,30 +1290,29 @@ stop() ->
     </p>
     <p>
       It is ordered by the state transition action
-      <c>{timeout,Time,EventContent}</c>, or just <c>Time</c>,
-      or even just <c>Time</c> instead of an action list
+      <c>{timeout,Time,EventContent}</c>, or just an integer <c>Time</c>,
+      even without the enclosing actions list
       (the latter is a form inherited from <c>gen_fsm</c>.
     </p>
     <p>
-      This type of time-out is useful to for example act on inactivity.
+      This type of time-out is useful for example to act on inactivity.
       Let us restart the code sequence
       if no button is pressed for say 30 seconds:
     </p>
     <code type="erl"><![CDATA[
 ...
 
-locked(
-  timeout, _, 
-  #{code := Code, remaining := Remaining} = Data) ->
-    {next_state, locked, Data#{remaining := Code}};
+locked(timeout, _, Data) ->
+    {next_state, locked, Data#{buttons := []}};
 locked(
   cast, {button,Digit},
-  #{code := Code, remaining := Remaining} = Data) ->
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
 ...
-        [Digit|Rest] -> % Incomplete
-            {next_state, locked, Data#{remaining := Rest}, 30000};
+	true -> % Incomplete | Incorrect
+            {next_state, locked, Data#{buttons := NewButtons},
+             30000} % Time in milliseconds
 ...
-     ]]></code>
+]]></code>
     <p>
       Whenever we receive a button event we start an event time-out
       of 30 seconds, and if we get an event type <c>timeout</c>
@@ -925,6 +1325,13 @@ locked(
       Whatever event you act on has already cancelled
       the event time-out...
     </p>
+    <p>
+      Note that an event time-out does not work well with
+      when you have for example a status call as in
+      <seealso marker="#All State Events">All State Events</seealso>,
+      or handle unknown events, since all kinds of events
+      will cancel the event time-out.
+    </p>
   </section>
 
 <!-- =================================================================== -->
@@ -952,37 +1359,43 @@ locked(
     <p>
       Here is how to accomplish the state time-out
       in the previous example by instead using a generic time-out
-      named <c>open_tm</c>:
+      named for example <c>open</c>:
     </p>
     <code type="erl"><![CDATA[
 ...
 locked(
   cast, {button,Digit},
-  #{code := Code, remaining := Remaining} = Data) ->
-    case Remaining of
-        [Digit] ->
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
+...
+    if
+        NewButtons =:= Code -> % Correct
 	    do_unlock(),
-            {next_state, open, Data#{remaining := Code},
-	     [{{timeout,open_tm},10000,lock}]};
+            {next_state, open, Data#{buttons := []},
+             [{{timeout,open},10000,lock}]}; % Time in milliseconds
 ...
 
-open({timeout,open_tm}, lock, Data) ->
+open({timeout,open}, lock, Data) ->
     do_lock(),
     {next_state,locked,Data};
 open(cast, {button,_}, Data) ->
     {keep_state,Data};
 ...
-    ]]></code>
+]]></code>
     <p>
-      Just as
-      <seealso marker="#State Time-Outs">state time-outs</seealso>
-      you can restart or cancel a specific generic time-out
+      Specific generic time-outs can just as
+      <seealso marker="#State Time-Outs">State Time-Outs</seealso>
+      be restarted or cancelled
       by setting it to a new time or <c>infinity</c>.
     </p>
     <p>
-      Another way to handle a late time-out can be to not cancel it,
-      but to ignore it if it arrives in a state
-      where it is known to be late.
+      In this particular case we do not need to cancel the timeout
+      since the timeout event is the only possible reason to
+      change the state from <c>open</c> to <c>locked</c>.
+    </p>
+    <p>
+      Instead of bothering with when to cancel a time-out,
+      a late time-out event can be handled by ignoring it
+      if it arrives in a state where it is known to be late.
     </p>
   </section>
 
@@ -994,7 +1407,7 @@ open(cast, {button,_}, Data) ->
     <p>
       The most versatile way to handle time-outs is to use
       Erlang Timers; see
-      <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer3,4</c></seealso>.
+      <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/3,4</c></seealso>.
       Most time-out tasks can be performed with the
       time-out features in <c>gen_statem</c>,
       but an example of one that can not is if you should need
@@ -1009,12 +1422,15 @@ open(cast, {button,_}, Data) ->
 ...
 locked(
   cast, {button,Digit},
-  #{code := Code, remaining := Remaining} = Data) ->
-    case Remaining of
-        [Digit] ->
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
+...
+    if
+        NewButtons =:= Code -> % Correct
 	    do_unlock(),
-	    Tref = erlang:start_timer(10000, self(), lock),
-            {next_state, open, Data#{remaining := Code, timer => Tref}};
+	    Tref =
+                 erlang:start_timer(
+                     10000, self(), lock), % Time in milliseconds
+            {next_state, open, Data#{buttons := [], timer => Tref}};
 ...
 
 open(info, {timeout,Tref,lock}, #{timer := Tref} = Data) ->
@@ -1023,7 +1439,7 @@ open(info, {timeout,Tref,lock}, #{timer := Tref} = Data) ->
 open(cast, {button,_}, Data) ->
     {keep_state,Data};
 ...
-    ]]></code>
+]]></code>
     <p>
       Removing the <c>timer</c> key from the map when we
       change to state <c>locked</c> is not strictly
@@ -1063,7 +1479,9 @@ open(cast, {button,_}, Data) ->
     </p>
     <p>
       Postponing is ordered by the state transition
-      <seealso marker="stdlib:gen_statem#type-action">action</seealso>
+      <seealso marker="#State Transition Actions">
+	State Transition Action
+      </seealso>
       <c>postpone</c>.
     </p>
     <p>
@@ -1076,15 +1494,18 @@ open(cast, {button,_}, Data) ->
 open(cast, {button,_}, Data) ->
     {keep_state,Data,[postpone]};
 ...
-    ]]></code>
+]]></code>
     <p>
       Since a postponed event is only retried after a state change,
       you have to think about where to keep a state data item.
       You can keep it in the server <c>Data</c>
       or in the <c>State</c> itself,
       for example by having two more or less identical states
-      to keep a boolean value, or by using a complex state with
-      <seealso marker="#Callback Modes">callback mode</seealso>
+      to keep a boolean value, or by using a complex state
+      (see section
+      <seealso marker="#Complex State">Complex State</seealso>)
+      with
+      <seealso marker="#Callback Modes">Callback Mode</seealso>
       <seealso marker="stdlib:gen_statem#type-callback_mode"><c>handle_event_function</c></seealso>.
       If a change in the value changes the set of events that is handled,
       then the value should be kept in the State.
@@ -1134,28 +1555,38 @@ start_link(Code) ->
       fun () ->
 	      true = register(?NAME, self()),
 	      do_lock(),
-	      locked(Code, Code)
+	      locked(Code, length(Code), [])
       end).
 
-button(Digit) ->
-    ?NAME ! {button,Digit}.
-
-locked(Code, [Digit|Remaining]) ->
+button(Button) ->
+    ?NAME ! {button,Button}.
+    ]]></code>
+    <code type="erl"><![CDATA[
+locked(Code, Length, Buttons) ->
     receive
-	{button,Digit} when Remaining =:= [] ->
-	    do_unlock(),
-	    open(Code);
-	{button,Digit} ->
-	    locked(Code, Remaining);
-	{button,_} ->
-	    locked(Code, Code)
+        {button,Button} ->
+            NewButtons =
+                if
+                    length(Buttons) < Length ->
+                        Buttons;
+                    true ->
+                        tl(Buttons)
+                end ++ [Button],
+            if
+                NewButtons =:= Code -> % Correct
+                    do_unlock(),
+		    open(Code, Length);
+                true -> % Incomplete | Incorrect
+                    locked(Code, Length, NewButtons)
+            end
     end.
-
-open(Code) ->
+    ]]></code>
+    <code type="erl"><![CDATA[
+open(Code, Length) ->
     receive
-    after 10000 ->
+    after 10000 -> % Time in milliseconds
 	    do_lock(),
-	    locked(Code, Code)
+	    locked(Code, Length, [])
     end.
 
 do_lock() ->
@@ -1178,8 +1609,10 @@ do_unlock() ->
       passing non-system messages to the callback module.
     </p>
     <p>
-      The state transition
-      <seealso marker="stdlib:gen_statem#type-action">action</seealso>
+      The
+      <seealso marker="#State Transition Actions">
+	State Transition Action
+      </seealso>
       <c>postpone</c> is designed to model
       selective receives. A selective receive implicitly postpones
       any not received events, but the <c>postpone</c>
@@ -1196,16 +1629,16 @@ do_unlock() ->
 <!-- =================================================================== -->
 
   <section>
-    <marker id="State Entry Actions" />
-    <title>State Entry Actions</title>
+    <marker id="State Enter Actions" />
+    <title>State Enter Actions</title>
     <p>
       Say you have a state machine specification
-      that uses state entry actions.
-      Allthough you can code this using self-generated events
+      that uses state enter actions.
+      Allthough you can code this using inserted events
       (described in the next section), especially if just
-      one or a few states has got state entry actions,
+      one or a few states has got state enter actions,
       this is a perfect use case for the built in
-      <seealso marker="#State Enter Calls">state enter calls</seealso>.
+      <seealso marker="#State Enter Calls">State Enter Calls</seealso>.
     </p>
     <p>
       You return a list containing <c>state_enter</c> from your
@@ -1219,7 +1652,7 @@ do_unlock() ->
 ...
 init(Code) ->
     process_flag(trap_exit, true),
-    Data = #{code => Code},
+    Data = #{code => Code, length = length(Code)},
     {ok, locked, Data}.
 
 callback_mode() ->
@@ -1227,24 +1660,26 @@ callback_mode() ->
 
 locked(enter, _OldState, Data) ->
     do_lock(),
-    {keep_state,Data#{remaining => Code}};
+    {keep_state,Data#{buttons => []}};
 locked(
   cast, {button,Digit},
-  #{code := Code, remaining := Remaining} = Data) ->
-    case Remaining of
-        [Digit] ->
-	    {next_state, open, Data};
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
+...
+    if
+        NewButtons =:= Code -> % Correct
+            {next_state, open, Data};
 ...
 
 open(enter, _OldState, _Data) ->
     do_unlock(),
-    {keep_state_and_data, [{state_timeout,10000,lock}]};
+    {keep_state_and_data,
+     [{state_timeout,10000,lock}]}; % Time in milliseconds
 open(state_timeout, lock, Data) ->
     {next_state, locked, Data};
 ...
-    ]]></code>
+]]></code>
     <p>
-      You can repeat the state entry code by returning one of
+      You can repeat the state enter code by returning one of
       <c>{repeat_state, ...}</c>, <c>{repeat_state_and_data,_}</c>
       or <c>repeat_state_and_data</c> that otherwise behaves
       exactly like their <c>keep_state</c> siblings.
@@ -1259,13 +1694,15 @@ open(state_timeout, lock, Data) ->
 <!-- =================================================================== -->
 
   <section>
-    <marker id="Self-Generated Events" />
-    <title>Self-Generated Events</title>
+    <marker id="Inserted Events" />
+    <title>Inserted Events</title>
     <p>
       It can sometimes be beneficial to be able to generate events
       to your own state machine.
-      This can be done with the state transition
-      <seealso marker="stdlib:gen_statem#type-action">action</seealso>
+      This can be done with the
+      <seealso marker="#State Transition Actions">
+	State Transition Action
+      </seealso>
       <c>{next_event,EventType,EventContent}</c>.
     </p>
     <p>
@@ -1279,58 +1716,75 @@ open(state_timeout, lock, Data) ->
     <p>
       One example for this is to pre-process incoming data, for example
       decrypting chunks or collecting characters up to a line break.
+    </p>
+    <p>
       Purists may argue that this should be modelled with a separate
       state machine that sends pre-processed events
-      to the main state machine.
-      But to decrease overhead the small pre-processing state machine
+      to the main state machine,
+      but to decrease overhead the small pre-processing state machine
       can be implemented in the common state event handling
       of the main state machine using a few state data variables
       that then sends the pre-processed events as internal events
       to the main state machine.
+      Using internal events also can make it easier
+      to synchronize the state machines.
+    </p>
+    <p>
+      A variant of this is to use a
+      <seealso marker="#Complex State">
+	Complex State
+      </seealso>
+      with
+      <seealso marker="#One Event Handler">One Event Handler</seealso>.
+      The state is then modeled with for example a tuple
+      <c>{MainFSMState,SubFSMState}</c>.
     </p>
     <p>
-      The following example uses an input model where you give the lock
-      characters with <c>put_chars(Chars)</c> and then call
-      <c>enter()</c> to finish the input.
+      To illustrate this we make up an example where the buttons
+      instead generate down and up (press and release) events,
+      and the lock responds to an up event only after
+      the corresponding down event.
     </p>
     <code type="erl"><![CDATA[
 ...
--export(put_chars/1, enter/0).
+-export(down/1, up/1).
 ...
-put_chars(Chars) when is_binary(Chars) ->
-    gen_statem:call(?NAME, {chars,Chars}).
+down(Button) ->
+    gen_statem:cast(?NAME, {down,Button}).
 
-enter() ->
-    gen_statem:call(?NAME, enter).
+up(Button) ->
+    gen_statem:cast(?NAME, {up,Button}).
 
 ...
 
 locked(enter, _OldState, Data) ->
     do_lock(),
     {keep_state,Data#{remaining => Code, buf => []}};
+locked(
+  internal, {button,Digit},
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
 ...
-
-handle_event({call,From}, {chars,Chars}, #{buf := Buf} = Data) ->
-    {keep_state, Data#{buf := [Chars|Buf],
-     [{reply,From,ok}]};
-handle_event({call,From}, enter, #{buf := Buf} = Data) ->
-    Chars = unicode:characters_to_binary(lists:reverse(Buf)),
-    try binary_to_integer(Chars) of
-        Digit ->
-            {keep_state, Data#{buf := []},
-             [{reply,From,ok},
-              {next_event,internal,{button,Chars}}]}
-    catch
-        error:badarg ->
-            {keep_state, Data#{buf := []},
-             [{reply,From,{error,not_an_integer}}]}
+]]></code>
+    <code type="erl"><![CDATA[
+handle_common(cast, {down,Button}, Data) ->
+    {keep_state, Data#{button := Button}};
+handle_common(cast, {up,Button}, Data) ->
+    case Data of
+        #{button := Button} ->
+            {keep_state,maps:remove(button, Data),
+             [{next_event,internal,{button,Button}}]};
+        #{} ->
+            keep_state_and_data
     end;
 ...
-    ]]></code>
+
+open(internal, {button,_}, Data) ->
+    {keep_state,Data,[postpone]};
+...
+]]></code>
     <p>
       If you start this program with <c>code_lock:start([17])</c>
-      you can unlock with <c>code_lock:put_chars(&lt;&lt;"001">>),
-      code_lock:put_chars(&lt;&lt;"7">>), code_lock:enter()</c>.
+      you can unlock with <c>code_lock:down(17), code_lock:up(17).</c>
     </p>
   </section>
 
@@ -1344,14 +1798,16 @@ handle_event({call,From}, enter, #{buf := Buf} = Data) ->
       modifications and some more using state enter calls,
       which deserves a new state diagram:
     </p>
-    <image file="../design_principles/code_lock_2.png">
+    <!-- The image is edited with dia in a .dia file,
+	 then exported to Scalable Vector Graphics. -->
+    <image file="../design_principles/code_lock_2.svg" width="80%">
       <icaption>Code Lock State Diagram Revisited</icaption>
     </image>
     <p>
       Notice that this state diagram does not specify how to handle
       a button event in the state <c>open</c>. So, you need to
-      read somewhere else that unspecified events
-      must be ignored as in not consumed but handled in some other state.
+      read in some side notes, that is, here: that unspecified events
+      shall be postponed (handled in some later state).
       Also, the state diagram does not show that the <c>code_length/0</c>
       call must be handled in every state.
     </p>
@@ -1368,8 +1824,8 @@ handle_event({call,From}, enter, #{buf := Buf} = Data) ->
 -define(NAME, code_lock_2).
 
 -export([start_link/1,stop/0]).
--export([button/1,code_length/0]).
--export([init/1,callback_mode/0,terminate/3,code_change/4]).
+-export([down/1,up/1,code_length/0]).
+-export([init/1,callback_mode/0,terminate/3]).
 -export([locked/3,open/3]).
 
 start_link(Code) ->
@@ -1377,52 +1833,75 @@ start_link(Code) ->
 stop() ->
     gen_statem:stop(?NAME).
 
-button(Digit) ->
-    gen_statem:cast(?NAME, {button,Digit}).
+down(Digit) ->
+    gen_statem:cast(?NAME, {down,Digit}).
+up(Digit) ->
+    gen_statem:cast(?NAME, {up,Digit}).
 code_length() ->
     gen_statem:call(?NAME, code_length).
-
+    ]]></code>
+      <code type="erl"><![CDATA[
 init(Code) ->
     process_flag(trap_exit, true),
-    Data = #{code => Code},
+    Data = #{code => Code, length => length(Code), buttons => []},
     {ok, locked, Data}.
 
 callback_mode() ->
     [state_functions,state_enter].
 
-locked(enter, _OldState, #{code := Code} = Data) ->
+-define(HANDLE_COMMON,
+    ?FUNCTION_NAME(T, C, D) -> handle_common(T, C, D)).
+%%
+handle_common(cast, {down,Button}, Data) ->
+    {keep_state, Data#{button => Button}};
+handle_common(cast, {up,Button}, Data) ->
+    case Data of
+        #{button := Button} ->
+            {keep_state, maps:remove(button, Data),
+             [{next_event,internal,{button,Button}}]};
+        #{} ->
+            keep_state_and_data
+    end;
+handle_common({call,From}, code_length, #{code := Code}) ->
+    {keep_state_and_data,
+     [{reply,From,length(Code)}]}.
+    ]]></code>
+    <code type="erl"><![CDATA[
+locked(enter, _OldState, Data) ->
     do_lock(),
-    {keep_state, Data#{remaining => Code}};
-locked(
-  timeout, _, 
-  #{code := Code, remaining := Remaining} = Data) ->
-    {keep_state, Data#{remaining := Code}};
+    {keep_state, Data#{buttons := []}};
+locked(state_timeout, button, Data) ->
+    {keep_state, Data#{buttons := []}};
 locked(
-  cast, {button,Digit},
-  #{code := Code, remaining := Remaining} = Data) ->
-    case Remaining of
-        [Digit] -> % Complete
+  internal, {button,Digit},
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
+    NewButtons =
+        if
+            length(Buttons) < Length ->
+                Buttons;
+            true ->
+                tl(Buttons)
+        end ++ [Button],
+    if
+        NewButtons =:= Code -> % Correct
+	    do_unlock(),
             {next_state, open, Data};
-        [Digit|Rest] -> % Incomplete
-            {keep_state, Data#{remaining := Rest}, 30000};
-        [_|_] -> % Wrong
-            {keep_state, Data#{remaining := Code}}
+	true -> % Incomplete | Incorrect
+            {keep_state, Data#{buttons := NewButtons},
+             [{state_timeout,30000,button}]} % Time in milliseconds
     end;
-locked(EventType, EventContent, Data) ->
-    handle_event(EventType, EventContent, Data).
-
+?HANDLE_COMMON.
+]]></code>
+    <code type="erl"><![CDATA[
 open(enter, _OldState, _Data) ->
     do_unlock(),
-    {keep_state_and_data, [{state_timeout,10000,lock}]};
+    {keep_state_and_data,
+     [{state_timeout,10000,lock}]}; % Time in milliseconds
 open(state_timeout, lock, Data) ->
     {next_state, locked, Data};
-open(cast, {button,_}, _) ->
+open(internal, {button,_}, _) ->
     {keep_state_and_data, [postpone]};
-open(EventType, EventContent, Data) ->
-    handle_event(EventType, EventContent, Data).
-
-handle_event({call,From}, code_length, #{code := Code}) ->
-    {keep_state_and_data, [{reply,From,length(Code)}]}.
+?HANDLE_COMMON.
 
 do_lock() ->
     io:format("Locked~n", []).
@@ -1432,9 +1911,7 @@ do_unlock() ->
 terminate(_Reason, State, _Data) ->
     State =/= locked andalso do_lock(),
     ok.
-code_change(_Vsn, State, Data, _Extra) ->
-    {ok,State,Data}.
-      ]]></code>
+    ]]></code>
     </section>
 
     <section>
@@ -1448,54 +1925,72 @@ code_change(_Vsn, State, Data, _Extra) ->
         so this example first branches depending on state:
       </p>
       <code type="erl"><![CDATA[
-...
 -export([handle_event/4]).
-
-...
+]]></code>
+      <code type="erl"><![CDATA[
 callback_mode() ->
     [handle_event_function,state_enter].
-
+    ]]></code>
+      <code type="erl"><![CDATA[
+%%
 %% State: locked
-handle_event(
-  enter, _OldState, locked,
-  #{code := Code} = Data) ->
+handle_event(enter, _OldState, locked, Data) ->
     do_lock(),
-    {keep_state, Data#{remaining => Code}};
-handle_event(
-  timeout, _, locked,
-  #{code := Code, remaining := Remaining} = Data) ->
-    {keep_state, Data#{remaining := Code}};
+    {keep_state, Data#{buttons := []}};
+handle_event(state_timeout, button, locked, Data) ->
+    {keep_state, Data#{buttons := []}};
 handle_event(
-  cast, {button,Digit}, locked,
-  #{code := Code, remaining := Remaining} = Data) ->
-    case Remaining of
-        [Digit] -> % Complete
+  internal, {button,Digit}, locked,
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
+    NewButtons =
+        if
+            length(Buttons) < Length ->
+                Buttons;
+            true ->
+                tl(Buttons)
+        end ++ [Button],
+    if
+        NewButtons =:= Code -> % Correct
+	    do_unlock(),
             {next_state, open, Data};
-        [Digit|Rest] -> % Incomplete
-            {keep_state, Data#{remaining := Rest}, 30000};
-        [_|_] -> % Wrong
-            {keep_state, Data#{remaining := Code}}
+	true -> % Incomplete | Incorrect
+            {keep_state, Data#{buttons := NewButtons},
+             [{state_timeout,30000,button}]} % Time in milliseconds
     end;
+    ]]></code>
+      <code type="erl"><![CDATA[
 %%
 %% State: open
 handle_event(enter, _OldState, open, _Data) ->
     do_unlock(),
-    {keep_state_and_data, [{state_timeout,10000,lock}]};
+    {keep_state_and_data,
+     [{state_timeout,10000,lock}]}; % Time in milliseconds
 handle_event(state_timeout, lock, open, Data) ->
     {next_state, locked, Data};
-handle_event(cast, {button,_}, open, _) ->
+handle_event(internal, {button,_}, open, _) ->
     {keep_state_and_data,[postpone]};
-%%
-%% Any state
-handle_event({call,From}, code_length, _State, #{code := Code}) ->
-    {keep_state_and_data, [{reply,From,length(Code)}]}.
-
-...
-      ]]></code>
+    ]]></code>
+      <code type="erl"><![CDATA[
+%% Common events
+handle_event(cast, {down,Button}, _State, Data) ->
+    {keep_state, Data#{button => Button}};
+handle_event(cast, {up,Button}, _State, Data) ->
+    case Data of
+        #{button := Button} ->
+            {keep_state, maps:remove(button, Data),
+             [{next_event,internal,{button,Button}},
+              {state_timeout,30000,button}]}; % Time in milliseconds
+        #{} ->
+            keep_state_and_data
+    end;
+handle_event({call,From}, code_length, _State, #{length := Length}) ->
+    {keep_state_and_data,
+     [{reply,From,Length}]}.
+    ]]></code>
     </section>
     <p>
-      Notice that postponing buttons from the <c>locked</c> state
-      to the <c>open</c> state feels like a strange thing to do
+      Notice that postponing buttons from the <c>open</c> state
+      to the <c>locked</c> state feels like a strange thing to do
       for a code lock, but it at least illustrates event postponing.
     </p>
   </section>
@@ -1532,7 +2027,7 @@ handle_event({call,From}, code_length, _State, #{code := Code}) ->
     </p>
     <code type="erl"><![CDATA[
 ...
--export([init/1,terminate/3,code_change/4,format_status/2]).
+-export([init/1,terminate/3,format_status/2]).
 ...
 
 format_status(Opt, [_PDict,State,Data]) ->
@@ -1540,7 +2035,6 @@ format_status(Opt, [_PDict,State,Data]) ->
 	{State,
 	 maps:filter(
 	   fun (code, _) -> false;
-	       (remaining, _) -> false;
 	       (_, _) -> true
 	   end,
 	   Data)},
@@ -1576,10 +2070,10 @@ format_status(Opt, [_PDict,State,Data]) ->
     <p>
       One reason to use this is when you have a state item
       that when changed should cancel the
-      <seealso marker="#State Time-Outs">state time-out</seealso>,
+      <seealso marker="#State Time-Outs">State Time-Out</seealso>,
       or one that affects the event handling
       in combination with postponing events.
-      We will complicate the previous example
+      We will go for the latter and complicate the previous example
       by introducing a configurable lock button
       (this is the state item in question),
       which in the <c>open</c> state immediately locks the door,
@@ -1588,33 +2082,33 @@ format_status(Opt, [_PDict,State,Data]) ->
     <p>
       Suppose now that we call <c>set_lock_button</c>
       while the door is open,
-      and have already postponed a button event
-      that until now was not the lock button.
-      The sensible thing can be to say that
-      the button was pressed too early so it is
-      not to be recognized as the lock button.
-      However, then it can be surprising that a button event
-      that now is the lock button event arrives (as retried postponed)
-      immediately after the state transits to <c>locked</c>.
-    </p>
-    <p>
-      So we make the <c>button/1</c> function synchronous
-      by using
-      <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call</c></seealso>
-      and still postpone its events in the <c>open</c> state.
-      Then a call to <c>button/1</c> during the <c>open</c>
-      state does not return until the state transits to <c>locked</c>,
-      as it is there the event is handled and the reply is sent.
-    </p>
-    <p>
-      If a process now calls <c>set_lock_button/1</c>
-      to change the lock button while another process
-      hangs in <c>button/1</c> with the new lock button,
-      it can be expected that the hanging lock button call
-      immediately takes effect and locks the lock.
-      Therefore, we make the current lock button a part of the state,
-      so that when we change the lock button, the state changes
-      and all postponed events are retried.
+      and we have already postponed a button event
+      that was the new lock button:
+    </p>
+    <code type="erl"><![CDATA[
+1> code_lock:start_link([a,b,c], x).
+{ok,<0.666.0>}
+2> code_lock:button(a).
+ok
+3> code_lock:button(b).
+ok
+4> code_lock:button(c).
+ok
+Open
+5> code_lock:button(y).
+ok
+6> code_lock:set_lock_button(y).
+x
+% What should happen here?  Immediate lock or nothing?
+]]></code>
+    <p>
+      We could say that the button was pressed too early
+      so it is not to be recognized as the lock button.
+      Or we can make the lock button part of the state so
+      when we then change the lock button in the locked state,
+      the change becomes a state change
+      and all postponed events are retried,
+      therefore the lock is immediately locked!
     </p>
     <p>
       We define the state as <c>{StateName,LockButton}</c>,
@@ -1627,8 +2121,8 @@ format_status(Opt, [_PDict,State,Data]) ->
 -define(NAME, code_lock_3).
 
 -export([start_link/2,stop/0]).
--export([button/1,code_length/0,set_lock_button/1]).
--export([init/1,callback_mode/0,terminate/3,code_change/4,format_status/2]).
+-export([button/1,set_lock_button/1]).
+-export([init/1,callback_mode/0,terminate/3]).
 -export([handle_event/4]).
 
 start_link(Code, LockButton) ->
@@ -1637,77 +2131,69 @@ start_link(Code, LockButton) ->
 stop() ->
     gen_statem:stop(?NAME).
 
-button(Digit) ->
-    gen_statem:call(?NAME, {button,Digit}).
-code_length() ->
-    gen_statem:call(?NAME, code_length).
+button(Button) ->
+    gen_statem:cast(?NAME, {button,Button}).
 set_lock_button(LockButton) ->
     gen_statem:call(?NAME, {set_lock_button,LockButton}).
-
+    ]]></code>
+    <code type="erl"><![CDATA[
 init({Code,LockButton}) ->
     process_flag(trap_exit, true),
-    Data = #{code => Code, remaining => undefined},
+    Data = #{code => Code, length => length(Code), buttons => []},
     {ok, {locked,LockButton}, Data}.
 
 callback_mode() ->
     [handle_event_function,state_enter].
 
-handle_event(
-  {call,From}, {set_lock_button,NewLockButton},
-  {StateName,OldLockButton}, Data) ->
-    {next_state, {StateName,NewLockButton}, Data,
-     [{reply,From,OldLockButton}]};
-handle_event(
-  {call,From}, code_length,
-  {_StateName,_LockButton}, #{code := Code}) ->
-    {keep_state_and_data,
-     [{reply,From,length(Code)}]};
-%%
 %% State: locked
+handle_event(enter, _OldState, {locked,_}, Data) ->
+    do_lock(),
+    {keep_state, Data#{buttons := []}};
+handle_event(state_timeout, button, {locked,_}, Data) ->
+    {keep_state, Data#{buttons := []}};
 handle_event(
-  EventType, EventContent,
-  {locked,LockButton}, #{code := Code, remaining := Remaining} = Data) ->
-    case {EventType, EventContent} of
-	{enter, _OldState} ->
-	    do_lock(),
-	    {keep_state, Data#{remaining := Code}};
-        {timeout, _} ->
-            {keep_state, Data#{remaining := Code}};
-	{{call,From}, {button,Digit}} ->
-	    case Remaining of
-		[Digit] -> % Complete
-		    {next_state, {open,LockButton}, Data,
-		     [{reply,From,ok}]};
-		[Digit|Rest] -> % Incomplete
-		    {keep_state, Data#{remaining := Rest},
-		     [{reply,From,ok}, 30000]};
-		[_|_] -> % Wrong
-		    {keep_state, Data#{remaining := Code},
-		     [{reply,From,ok}]}
-	    end
+  cast, {button,Digit}, {locked,LockButton},
+  #{code := Code, length := Length, buttons := Buttons} = Data) ->
+    NewButtons =
+        if
+            length(Buttons) < Length ->
+                Buttons;
+            true ->
+                tl(Buttons)
+        end ++ [Button],
+    if
+        NewButtons =:= Code -> % Correct
+	    do_unlock(),
+            {next_state, {open,LockButton}, Data};
+	true -> % Incomplete | Incorrect
+            {keep_state, Data#{buttons := NewButtons},
+             [{state_timeout,30000,button}]} % Time in milliseconds
     end;
+    ]]></code>
+    <code type="erl"><![CDATA[
 %%
 %% State: open
+handle_event(enter, _OldState, {open,_}, _Data) ->
+    do_unlock(),
+    {keep_state_and_data,
+     [{state_timeout,10000,lock}]}; % Time in milliseconds
+handle_event(state_timeout, lock, {open,_}, Data) ->
+    {next_state, locked, Data};
+handle_event(cast, {button,LockButton}, {open,LockButton}, Data) ->
+    {next_state, {locked,LockButton}, Data};
+handle_event(cast, {button,_}, {open,_}, Data) ->
+    {keep_state_and_data,[postpone]};
+    ]]></code>
+    <code type="erl"><![CDATA[
+%%
+%% Common events
 handle_event(
-  EventType, EventContent,
-  {open,LockButton}, Data) ->
-    case {EventType, EventContent} of
-	{enter, _OldState} ->
-	    do_unlock(),
-	    {keep_state_and_data, [{state_timeout,10000,lock}]};
-	{state_timeout, lock} ->
-	    {next_state, {locked,LockButton}, Data};
-	{{call,From}, {button,Digit}} ->
-	    if
-		Digit =:= LockButton ->
-		    {next_state, {locked,LockButton}, Data,
-		     [{reply,From,locked}]};
-		true ->
-		    {keep_state_and_data,
-		     [postpone]}
-	    end
-    end.
-
+  {call,From}, {set_lock_button,NewLockButton},
+  {StateName,OldLockButton}, Data) ->
+    {next_state, {StateName,NewLockButton}, Data,
+     [{reply,From,OldLockButton}]}.
+    ]]></code>
+    <code type="erl"><![CDATA[
 do_lock() ->
     io:format("Locked~n", []).
 do_unlock() ->
@@ -1716,29 +2202,7 @@ do_unlock() ->
 terminate(_Reason, State, _Data) ->
     State =/= locked andalso do_lock(),
     ok.
-code_change(_Vsn, State, Data, _Extra) ->
-    {ok,State,Data}.
-format_status(Opt, [_PDict,State,Data]) ->
-    StateData =
-	{State,
-	 maps:filter(
-	   fun (code, _) -> false;
-	       (remaining, _) -> false;
-	       (_, _) -> true
-	   end,
-	   Data)},
-    case Opt of
-	terminate ->
-	    StateData;
-	normal ->
-	    [{data,[{"State",StateData}]}]
-    end.
     ]]></code>
-    <p>
-      It can be an ill-fitting model for a physical code lock
-      that the <c>button/1</c> call can hang until the lock
-      is locked. But for an API in general it is not that strange.
-    </p>
   </section>
 
 <!-- =================================================================== -->
@@ -1770,17 +2234,15 @@ format_status(Opt, [_PDict,State,Data]) ->
     </p>
     <code type="erl"><![CDATA[
 ...
+%%
 %% State: open
-handle_event(
-  EventType, EventContent,
-  {open,LockButton}, Data) ->
-    case {EventType, EventContent} of
-        {enter, _OldState} ->
-            do_unlock(),
-            {keep_state_and_data,
-             [{state_timeout,10000,lock},hibernate]};
+handle_event(enter, _OldState, {open,_}, _Data) ->
+    do_unlock(),
+    {keep_state_and_data,
+     [{state_timeout,10000,lock}, % Time in milliseconds
+      hibernate]};
 ...
-    ]]></code>
+]]></code>
     <p>
       The atom
       <seealso marker="stdlib:gen_statem#type-hibernate"><c>hibernate</c></seealso>
@@ -1793,20 +2255,34 @@ handle_event(
     <p>
       To change that we would need to insert
       action <c>hibernate</c> in more places.
-      For example, for the state-independent <c>set_lock_button</c>
-      and <c>code_length</c> operations that then would have to
-      be aware of using <c>hibernate</c> while in the
+      For example, the state-independent <c>set_lock_button</c>
+      operation would have to use <c>hibernate</c> but only in the
       <c>{open,_}</c> state, which would clutter the code.
     </p>
     <p>
-      Another not uncommon scenario is to use the event time-out
-      to triger hibernation after a certain time of inactivity.
+      Another not uncommon scenario is to use the
+      <seealso marker="#Event Time-Outs">Event Time-Out</seealso>
+      to trigger hibernation after a certain time of inactivity.
+      There is also a server start option
+      <seealso marker="stdlib:gen_statem#type-hibernate_after_opt">
+	<c>{hibernate_after, Timeout}</c>
+      </seealso>
+      for
+      <seealso marker="stdlib:gen_statem#start/3">
+	<c>start/3,4</c>
+      </seealso>
+      or
+      <seealso marker="stdlib:gen_statem#start_link/3">
+	<c>start_link/3,4</c>
+      </seealso>
+      that may be used to automatically hibernate the server.
     </p>
     <p>
-      This server probably does not use
+      This particular server probably does not use
       heap memory worth hibernating for.
       To gain anything from hibernation, your server would
-      have to produce some garbage during callback execution,
+      have to produce non-insignificant garbage
+      during callback execution,
       for which this example server can serve as a bad example.
     </p>
   </section>