Merge pull request #542 from jvalue/545-consistent-writing-style-in-docs

Make writing style in docs more consistent

apps/docs/docs/dev/04-guides/05-standard-library.md

@@ -3,7 +3,7 @@ title: Working with the Standard Library
 sidebar_position: 5
 ---
 
-Jayvee ships with its own standard library on board, including the most often used valuetypes, transformations, and so on.
+Jayvee ships with its own standard library on board, including the most often used _value types_, transformations, and so on.
 The standard library itself is written in `.jv` files [here](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/).
 
 ## Standard Library Contents
@@ -12,23 +12,23 @@ The following elements are part of the standard library:
 
 ## Builtin Contents
 
-The implementations of builtin contents are not expressed in Jayvee itself but on the TypeScript layer. Examples:
+The implementations of built-in contents are not expressed in Jayvee itself but on the TypeScript layer. Examples:
 
-- **Builtin valuetypes**: These valuetypes are the base for defining user-defined value types in Jayvee, e.g., `text`, `integer`, `decimal`, `boolean`.
-- **Builtin iotypes**: These iotypes are used to describe in inputs and outputs of blocktypes, e.g., `Sheet`, `File`.
-- **Builtin blocktypes**: These blocktypes are the very basic building blocks in Jayvee, e.g., `HttpExtractor`, `SqliteLoader`.
-- **Builtin constraint types**: These constraint types are constraints with custom logic, e.g., `LengthConstraint`, `RegexConstraint`.
+- **Builtin value types**: These _value types_ are the base for defining user-defined _value types_ in Jayvee, e.g., `text`, `integer`, `decimal`, `boolean`.
+- **Builtin io types**: These _io types_ are used to describe in inputs and outputs of _block types_, e.g., `Sheet`, `File`.
+- **Builtin block types**: These _block types_ are the very basic building _blocks_ in Jayvee, e.g., `HttpExtractor`, `SqliteLoader`.
+- **Builtin constraint types**: These _constraint types_ are constraints with custom logic, e.g., `LengthConstraint`, `RegexConstraint`.
 
 Builtin definitions are usually generated and added to the standard library from the internal representations of the concepts.
 
 ### User-defined Contents
 
 The implementations of user-defined contents are expressed in Jayvee itself. Examples:
 
-- **User-defined valuetypes**: These valuetypes are based on builtin or other user-defined value types. Their definition is expressed natively in Jayvee, e.g., `Percent`.
-- **User-defined blocktypes**: These blocktypes are based on builtin or other user-defined blocktypes. Their definition is expressed natively in Jayvee.
+- **User-defined value types**: These _value types_ are based on built-in or other user-defined _value types_. Their definition is expressed natively in Jayvee, e.g., `Percent`.
+- **User-defined block types**: These _block types_ are based on built-in or other user-defined _block types_. Their definition is expressed natively in Jayvee.
 
-We use `jv` files to add user-defined valuetypes to the standard library (see below).
+We use `jv` files to add user-defined _value types_ to the standard library (see below).
 
 ## Extending the Standard Library
 
@@ -42,7 +42,7 @@ We use code generation to transform these `.jv` files into TypeScript files that
 
 ### 2. Builtin libraries
 
-The solution we chose to implement the standard library mechanism is close to the [builtin library tutorial](https://langium.org/guides/builtin-library/) by Langium. The following components are of interest:
+The solution we chose to implement the standard library mechanism is close to the [built-in library tutorial](https://langium.org/guides/builtin-library/) by Langium. The following components are of interest:
 
 - [JayveeWorkspaceManager](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/lib/builtin-library/jayvee-workspace-manager.ts) in the `language-server` that registers all libraries with the langium framework.
 - [StandardLibraryFileSystemProvider](https://github.com/jvalue/jayvee/tree/main/apps/vs-code-extension/src/standard-library-file-system-provider.ts) in the `vs-code-extension` that registers all libraries with the vscode plugin framework.

apps/docs/docs/dev/04-guides/06-jayvee-extensions.md

@@ -86,9 +86,9 @@ export class StdExecExtension extends JayveeExecExtension {
 
 ### Add a new block type in a Jayvee extension
 
-#### 1. Create a builtin blocktype
+#### 1. Create a built-in block type
 
-Define the syntax of the new blocktype in the [language server's builtin blocktypes](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/builtin-blocktypes).
+Define the syntax of the new _block type_ in the [language server's built-in _block types_](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/builtin-blocktypes).
 
 The following example defines a block type `MyExtractor` with a text property called `url` and a property `retries` with a default value:
 
@@ -166,7 +166,7 @@ export class MyExtractorExecutor
 > The interface `BlockExecutor<I,O>` is used as an API for block executors. The abstract class `AbstractBlockExecutor<I,O>` gives some further functionality for free, e.g., debug logging.
 
 > **Warning**
-> The generic types of `AbstractBlockExecutor<I,O>` need to match the input and output types of the corresponding `blocktype` definition.
+> The generic types of `AbstractBlockExecutor<I,O>` need to match the input and output types of the corresponding _block type_ definition.
 
 #### 4. Register the new `BlockExecutor` in the execution extension
 

apps/docs/docs/user/block-types/_category_.json

@@ -3,6 +3,6 @@
   "position": 3,
   "link": {
     "type": "generated-index",
-    "description": "These blocks are shipped with Jayvee and are available right out of the box."
+    "description": "These block types are shipped with Jayvee and are available right out of the box."
   }
 }

apps/docs/docs/user/composite-blocks.md → apps/docs/docs/user/composite-block-types.md

@@ -2,21 +2,24 @@
 sidebar_position: 4
 ---
 
-# Composite Blocks
+# Composite Block Types
 
-Composite blocks are a way to create new blocktypes in Jayvee by combining the functionality of existing blocks and pipes. By relying on composite blocks instead of implementing more builtin blocks in a language interpreter, Jayvee supports easy extension by users.
+_Composite block types_ are a way to create new _block types_ in Jayvee by combining the functionality of existing _blocks_ and _pipes_. By relying on _composite block types_ instead of implementing more _built-in block types_ in a language interpreter, Jayvee supports easy extension by users.
 
-Composite blocks define:
-- with the `property` keyword: properties with a name and [value type](./core-concepts.md#valuetypes), optionally a default value
-- with the `input` keyword: one input with a name and io type (that can be None)
-- with the `output` keyword: one output with a name and io type (that can be None)
-- one pipeline definition, starting from the input (using its name) and ending in the output (again using its name)
-- all blocks that are used in the pipeline definition (either builtin or other composite blocks)
+_Composite block types_ define:
+
+- with the `property` keyword: properties with a name and [value type](<./core-concepts.md#value types>), optionally a default value
+- with the `input` keyword: one input with a name and _io type_ (that can be `None`)
+- with the `output` keyword: one output with a name and _io type_ (that can be `None`)
+- one _pipeline_ definition, starting from the input (using its name) and ending in the output (again using its name)
+- all _blocks_ that are used in the _pipeline_ definition (either _blocks_ of _built-in_ or _composite block types_)
 
 ## Example
-As an example, the common use-case of extracting a CSV file from a webserver using HTTP. With builtin blocks, a pipeline would start with a HttpExtractor source that downloads a file from the internet and outputs a binary file. This file must be interpreted as text (using a TextFileInterpreter) and finally as Sheet (using a CSVInterpreter). 
 
-### Implementation with builtin blocks
+As an example, the common use-case of extracting a CSV file from a web server using HTTP. With _built-in block types_, a _pipeline_ would start with a `HttpExtractor` source that downloads a file from the internet and outputs a binary file. This file must be interpreted as text (using a `TextFileInterpreter`) and finally as `Sheet` (using a `CSVInterpreter`).
+
+### Implementation with built-in block types
+
 ```mermaid
 flowchart LR
     A[HttpExtractor] --> B(TextFileInterpreter)
@@ -25,13 +28,13 @@ flowchart LR
     D --> E[SQLiteSink]
 ```
 
-A pipeline with builtin blocks is very verbose:
+A _pipeline_ with _blocks_ using _built-in block types_ is very verbose:
 
 ```jayvee
 pipeline CarsPipeline {
 	CarsExtractor
         -> CarsTextFileInterpreter
-	    -> CarsCSVInterpreter 
+	    -> CarsCSVInterpreter
 	   	-> CarsTableInterpreter
 		-> CarsLoader;
 
@@ -48,12 +51,12 @@ pipeline CarsPipeline {
 }
 ```
 
-### Refactoring using composite blocks
+### Refactoring using composite block types
 
-The common use-case of downloading a CSV file using HTTP can be refactored into a composite block. Note that we define all properties of the builtin blocks that are used as properties of the new CSVExtractor blocktype (but add fallback values). If some internal configuration is always the same, we could also not expose it as a property of the new blocktype.
+The common use-case of downloading a CSV file using HTTP can be refactored into a _composite block type_. Note that we define all properties of the _built-in blocks_ that are used as properties of the new `CSVExtractor` _block type_ (but add fallback values). If some internal configuration is always the same, we could also not expose it as a property of the new _block type_.
 
 ```jayvee
-// Define a new blocktype named CSVExtractor outside of the pipeline
+// Define a new composite block type named CSVExtractor outside of the pipeline
 composite blocktype CSVExtractor {
     // Properties of the CSVExtractor, some with default values
     property url oftype text;
@@ -84,7 +87,7 @@ composite blocktype CSVExtractor {
 }
 ```
 
-With the new CSVExtractor composite blocktype, the pipeline now looks like this.
+With the new `CSVExtractor` _composite block type_, the _pipeline_ now looks like this.
 
 ```mermaid
 flowchart LR
@@ -97,7 +100,7 @@ flowchart LR
 end
 ```
 
-If the CSVExtractor is available in the scope of the `CarsPipeline` from before (e.g., by defining it above the pipeline), it can then be used to shorten the actual pipeline code.
+If the `CSVExtractor` is available in the scope of the `CarsPipeline` from before (e.g., by defining it above the _pipeline_), it can then be used to shorten the actual _pipeline_ code.
 
 ```jayvee
 pipeline CarsPipeline {
@@ -112,4 +115,4 @@ pipeline CarsPipeline {
 
     // ... further block definitions
 }
-```
+```

apps/docs/docs/user/constraint-types/_category_.json

@@ -3,6 +3,6 @@
   "position": 6,
   "link": {
     "type": "generated-index",
-    "description": "These constraints are shipped with Jayvee and are available right out of the box."
+    "description": "These constraint types are shipped with Jayvee and are available right out of the box."
   }
 }

apps/docs/docs/user/core-concepts.md

@@ -4,13 +4,13 @@ sidebar_position: 2
 
 # Core Concepts
 
-The core concepts of Jayvee are `Pipelines`, `Blocks`, and `ValueTypes`.
+The core concepts of Jayvee are _pipelines_, _blocks_, and _value types_.
 
 ## Pipelines
 
-A `Pipeline` is a sequence of different computing steps, the `Blocks`.
-The default output of a block becomes the default input of the next block, building a chain of computing steps.
-In the scope of a `Pipeline`, you can connect these blocks via the `pipe` syntax:
+A _pipeline_ is a sequence of different computing steps, the _blocks_.
+The default output of a _block_ becomes the default input of the next _block_, building a chain of computing steps.
+In the scope of a _pipeline_, you can connect these _blocks_ via the _pipe_ syntax:
 
 ```jayvee
 pipeline CarsPipeline {
@@ -26,14 +26,14 @@ pipeline CarsPipeline {
 
 ## Blocks
 
-A `Block` is a processing step within a `Pipeline`.
+A _block_ is a processing step within a _pipeline_.
 It can have a default input and a default output.
-We differentiate the following types of `Blocks`:
-- `ExtractorBlocks` do not have a default input but only a default output. They model a **data source**.
-- `TransformatorBlocks` have a default input and a default output. They model a **transformation**.
-- `LoaderBlocks` do have a default input but nor a default output. They model a **data sink**.
+We differentiate the following types of _blocks_:
+- _Extractor blocks_ do not have a default input but only a default output. They model a **data source**.
+- _Transformator blocks_ have a default input and a default output. They model a **transformation**.
+- _Loader blocks_ do have a default input but nor a default output. They model a **data sink**.
 
-The general structure of a `Pipeline` consisting of different blocks is the following:
+The general structure of a _pipeline_ consisting of different blocks is the following:
 
 ```mermaid
 flowchart LR
@@ -42,8 +42,8 @@ flowchart LR
     C --> D(LoaderBlock)
 ```
 
-The common syntax of blocks is at its core a key-value map to provide configuration to the block.
-The availability of property keys and their respective `ValueTypes` is determined by the type of the `Block` - indicated by the identifier after the keyword `oftype`:
+The common syntax of _blocks_ is at its core a key-value map to provide configuration to the _block_.
+The availability of property keys and their respective _value types_ is determined by the type of the _block_, called _block type_ - indicated by the identifier after the keyword `oftype`:
 
 ```jayvee
 block GasReserveHttpExtractor oftype HttpExtractor {
@@ -52,20 +52,20 @@ block GasReserveHttpExtractor oftype HttpExtractor {
 } 
 ```
 
-In the example above, the `url` property of type `text` is defined by the corresponding `HttpExtractor` block type.
+In the example above, the `url` property of type `text` is defined by the corresponding `HttpExtractor` _block type_.
 
-Blocks can be either defined as part of the language, called `builtin` or defined as composition of existing blocks by users in Jayvee, called `composite`. See the documentation for [Composite Blocks](./composite-blocks.md).
+_Blocks_ can be either defined as part of the language, called _built-in_ or defined as composition of existing _blocks_ by users in Jayvee, called _composite block types_. See the documentation for [_composite block types_](./composite-block-types.md).
 
-## ValueTypes
+## Value types
 
-A `ValueType` is the definition of a data type of the processed data.
-Some `Blocks` use `ValueTypes` to define logic (like filtering or assessing the data type in a data sink).
-We differentiate the following types of `ValueTypes`:
-- `Built-in ValueTypes` come with the basic version of Jayvee. See [Built-in Valuetypes](./value-types/builtin-value-types).
-- `Primitive ValueTypes` can be defined by the user to model domain-specific data types and represent a single value.
-  `Constraints` can be added to a `Primitive ValueType`.
-See [Primitive Valuetypes](./value-types/primitive-value-types).
-- `Compound ValueTypes`: UPCOMING.
+A _value type_ is the definition of a data type of the processed data.
+Some _blocks_ use _value types_ to define logic (like filtering or assessing the data type in a data sink).
+We differentiate the following kinds of _value types_:
+- _Built-in value types_ come with the basic version of Jayvee. See [built-in value types](./value-types/built-in-value-types).
+- _Primitive value types_ can be defined by the user to model domain-specific data types and represent a single value.
+  _Constraints_ can be added to a _primitive value types_.
+See [primitive value types](./value-types/primitive-value-types).
+- _Compound value types_: UPCOMING.
 
 ```jayvee
 valuetype GasFillLevel oftype integer {
@@ -77,7 +77,7 @@ constraint GasFillLevelRange on decimal:
 ```
 
 ## Transforms
-`Transforms` are used to transform data from one `ValueType` to a different one. For more details, see [Transforms](./transforms.md).
+_Transforms_ are used to transform data from one _value type_ to a different one. For more details, see [transforms](./transforms.md).
 
 ```jayvee
 transform CelsiusToKelvin {

apps/docs/docs/user/expressions.md

@@ -9,7 +9,7 @@ Expressions in Jayvee are arbitrarily nested statements. They consist of:
 - variables (e.g., declared by `from` properties in [Transforms](./transforms.md))
 - operators (e.g., `*` or `sqrt`)
 
-Expressions get evaluated at runtime by the interpreter to a [Built-in ValueType](./value-types/builtin-value-types).
+Expressions get evaluated at runtime by the interpreter to a [built-in _value type_](./value-types/built-in-value-types).
 
 ### Example
 

apps/docs/docs/user/runtime-parameters.md

@@ -4,11 +4,11 @@ sidebar_position: 9
 
 # Runtime Parameters
 
-Property values in Jayvee can be assigned to `values` or left open for later configuration via `runtime parameters`.
+Property values in Jayvee can be assigned to _values_ or left open for later configuration via _runtime parameters_.
 
 ## Syntax
 
-Runtime parameters are indicated by the `requires` keyword, followed by the identifier of the parameter. Example
+_Runtime parameters_ are indicated by the `requires` keyword, followed by the identifier of the parameter. Example
 
 ```jayvee
 block CarsLoader oftype SQLiteLoader {

apps/docs/docs/user/transforms.md

@@ -4,8 +4,8 @@ sidebar_position: 8
 
 # Transforms
 
-Transforms are a concept in Jayvee to define the transformation of individual values.
-They are similar to functions in programming languages, i.e. they perform computations on some input values and produce output values. Transform work by mapping input values to outputs using [expressions](./expressions.md).
+_Transforms_ are a concept in Jayvee to define the transformation of individual values.
+They are similar to functions in programming languages, i.e. they perform computations on some input values and produce output values. _Transforms_ work by mapping input values to outputs using [expressions](./expressions.md).
 
 :::info Important
 
@@ -23,23 +23,23 @@ For the future, it is planned to support arbitrary numbers for outputs as well.
 
 ## Syntax
 
-The general syntax of transforms looks like this:
+The general syntax of _transforms_ looks like this:
 
 ```jayvee
 transform <name> {
-  from <inputName> oftype <inputValuetype>;
-  to <outputName> oftype <outputValuetype>;
+  from <inputName> oftype <inputValueType>;
+  to <outputName> oftype <outputValueType>;
 
   <outputName>: <expression>;
 }
 ```
 
-The `transform` keyword is used to define a transform and give it a name.
-The curly braces denote the body of the transform.
+The `transform` keyword is used to define a _transform_ and give it a name.
+The curly braces denote the body of the _transform_.
 
 The body first contains the definitions of input and output ports.
 Input ports are defined using the `from` keyword whereas output ports use the `to` keyword.
-Next, they are given a name and, after the `oftype` keyword, typed with a valuetype.
+Next, they are given a name and, after the `oftype` keyword, typed with a _value type_.
 
 Below, there needs to be an output assignment for each output port.
 The output assignment defines how a particular output value is computed.
@@ -60,7 +60,7 @@ transform CelsiusToKelvin {
 }
 ```
 
-The following transform converts a text based status into a boolean value, `true` if the text is `Active`, `false` for any other value:
+The following _transform_ converts a text based status into a boolean value, `true` if the text is `Active`, `false` for any other value:
 
 ```jayvee
 transform StatusToBoolean {

apps/docs/docs/user/value-types/.gitignore

@@ -2,4 +2,4 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-only
 
-builtin-value-types.md
+built-in-value-types.md

apps/docs/docs/user/value-types/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "ValueTypes",
+  "label": "Value Types",
   "position": 5,
   "link": {
     "type": "generated-index",