Merge remote-tracking branch 'origin/topic/jsiwek/zeekygen-code-links'

- Applied minor spelling/grammar suggestions from Johanna during merge

* origin/topic/jsiwek/zeekygen-code-links:
  Change update-zeekygen-docs.sh to set release branch in Sphinx config
  Teach Zeekygen to produce source-code-range information
  Add normalize_script_path() zeek::zeekygen::detail namespace
  Add starts_with()/ends_with() to zeek::util namespace

CHANGES

@@ -1,3 +1,18 @@
+
+4.1.0-dev.272 | 2021-03-01 11:36:06 -0800
+
+  * Change update-zeekygen-docs.sh to set release branch in Sphinx config (Jon Siwek, Corelight)
+
+    Allows release branches to generate correct links to GitHub source code.
+
+  * Teach Zeekygen to produce source-code-range information (Jon Siwek, Corelight)
+
+    Related to https://github.com/zeek/zeek-docs/issues/56
+
+  * Add normalize_script_path() zeek::zeekygen::detail namespace (Jon Siwek, Corelight)
+
+  * Add starts_with()/ends_with() to zeek::util namespace (Jon Siwek, Corelight)
+
 4.1.0-dev.266 | 2021-02-25 08:45:49 -0700
 
   * Avoid superfluous string copies when adding to zeek::detail::sig_files

VERSION

@@ -1 +1 @@
-4.1.0-dev.266
+4.1.0-dev.272

ci/update-zeekygen-docs.sh

@@ -63,6 +63,16 @@ generate_index "packet_analyzer" "autogenerated-packet-analyzer-index.rst"
 
 echo
 
+branch="$(git branch --show-current)"
+
+if [[ "$branch" =~ ^release/.* ]]; then
+    doc_config_file=$source_dir/doc/conf.py
+    cat ${doc_config_file} | sed \
+        -e "s#\(zeek_code_version[[:space:]]*=[[:space:]]*\)[^\n]*#\1'$branch'#g" \
+        >${doc_config_file}.tmp
+    mv ${doc_config_file}.tmp ${doc_config_file}
+fi
+
 if [ -n "$(cd $source_dir/doc && git status --porcelain)" ]; then
     echo "*** There are changes in zeek-docs that need a review, commit, and push ***"
 else

doc

@@ -1 +1 @@
-Subproject commit c548b00a3c0d5debfd7778bea1465ecd0d5209fe
+Subproject commit cf113b72a056908fff74988926ad4c85e995b074

src/ID.cc

@@ -18,6 +18,7 @@
 #include "zeek/zeekygen/Manager.h"
 #include "zeek/zeekygen/IdentifierInfo.h"
 #include "zeek/zeekygen/ScriptInfo.h"
+#include "zeek/zeekygen/utils.h"
 #include "zeek/module_util.h"
 
 namespace zeek {
@@ -492,7 +493,15 @@ void ID::DescribeReST(ODesc* d, bool roles_only) const
 			d->Add(".. zeek:type:: ");
 		else
 			d->Add(".. zeek:id:: ");
+
 		d->Add(name);
+
+		if ( auto sc = zeek::zeekygen::detail::source_code_range(this) )
+			{
+			d->PushIndent();
+			d->Add(util::fmt(":source-code: %s", sc->data()));
+			d->PopIndentNoNL();
+			}
 		}
 
 	d->PushIndent();

src/util.cc

@@ -78,36 +78,6 @@ static bool can_read(const string& path)
 	return access(path.c_str(), R_OK) == 0;
 	}
 
-static bool starts_with(std::string_view s, std::string_view beginning)
-	{
-	if ( beginning.size() > s.size() )
-		return false;
-
-	return std::equal(beginning.begin(), beginning.end(), s.begin());
-	}
-
-TEST_CASE("util starts_with")
-	{
-	CHECK(starts_with("abcde", "ab") == true);
-	CHECK(starts_with("abcde", "de") == false);
-	CHECK(starts_with("abcde", "abcedf") == false);
-	}
-
-static bool ends_with(std::string_view s, std::string_view ending)
-	{
-	if ( ending.size() > s.size() )
-		return false;
-
-	return std::equal(ending.rbegin(), ending.rend(), s.rbegin());
-	}
-
-TEST_CASE("util ends_with")
-	{
-	CHECK(ends_with("abcde", "de") == true);
-	CHECK(ends_with("abcde", "fg") == false);
-	CHECK(ends_with("abcde", "abcedf") == false);
-	}
-
 static string zeek_path_value;
 
 namespace zeek::util {
@@ -1157,6 +1127,36 @@ int streq(const char* s1, const char* s2)
 	return ! strcmp(s1, s2);
 	}
 
+bool starts_with(std::string_view s, std::string_view beginning)
+	{
+	if ( beginning.size() > s.size() )
+		return false;
+
+	return std::equal(beginning.begin(), beginning.end(), s.begin());
+	}
+
+TEST_CASE("util starts_with")
+	{
+	CHECK(starts_with("abcde", "ab") == true);
+	CHECK(starts_with("abcde", "de") == false);
+	CHECK(starts_with("abcde", "abcedf") == false);
+	}
+
+bool ends_with(std::string_view s, std::string_view ending)
+	{
+	if ( ending.size() > s.size() )
+		return false;
+
+	return std::equal(ending.rbegin(), ending.rend(), s.rbegin());
+	}
+
+TEST_CASE("util ends_with")
+	{
+	CHECK(ends_with("abcde", "de") == true);
+	CHECK(ends_with("abcde", "fg") == false);
+	CHECK(ends_with("abcde", "abcedf") == false);
+	}
+
 char* skip_whitespace(char* s)
 	{
 	while ( *s == ' ' || *s == '\t' )

src/util.h

@@ -311,6 +311,8 @@ std::vector<std::string_view> tokenize_string(std::string_view input, const char
 
 extern char* copy_string(const char* s);
 extern int streq(const char* s1, const char* s2);
+extern bool starts_with(std::string_view s, std::string_view beginning);
+extern bool ends_with(std::string_view s, std::string_view ending);
 
 extern char* skip_whitespace(char* s);
 extern const char* skip_whitespace(const char* s);

src/zeekygen/Manager.cc

@@ -5,8 +5,9 @@
 #include <utility>
 #include <cstdlib>
 
-#include "zeek/plugin/Manager.h"
+#include "zeek/DebugLogger.h"
 #include "zeek/util.h"
+#include "zeek/zeekygen/utils.h"
 #include "zeek/zeekygen/Info.h"
 #include "zeek/zeekygen/PackageInfo.h"
 #include "zeek/zeekygen/ScriptInfo.h"
@@ -52,20 +53,6 @@ static string RemoveLeadingSpace(const string& s)
 	return rval;
 	}
 
-// Turns a script's full path into a shortened, normalized version that we
-// use for indexing.
-static string NormalizeScriptPath(const string& path)
-	{
-	if ( auto p = plugin_mgr->LookupPluginByPath(path) )
-		{
-		auto rval = util::detail::normalize_path(path);
-		auto prefix = util::SafeBasename(p->PluginDirectory()).result;
-		return prefix + "/" + rval.substr(p->PluginDirectory().size() + 1);
-		}
-
-	return util::detail::without_zeekpath_component(path);
-	}
-
 Manager::Manager(const string& arg_config, const string& bro_command)
 	: disabled(), comment_buffer(), comment_buffer_map(), packages(), scripts(),
 	  identifiers(), all_info(), last_identifier_seen(), incomplete_type(),
@@ -135,7 +122,7 @@ void Manager::Script(const string& path)
 	if ( disabled )
 		return;
 
-	string name = NormalizeScriptPath(path);
+	string name = normalize_script_path(path);
 
 	if ( scripts.GetInfo(name) )
 		{
@@ -179,8 +166,8 @@ void Manager::ScriptDependency(const string& path, const string& dep)
 		return;
 		}
 
-	string name = NormalizeScriptPath(path);
-	string depname = NormalizeScriptPath(dep);
+	string name = normalize_script_path(path);
+	string depname = normalize_script_path(dep);
 	ScriptInfo* script_info = scripts.GetInfo(name);
 
 	if ( ! script_info )
@@ -204,7 +191,7 @@ void Manager::ModuleUsage(const string& path, const string& module)
 	if ( disabled )
 		return;
 
-	string name = NormalizeScriptPath(path);
+	string name = normalize_script_path(path);
 	ScriptInfo* script_info = scripts.GetInfo(name);
 
 	if ( ! script_info )
@@ -263,7 +250,7 @@ void Manager::StartType(zeek::detail::IDPtr id)
 		return;
 		}
 
-	string script = NormalizeScriptPath(id->GetLocationInfo()->filename);
+	string script = normalize_script_path(id->GetLocationInfo()->filename);
 	ScriptInfo* script_info = scripts.GetInfo(script);
 
 	if ( ! script_info )
@@ -327,7 +314,7 @@ void Manager::Identifier(zeek::detail::IDPtr id, bool from_redef)
 		return;
 		}
 
-	string script = NormalizeScriptPath(id->GetLocationInfo()->filename);
+	string script = normalize_script_path(id->GetLocationInfo()->filename);
 	ScriptInfo* script_info = scripts.GetInfo(script);
 
 	if ( ! script_info )
@@ -357,7 +344,7 @@ void Manager::RecordField(const zeek::detail::ID* id, const TypeDecl* field,
 		return;
 		}
 
-	string script = NormalizeScriptPath(path);
+	string script = normalize_script_path(path);
 	idd->AddRecordField(field, script, comment_buffer, from_redef);
 	comment_buffer.clear();
 	DBG_LOG(DBG_ZEEKYGEN, "Document record field %s, identifier %s, script %s",
@@ -385,7 +372,7 @@ void Manager::Redef(const zeek::detail::ID* id, const string& path,
 		return;
 		}
 
-	string from_script = NormalizeScriptPath(path);
+	string from_script = normalize_script_path(path);
 	ScriptInfo* script_info = scripts.GetInfo(from_script);
 
 	if ( ! script_info )
@@ -413,7 +400,7 @@ void Manager::SummaryComment(const string& script, const string& comment)
 	if ( disabled )
 		return;
 
-	string name = NormalizeScriptPath(script);
+	string name = normalize_script_path(script);
 	ScriptInfo* info = scripts.GetInfo(name);
 
 	if ( info )

src/zeekygen/utils.cc

@@ -6,8 +6,11 @@
 #include <errno.h>
 
 #include "zeek/ID.h"
+#include "zeek/Val.h"
+#include "zeek/Func.h"
 #include "zeek/Scope.h"
 #include "zeek/Reporter.h"
+#include "zeek/plugin/Manager.h"
 
 using namespace std;
 
@@ -137,4 +140,79 @@ string redef_indication(const string& from_script)
 	                 from_script.c_str());
 	}
 
+std::string normalize_script_path(std::string_view path)
+	{
+	if ( auto p = plugin_mgr->LookupPluginByPath(path) )
+		{
+		auto rval = util::detail::normalize_path(path);
+		auto prefix = util::SafeBasename(p->PluginDirectory()).result;
+		return prefix + "/" + rval.substr(p->PluginDirectory().size() + 1);
+		}
+
+	return util::detail::without_zeekpath_component(path);
+	}
+
+std::optional<std::string> source_code_range(const zeek::detail::ID* id)
+	{
+	const auto& type = id->GetType();
+
+	if ( ! type )
+		return {};
+
+	// Some object locations won't end up capturing concrete syntax of closing
+	// braces on subsequent line -- of course that doesn't have to always be
+	// case, but it's true for current code style and the possibility of
+	// capturing an extra line of context is not harmful (human reader shouldn't
+	// be too confused by it).
+	int extra_lines = 0;
+	const zeek::detail::Location* loc = &zeek::detail::no_location;
+
+	switch ( type->Tag() ) {
+	case TYPE_FUNC:
+		{
+		const auto& v = id->GetVal();
+
+		if ( v && v->AsFunc()->GetBodies().size() == 1 )
+			{
+			// Either a function or an event/hook with single body can
+			// report that single, continuous range.
+			loc = v->AsFunc()->GetBodies()[0].stmts->GetLocationInfo();
+			++extra_lines;
+			}
+		else
+			loc = id->GetLocationInfo();
+		}
+		break;
+	case TYPE_ENUM:
+		// Fallthrough
+	case TYPE_RECORD:
+		if ( id->IsType() )
+			{
+			loc = type->GetLocationInfo();
+
+			if ( zeek::util::ends_with(loc->filename, ".bif.zeek") )
+				// Source code won't be available to reference, so fall back
+				// to identifier location which may actually be in a regular
+				// .zeek script.
+				loc = id->GetLocationInfo();
+			else
+				++extra_lines;
+			}
+		else
+			loc = id->GetLocationInfo();
+
+		break;
+	default:
+		loc = id->GetLocationInfo();
+		break;
+	}
+
+	if ( loc == &zeek::detail::no_location )
+		return {};
+
+	return util::fmt("%s %d %d",
+	                 normalize_script_path(loc->filename).data(),
+	                 loc->first_line, loc->last_line + extra_lines);
+	}
+
 } // namespace zeek::zeekygen::detail

src/zeekygen/utils.h

@@ -6,6 +6,7 @@
 
 #include <time.h> // for time_t
 #include <string>
+#include <optional>
 
 namespace zeek::detail { class ID; }
 
@@ -64,4 +65,28 @@ bool is_all_whitespace(const std::string& s);
  */
 std::string redef_indication(const std::string& from_script);
 
+/**
+ * Turns a script's path into a shortened, normalized version that
+ * can be used for indexing and cross-referencing links.
+ *
+ * @param path  the associate path to a Zeek script, which may be absolute.
+ *
+ * @return  a normalized/shortened path (containing no ZEEKPATH components)
+ *
+ */
+std::string normalize_script_path(std::string_view path);
+
+/**
+ * Determines the associated section of source code associated with an
+ * identifier's definition.
+ *
+ * @param id  identifier for which obtain source code location info is obtained
+ *
+ * @return  a nil value if source code location could not be determined, else
+ * a space-separated string with 3 components.  The 1st component is a path
+ * relative to the "scripts/" directory, the 2nd and 3rd components are
+ * line numbers denoting the start and end of the relevant source code.
+ */
+std::optional<std::string> source_code_range(const zeek::detail::ID* id);
+
 } // namespace zeek::zeekygen::detail

testing/btest/Baseline/doc.zeekygen.enums/autogen-reST-enums.rst

@@ -1,5 +1,6 @@
 ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63.
 .. zeek:type:: TestEnum1
+   :source-code: <...>/enums.zeek 6 15
 
    :Type: :zeek:type:`enum`
 
@@ -31,6 +32,7 @@
    There's tons of ways an enum can look...
 
 .. zeek:type:: TestEnum2
+   :source-code: <...>/enums.zeek 17 26
 
    :Type: :zeek:type:`enum`
 
@@ -52,6 +54,7 @@
    The final comma is optional
 
 .. zeek:id:: TestEnumVal
+   :source-code: <...>/enums.zeek 40 40
 
    :Type: :zeek:type:`TestEnum1`
    :Attributes: :zeek:attr:`&redef`

testing/btest/Baseline/doc.zeekygen.example/example.rst

@@ -111,6 +111,7 @@ Detailed Interface
 Redefinable Options
 ###################
 .. zeek:id:: ZeekygenExample::an_option
+   :source-code: zeekygen/example.zeek 132 132
 
    :Type: :zeek:type:`set` [:zeek:type:`addr`, :zeek:type:`addr`, :zeek:type:`string`]
    :Attributes: :zeek:attr:`&redef`
@@ -120,6 +121,7 @@ Redefinable Options
    The type/attribute information is all generated automatically.
 
 .. zeek:id:: ZeekygenExample::option_with_init
+   :source-code: zeekygen/example.zeek 135 135
 
    :Type: :zeek:type:`interval`
    :Attributes: :zeek:attr:`&redef`
@@ -131,6 +133,7 @@ Redefinable Options
 State Variables
 ###############
 .. zeek:id:: ZeekygenExample::a_var
+   :source-code: zeekygen/example.zeek 140 140
 
    :Type: :zeek:type:`bool`
 
@@ -139,6 +142,7 @@ State Variables
    in the generated docs.
 
 .. zeek:id:: ZeekygenExample::summary_test
+   :source-code: zeekygen/example.zeek 148 148
 
    :Type: :zeek:type:`string`
 
@@ -147,6 +151,7 @@ State Variables
    by the table of all identifiers declared by this script.
 
 .. zeek:id:: ZeekygenExample::var_without_explicit_type
+   :source-code: zeekygen/example.zeek 143 143
 
    :Type: :zeek:type:`string`
    :Default: ``"this works"``
@@ -156,6 +161,7 @@ State Variables
 Types
 #####
 .. zeek:type:: ZeekygenExample::ComplexRecord
+   :source-code: zeekygen/example.zeek 110 117
 
    :Type: :zeek:type:`record`
 
@@ -177,6 +183,7 @@ Types
    General documentation for a type "ComplexRecord" goes here.
 
 .. zeek:type:: ZeekygenExample::Info
+   :source-code: zeekygen/example.zeek 124 128
 
    :Type: :zeek:type:`record`
 
@@ -193,6 +200,7 @@ Types
    (provided they are also @load'ed).
 
 .. zeek:type:: ZeekygenExample::SimpleEnum
+   :source-code: zeekygen/example.zeek 78 85
 
    :Type: :zeek:type:`enum`
 
@@ -219,6 +227,7 @@ Types
    It can span multiple lines.
 
 .. zeek:type:: ZeekygenExample::SimpleRecord
+   :source-code: zeekygen/example.zeek 97 101
 
    :Type: :zeek:type:`record`
 
@@ -239,6 +248,7 @@ Types
 Events
 ######
 .. zeek:id:: ZeekygenExample::an_event
+   :source-code: zeekygen/example.zeek 171 171
 
    :Type: :zeek:type:`event` (name: :zeek:type:`string`)
 
@@ -255,6 +265,7 @@ Events
 Functions
 #########
 .. zeek:id:: ZeekygenExample::a_function
+   :source-code: zeekygen/example.zeek 161 161
 
    :Type: :zeek:type:`function` (tag: :zeek:type:`string`, msg: :zeek:type:`string`) : :zeek:type:`string`
 

testing/btest/Baseline/doc.zeekygen.func-params/autogen-reST-func-params.rst

@@ -1,5 +1,6 @@
 ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63.
 .. zeek:id:: test_func_params_func
+   :source-code: <...>/func-params.zeek 11 11
 
    :Type: :zeek:type:`function` (i: :zeek:type:`int`, j: :zeek:type:`int`) : :zeek:type:`string`
 
@@ -14,6 +15,7 @@
    :returns: A string.
 
 .. zeek:type:: test_func_params_rec
+   :source-code: <...>/func-params.zeek 13 21
 
    :Type: :zeek:type:`record`
 

testing/btest/Baseline/doc.zeekygen.identifier/test.rst

@@ -1,5 +1,6 @@
 ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63.
 .. zeek:id:: ZeekygenExample::Zeekygen_One
+   :source-code: zeekygen/example.zeek 59 59
 
    :Type: :zeek:type:`Notice::Type`
 
@@ -7,6 +8,7 @@
    will document "Zeekygen_One".
 
 .. zeek:id:: ZeekygenExample::Zeekygen_Two
+   :source-code: zeekygen/example.zeek 60 60
 
    :Type: :zeek:type:`Notice::Type`
 
@@ -14,11 +16,13 @@
    will document "ZEEKYGEN_TWO".
 
 .. zeek:id:: ZeekygenExample::Zeekygen_Three
+   :source-code: zeekygen/example.zeek 62 62
 
    :Type: :zeek:type:`Notice::Type`
 
 
 .. zeek:id:: ZeekygenExample::Zeekygen_Four
+   :source-code: zeekygen/example.zeek 64 64
 
    :Type: :zeek:type:`Notice::Type`
 
@@ -26,11 +30,13 @@
    it's probably best to use only one style consistently.
 
 .. zeek:id:: ZeekygenExample::LOG
+   :source-code: zeekygen/example.zeek 70 70
 
    :Type: :zeek:type:`Log::ID`
 
 
 .. zeek:type:: ZeekygenExample::SimpleEnum
+   :source-code: zeekygen/example.zeek 78 85
 
    :Type: :zeek:type:`enum`
 
@@ -57,6 +63,7 @@
    It can span multiple lines.
 
 .. zeek:id:: ZeekygenExample::ONE
+   :source-code: zeekygen/example.zeek 81 81
 
    :Type: :zeek:type:`ZeekygenExample::SimpleEnum`
 
@@ -64,29 +71,34 @@
    And can also span multiple lines.
 
 .. zeek:id:: ZeekygenExample::TWO
+   :source-code: zeekygen/example.zeek 82 82
 
    :Type: :zeek:type:`ZeekygenExample::SimpleEnum`
 
    Or this style is valid to document the preceding enum value.
 
 .. zeek:id:: ZeekygenExample::THREE
+   :source-code: zeekygen/example.zeek 83 83
 
    :Type: :zeek:type:`ZeekygenExample::SimpleEnum`
 
 
 .. zeek:id:: ZeekygenExample::FOUR
+   :source-code: zeekygen/example.zeek 89 89
 
    :Type: :zeek:type:`ZeekygenExample::SimpleEnum`
 
    And some documentation for "FOUR".
 
 .. zeek:id:: ZeekygenExample::FIVE
+   :source-code: zeekygen/example.zeek 91 91
 
    :Type: :zeek:type:`ZeekygenExample::SimpleEnum`
 
    Also "FIVE".
 
 .. zeek:type:: ZeekygenExample::SimpleRecord
+   :source-code: zeekygen/example.zeek 97 101
 
    :Type: :zeek:type:`record`
 
@@ -105,6 +117,7 @@
    for enums.
 
 .. zeek:type:: ZeekygenExample::ComplexRecord
+   :source-code: zeekygen/example.zeek 110 117
 
    :Type: :zeek:type:`record`
 
@@ -126,6 +139,7 @@
    General documentation for a type "ComplexRecord" goes here.
 
 .. zeek:type:: ZeekygenExample::Info
+   :source-code: zeekygen/example.zeek 124 128
 
    :Type: :zeek:type:`record`
 
@@ -142,6 +156,7 @@
    (provided they are also @load'ed).
 
 .. zeek:id:: ZeekygenExample::an_option
+   :source-code: zeekygen/example.zeek 132 132
 
    :Type: :zeek:type:`set` [:zeek:type:`addr`, :zeek:type:`addr`, :zeek:type:`string`]
    :Attributes: :zeek:attr:`&redef`
@@ -151,6 +166,7 @@
    The type/attribute information is all generated automatically.
 
 .. zeek:id:: ZeekygenExample::option_with_init
+   :source-code: zeekygen/example.zeek 135 135
 
    :Type: :zeek:type:`interval`
    :Attributes: :zeek:attr:`&redef`
@@ -160,14 +176,16 @@
    More docs can be added here.
 
 .. zeek:id:: ZeekygenExample::a_var
+   :source-code: zeekygen/example.zeek 140 140
 
    :Type: :zeek:type:`bool`
 
    Put some documentation for "a_var" here.  Any global/non-const that
-   isn't a function/event/hook is classified as a "state variable"
+   isn't a function<...>/hook is classified as a "state variable"
    in the generated docs.
 
 .. zeek:id:: ZeekygenExample::var_without_explicit_type
+   :source-code: zeekygen/example.zeek 143 143
 
    :Type: :zeek:type:`string`
    :Default: ``"this works"``
@@ -175,6 +193,7 @@
    Types are inferred, that information is self-documenting.
 
 .. zeek:id:: ZeekygenExample::summary_test
+   :source-code: zeekygen/example.zeek 148 148
 
    :Type: :zeek:type:`string`
 
@@ -183,6 +202,7 @@
    by the table of all identifiers declared by this script.
 
 .. zeek:id:: ZeekygenExample::a_function
+   :source-code: zeekygen/example.zeek 161 161
 
    :Type: :zeek:type:`function` (tag: :zeek:type:`string`, msg: :zeek:type:`string`) : :zeek:type:`string`
 
@@ -202,6 +222,7 @@
    :returns: Describe the return type here.
 
 .. zeek:id:: ZeekygenExample::an_event
+   :source-code: zeekygen/example.zeek 171 171
 
    :Type: :zeek:type:`event` (name: :zeek:type:`string`)
 
@@ -216,11 +237,13 @@
    :name: Describe the argument here.
 
 .. zeek:id:: ZeekygenExample::function_without_proto
+   :source-code: zeekygen/example.zeek 176 184
 
    :Type: :zeek:type:`function` (tag: :zeek:type:`string`) : :zeek:type:`string`
 
 
 .. zeek:type:: ZeekygenExample::PrivateRecord
+   :source-code: zeekygen/example.zeek 190 193
 
    :Type: :zeek:type:`record`
 

testing/btest/Baseline/doc.zeekygen.records/autogen-reST-records.rst

@@ -1,5 +1,6 @@
 ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63.
 .. zeek:type:: TestRecord1
+   :source-code: <...>/records.zeek 6 9
 
    :Type: :zeek:type:`record`
 
@@ -9,6 +10,7 @@
 
 
 .. zeek:type:: TestRecord2
+   :source-code: <...>/records.zeek 12 23
 
    :Type: :zeek:type:`record`
 

testing/btest/Baseline/doc.zeekygen.type-aliases/autogen-reST-type-aliases.rst

@@ -1,17 +1,20 @@
 ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63.
 .. zeek:type:: ZeekygenTest::TypeAlias
+   :source-code: <...>/type-aliases.zeek 9 9
 
    :Type: :zeek:type:`bool`
 
    This is just an alias for a builtin type ``bool``.
 
 .. zeek:type:: ZeekygenTest::NotTypeAlias
+   :source-code: <...>/type-aliases.zeek 12 12
 
    :Type: :zeek:type:`bool`
 
    This type should get its own comments, not associated w/ TypeAlias.
 
 .. zeek:type:: ZeekygenTest::OtherTypeAlias
+   :source-code: <...>/type-aliases.zeek 18 18
 
    :Type: :zeek:type:`bool`
 
@@ -21,18 +24,21 @@
    find out what the actual type is...
 
 .. zeek:id:: ZeekygenTest::a
+   :source-code: <...>/type-aliases.zeek 21 21
 
    :Type: :zeek:type:`ZeekygenTest::TypeAlias`
 
    But this should reference a type of ``TypeAlias``.
 
 .. zeek:id:: ZeekygenTest::b
+   :source-code: <...>/type-aliases.zeek 24 24
 
    :Type: :zeek:type:`ZeekygenTest::OtherTypeAlias`
 
    And this should reference a type of ``OtherTypeAlias``.
 
 .. zeek:type:: ZeekygenTest::MyRecord
+   :source-code: <...>/type-aliases.zeek 26 30
 
    :Type: :zeek:type:`record`
 

testing/btest/Baseline/doc.zeekygen.vectors/autogen-reST-vectors.rst

@@ -1,5 +1,6 @@
 ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63.
 .. zeek:id:: test_vector0
+   :source-code: <...>/vectors.zeek 11 11
 
    :Type: :zeek:type:`vector` of :zeek:type:`string`
    :Default:
@@ -12,6 +13,7 @@
    Yield type is documented/cross-referenced for primitize types.
 
 .. zeek:id:: test_vector1
+   :source-code: <...>/vectors.zeek 14 14
 
    :Type: :zeek:type:`vector` of :zeek:type:`TestRecord`
    :Default:
@@ -24,6 +26,7 @@
    Yield type is documented/cross-referenced for composite types.
 
 .. zeek:id:: test_vector2
+   :source-code: <...>/vectors.zeek 17 17
 
    :Type: :zeek:type:`vector` of :zeek:type:`vector` of :zeek:type:`TestRecord`
    :Default:

testing/btest/doc/zeekygen/enums.zeek

@@ -1,5 +1,5 @@
 # @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT
-# @TEST-EXEC: btest-diff autogen-reST-enums.rst
+# @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-enums.rst
 
 @TEST-START-FILE zeekygen.config
 identifier	TestEnum*	autogen-reST-enums.rst

testing/btest/doc/zeekygen/func-params.zeek

@@ -1,5 +1,5 @@
 # @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT
-# @TEST-EXEC: btest-diff autogen-reST-func-params.rst
+# @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-func-params.rst
 
 @TEST-START-FILE zeekygen.config
 identifier	test_func_params*	autogen-reST-func-params.rst

testing/btest/doc/zeekygen/identifier.zeek

@@ -1,6 +1,6 @@
 # @TEST-PORT: BROKER_PORT
 # @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT
-# @TEST-EXEC: btest-diff test.rst
+# @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff test.rst
 
 @TEST-START-FILE zeekygen.config
 identifier	ZeekygenExample::*	test.rst

testing/btest/doc/zeekygen/records.zeek

@@ -1,5 +1,5 @@
 # @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT
-# @TEST-EXEC: btest-diff autogen-reST-records.rst
+# @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-records.rst
 
 @TEST-START-FILE zeekygen.config
 identifier	TestRecord*	autogen-reST-records.rst

testing/btest/doc/zeekygen/type-aliases.zeek

@@ -1,5 +1,5 @@
 # @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT
-# @TEST-EXEC: btest-diff autogen-reST-type-aliases.rst
+# @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-type-aliases.rst
 
 @TEST-START-FILE zeekygen.config
 identifier	ZeekygenTest::*	autogen-reST-type-aliases.rst

testing/btest/doc/zeekygen/vectors.zeek

@@ -1,5 +1,5 @@
 # @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT
-# @TEST-EXEC: btest-diff autogen-reST-vectors.rst
+# @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-vectors.rst
 
 @TEST-START-FILE zeekygen.config
 identifier	test_vector*	autogen-reST-vectors.rst