Merge branch 'main' into java-generic-outbox

about/features.md

@@ -203,7 +203,7 @@ Following is an index of the features currently covered by CAP, with status and
 
 > <sup>1</sup> To speed up development. Not for productive use! <br>
 
-> You can already integrate your database of choice in a project or a contribution level. The last two are meant to further facilitate this by out-of-the-box features in CAP.
+> Note: You can already integrate your database of choice in a project or a contribution level. The last two are meant to further facilitate this by out-of-the-box features in CAP.
 
 <!--| [Migration to SAP HANA Cloud](../guides/databases)            |   <D/>    | <Na/>  | <Na/> |
 | [Streamlined Schema Evolution](../guides/databases)       |   <D/>    | <Na/>  | <Na/> |

about/index.md

@@ -230,7 +230,7 @@ Following is an excerpt of generic features provided:
 
 All data access in CAP is through dynamic queries, which allows clients to request the exact information they really need. These powerful intrinsic querying capabilities are key enablers for **serving requests automatically**.
 
-> The querying-based approach to process data is in strong contrast to Object-Relational Mapping (→ see also *[Related Concepts: CAP != ORM](related#orm)*)
+> Note: The querying-based approach to process data is in strong contrast to Object-Relational Mapping (→ see also *[Related Concepts: CAP != ORM](related#orm)*)
 
 <br>
 

advanced/fiori.md

@@ -79,7 +79,7 @@ For example, you can copy the [SAP Fiori apps from cap/samples](https://github.c
 
 ### From [Incidents Sample](https://github.com/SAP-samples/fiori-elements-incident-management/tree/sampleSolution)
 
-> This is a sample to create an incident management app with SAP Fiori elements for OData V4.
+This is a sample to create an incident management app with SAP Fiori elements for OData V4.
 
 
 ## Fiori Annotations
@@ -159,7 +159,7 @@ The CDS OData Language Server provides a list of context-sensitive suggestions b
 
 To trigger code completion, choose <kbd>⌘</kbd> + <kbd class="space">⎵</kbd> (macOS) or <kbd>Ctrl</kbd> + <kbd class="space">⎵</kbd> (other platforms). The list of suggested values is displayed.
 
-> You can filter the list of suggested values by typing more characters.
+> Note: You can filter the list of suggested values by typing more characters.
 
 Navigate to the desired value using the up or down arrows or your mouse. Accept the highlighted value by pressing <kbd>Enter</kbd> or by clicking the mouse.
 Use code completion to add and change individual values (word-based completion) and to add small code blocks containing annotation structures along with mandatory properties (micro-snippets). In an active code snippet, you can use the <kbd>&#x21e5;</kbd> (tab) key to quickly move to the next tab stop.
@@ -179,11 +179,10 @@ Use code completion to add and change individual values (word-based completion)
 
     ::: tip
     To choose an element of an associated entity, first select the corresponding association from the list and type *. \(period\)*. Elements of associated entity are suggested.
+
+    Note: You can add multiple values separated by comma.
     :::
-
-    > You can add multiple values separated by comma.
-
-
+
    ```cds
    annotate Foo.Bar with @UI : { SelectionFields : [
        description, assignedIndividual.lastName|
@@ -206,7 +205,7 @@ Use code completion to add and change individual values (word-based completion)
    };
    ```
 
-    > For each record type, two kinds of micro-snippets are provided: one containing only mandatory properties and one containing all properties defined for this record \(full record\). Usually you need just a subset of properties. So, you either select a full record and then remove the properties you don't need, or add the record containing only required properties and then add the remaining properties.
+    > Note: For each record type, two kinds of micro-snippets are provided: one containing only mandatory properties and one containing all properties defined for this record \(full record\). Usually you need just a subset of properties. So, you either select a full record and then remove the properties you don't need, or add the record containing only required properties and then add the remaining properties.
 
 6.  Use code completion to add values for the annotation properties.
 
@@ -229,7 +228,7 @@ Use code completion to add and change individual values (word-based completion)
     };
     ```
 
-    > To add values pointing to annotations defined in another CDS source, you must reference this source with the `using` directive. See [The `using` Directive](../cds/cdl#using) for more details.
+    > Note: To add values pointing to annotations defined in another CDS source, you must reference this source with the `using` directive. See [The `using` Directive](../cds/cdl#using) for more details.
 
 
 ##### Example: Annotating Entity Elements
@@ -278,7 +277,7 @@ Validation is performed when you open a _.cds_ file and then is retriggered with
 
 You can view the diagnostic messages by hovering over the highlighted part in the annotation file or by opening the problems panel. Click on the message in the problems panel to navigate to the related place in the annotation file.
 
-> If an annotation value points to the annotation defined in another CDS source, you must reference this source with a `using` directive to avoid warnings. See [The `using` Directive](../cds/cdl#using) for more details.
+> Note: If an annotation value points to the annotation defined in another CDS source, you must reference this source with a `using` directive to avoid warnings. See [The `using` Directive](../cds/cdl#using) for more details.
 
 
 ### Navigation to Referenced Annotations
@@ -287,7 +286,7 @@ CDS OData Language Server enables quick navigation to the definition of referenc
 
 You can navigate to the referenced annotation using the [Peek Definition](#peek-definition) and [Go To Definition](#go-to-definition) features.
 
-> If the referenced annotation is defined in another CDS source, you must reference this source with the `using` directive to enable the navigation. See [The `using` Directive](../cds/cdl#using) for more details.
+> Note: If the referenced annotation is defined in another CDS source, you must reference this source with the `using` directive to enable the navigation. See [The `using` Directive](../cds/cdl#using) for more details.
 
 
 #### Peek Definition { #peek-definition}
@@ -320,7 +319,7 @@ The annotation language server provides quick information for annotation terms,
 -   Is the annotation term/record type/property experimental? Is it deprecated?
 -   Is this annotation property mandatory or optional?
 
-> The exact content depends on the availability in OData vocabularies.
+> Note: The exact content depends on the availability in OData vocabularies.
 
 To view the quick info for an annotation term, record type, or property used in the annotation file, hover your mouse over it. The accompanying documentation is displayed in a hover window, if provided in the respective OData vocabularies.
 
@@ -414,7 +413,9 @@ Annotate the underlying base entity in the base model with `@fiori.draft.enabled
 annotate sap.capire.bookshop.Books with @fiori.draft.enabled;
 ```
 
-> Background: SAP Fiori drafts required single keys of type `UUID`, which isn't the case by default for the automatically generated `_texts` entities (&rarr; [see the _Localized Data_ guide for details](../guides/localized-data#behind-the-scenes)). The `@fiori.draft.enabled` annotation tells the compiler to add such a technical primary key element named `ID_texts`.
+:::info Background
+SAP Fiori drafts required single keys of type `UUID`, which isn't the case by default for the automatically generated `_texts` entities (&rarr; [see the _Localized Data_ guide for details](../guides/localized-data#behind-the-scenes)). The `@fiori.draft.enabled` annotation tells the compiler to add such a technical primary key element named `ID_texts`.
+:::
 
 ::: warning
 Adding the annotation `@fiori.draft.enabled` won't work if the corresponding `_texts` entities contain any entries, because existing entries don't have a value for the new key field `ID_texts`.
@@ -567,7 +568,7 @@ To define what the action actually is doing, you need to write some custom code.
 ```js
 this.on('acceptTravel', req => UPDATE(req._target).with({TravelStatus_code:'A'}))
 ```
-> `req._target` is a workaround that has been [introduced in SFlight](https://github.com/SAP-samples/cap-sflight/blob/685867de9e6a91d61276671e4af7354029c70ac8/srv/workarounds.js#L52). In the future, there might be an official API for it.
+> Note: `req._target` is a workaround that has been [introduced in SFlight](https://github.com/SAP-samples/cap-sflight/blob/685867de9e6a91d61276671e4af7354029c70ac8/srv/workarounds.js#L52). In the future, there might be an official API for it.
 
 Create the buttons, to bring this action onto the UI and make it actionable for the user. There are two buttons: On the overview and in the detail screen. Both are defined in the [_layouts.cds_](https://github.com/SAP-samples/cap-sflight/blob/dfc7827da843ace0ea126f76fc78a6591b325c67/app/travel_processor/layouts.cds) file.
 
@@ -607,7 +608,9 @@ annotate TravelService.Travel with actions {
 ```
 This annotation uses [dynamic expressions](../advanced/odata#dynamic-expressions) to control the buttons for each action. And the status of a travel on the UI is updated, triggered by the `@Common.SideEffects.TargetProperties` annotation.
 
-> If you've the need for a more complex calculation, then the interesting parts in SFLIGHT are [virtual fields in _field-control.cds_](https://github.com/SAP-samples/cap-sflight/blob/dfc7827da843ace0ea126f76fc78a6591b325c67/app/travel_processor/field-control.cds#L10-L16) (also lines 37-44) and [custom code in _travel-service.js_](https://github.com/SAP-samples/cap-sflight/blob/dfc7827da843ace0ea126f76fc78a6591b325c67/srv/travel-service.js#L13-L22).
+:::info More complex calculation
+If you have the need for a more complex calculation, then the interesting parts in SFLIGHT are [virtual fields in _field-control.cds_](https://github.com/SAP-samples/cap-sflight/blob/dfc7827da843ace0ea126f76fc78a6591b325c67/app/travel_processor/field-control.cds#L10-L16) (also lines 37-44) and [custom code in _travel-service.js_](https://github.com/SAP-samples/cap-sflight/blob/dfc7827da843ace0ea126f76fc78a6591b325c67/srv/travel-service.js#L13-L22).
+:::
 
 
 <div id="client-side-validations" />

advanced/hana.md

@@ -49,7 +49,7 @@ Steps to match the signature of a database object in a facade entity:
 * After applying the CDS-to-DB type mapping, check that the types of the facade entity's elements match the types of the database object's columns.
 * For a view, table function, or calculation view with parameters, check that the parameter names and types match, too.
 
-> If a field of that entity is defined as `not null` and you want to disable its runtime check, you can add [`@assert.notNull: false`](../guides/providing-services#assert-notNull). This is important if you want to use, for example [SAP HANA history tables](https://help.sap.com/docs/SAP_HANA_PLATFORM/6b94445c94ae495c83a19646e7c3fd56/d0b2c5142a19405fb912f71782cd0a84.html).
+> Note: If a field of that entity is defined as `not null` and you want to disable its runtime check, you can add [`@assert.notNull: false`](../guides/providing-services#assert-notNull). This is important if you want to use, for example [SAP HANA history tables](https://help.sap.com/docs/SAP_HANA_PLATFORM/6b94445c94ae495c83a19646e7c3fd56/d0b2c5142a19405fb912f71782cd0a84.html).
 
 
 As a result, the database name is defined by the name of the entity or its elements, after applying the SQL name mapping.
@@ -219,7 +219,7 @@ context Bookshop {
 #### Quoted Names
 
 Assume the SQL view with parameters has quoted names. Put a mapping view on top of the existing one that maps all the names, except the parameter names, to plain ones.
-> Names of parameters in SQL views and in table functions can't be quoted.
+> Note: Names of parameters in SQL views and in table functions can't be quoted.
 
 ::: code-group
 ```sql [existing-view-quoted-names.hdbview]

advanced/odata.md

@@ -347,7 +347,7 @@ Rendering a `null` value must be done as dynamic expression:
 
 ### Records
 
-> The `@Some` annotation isn't a valid term definition. The following example illustrates the rendering of record values.
+> Note: The `@Some` annotation isn't a valid term definition. The following example illustrates the rendering of record values.
 
 Record-like source structures are mapped to `<Record>` nodes in EDMX, with primitive types translated analogously to the above:
 
@@ -427,7 +427,7 @@ To overwrite the default, use an explicit `$Type` like shown previously.
 
 ### Collections
 
-> The `@Some` annotation isn't a valid term definition. The following example illustrates the rendering of collection values.
+> Note: The `@Some` annotation isn't a valid term definition. The following example illustrates the rendering of collection values.
 
 Arrays are mapped to `<Collection>` nodes in EDMX and if primitives show up as direct elements of the array, these elements are wrapped into individual primitive child nodes of the resulting collection as is. The rules for records and collections are applied recursively:
 
@@ -456,7 +456,7 @@ Arrays are mapped to `<Collection>` nodes in EDMX and if primitives show up as d
 
 ### References
 
->  The `@Some` annotation isn't a valid term definition. The following example illustrates the rendering of reference values.
+> Note: The `@Some` annotation isn't a valid term definition. The following example illustrates the rendering of reference values.
 
 References in `cds` annotations are mapped to `.Path` properties or nested `<Path>` elements respectively:
 

cds/cdl.md

@@ -251,7 +251,7 @@ entity ![Entity] {
 }
 ```
 
->You can escape `]` by `]]`, for example `![L[C]]R]` which will be parsed as `L[C]R`.
+> You can escape `]` by `]]`, for example `![L[C]]R]` which will be parsed as `L[C]R`.
 
 <span id="calculated-fields"/>
 
@@ -612,7 +612,7 @@ entity Employees {
 This example is equivalent to the [unmanaged example above](#unmanaged-associations), with the foreign
 key element `address_ID` being added automatically upon activation to a SQL database.
 
-> For adding foreign key constraints on database level, see [Database Constraints.](../guides/databases#db-constraints).
+> Note: For adding foreign key constraints on database level, see [Database Constraints.](../guides/databases#db-constraints).
 
 If the target has a single primary key, a default value can be provided.
 This default applies to the generated foreign key element `address_ID`:
@@ -670,7 +670,7 @@ entity Emp2Addr {
 
 ### Compositions
 
-Compositions constitute document structures through 'contained-in' relationships.
+Compositions constitute document structures through _contained-in_ relationships.
 They frequently show up in to-many header-child scenarios.
 
 ```cds
@@ -686,8 +686,9 @@ entity Orders.Items {
 }
 ```
 
-> Essentially, Compositions are the same as _[associations](#associations)_, just with the additional information that this association represents a contained-in relationship so the same syntax and rules apply in their base form.
-
+:::info Contained-in relationship
+Essentially, Compositions are the same as _[associations](#associations)_, just with the additional information that this association represents a _contained-in_ relationship so the same syntax and rules apply in their base form.
+:::
 
 ### Managed Compositions of Aspects {#managed-compositions}
 

cds/common.md

@@ -198,7 +198,7 @@ type Timezone : Association to sap.common.Timezones;
 
 As seen in the previous section, the reuse types `Country`, `Currency`, and `Language` are defined as associations to respective code list entities. They act as code list tables for respective elements in your domain model.
 
-> You rarely have to refer to the code lists in consuming models, but always only do so transitively by using the corresponding reuse types [as shown previously](#code-types).
+> Note: You rarely have to refer to the code lists in consuming models, but always only do so transitively by using the corresponding reuse types [as shown previously](#code-types).
 
 #### Namespace: `sap.common`
 

cds/csn.md

@@ -99,11 +99,13 @@ For the remainder of this spec, you see examples in plain JavaScript representat
 * [`extensions`](#aspects) – an array of unnamed [aspects](#aspects)
 * [`i18n`](#i18n) – a dictionary of dictionaries of [text translations](#i18n)
 
-::: tip
-All properties are optional. For example, one model could contain a few definitions, while another one only contains some extensions.
+::: tip All properties are optional
+For example, one model could contain a few definitions, while another one only contains some extensions.
 :::
 
-> References are case-sensitive. All references in properties like `type` or `target` use exactly the same notation regarding casing as their targets' names. To avoid problems when translating models to case-insensitive environments like SQL databases, avoid case-significant names and references. For example, avoid two different definitions in the same scope whose names only differ in casing, such as `foo` and `Foo`.
+::: info References are case-sensitive
+All references in properties like `type` or `target` use exactly the same notation regarding casing as their targets' names. To avoid problems when translating models to case-insensitive environments like SQL databases, avoid case-significant names and references. For example, avoid two different definitions in the same scope whose names only differ in casing, such as `foo` and `Foo`.
+:::
 
 
 
@@ -652,7 +654,7 @@ Example:
 * `returns` – a [Type Definition](#type-definitions)
   describing the response
 
-> The definition of the response can be a reference to a declared type or the inline definition of a new (structured) type.
+> Note: The definition of the response can be a reference to a declared type or the inline definition of a new (structured) type.
 
 
 

cds/cxn.md

@@ -165,7 +165,7 @@ cds.parse.expr(`exists books[year = 2000]`)  ==//> returns:
 ]}
 ```
 
-> CQN intentionally doesn't aim to _understand_ the individual operators and related expressions. It captures them as arbitrary sequences, in the same lexical structure and order they're written in the source. This 'ignorance' allows us to stay open to any kind of operators and keywords. For example, we can easily express native extensions of underlying database dialects.
+CQN intentionally doesn't aim to _understand_ the individual operators and related expressions. It captures them as arbitrary sequences, in the same lexical structure and order they're written in the source. This 'ignorance' allows us to stay open to any kind of operators and keywords. For example, we can easily express native extensions of underlying database dialects.
 
 As an exception to that rule, CDS supports the ternary conditional operator on source level,
 but immediately converts it to the corresponding CASE expression in CXN: