Clean up and revise frontmatter like synopsis

.vitepress/config.js

@@ -164,7 +164,7 @@ config.themeConfig.search = {
         tokenize: text => text.split( /[\n\r #%*,=/:;?[\]{}()&]+/u ), // simplified charset: removed [-_.@] and non-english chars (diacritics etc.)
         processTerm: (term, fieldName) => {
           term = term.trim().toLowerCase().replace(/^\.+/, '').replace(/\.+$/, '')
-          const stopWords = ['frontmatter', '$frontmatter.synopsis', 'and', 'about', 'but', 'now', 'the', 'with', 'you']
+          const stopWords = ['frontmatter', '$frontmatter.description', 'and', 'about', 'but', 'now', 'the', 'with', 'you']
           if (term.length < 2 || stopWords.includes(term))  return false
 
           if (fieldName === 'text') {

.vitepress/theme/components/IndexList.vue

@@ -11,7 +11,7 @@
   <dl class="index" v-else>
     <template v-for="p in pages" :key="p.url">
       <dt><a :href="p.url">{{ p.title }}</a></dt>
-      <dd v-html="p.frontmatter?.synopsis || ''"></dd>
+      <dd v-html="p.frontmatter?.description || ''"></dd>
     </template>
   </dl>
 </template>

.vitepress/theme/components/indexFilter.ts

@@ -31,7 +31,7 @@ export default (pages:ContentDataCustom[], basePath:string):ContentDataCustom[]
       url: p.url,
       title: p.title,
       frontmatter: {
-        synopsis: p.frontmatter.synopsis
+        description: p.frontmatter.description
       },
       // this data is inlined in each index page, so omit unnecessary data
       src:undefined, html:undefined, excerpt:undefined

cds/annotations.md

@@ -1,15 +1,12 @@
 ---
-# layout: cds-ref
-shorty: Annotations
-synopsis: >
+description: >
   Find here a reference and glossary of common annotations intrinsically supported by the CDS compiler and runtimes.
-status: released
 uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/855e00bd559742a3b8276fbed4af1008.html
 ---
 
 # Common Annotations
 
-{{ $frontmatter.synopsis }}
+{{ $frontmatter.description }}
 
 [Learn more about the syntax of annotations.](./cdl#annotations){.learn-more}
 

cds/aspects.md

@@ -1,7 +1,6 @@
 ---
-synopsis: >
+description: >
   Discusses the differences of the mixin-based approach of Aspects to inheritance as known from languages like Java.
-status: released
 ---
 
 # Aspect-Oriented Modeling

cds/cdl.md

@@ -1,7 +1,6 @@
 ---
-# shorty: Definition Language
-synopsis: >
-  Specification of the definition language used to model data models and services in an easy and user-centric syntax. Includes a reference and overview of all CDS concepts and features with compact examples.
+description: >
+  Specification of the definition language used to model data models and services in an easy, user-centric syntax, including a reference and overview of all CDS concepts and features with compact examples.
 #permalink: /cds/cdl/
 uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/855e00bd559742a3b8276fbed4af1008.html
 ---
@@ -285,7 +284,7 @@ CDL supports line-end, block comments, and *doc* comments as in Java and JavaScr
 /** doc comment */
 ```
 
-#### Doc Comments 
+#### Doc Comments
 
 A multi-line comment of the form `/** … */` at an [annotation position](#annotation-targets) is considered a *doc comment*:
 
@@ -451,7 +450,7 @@ type EmailAddress : { kind:String; address:String; }
 
 > Keywords `many` and `array of` are mere syntax variants with identical semantics and implementations.
 
-When deployed to SQL databases, such fields are mapped to [LargeString](./types) columns and the data is stored denormalized as JSON array. 
+When deployed to SQL databases, such fields are mapped to [LargeString](./types) columns and the data is stored denormalized as JSON array.
 With OData V4, arrayed types are rendered as `Collection` in the EDM(X).
 
 
@@ -858,7 +857,7 @@ Result result = service.run(Select.from("UsingView"), params);
 
 ### Runtime Views { #runtimeviews }
 
-To add or update CDS views without redeploying the database schema, annotate them with [@cds.persistence.skip](../guides/databases/cdl-to-ddl#cdspersistenceskip). This advises the CDS compiler to skip generating database views for these CDS views. Instead, CAP resolves them *at runtime* on each request. 
+To add or update CDS views without redeploying the database schema, annotate them with [@cds.persistence.skip](../guides/databases/cdl-to-ddl#cdspersistenceskip). This advises the CDS compiler to skip generating database views for these CDS views. Instead, CAP resolves them *at runtime* on each request.
 
 Runtime views must be simple [projections](#as-projection-on), not using *aggregations*, *join*, *union* or *subqueries* in the *from* clause, but may have a *where* condition if they are only used to read.
 
@@ -934,7 +933,7 @@ entity Addresses {
 ```
 
 
-### Managed (To-One) Associations 
+### Managed (To-One) Associations
 ###### managed-associations
 
 For to-one associations, CDS can automatically resolve and add requisite foreign key elements from the target's primary keys and implicitly add respective join conditions.

cds/common.md

@@ -1,6 +1,5 @@
 ---
-# layout: cds-ref
-synopsis: >
+description: >
   Introduces <i>@sap/cds/common</i>, a prebuilt CDS model shipped with <i>@sap/cds</i> that provides common types and aspects.
 uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/855e00bd559742a3b8276fbed4af1008.html
 ---

cds/compiler/hdbcds-to-hdbtable.md

@@ -1,6 +1,6 @@
 ---
-# layout: cds-ref
-status: released
+description: >
+  Step-by-step instructions for migrating SAP HANA database deployments from the deprecated `hdbcds` format to `hdbtable`.
 ---
 
 # Moving From _.hdbcds_ To _.hdbtable_

cds/compiler/v2.md

@@ -1,18 +1,13 @@
 ---
-shorty: Compiler v2
-synopsis: >
-  This document describes the upgrade to compiler version 2, released March 2021. As both compiler version 1 and version 2 are out of maintenance by now,
-  we expect that all projects have already upgraded. If in doubt, run `cds v` to find out which version of the CAP modules you have in use.
-
-# layout: cds-ref
-status: released
+description: >
+  Describes the upgrade to CDS compiler version 2 (released March 2021), which is now out of maintenance and expected to already be in use by all projects.
 ---
 
 <!-- Keep this page, as _many_ links point to it! -->
 
 # Upgrade to Compiler v2
 
-{{ $frontmatter.synopsis }}
+{{ $frontmatter.description }}
 
 CDS compiler version 2 brings numerous improvements, which allow us to significantly streamline model processing going forward.
 Changes mostly affect internal implementations of the compiler and nonpublic parts of the artifacts produced by the compiler (CSN, EDMX, ...), hence are unlikely to be observed by users of CDS.
@@ -636,7 +631,7 @@ CAP Java supports using CDS models that have been compiled with the CDS complier
 
 For every entity that has *localized* elements the CDS compiler [behind the scenes](../../guides/uis/localized-data#behind-the-scenes) generates a corresponding "texts" entity that holds the translated texts. The name of this entity changes with CDS compiler v2.
 
-::: warning 
+::: warning
 With compiler v1 the "texts" entity is generated with the suffix `_texts`, while the compiler v2 uses the suffix `.texts`!
 :::
 
@@ -711,7 +706,7 @@ CAP Java allows to [provide initial data](../../guides/databases/initial-data) t
 mv bookshop-Books_texts.csv bookshop-Books.texts.csv
 ```
 
-::: warning 
+::: warning
 If a CSV file has already been deployed to a productive SAP HANA schema it can't be renamed any longer. To support this situation cds deploy as well as the CSV data loader in CAP Java still suppport CSV files with a `_texts` suffix.
 :::
 
@@ -754,7 +749,7 @@ In this example, the return type of the `cancel` function is automatically expos
 
 With compiler v1 this change was also reflected in the CSN. With compiler v2 this is not the case any longer.
 
-::: warning 
+::: warning
 If types are used in a service that are defined outside of the service the [generated accessor interface](../../java/cds-data#generated-accessor-interfaces) will change when upgrading from compiler v1 to v2!
 :::
 
@@ -838,7 +833,7 @@ OData, however, does not support anonymous types. Hence, the compiler will autom
 
 In this example the compiler generated the type `Person_emails` in the OData service `hr`.
 
-::: warning 
+::: warning
 If an inline defined type is used in a service the [generated accessor interface](../../java/cds-data#generated-accessor-interfaces) will change (an inner interface is generated) when upgrading from compiler v1 to v2!
 :::
 

cds/cql.md

@@ -1,7 +1,5 @@
 ---
-# layout: cds-ref
-shorty: Query Language
-synopsis: >
+description: >
   Specification of the CDS Query Language (aka CQL) which is an extension of the standard SQL SELECT statement.
 uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/855e00bd559742a3b8276fbed4af1008.html
 ---
@@ -422,14 +420,14 @@ where the corresponding type can be deduced:
 type Status : String enum { open; closed; in_progress; };
 
 entity OpenOrder as projection on Order {
-  
+
   case status when #open        then 0
               when #in_progress then 1 end
     as status_int : Integer,
 
   (status = #in_progress ? 'is in progress' : 'is open')
-    as status_txt : String,  
-    
+    as status_txt : String,
+
 } where status = #open or status = #in_progress;
 ```
 

cds/cqn.md

@@ -1,9 +1,6 @@
 ---
-# layout: cds-ref
-shorty: Query Notation
-synopsis: >
+description: >
   Specification of the Core Query Notation (CQN) format that is used to capture queries as plain JavaScript objects.
-status: released
 ---
 
 # Query Notation (CQN)

cds/csn.md

@@ -1,7 +1,5 @@
 ---
-# layout: cds-ref
-shorty: Schema Notation
-synopsis: >
+description: >
   Specification of CSN, CDS' canonical format for representing CDS models as plain JavaScript objects, similar to <a href="https://json-schema.org" target="_blank" rel="noopener noreferrer">JSON Schema</a>.
 uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/855e00bd559742a3b8276fbed4af1008.html
 ---

cds/cxl.md

@@ -1,5 +1,5 @@
 ---
-synopsis: >
+description: >
   Specification of the CDS Expression Language (CXL) used to capture expressions in CDS.
 ---
 
@@ -121,7 +121,7 @@ This syntax diagram describes the possible expressions:
 > [Operators](#xpr),
 > [Literals](#val),
 > [Functions](#func),
-> 
+>
 > Used in:
 > [Calculated Elements](#in-calculated-elements),
 > [Annotations](#in-annotations),
@@ -249,8 +249,8 @@ Compared to the previous example, we now use the expression directly in the quer
 to calculate the total value of all books in stock.
 
 
-## Path Expressions (`ref`) 
-###### ref 
+## Path Expressions (`ref`)
+###### ref
 
 A `ref` (short for reference) is used to refer to an element within the model.
 It can be used to navigate along path segments. Such a navigation is often
@@ -260,7 +260,7 @@ referred to as a **path expression**.
 
 > Using:
 > [Infix Filters](#infix-filters)
-> 
+>
 > Used in:
 > [Expressions](#expr)
 
@@ -400,15 +400,15 @@ This allows you to specify conditions on subsets of associated entities, enablin
 
 An infix in linguistics refers to a letter or group of letters that are added in the middle of a word to make a new word.
 
-If we apply this terminology to path expressions, an infix filter condition is an expression 
+If we apply this terminology to path expressions, an infix filter condition is an expression
 that is applied to a path segment of a path expression.
 This allows you to filter the target of an association based on certain criteria.
 
 ![](assets/cxl/infix-filter.drawio.svg?raw)
 
 > Using:
 > [Expressions](#expr)
-> 
+>
 > Used in:
 > [Path Expressions](#ref)
 
@@ -554,7 +554,7 @@ As depicted in below excerpt of the syntax diagram for `expr`, CXL supports all
 
 > Using:
 > [Expressions](#expr)
-> 
+>
 > Used in:
 > [Expressions](#expr)
 
@@ -578,7 +578,7 @@ Following table gives an overview of the guaranteed supported operators in CXL:
 > [!tip] Bivalent `==` and `!=` Operators
 > In addition to standard SQL's `=` and `<>` operators, CXL also supports `==` and `!=` as bivalent variants as opposed to the trivalent semantics of `=` and `<>` when it comes to null handling. Learn more about this in the [_Bivalent `==` and `!=` Operators_](../guides/databases/cap-level-dbs#bivalent--and--operators) section of the databases documentation.
 
-> [!tip] Ternary `?:` Operator 
+> [!tip] Ternary `?:` Operator
 > In addition to the standard SQL `case when then` expression, CXL also supports the ternary `?:` operator as a more concise syntax for simple case expressions. Learn more about this in the [_Ternary `?:` Operator_](../guides/databases/cap-level-dbs#ternary--operator) section of the databases documentation.
 
 
@@ -590,7 +590,7 @@ Following table gives an overview of the guaranteed supported operators in CXL:
 
 > Using:
 > [Expressions](#expr)
-> 
+>
 > Used in:
 > [Expressions](#expr)
 

cds/cxn.md

@@ -1,7 +1,5 @@
 ---
-# layout: cds-ref
-shorty: Expressions
-synopsis: >
+description: >
   Specification of the Core Expression Notation (CXN) used to capture expressions as plain JavaScript objects.
 uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/855e00bd559742a3b8276fbed4af1008.html
 ---
@@ -137,10 +135,10 @@ Examples:
 
 ```js
 [dev] cds repl
-> cds.parse.expr(`x<9`)  == 
+> cds.parse.expr(`x<9`)  ==
 {xpr:[ {ref:['x']}, '<', {val:9} ]}
 
-> cds.parse.expr(`x<9 and (y=1 or z=2)`)  == 
+> cds.parse.expr(`x<9 and (y=1 or z=2)`)  ==
 {xpr:[
   {ref:['x']}, '<', {val:9}, 'and', {xpr:[
     {ref:['y']}, '=', {val:1}, 'or', {ref:['z']}, '=', {val:2}

cds/index.md

@@ -1,5 +1,6 @@
 ---
-status: released
+description: >
+  Core Data Services (CDS) is CAP's modeling language for declaratively capturing service definitions, data models, queries, and expressions.
 ---
 
 # Core Data Services (CDS)

cds/models.md

@@ -1,14 +1,12 @@
 ---
-# layout: cds-ref
-synopsis: >
+description: >
   Introduces the fundamental principles of CDS models.
-status: released
 ---
 
 
 # On The Nature of Models
 
-{{ $frontmatter.synopsis }}
+{{ $frontmatter.description }}
 
 
 ## Metaphysics of Languages
@@ -20,17 +18,17 @@ For example, a *data model describes the type structure (commonly also called *'
 
 ### Representations
 
-Models can come in different *representations*, which follow different *syntaxes*. For example, we use the *CDL* syntax for *human-readable* representations of CDS models, while CSN is an *object notation*, that is a special form of *syntax*, used for *machine-readable* representations of CDS models. 
+Models can come in different *representations*, which follow different *syntaxes*. For example, we use the *CDL* syntax for *human-readable* representations of CDS models, while CSN is an *object notation*, that is a special form of *syntax*, used for *machine-readable* representations of CDS models.
 
-::: details On CSN representations... 
+::: details On CSN representations...
 
-We can go one meta-level further and distinguish between different representations of CSN representations: in a Node.js process at runtime they are just native in-memory JavaScript objects, when shared they are serialized to JSON format, which can in turn be translated to YAML, and so forth. When we create CSN objects at runtime, they could be plain JavaScript code. 
+We can go one meta-level further and distinguish between different representations of CSN representations: in a Node.js process at runtime they are just native in-memory JavaScript objects, when shared they are serialized to JSON format, which can in turn be translated to YAML, and so forth. When we create CSN objects at runtime, they could be plain JavaScript code.
 
 :::
 
 ### Reflections
 
-CDS models can be compiled to other languages, that play in the same fields, yet not covering the same information, but rather with some loss of information — we call these '*reflections*'. 
+CDS models can be compiled to other languages, that play in the same fields, yet not covering the same information, but rather with some loss of information — we call these '*reflections*'.
 
 Examples are:
 

cds/types.md

@@ -1,9 +1,6 @@
 ---
-# layout: cds-ref
-shorty: Built-in Types
-synopsis: >
+description: >
   Find here a brief overview of the predefined types shipped with CDS.
-status: released
 ---
 
 

get-started/bookshop.md

@@ -1,5 +1,6 @@
 ---
-notebook: true
+description: >
+  A step-by-step walkthrough building a simple bookshop application to gain hands-on experience with core CAP concepts and best practices.
 uacp: This page is linked from the Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/29c25e504fdb4752b0383d3c407f52a6.html
 ---