docs: documentation improvements (VirusTotal#582)

These commit fixes a few small typos, confusing sentences, and missing examples in the docs.

Author: agreene0

AUTHORS

@@ -8,6 +8,7 @@
 
 # Please keep the list sorted.
 
+Akamai Technologies
 Gen Digital Inc.
 Google Inc.
 Marek Milkovič <milkovic.marek@gmail.com>

CONTRIBUTORS

@@ -26,6 +26,7 @@
 
 # Please keep the list sorted.
 
+Amanda Greene <agreene@akamai.com>
 Jacob Latonis <jlatonis@me.com>
 Marek Milkovič <milkovic.marek@gmail.com>;<marek.milkovic@gendigital.com> 
 Tomáš Ďuriš <duristomas67@gmail.com>

site/content/docs/modules/math.md

@@ -73,6 +73,10 @@ Examples:
 
 Returns the serial correlation for the given string.
 
+Examples:
+
+`math.serial_correlation("BCA")` → `-0.5`
+
 ### mean(offset, size)
 
 Returns the mean for the size bytes starting at offset. When scanning a running
@@ -87,6 +91,10 @@ Examples:
 
 Returns the mean for the given string.
 
+Examples:
+
+`math.mean("ABCABC")` → `66.0`
+
 ### deviation(offset, size, mean)
 
 Returns the deviation from the mean for the size bytes starting at offset. When
@@ -111,7 +119,7 @@ comparisons are inclusive.
 
 Examples:
 
-`math.in_range(math.deviation(0, filesize, math.MEAN_BYTES), 63.9, 64,1)`
+`math.in_range(math.deviation(0, filesize, math.MEAN_BYTES), 63.9, 64.1)`
 
 ### max(int, int)
 
@@ -185,7 +193,9 @@ Converts the given integer to a string. Note: integers in YARA are signed.
 
 Examples:
 
-`math.to_string(10) == "10" Example: math.to_string(-1) == "-1"`
+`math.to_string(10) == "10"`
+
+`math.to_string(-1) == "-1"`
 
 ### to_string(int, base)
 

site/content/docs/writing_rules/external_variables.md

@@ -18,22 +18,22 @@ seo:
   noindex: false # false (default) or true
 ---
 
-External variables enable rules to depend on dynamic values from external
-sources. For instance, consider the following rule:
+Rules can reference external variables that are defined at compile time.
+For instance, consider the following rule:
 
-```
+```yara
 rule VariableExample1 {
     condition:
         ext_var == 10
 }
 ```
 
-Here, `ext_var` is an external variable whose value is determined at
-run-time. External variables can be integers, strings, or booleans, depending
-on their assigned value.
+Here, `ext_var` is an external variable that is defined when the rule is
+compiled with the `--define ext_var=VALUE` flag. 
 
-Integer variables can replace integer constants in conditions, while boolean
-variables can act as boolean expressions. For example:
+External variables can be integers, strings, or booleans. Integer variables can
+replace integer constants in conditions, while boolean variables can act as
+boolean expressions. For example:
 
 ```yara
 rule VariableExample2 {
@@ -42,6 +42,9 @@ rule VariableExample2 {
 }
 ```
 
+The above rule may be compiled with the flags 
+`-d bool_ext_var=true -d int_ext_var=100` for example.
+
 External variables of type `string` can be used with any operators that works
 on strings, like `contains`, `startswith`, `endswith`, etc. Let's see some
 examples:
@@ -73,12 +76,15 @@ rule MatchesExample {
 }
 ```
 
-Every external variable used in your rules must be defined when the rules
-are being compiled. This can be done using the `--define` option (or `-d`) in
+The rules above could be compiled with the flag `-d string_ext_var=\"Hello\"`
+for example.
+
+Every external variable used in your rules must be defined at compile time.
+This can be done using the `--define VAR=VALUE` option (or `-d VAR=VALUE`) in
 the command-line tool, or by using the appropriate API.
-(like [this one](
+(Like [this one](
 https://docs.rs/yara-x/latest/yara_x/struct.Compiler.html#method.define_global)
 in Rust or
 [this one]({{< ref "python.md" >}}#define_globalidentifier-value)
-in Python).
+in Python.)
 

site/content/docs/writing_rules/text_patterns.md

@@ -87,17 +87,16 @@ rule WideCharTextExample2 {
 }
 ```
 
-The `ascii` modifier can appear alone, without an accompanying `wide` modifier,
-but it's not necessary to write it because in absence of `wide` the string is
-assumed to be ASCII by default.
+Using the `ascii` modifier without `wide` is allowed but unnecessary; strings
+without `wide` are assumed to be ASCII by default.
 
 ## "xor" modifier
 
 The `xor` modifier can be used to search for strings that are XORed with a
 single byte.
 
-The following rule will search for every single byte XOR applied to the string "
-This program cannot" (including the plaintext string):
+The following rule will search for every single byte XOR applied to the string
+"This program cannot" (including the plaintext string):
 
 ```yara
 rule XorExample1 {
@@ -210,15 +209,13 @@ RoaXMgcHJvZ3JhbSBjYW5ub3
 UaGlzIHByb2dyYW0gY2Fubm90
 ```
 
-The `base64wide` modifier works just like the `base64` modifier but the results
-of the `base64` modifier are converted to wide.
+The `base64wide` modifier converts the results of the `base64` modifier to
+`wide` format.
 
-The interaction between `base64` (or `base64wide`) and `wide` and `ascii` is as
-you might expect. `wide` and `ascii` are applied to the string first, and then
-the `base64` and `base64wide` modifiers are applied. At no point is the
-plaintext of the `ascii` or `wide` versions of the strings included in the
-search. If you want to also include those you can put them in a secondary
-pattern.
+First, `wide` and `ascii` are applied to the string, then the `base64` and
+`base64wide` modifiers are applied. The plaintext versions of the `ascii` or
+`wide` strings are never included in the search. If you want to include
+the plaintext string, put it in a second pattern.
 
 The `base64` and `base64wide` modifiers also support a custom alphabet. For
 example:
@@ -234,11 +231,11 @@ rule Base64Example2 {
 
 The alphabet must be 64 bytes long.
 
-The `base64` and `base64wide` modifiers are only supported for text patterns
-that are at least 3 bytes long. Using these modifiers with a hex patterns,
-regular expression, or text patterns that are too short, will cause a compiler
-error. Also, the `xor`, `fullword`, and `nocase` modifiers used in combination
-with `base64` or `base64wide` will cause a compiler error.
+The `base64` and `base64wide` modifiers are only supported for patterns that
+are at least 3 bytes long. Using these modifiers with a hex pattern, regular
+expression, or text pattern that is too short will cause a compiler error. Also,
+the `xor`, `fullword`, and `nocase` modifiers used in combination with `base64`
+or `base64wide` will cause a compiler error.
 
 {{< callout title="Incompatibility notice">}}