From 831ac8a0b824291b80322cd6561e5ea5e5b0d886 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Fri, 31 May 2024 17:27:40 -0700 Subject: [PATCH] finished initial cut of links and text --- format-specs/README.md | 44 +++++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/format-specs/README.md b/format-specs/README.md index f57dc8a..e5f0b0c 100644 --- a/format-specs/README.md +++ b/format-specs/README.md @@ -1,33 +1,41 @@ # GeoParquet Standard -The GeoParquet specification is detailed in this directory. For the clearest explanation of what is in the standard see [`geoparquet.md`](geoparquet.md). It is the 'latest' version of the specification, and you can see its version in the [Version and Schema](geoparquet.md#version-and-schema) section of the document. If it has `-dev` in the suffix then it is an unreleased version of the standard. For the stable versions view the `geoparquet.md` file in the git tree tagged in [the releases](https://github.com/opengeospatial/geoparquet/releases), for example [v1.0.0/format-specs/geoparquet.md](https://github.com/opengeospatial/geoparquet/blob/v1.0.0/format-specs/geoparquet.md) +The GeoParquet standard is specified in this directory. For the clearest overview of the requirements see [`geoparquet.md`](geoparquet.md). It is the 'latest' version of the specification, and you can see its version in the [Version and Schema](geoparquet.md#version-and-schema) section of the document. If it has `-dev` in the suffix then it is an unreleased version of the standard. For the stable versions view the `geoparquet.md` file in the git tree tagged in [the releases](https://github.com/opengeospatial/geoparquet/releases), for example [v1.0.0/format-specs/geoparquet.md](https://github.com/opengeospatial/geoparquet/blob/v1.0.0/format-specs/geoparquet.md) for version 1.0.0. -The official OGC standard will often lag behind the markdown document, and the target version can be found in the Preface of the [front material document](sections/clause_0_front_material.adoc). The OGC standard is built from the various other documents in this directory. They are `.adoc` files, in the [asciidoc](https://asciidoc.org/) format. They all automatically get built into a single pdf and published at [docs.ogc.org/DRAFTS/24-013.html](https://docs.ogc.org/DRAFTS/24-013.html) by a cron job running on OGC's infrastructure. The 'official' OGC version will be proposed from that draft, and when accepted by the OGC Technical Committee (TC) will become the official 1.0.0 version of the specification. +The official OGC GeoParquet standard is also contained in this directory, and it will often lag behind the markdown document. The target version of the GeoParquet standard can be found in the Preface of the [front material document](sections/clause_0_front_material.adoc). The OGC standard is built from the various other documents in this directory. They are `.adoc` files, in the [asciidoc](https://asciidoc.org/) format. They all automatically get built into a single pdf and published at [docs.ogc.org/DRAFTS/24-013.html](https://docs.ogc.org/DRAFTS/24-013.html) by a cron job running on OGC's infrastructure. The 'official' OGC version will be proposed from that draft, and when accepted by the OGC Technical Committee (TC) will become the official 1.0.0 version of the specification. [Released versions](https://github.com/opengeospatial/geoparquet/releases) of GeoParquet (from the markdown file in this repository) will not be changed when OGC officially releases GeoParquet 1.0.0, so if changes are needed for OGC approval, then the will be released with a new version number. There will continue to be releases from this repository, which will technically remain 'draft' standards until the OGC TC has officially accepted the next version. ## In this directory -* [`geoparquet.md`](geoparquet.md) - The latest specification overview, which may run ahead of the standard. -* [`document.adoc`](document.adoc) - The main standard document which sets the order of the other sections. -* [sections/](sections/) - Each section of the standard document is a separate document in this folder. -* `figures` - figures go here -* `images` - Image files for graphics go here. Image files for figures go in the `figures` directory. Only place in here images not used in figures (e.g., as parts of tables, as logos, etc.) -* `requirements` - directory for requirements and requirement classes to be referenced in `clause_7_normative_text.adoc` -* `code` - sample code to accompany the standard, if desired -* `abstract_tests` - the Abstract Test Suite comprising one test for every requirement, optional -* `UML` - UML diagrams, if applicable +The key files and folders in this directory are as follows: -More information about the document template is https://github.com/opengeospatial/templates/tree/master/standard#readme[here]. +* [`geoparquet.md`](geoparquet.md) - The latest specification overview, which may run ahead of the standard. It consists of narrative explanations and clear tables for people to get a clear idea of all that needs to be done to implement GeoParquet. +* [`schema.json`](schema.json) - The definitive schema that validates GeoParquet metadata to ensure complaince with the standard. +* [`compatible-parquet.md`](compatible-parquet.md) - A set of guidelines for those would like to produce geospatial Parquet data but are using tools that are not yet fully implementing GeoParquet metadata. Not an official part of the standard. +* [`document.adoc`](document.adoc) - The main standard document which sets the order of the other sections. This is less 'human-readable', as it is designed to be an official 'standard', with specific language to detail testable requirements. +* [`sections/`](sections/) - Each section of the standard document is a separate document in this folder. The order in the official standard is determined by the `document.adoc`. Most of these documents are boilerplate. +* [`sections/clause_6_normative_text.adoc`](sections/clause_6_normative_text.adoc) - The main text of the standard. Similar to the +`geoparquet.md`, but links to the definitive `requirements`. +* [`requirements/`](requirements/) - directory for requirements and requirement classes to be referenced in the normative text. +* [`abstract_tests/`](abstract_tests/) - the Abstract Test Suite comprising one test for every requirement. -An authoring guide is available at https://www.metanorma.org/author/ogc/authoring-guide/[metanorma.org]. +There are a number of other folders, that are currently all empty, but are potentially used for the standard. These are retained for potential future use, but all are currently empty (except for template readmes) -== Authoring the Specification +* [`figures`](figures/) - Any figures needed for the standard go in this folder. +* [`images`](images/) - Image files for graphics in the standard go in this folder. Image files for figures go in the `figures` directory. Only place in here images not used in figures (e.g., as parts of tables, as logos, etc.) +* [`code`](code/) - Sample code to accompany the standard, if desired -== Building +More information about the document template is [here](https://github.com/opengeospatial/templates/tree/master/standard#readme). -Run `docker run -v "$(pwd)":/metanorma -v ${HOME}/.fontist/fonts/:/config/fonts metanorma/metanorma metanorma compile --agree-to-terms -t ogc -x html document.adoc`. +## Authoring the Specification -== Auto built document +An authoring guide is available at [metanorma.org](https://www.metanorma.org/author/ogc/authoring-guide/). -A daily built document is available at https://docs.ogc.org/DRAFTS/[OGC Document DRAFTS]. +## Building the OGC standard + +A local version of the OGC standard can be created by running `docker run -v "$(pwd)":/metanorma -v ${HOME}/.fontist/fonts/:/config/fonts metanorma/metanorma metanorma compile --agree-to-terms -t ogc -x html document.adoc`. + +## Auto built document + +A daily built document is available at [OGC Document DRAFTS](https://docs.ogc.org/DRAFTS/).