From d2a0223f337c0dd9f029910e894b4d3bd5c6a4a1 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/autogen/init-framework.zeek |  8 ++++++-
 devel/spicy/reference.rst               | 32 +++++++++++++++++++++++++
 devel/spicy/tutorial.rst                |  8 +++++++
 3 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/devel/spicy/autogen/init-framework.zeek b/devel/spicy/autogen/init-framework.zeek
index ae3a3b8e6..de6b528ee 100644
--- a/devel/spicy/autogen/init-framework.zeek
+++ b/devel/spicy/autogen/init-framework.zeek
@@ -47,12 +47,18 @@ export {
 
 # Marked with &is_used to suppress complaints when there aren't any
 # Spicy file analyzers loaded, and hence this event can't be generated.
-# The attribute is only supported for Zeek 5.0 and higher.
 event spicy_analyzer_for_mime_type(a: Files::Tag, mt: string) &is_used
     {
     Files::register_for_mime_type(a, mt);
     }
 
+# Marked with &is_used to suppress complaints when there aren't any
+# Spicy protocol analyzers loaded, and hence this event can't be generated.
+event spicy_analyzer_for_port(a: Analyzer::Tag, p: port) &is_used
+    {
+    Analyzer::register_for_port(a, p);
+    }
+
 function enable_protocol_analyzer(tag: Analyzer::Tag) : bool
     {
     return Spicy::__toggle_analyzer(tag, T);
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