From be0bf2df784f2e6b27b19fbf754b2cf21a0f94f1 Mon Sep 17 00:00:00 2001 From: Matt Jones Date: Mon, 26 Nov 2018 14:13:07 -0800 Subject: [PATCH] Rewrote validity and features sections, and renamed files. Also updated section headings to be clearer. --- docs/_bookdown.yml | 2 +- docs/ch2-spec-overview.md | 4 +- docs/eml-220info.md | 2 +- docs/{ch1-spec-preface.md => eml-features.md} | 56 +++++++------------ 4 files changed, 23 insertions(+), 41 deletions(-) rename docs/{ch1-spec-preface.md => eml-features.md} (61%) diff --git a/docs/_bookdown.yml b/docs/_bookdown.yml index 93d4d709..3908ace3 100644 --- a/docs/_bookdown.yml +++ b/docs/_bookdown.yml @@ -4,9 +4,9 @@ output: documentclass: book rmd_files: ["index.Rmd", "../README.md", + "eml-features.md", "contributors.md", "eml-220info.md", - "ch1-spec-preface.md", "ch2-spec-overview.md", "ch3-spec-architecture.md", "release-notes.md", diff --git a/docs/ch2-spec-overview.md b/docs/ch2-spec-overview.md index 5202a511..9891d077 100644 --- a/docs/ch2-spec-overview.md +++ b/docs/ch2-spec-overview.md @@ -1,6 +1,6 @@ -# Chapter 2. Overview of EML modules and their use +# EML modules and their use -## Module Overview Foreword +## Modules Overview The following section briefly describes each EML module and how they are logically designed in order to document ecological resources. Some of diff --git a/docs/eml-220info.md b/docs/eml-220info.md index 836e1e08..2c7b8b7b 100644 --- a/docs/eml-220info.md +++ b/docs/eml-220info.md @@ -1,4 +1,4 @@ -# Changes and New Features in EML 2.2.0 +# What's New in EML 2.2.0 This document highlights changes and new features in EML 2.2. EML authors should also refer to the affected sections in the normative schema documents diff --git a/docs/ch1-spec-preface.md b/docs/eml-features.md similarity index 61% rename from docs/ch1-spec-preface.md rename to docs/eml-features.md index 0729330c..a86bda93 100644 --- a/docs/ch1-spec-preface.md +++ b/docs/eml-features.md @@ -1,29 +1,10 @@ -# Chapter 1. Preface - -## Introduction - -The Ecological Metadata Language (EML) is a metadata standard developed -by the ecology discipline and for the ecology discipline. It is based on -prior work done by the Ecological Society of America and associated -efforts (Michener et al., 1997, Ecological Applications). EML is -implemented as a series of XML document types that can by used in a -modular and extensible manner to document ecological data. Each EML -module is designed to describe one logical part of the total metadata -that should be included with any ecological dataset. - -## Purpose Statement - -To provide the ecological community with an extensible, flexible, -metadata standard for use in data analysis and archiving that will allow -automated machine processing, searching and retrieval. - -## Features +# Features The architecture of EML was designed to serve the needs of the -ecological community, and has benefitted from previous work in other +research community, and has benefitted from previous work in other related metadata languages. EML has adopted the strengths of many of -these languages, but also addresses a number of short-comings that have -proved to inhibit the automated processing and integration of dataset +these languages, but also addresses a number of shortcomings that have +inhibited the automated processing and integration of dataset resources via their metadata. The following list represents some of the features of EML: @@ -38,29 +19,29 @@ The following list represents some of the features of EML: a detailed soils metadata profile that extends eml-dataset). The intent is to provide a common set of core modules for information exchange, but to allow for future customizations of the language - without the need of going through a lengthy \'approval\' process. + without the need of going through a lengthy approval process. - Detailed Structure: EML strives to balance the tradeoff of too much detail with enough detail to enable advanced services in terms of processing data through the parsing of accompanied metadata. - Therefore, a driving question throughout the design was: \'Will this + Therefore, a driving question throughout the design was: 'Will this particular piece of information be machine-processed, just human - readable, or both?\' Information was then broken down into more + readable, or both?' Information was then broken down into more highly structured elements when the answer involved machine processing. -- Compatibility: EML adopts much of it\'s syntax from the other +- Compatibility: EML adopts much of it's syntax from the other metadata standards that have evolved from the expertise of groups in other disciplines. Whenever possible, EML adopted entire trees of information in order to facilitate conversion of EML documents into other metadata languages. EML was designed with the following standards in mind: Dublin Core Metadata Initiative, the Content - Standard for Digital Geospatial Metadata (CSDGM from the US - geological Survey\'s Federal Geographic Data Committee (FGDC)), the + Standard for Digital Geospatial Metadata (CSDGM from the + Federal Geographic Data Committee (FGDC)), the Biological Profile of the CSDGM (from the National Biological Information Infrastructure), the International Standards - Organization\'s Geographic Information Standard (ISO 19115), the ISO - 8601 Date and Time Standard, the OpenGIS Consortiums\'s Geography + Organization's Geographic Information Standard (ISO 19115), the ISO + 8601 Date and Time Standard, the OpenGIS Consortiums's Geography Markup Language (GML), the Scientific, Technical, and Medical Markup Language (STMML), and the Extensible Scientific Interchange Language (XSIL). @@ -69,15 +50,15 @@ The following list represents some of the features of EML: (XML) known as [XML Schema](http://www.w3.org/XML/Schema), which is a language that defines the rules that govern the EML syntax. XML Schema is an internet recommendation from the [World Wide Web - Consortium](http://www.w3.org), and so a metadata document that is - said to comply with the syntax of EML will structurally meet the + Consortium](http://www.w3.org), and so a metadata document complies + with the syntax of EML will structurally meet the criteria defined in the XML Schema documents for EML. Over and above the structure (what elements can be nested within others, cardinality, etc.), XML Schema provides the ability to use strong data typing within elements. This allows for finer validation of the - contents of the element, not just it\'s structure. For instance, an - element may be of type \'date\', and so the value that is inserted - in the field will be checked against XML Schema\'s definition of a + contents of the element, not just it's structure. For instance, an + element may be of type 'date', and so the value that is inserted + in the field will be checked against XML Schema's definition of a date. Traditionally, XML documents (including previous versions of EML) have been validated against Document Type Definitions (DTDs), which do not provide a means to employ strong validation on field @@ -90,4 +71,5 @@ The following list represents some of the features of EML: model). The normative sections below define the content model and the XML Schema documents distributed with EML define the syntactic implementation. For the foreseeable future, XML Schema will be the - syntactic specification, although it may change later. + syntactic specification, although it is reasonable to create other + syntactic representations of the vocabularly, such as in JSON-LD or RDF.