Update images grammar spelling xrefs

docs/sources/flow/concepts/configuration_language.md

@@ -13,9 +13,7 @@ weight: 400
 
 # Configuration language concepts
 
-The {{< param "PRODUCT_NAME" >}} _configuration language_ refers to the language used in configuration files that define and configure components to run.
-
-The configuration language is called River, a Terraform/HCL-inspired language:
+The {{< param "PRODUCT_NAME" >}} _configuration language_, River, refers to the language used in configuration files that define and configure components to run.
 
 ```river
 prometheus.scrape "default" {
@@ -32,45 +30,45 @@ prometheus.remote_write "default" {
 }
 ```
 
-River was designed with the following requirements in mind:
+River is designed with the following requirements in mind:
 
 * _Fast_: The configuration language must be fast so the component controller can quickly evaluate changes.
 * _Simple_: The configuration language must be easy to read and write to minimize the learning curve.
 * _Debuggable_: The configuration language must give detailed information when there's a mistake in the configuration file.
 
 ## Attributes
 
-_Attributes_ are used to configure individual settings. They always take the
-form of `ATTRIBUTE_NAME = ATTRIBUTE_VALUE`.
+You use _Attributes_ to configure individual settings.
+Attributes always take the form of `ATTRIBUTE_NAME = ATTRIBUTE_VALUE`.
+
+The following example shows you how to set the `log_level` attribute to `"debug"`.
 
 ```river
 log_level = "debug"
 ```
 
-This sets the `log_level` attribute to `"debug"`.
-
 ## Expressions
 
-Expressions are used to compute the value of an attribute.
+You use expressions to compute the value of an attribute.
 The simplest expressions are constant values like `"debug"`, `32`, or `[1, 2, 3, 4]`.
-River supports more complex expressions, such as:
+River supports complex expressions, for example:
 
 * Referencing the exports of components: `local.file.password_file.content`
 * Mathematical operations: `1 + 2`, `3 * 4`, `(5 * 6) + (7 + 8)`
 * Equality checks: `local.file.file_a.content == local.file.file_b.content`
-* Calling functions from River's standard library: `env("HOME")` (retrieve the value of the `HOME` environment variable)
+* Calling functions from River's standard library: `env("HOME")` retrieves the value of the `HOME` environment variable.
 
-Expressions may be used for any attribute inside a component definition.
+You can use expressions for any attribute inside a component definition.
 
 ### Referencing component exports
 
-The most common expression is to reference the exports of a component like `local.file.password_file.content`.
-A reference to a component's exports is formed by merging the component's name (for example, `local.file`),
+The most common expression is to reference the exports of a component, for example, `local.file.password_file.content`.
+You form a reference to a component's exports by merging the component's name (for example, `local.file`),
 label (for example, `password_file`), and export name (for example, `content`), delimited by period.
 
 ## Blocks
 
-_Blocks_ are used to configure components and groups of attributes.
+You use _Blocks_ to configure components and groups of attributes.
 Each block can contain any number of attributes or nested blocks.
 
 ```river
@@ -81,7 +79,7 @@ prometheus.remote_write "default" {
 }
 ```
 
-This file has two blocks:
+The preceding example has two blocks:
 
 * `prometheus.remote_write "default"`: A labeled block which instantiates a `prometheus.remote_write` component.
   The label is the string `"default"`.
@@ -90,7 +88,7 @@ This file has two blocks:
 
 ## More information
 
-River is documented in detail in [Configuration language][config-docs] section of the {{< param "PRODUCT_NAME" >}} docs.
+Refer to [Configuration language][config-docs] for more information about River.
 
 {{% docs/reference %}}
 [config-docs]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/config-language"

docs/sources/flow/concepts/modules.md

@@ -13,46 +13,48 @@ weight: 300
 
 # Modules
 
-_Modules_ are a way to create {{< param "PRODUCT_NAME" >}} configurations which can be loaded as a component.
+You use _Modules_ to create {{< param "PRODUCT_NAME" >}} configurations that you can load as a component.
 Modules are a great way to parameterize a configuration to create reusable pipelines.
 
 Modules are {{< param "PRODUCT_NAME" >}} configurations which have:
 
-* Arguments: Settings that configure a module.
-* Exports: Named values that a module exposes to the consumer of the module.
-* Components: {{< param "PRODUCT_NAME" >}} Components to run when the module is running.
+* _Arguments_: Settings that configure a module.
+* _Exports_: Named values that a module exposes to the consumer of the module.
+* _Components_: {{< param "PRODUCT_NAME" >}} components to run when the module is running.
 
-Modules are loaded into {{< param "PRODUCT_NAME" >}} by using a [Module loader](#module-loaders).
+You use a [Module loader](#module-loaders) to load Modules into {{< param "PRODUCT_NAME" >}}.
 
-Refer to the documentation for the [argument block][] and [export block][] to learn how to define arguments and exports for a module.
+Refer to [argument block][] and [export block][] to learn how to define arguments and exports for a module.
 
 ## Module loaders
 
-A _Module loader_ is a {{< param "PRODUCT_NAME" >}} component that retrieves a module and runs the components defined inside of it.
+A _Module loader_ is a {{< param "PRODUCT_NAME" >}} component that retrieves a module and runs the defined components.
 
-Module loader components are responsible for the following:
+Module loader components are responsible for the following functions:
 
-* Retrieving the module source to run.
-* Creating a [Component controller][] for the module to run in.
+* Retrieving the module source.
+* Creating a [Component controller][] for the module.
 * Passing arguments to the loaded module.
 * Exposing exports from the loaded module.
 
 Module loaders typically are called `module.LOADER_NAME`.
-The list of module loader components can be found in the list of {{< param "PRODUCT_NAME" >}} [Components][].
 
+{{% admonition type="note" %}}
 Some module loaders may not support running modules with arguments or exports.
-Refer to the documentation for the module loader you are using for more information.
+{{% /admonition %}}
+
+Refer to [Components][] for more information about the module loader components.
 
 ## Module sources
 
-Modules are designed to be flexible and can have their configuration retrieved from anywhere, such as:
+Modules are flexible and you can retrieve their configuration anywhere, such as:
 
 * The local filesystem.
 * An S3 bucket.
 * An HTTP endpoint.
 
-Each module loader component supports different ways of retrieving module.sources.
-The most generic module loader component, `module.string`, can load modules from the export of another {{< param "PRODUCT_NAME" >}} component:
+Each module loader component supports different ways of retrieving `module.sources`.
+The most generic module loader component, `module.string`, can load modules from the export of another {{< param "PRODUCT_NAME" >}} component.
 
 ```river
 local.file "my_module" {
@@ -72,7 +74,7 @@ module.string "my_module" {
 
 ## Example module
 
-This example module manages a pipeline that filters out debug- and info-level log lines that are given to it:
+This example module manages a pipeline that filters out debug-level and info-level log lines:
 
 ```river
 // argument.write_to is a required argument that specifies where filtered
@@ -105,7 +107,7 @@ export "filter_input" {
 }
 ```
 
-The module above can be saved to a file and then used as a processing step before writing logs to Loki:
+You can save the module to a file and then use it as a processing step before writing logs to Loki.
 
 ```river
 loki.source.file "self" {

docs/sources/flow/config-language/_index.md

@@ -42,10 +42,8 @@ BLOCK_NAME {
 }
 ```
 
-> River is similar to HCL, the language Terraform and other Hashicorp projects use.
-> River was inspired by HCL, but is a distinct language with different syntax and features, such as first-class functions.
-
-> For historical context on River was introduced, you can read the original [RFC][].
+[River][RFC] is similar to HCL, the language Terraform and other Hashicorp projects use.
+River was inspired by HCL, but is a distinct language with different syntax and features, such as first-class functions.
 
 * Blocks are a group of related settings and usually represent creating a component.
   Blocks have a name that consist of zero or more identifiers separated by `.`, an optional user label, and a body that contains attributes and nested blocks.

docs/sources/flow/config-language/components.md

@@ -17,12 +17,11 @@ Components are the defining feature of {{< param "PRODUCT_NAME" >}}.
 Components are small, reusable pieces of business logic that perform a single task like retrieving secrets or collecting Prometheus metrics,
 and you can wire them together to form programmable pipelines of telemetry data.
 
-Under the hood, components are orchestrated via the [_component controller_]({{< relref "../concepts/component_controller.md" >}}),
-which is responsible for scheduling them, reporting their health and debug status, re-evaluating their arguments, and providing their exports.
+The [_component controller_]controller[] is responsible for scheduling components, reporting their health and debug status, re-evaluating their arguments, and providing their exports.
 
 ## Configuring components
 
-[Components]({{< relref "../reference/components/_index.md" >}}) are created by defining a top-level River block.
+You create [components][] by defining a top-level River block.
 All components are identified by their name, describing what the component is responsible for, and a user-specified _label_.
 
 ## Arguments and exports
@@ -33,14 +32,14 @@ Most user interactions with components center around two basic concepts, _argume
   They can be any number of attributes or nested unlabeled blocks, some required and some optional.
   Any optional arguments that aren't set take on their default values.
 
-* _Exports_ are zero or more output values that can be referred to by other components and can be of any River type.
+* _Exports_ are zero or more output values that other components can refer to, and they can be of any River type.
 
 The following block defines a `local.file` component labeled "targets".
 The `local.file.targets` component exposes the file `content` as a string in its exports.
 
 The `filename` attribute is a _required_ argument.
 You can also define a number of _optional_ arguments, in this case, `detector`, `poll_frequency`, and `is_secret`,
-which configure how and how often the file should be polled and whether its contents are sensitive or not.
+that configure how and how often the file should be polled and whether its contents are sensitive or not.
 
 ```river
 local.file "targets" {
@@ -80,11 +79,15 @@ prometheus.scrape "default" {
 }
 ```
 
-Every time the file contents change, the `local.file` updates its exports. The new value is provided to the `prometheus.scrape` targets field.
+Every time the file contents change, the `local.file` updates its exports. The new value is given to the `prometheus.scrape` targets field.
 
-Each argument and exported field has an underlying [type]({{< relref "./expressions/types_and_values.md" >}}).
+Each argument and exported field has an underlying [type][].
 River type-checks expressions before assigning a value to an attribute.
-The documentation of each [component]({{< relref "../reference/components/_index.md" >}}) provides more information about the ways that you can wire components together.
+The documentation of each [component][components] provides more information about the ways that you can wire components together.
 
-In the previous example, the contents of the `local.file.targets.content` expression must first be evaluated in a concrete
-value then type-checked and substituted into `prometheus.scrape.default` for it to be configured.
+In the previous example, the contents of the `local.file.targets.content` expression is evaluated to a concrete value.
+The value is type-checked and substituted into `prometheus.scrape.default` where it can be configured.
+
+[components]: {{< relref "../reference/components/_index.md" >}}
+[controller]: {{< relref "../concepts/component_controller.md" >}}
+[type]: {{< relref "./expressions/types_and_values.md" >}}

docs/sources/flow/config-language/expressions/_index.md

@@ -13,13 +13,14 @@ weight: 400
 
 # Expressions
 
-Expressions represent or compute values that can be assigned to attributes within a configuration.
+Expressions represent or compute values that you can assign to attributes within a configuration.
 
 Basic expressions are literal values, like `"Hello, world!"` or `true`.
 Expressions may also do things like [refer to values][] exported by components, perform arithmetic, or [call functions][].
 
-Expressions can be used when configuring any component.
-As all component arguments have an underlying [type][], River type-checks expressions before assigning the result to an attribute.
+You use expressions when you configure any component.
+All component arguments have an underlying [type][].
+River type-checks expressions before assigning the result to an attribute.
 
 [refer to values]: {{< relref "./referencing_exports.md" >}}
 [call functions]: {{< relref "./function_calls.md" >}}

docs/sources/flow/config-language/expressions/operators.md

@@ -13,7 +13,7 @@ weight: 300
 
 # Operators
 
-River uses a set of operators that most should be familiar with.
+River uses a common set of operators.
 All operations follow the standard [PEMDAS][] rule for operator precedence.
 
 ## Arithmetic operators
@@ -44,10 +44,10 @@ Operator | Description
 `>`      | `true` when the left value is greater than the right value.
 `>=`     | `true` when the left value is greater or equal to the right value.
 
-The equality operators `==` and `!=` can be applied to any operands.
+You can apply the equality operators `==` and `!=` to any operands.
 
-On the other hand, for the ordering operators `<` `<=` `>` and `>=`, the two operands must both be _orderable_ and of the same type.
-The results of the comparisons are defined as follows:
+The two operands in ordering operators `<` `<=` `>` and `>=`  must both be _orderable_ and of the same type.
+The results of the comparisons are:
 
 * Boolean values are equal if they're either both true or both false.
 * Numerical (integer and floating-point) values are orderable in the usual way.
@@ -72,11 +72,11 @@ River uses `=` as its assignment operator.
 An assignment statement may only assign a single value.
 Each value must be _assignable_ to the attribute or object key.
 
-* The `null` value can be assigned to any attribute.
-* Numerical, string, boolean, array, function, capsule, and object types are assignable to attributes of the corresponding type.
-* Numbers can be assigned to string attributes with an implicit conversion.
-* Strings can be assigned to numerical attributes, provided that they represent a number.
-* Blocks aren't assignable.
+* You can assign `null` to any attribute.
+* You can assign numerical, string, boolean, array, function, capsule, and object types to attributes of the corresponding type.
+* You can assign numbers to string attributes with an implicit conversion.
+* You can assign strings to numerical attributes if they represent a number.
+* You can't assign blocks.
 
 ## Brackets
 
@@ -86,7 +86,7 @@ Brackets | Description
 `( )`    | Groups and prioritizes expressions.
 `[ ]`    | Defines arrays.
 
-In the following example, you can see the use of curly braces and square brackets to define an object and an array.
+The following example uses curly braces and square brackets to define an object and an array.
 
 ```river
 obj = { app = "agent", namespace = "dev" }

docs/sources/flow/config-language/expressions/referencing_exports.md

@@ -18,16 +18,16 @@ While components can work in isolation, they're more useful when one component's
 building a dependency relationship between the two.
 
 Such references can only appear as part of another component's arguments or a configuration block's fields.
-That means that components can't reference themselves.
+Components can't reference themselves.
 
 ## Using references
 
-These references are built by combining the component's name, label, and named export with dots.
+You build references by combining the component's name, label, and named export with dots.
 
-For example, the contents of a file exported by the `local.file` component labeled `target` might be referenced as `local.file.target.content`.
+For example, you can reference the contents of a file exported by the `local.file` component labeled `target` as `local.file.target.content`.
 Similarly, a `prometheus.remote_write` component instance labeled `onprem` exposes its receiver for metrics on `prometheus.remote_write.onprem.receiver`.
 
-The following example shows this.
+The following example shows some references.
 
 ```river
 local.file "target" {
@@ -46,11 +46,9 @@ prometheus.remote_write "onprem" {
 }
 ```
 
-In the previous example, you wired together a very simple pipeline by writing a few River expressions.
+In the preceding example, you wired together a very simple pipeline by writing a few River expressions.
 
-<p align="center">
-<img src="../../../../assets/flow_referencing_exports_diagram.svg" alt="Flow of example pipeline" width="500" />
-</p>
+![Flow of example pipeline](/media/docs/agent/flow_referencing_exports_diagram.svg)
 
 As with all expressions, once the value is resolved, it must match the [type][] of the attribute it is assigned to.
 While you can only configure attributes using the basic River types,