From c828867852f332829d49c942a7df395eb9b98b18 Mon Sep 17 00:00:00 2001
From: Bryan <bryan.crotaz@silvercurve.co.uk>
Date: Sat, 19 Oct 2024 17:50:00 +0100
Subject: [PATCH] add documentation

---
 docs/syntax/packet.md                      | 40 ++++++++--------------
 packages/mermaid/src/docs/syntax/packet.md | 16 +++++++--
 2 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/docs/syntax/packet.md b/docs/syntax/packet.md
index 5eab81910..5214f6c00 100644
--- a/docs/syntax/packet.md
+++ b/docs/syntax/packet.md
@@ -23,6 +23,17 @@ start-end: "Block name" %% Multi-bit blocks
 ... More Fields ...
 ```
 
+### Bits Syntax (v\<MERMAID_RELEASE_VERSION>+)
+
+Using start and end bit counts can be difficult, especially when modifying a design. For this we add a bit count field, which starts from the end of the previous field automagically. Use `bit` or `bits` interchangeably to set the number of bits, thus:
+
+````md
+packet-beta
+1bit: "Block name" %% Single-bit block
+8bits: "Block name" %% 8-bit block
+9-15: "Manually set start and end, it's fine to mix and match"
+... More Fields ...
+
 ## Examples
 
 ```mermaid-example
@@ -30,32 +41,8 @@ start-end: "Block name" %% Multi-bit blocks
 title: "TCP Packet"
 ---
 packet-beta
-0-15: "Source Port"
-16-31: "Destination Port"
-32-63: "Sequence Number"
-64-95: "Acknowledgment Number"
-96-99: "Data Offset"
-100-105: "Reserved"
-106: "URG"
-107: "ACK"
-108: "PSH"
-109: "RST"
-110: "SYN"
-111: "FIN"
-112-127: "Window"
-128-143: "Checksum"
-144-159: "Urgent Pointer"
-160-191: "(Options and Padding)"
-192-255: "Data (variable length)"
-```
-
-```mermaid
----
-title: "TCP Packet"
----
-packet-beta
-0-15: "Source Port"
-16-31: "Destination Port"
+16bits: "Source Port"
+16bits: "Destination Port"
 32-63: "Sequence Number"
 64-95: "Acknowledgment Number"
 96-99: "Data Offset"
@@ -72,6 +59,7 @@ packet-beta
 160-191: "(Options and Padding)"
 192-255: "Data (variable length)"
 ```
+````
 
 ```mermaid-example
 packet-beta
diff --git a/packages/mermaid/src/docs/syntax/packet.md b/packages/mermaid/src/docs/syntax/packet.md
index c7b6cb71b..5a2992654 100644
--- a/packages/mermaid/src/docs/syntax/packet.md
+++ b/packages/mermaid/src/docs/syntax/packet.md
@@ -17,6 +17,17 @@ start-end: "Block name" %% Multi-bit blocks
 ... More Fields ...
 ```
 
+### Bits Syntax (v<MERMAID_RELEASE_VERSION>+)
+
+Using start and end bit counts can be difficult, especially when modifying a design. For this we add a bit count field, which starts from the end of the previous field automagically. Use `bit` or `bits` interchangeably to set the number of bits, thus:
+
+````md
+packet-beta
+1bit: "Block name" %% Single-bit block
+8bits: "Block name" %% 8-bit block
+9-15: "Manually set start and end, it's fine to mix and match"
+... More Fields ...
+
 ## Examples
 
 ```mermaid-example
@@ -24,8 +35,8 @@ start-end: "Block name" %% Multi-bit blocks
 title: "TCP Packet"
 ---
 packet-beta
-0-15: "Source Port"
-16-31: "Destination Port"
+16bits: "Source Port"
+16bits: "Destination Port"
 32-63: "Sequence Number"
 64-95: "Acknowledgment Number"
 96-99: "Data Offset"
@@ -42,6 +53,7 @@ packet-beta
 160-191: "(Options and Padding)"
 192-255: "Data (variable length)"
 ```
+````
 
 ```mermaid-example
 packet-beta