search

oasis-tcs / odata-specs

OASIS OData TC: Markdown sources for OData specification drafts. https://github.com/oasis-tcs/odata-specs
https://oasis-tcs.github.io/odata-specs/
Other
6 stars 2 forks source link

Build spec document for OData Vocabularies #1934

Closed HeikoTheissen closed 5 months ago

HeikoTheissen commented 6 months ago

Subfolder odata-vocabularies contains the Markdown necessary for generating a spec document OData Vocabularies. It consists mostly of cross-references to the oasis-tcs/odata-vocabularies repo. This allows building the documents locally, but not in a GitHub action.

ralfhandl commented 6 months ago

Why not place all specs - including the Vocab spec - in the odata-specs repo?

We do already pull vocabs, schemas, and ABNF from other repos into the odata-specs repo when building the ZIP files.

HeikoTheissen commented 6 months ago

Why not place all specs - including the Vocab spec - in the odata-specs repo?

Because then the source for the build step would come from a different repo, which is complicated to achieve in a GitHub action.

ralfhandl commented 6 months ago

which is complicated to achieve in a GitHub action

Why would we want to do this in a GitHub action? We only need to run a build & zip script once we want to publish the document via OASIS, same as the other specs.

HeikoTheissen commented 6 months ago

@ralfhandl, what must go into the front matter, the introduction and the appendix?

ralfhandl commented 6 months ago

Same structure as the other specs

ralfhandl commented 6 months ago

References see https://docs.oasis-open.org/odata/odata-vocabularies/v4.0/csprd01/odata-vocabularies-v4.0-csprd01.html#_Toc472083027

HeikoTheissen commented 6 months ago

References see https://docs.oasis-open.org/odata/odata-vocabularies/v4.0/csprd01/odata-vocabularies-v4.0-csprd01.html#_Toc472083027

The "Normative References" [OData-XXXVoc] make no sense, because the generated document already includes them completely.

ralfhandl commented 6 months ago

@ralfhandl, what must go into the front matter, the introduction and the appendix?

Adjusted