From f06db5c367f19904643834f124be825a2235ec2d Mon Sep 17 00:00:00 2001
From: Robin Sommer <robin@icir.org>
Date: Mon, 19 Aug 2024 09:48:37 +0200
Subject: [PATCH] Documentation updates for un-deprecation of Spicy's `port`.

---
 devel/spicy/reference.rst | 32 ++++++++++++++++++++++++++++++++
 devel/spicy/tutorial.rst  |  8 ++++++++
 2 files changed, 40 insertions(+)

diff --git a/devel/spicy/reference.rst b/devel/spicy/reference.rst
index 6d99f5368..76f316fec 100644
--- a/devel/spicy/reference.rst
+++ b/devel/spicy/reference.rst
@@ -111,6 +111,38 @@ properties are supported:
             ``SPICY_UNIT`` may define (as long as the attribute's
             direction is not ``originator``).
 
+        .. note::
+
+            .. _zeek_init_instead_of_port:
+
+            While using ``port`` (or ``%port``) can be convinient, for
+            production analyzers we recommended to instead register
+            their well-known ports from inside a Zeek script, using a
+            snippet like this:
+
+            .. code-block:: zeek
+
+                module MyAnalyzer;
+
+                export {
+                    const ports = { 12345/tcp } &redef;
+                }
+
+                redef likely_server_ports += { ports };
+
+                event zeek_init() &priority=5
+                    {
+                    Analyzer::register_for_ports(Analyzer::ANALYZER_MY_ANALYZER, ports);
+                    }
+
+            This follows the idiomatic Zeek pattern for defining
+            well-known ports that allows users to customize them
+            through their own site-specific scripts (e.g., ``redef
+            MyAnalyzer::port += { 12346/tcp };``). The :ref:`package
+            template <zkg_create_package>` includes such code instead
+            of defining ports inside the EVT file.
+
+
     ``replaces ANALYZER_NAME``
         Replaces a built-in analyzer that Zeek already provides with a
         new Spicy version by internally disabling the existing
diff --git a/devel/spicy/tutorial.rst b/devel/spicy/tutorial.rst
index e72220e9c..abb6ffa5f 100644
--- a/devel/spicy/tutorial.rst
+++ b/devel/spicy/tutorial.rst
@@ -94,6 +94,14 @@ analyzer for all sessions on UDP port 69 (i.e., TFTP's well known
 port). See :ref:`spicy_evt_analyzer_setup` for more details on defining
 such a ``protocol analyzer`` section.
 
+.. note::
+
+    We use the ``port`` attribute in the ``protocol analyzer`` section
+    mainly for convenience; it's not the only way to define the
+    well-known ports. For a production analyzer, it's more idiomatic
+    to use the a Zeek script instead; see :ref:`this note
+    <zeek_init_instead_of_port>` for more information.
+
 With this in place, we can already employ the analyzer inside Zeek. It
 will not generate any events yet, but we can at least see the output of
 the ``on %done { print self; }`` hook that still remains part of the