diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index 0761b4d4..234c835a 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -20,6 +20,10 @@ jobs: uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} + - name: Setup pandoc + uses: nikeee/setup-pandoc@v1 + with: + pandoc-version: 3.1.12.2 - name: npm install, build, and test run: | npm ci diff --git a/lib/README.md b/lib/README.md index da94a6c4..1c2a270e 100644 --- a/lib/README.md +++ b/lib/README.md @@ -65,8 +65,9 @@ If you use [Visual Studio Code](https://code.visualstudio.com/), you can [run th You should also install the recommended extension for [XML Language Support by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml). It will validate the XML files against the official [OData CDSL XML schemas](https://github.com/oasis-tcs/odata-csdl-schemas/tree/main/schemas). -`npm run pages` builds pages that can be deployed to github.io. To test these pages locally, -run `npm run serve-pages`. +`npm run pages` builds pages that can be deployed to github.io. It needs a local installation of +[Pandoc](https://pandoc.org/), version 3.1.12.2 or higher. +To test the built pages locally, run `npm run serve-pages`. Node.js packages with a dependency on `odata-vocabularies` can inherit the page building functionality by including the following in their `package.json`: diff --git a/lib/csdl2markdown.js b/lib/csdl2markdown.js index 589b4c4f..66997c1e 100644 --- a/lib/csdl2markdown.js +++ b/lib/csdl2markdown.js @@ -1,3 +1,5 @@ +const { spawnSync } = require("child_process"); + /** * Converts OData CSDL JSON to Github Flavored Markdown * @@ -659,12 +661,21 @@ module.exports.csdl2markdown = function (filename, csdl, referenced = {}) { * @return {string} Escaped text */ function escape(text) { - return (text || "") - .trim() - .replace(/\n\n/g, "
") - .replace(/\n/g, " ") - .replace(/[ \t]+/g, " ") - .replace(/\|/g, "\\|"); + if (text && /(?<=^|\n)([-+*]|\d+\.) /.test(text)) + return spawnSync( + "pandoc", + ["-f", "gfm+tex_math_dollars", "-t", "html", "--mathjax", "--eol=lf"], + { input: text }, + ) + .stdout.toString() + .replaceAll("\n", " "); + else + return (text || "") + .trim() + .replace(/\n\n/g, "
") + .replace(/\n/g, " ") + .replace(/[ \t]+/g, " ") + .replace(/\|/g, "\\|"); } /** diff --git a/vocabularies/Org.OData.Aggregation.V1.json b/vocabularies/Org.OData.Aggregation.V1.json index 89d59202..59a7a024 100644 --- a/vocabularies/Org.OData.Aggregation.V1.json +++ b/vocabularies/Org.OData.Aggregation.V1.json @@ -62,7 +62,7 @@ "EntityContainer" ], "@Core.Description": "Default support of the `$apply` system query option for all collection-valued resources in the container", - "@Core.LongDescription": "Annotating term [`ApplySupported`](#ApplySupported) for a specific collection-valued resource overrides the default support with the specified properties using PATCH semantics:\n\n- Primitive or collection-valued properties specified in `ApplySupported` replace the corresponding properties specified in `ApplySupportedDefaults`\n\n- Complex-valued properties specified in `ApplySupported` override the corresponding properties specified in `ApplySupportedDefaults` using PATCH semantics recursively\n\n- Properties specified neither in `ApplySupported` nor in `ApplySupportedDefaults` have their default value\n " + "@Core.LongDescription": "Annotating term [`ApplySupported`](#ApplySupported) for a specific collection-valued resource overrides the default support with the specified properties using PATCH semantics:\n- Primitive or collection-valued properties specified in `ApplySupported` replace the corresponding properties specified in `ApplySupportedDefaults`\n- Complex-valued properties specified in `ApplySupported` override the corresponding properties specified in `ApplySupportedDefaults` using PATCH semantics recursively\n- Properties specified neither in `ApplySupported` nor in `ApplySupportedDefaults` have their default value" }, "ApplySupportedBase": { "$Kind": "ComplexType", diff --git a/vocabularies/Org.OData.Aggregation.V1.md b/vocabularies/Org.OData.Aggregation.V1.md index b8c494e4..f39dc5fc 100644 --- a/vocabularies/Org.OData.Aggregation.V1.md +++ b/vocabularies/Org.OData.Aggregation.V1.md @@ -11,21 +11,21 @@ Related to the specification document [OData-Data-Agg-v4.0](http://docs.oasis-op Term|Type|Description :---|:---|:---------- [ApplySupported](./Org.OData.Aggregation.V1.xml#L82:~:text=This entity set or collection supports the `$apply` system query option -[ApplySupportedDefaults](./Org.OData.Aggregation.V1.xml#L88:~:text=Default support of the `$apply` system query option for all collection-valued resources in the container
Annotating term [`ApplySupported`](#ApplySupported) for a specific collection-valued resource overrides the default support with the specified properties using PATCH semantics:
- Primitive or collection-valued properties specified in `ApplySupported` replace the corresponding properties specified in `ApplySupportedDefaults`
- Complex-valued properties specified in `ApplySupported` override the corresponding properties specified in `ApplySupportedDefaults` using PATCH semantics recursively
- Properties specified neither in `ApplySupported` nor in `ApplySupportedDefaults` have their default value -[Groupable](./Org.OData.Aggregation.V1.xml#L309:~:text=Deprecated in favor of [`ApplySupported/GroupableProperties`](#ApplySupported) -[Aggregatable](./Org.OData.Aggregation.V1.xml#L321:~:text=Deprecated in favor of [`ApplySupported/AggregatableProperties`](#ApplySupported) -[CustomAggregate](./Org.OData.Aggregation.V1.xml#L333:~:text=Dynamic property that can be used in the `aggregate` transformation
This term MUST be applied with a Qualifier, the Qualifier value is the name of the dynamic property. The value of the annotation MUST be the qualified name of a primitive type. The aggregated value will be of that type. -[ContextDefiningProperties](./Org.OData.Aggregation.V1.xml#L339:~:text=The annotated property or custom aggregate is only well-defined in the context of these properties
The context-defining properties need either be part of the result entities, or be restricted to a single value by a pre-filter operation. Examples are postal codes within a country, or monetary amounts whose context is the unit of currency. -[LeveledHierarchy](./Org.OData.Aggregation.V1.xml#L346:~:text=Defines a leveled hierarchy (OData-Data-Agg-v4.0, section 5.5.1) -[RecursiveHierarchy](./Org.OData.Aggregation.V1.xml#L350:~:text=Defines a recursive hierarchy (OData-Data-Agg-v4.0, section 5.5.2) -[UpPath](./Org.OData.Aggregation.V1.xml#L523:~:text=The string values of the node identifiers in a path from the annotated node to a start node in a traversal of a recursive hierarchy
This instance annotation occurs in the result set after a `traverse` transformation (OData-Data-Agg-v4.0, section 6.2.2.2). A use case for this is traversal with multiple parents, when this annotation takes as value one parent node identifier followed by one grandparent node identifier and so on. -[AvailableOnAggregates](./Org.OData.Aggregation.V1.xml#L532:~:text=This function is available on aggregated entities if the `RequiredProperties` are still defined +[ApplySupportedDefaults](./Org.OData.Aggregation.V1.xml#L88:~:text=Default support of the `$apply` system query option for all collection-valued resources in the container

Annotating term ApplySupported for a specific collection-valued resource overrides the default support with the specified properties using PATCH semantics:

  • Primitive or collection-valued properties specified in ApplySupported replace the corresponding properties specified in ApplySupportedDefaults
  • Complex-valued properties specified in ApplySupported override the corresponding properties specified in ApplySupportedDefaults using PATCH semantics recursively
  • Properties specified neither in ApplySupported nor in ApplySupportedDefaults have their default value
+[Groupable](./Org.OData.Aggregation.V1.xml#L305:~:text=Deprecated in favor of [`ApplySupported/GroupableProperties`](#ApplySupported) +[Aggregatable](./Org.OData.Aggregation.V1.xml#L317:~:text=Deprecated in favor of [`ApplySupported/AggregatableProperties`](#ApplySupported) +[CustomAggregate](./Org.OData.Aggregation.V1.xml#L329:~:text=Dynamic property that can be used in the `aggregate` transformation
This term MUST be applied with a Qualifier, the Qualifier value is the name of the dynamic property. The value of the annotation MUST be the qualified name of a primitive type. The aggregated value will be of that type. +[ContextDefiningProperties](./Org.OData.Aggregation.V1.xml#L335:~:text=The annotated property or custom aggregate is only well-defined in the context of these properties
The context-defining properties need either be part of the result entities, or be restricted to a single value by a pre-filter operation. Examples are postal codes within a country, or monetary amounts whose context is the unit of currency. +[LeveledHierarchy](./Org.OData.Aggregation.V1.xml#L342:~:text=Defines a leveled hierarchy (OData-Data-Agg-v4.0, section 5.5.1) +[RecursiveHierarchy](./Org.OData.Aggregation.V1.xml#L346:~:text=Defines a recursive hierarchy (OData-Data-Agg-v4.0, section 5.5.2) +[UpPath](./Org.OData.Aggregation.V1.xml#L519:~:text=The string values of the node identifiers in a path from the annotated node to a start node in a traversal of a recursive hierarchy
This instance annotation occurs in the result set after a `traverse` transformation (OData-Data-Agg-v4.0, section 6.2.2.2). A use case for this is traversal with multiple parents, when this annotation takes as value one parent node identifier followed by one grandparent node identifier and so on. +[AvailableOnAggregates](./Org.OData.Aggregation.V1.xml#L528:~:text=This function is available on aggregated entities if the `RequiredProperties` are still defined ## Functions -### [isnode](./Org.OData.Aggregation.V1.xml#L375:~:text= -### [isroot](./Org.OData.Aggregation.V1.xml#L388:~:text= -### [isdescendant](./Org.OData.Aggregation.V1.xml#L401:~:text= -### [isancestor](./Org.OData.Aggregation.V1.xml#L433:~:text= -### [issibling](./Org.OData.Aggregation.V1.xml#L465:~:text= -### [isleaf](./Org.OData.Aggregation.V1.xml#L481:~:text= -### [rollupnode](./Org.OData.Aggregation.V1.xml#L494:~:text=Every instance in the output set of a `groupby` transformation with M `rolluprecursive` operators has M relationships to M nodes in M recursive hierarchies. This function returns the node x with path r to the root in relationship number N. If several such `groupby` transformations are nested, this function refers to the innermost one. -[→](./Org.OData.Aggregation.V1.xml#L520:~:text=Every instance in the output set of a `groupby` transformation with M `rolluprecursive` operators has M relationships to M nodes in M recursive hierarchies. This function returns the node x with path r to the root in relationship number N. If several such `groupby` transformations are nested, this function refers to the innermost one. +[→](./Org.OData.Aggregation.V1.xml#L516:~:text= -## [ApplySupportedBase](./Org.OData.Aggregation.V1.xml#L103:~:text= -## [ApplySupportedType](./Org.OData.Aggregation.V1.xml#L122:~:text= -## [AggregatablePropertyType](./Org.OData.Aggregation.V1.xml#L141:~:text= -## [Transformation](./Org.OData.Aggregation.V1.xml#L159:~:text= -## [AggregationMethod](./Org.OData.Aggregation.V1.xml#L259:~:text=For navigation properties, it counts the distinct entities in the union of all entities related to entities in the input set. For collection-valued primitive properties, it counts the distinct items in the union of all collection values in the input set. +[sum](./Org.OData.Aggregation.V1.xml#L264:~:text=For navigation properties, it counts the distinct entities in the union of all entities related to entities in the input set. For collection-valued primitive properties, it counts the distinct items in the union of all collection values in the input set. -## [RollupType](./Org.OData.Aggregation.V1.xml#L296:~:text= -## [RecursiveHierarchyType](./Org.OData.Aggregation.V1.xml#L354:~:text= -## [HierarchyQualifier](./Org.OData.Aggregation.V1.xml#L363:~:text= -## [AvailableOnAggregatesType](./Org.OData.Aggregation.V1.xml#L535:~:text= -## [NavigationPropertyAggregationCapabilities](./Org.OData.Aggregation.V1.xml#L541:~:text= -## [CustomAggregateType](./Org.OData.Aggregation.V1.xml#L559:~:text= Annotating term [`ApplySupported`](#ApplySupported) for a specific collection-valued resource overrides the default support with the specified properties using PATCH semantics: - - Primitive or collection-valued properties specified in `ApplySupported` replace the corresponding properties specified in `ApplySupportedDefaults` - - Complex-valued properties specified in `ApplySupported` override the corresponding properties specified in `ApplySupportedDefaults` using PATCH semantics recursively - -- Properties specified neither in `ApplySupported` nor in `ApplySupportedDefaults` have their default value - +- Properties specified neither in `ApplySupported` nor in `ApplySupportedDefaults` have their default value diff --git a/vocabularies/Org.OData.Capabilities.V1.json b/vocabularies/Org.OData.Capabilities.V1.json index 059a02e5..1fca2030 100644 --- a/vocabularies/Org.OData.Capabilities.V1.json +++ b/vocabularies/Org.OData.Capabilities.V1.json @@ -1466,7 +1466,7 @@ "EntityContainer" ], "@Core.Description": "Default capability settings for all collection-valued resources in the container", - "@Core.LongDescription": "Annotating a specific capability term, which is included as property in `DefaultCapabilitiesType`, for a specific collection-valued resource overrides the default capability with the specified properties using PATCH semantics:\n\n- Primitive or collection-valued properties specified in the specific capability term replace the corresponding properties specified in `DefaultCapabilities`\n\n- Complex-valued properties specified in the specific capability term override the corresponding properties specified in `DefaultCapabilities` using PATCH semantics recursively\n\n- Properties specified neither in the specific term nor in `DefaultCapabilities` have their default value\n " + "@Core.LongDescription": "Annotating a specific capability term, which is included as property in `DefaultCapabilitiesType`, for a specific collection-valued resource overrides the default capability with the specified properties using PATCH semantics:\n- Primitive or collection-valued properties specified in the specific capability term replace the corresponding properties specified in `DefaultCapabilities`\n- Complex-valued properties specified in the specific capability term override the corresponding properties specified in `DefaultCapabilities` using PATCH semantics recursively\n- Properties specified neither in the specific term nor in `DefaultCapabilities` have their default value" }, "DefaultCapabilitiesType": { "$Kind": "ComplexType", diff --git a/vocabularies/Org.OData.Capabilities.V1.md b/vocabularies/Org.OData.Capabilities.V1.md index 99ce1104..52633cc5 100644 --- a/vocabularies/Org.OData.Capabilities.V1.md +++ b/vocabularies/Org.OData.Capabilities.V1.md @@ -86,7 +86,7 @@ Term|Type|Description [CustomHeaders](./Org.OData.Capabilities.V1.xml#L976:~:text=Custom headers that are supported/required for the annotated resource ([Example](./Org.OData.Capabilities.V1.xml#L978)) [CustomQueryOptions](./Org.OData.Capabilities.V1.xml#L1002:~:text=Custom query options that are supported/required for the annotated resource ([Example](./Org.OData.Capabilities.V1.xml#L1005))
If the entity container is annotated, the query option is supported/required by all resources in that container. [MediaLocationUpdateSupported](./Org.OData.Capabilities.V1.xml#L1054:~:text=Stream property or media stream supports update of its media edit URL and/or media read URL -[DefaultCapabilities](./Org.OData.Capabilities.V1.xml#L1059:~:text=Default capability settings for all collection-valued resources in the container
Annotating a specific capability term, which is included as property in `DefaultCapabilitiesType`, for a specific collection-valued resource overrides the default capability with the specified properties using PATCH semantics:
- Primitive or collection-valued properties specified in the specific capability term replace the corresponding properties specified in `DefaultCapabilities`
- Complex-valued properties specified in the specific capability term override the corresponding properties specified in `DefaultCapabilities` using PATCH semantics recursively
- Properties specified neither in the specific term nor in `DefaultCapabilities` have their default value +[DefaultCapabilities](./Org.OData.Capabilities.V1.xml#L1059:~:text=Default capability settings for all collection-valued resources in the container

Annotating a specific capability term, which is included as property in DefaultCapabilitiesType, for a specific collection-valued resource overrides the default capability with the specified properties using PATCH semantics:

  • Primitive or collection-valued properties specified in the specific capability term replace the corresponding properties specified in DefaultCapabilities
  • Complex-valued properties specified in the specific capability term override the corresponding properties specified in DefaultCapabilities using PATCH semantics recursively
  • Properties specified neither in the specific term nor in DefaultCapabilities have their default value
## [ConformanceLevelType](./Org.OData.Capabilities.V1.xml#L118:~:text= -## [DefaultCapabilitiesType](./Org.OData.Capabilities.V1.xml#L1072:~:text= -## [HttpResponse](./Org.OData.Capabilities.V1.xml#L1123:~:text= Annotating a specific capability term, which is included as property in `DefaultCapabilitiesType`, for a specific collection-valued resource overrides the default capability with the specified properties using PATCH semantics: - - Primitive or collection-valued properties specified in the specific capability term replace the corresponding properties specified in `DefaultCapabilities` - - Complex-valued properties specified in the specific capability term override the corresponding properties specified in `DefaultCapabilities` using PATCH semantics recursively - -- Properties specified neither in the specific term nor in `DefaultCapabilities` have their default value - +- Properties specified neither in the specific term nor in `DefaultCapabilities` have their default value