From 782c8ad72a17a6b74d20144eb8e11d6164a27e73 Mon Sep 17 00:00:00 2001 From: Matt Jones Date: Wed, 21 Nov 2018 16:27:55 -0800 Subject: [PATCH] Initial structure for a Bookdown version of the EML spec. More work to be done to convert the old docbook structure to markdown. See issue #321. --- .gitignore | 13 ++ README.md | 242 +++------------------------ docs/_output.yml | 10 ++ docs/book.bib | 10 ++ docs/{members.md => contributors.md} | 40 ++--- docs/eml-220info.md | 13 +- docs/emldocs.Rproj | 18 ++ docs/index.Rmd | 11 ++ docs/index.md | 43 ----- docs/release-notes.md | 205 +++++++++++++++++++++++ 10 files changed, 309 insertions(+), 296 deletions(-) create mode 100755 docs/_output.yml create mode 100644 docs/book.bib rename docs/{members.md => contributors.md} (69%) create mode 100644 docs/emldocs.Rproj create mode 100644 docs/index.Rmd delete mode 100644 docs/index.md create mode 100644 docs/release-notes.md diff --git a/.gitignore b/.gitignore index ca3270be..95a039f0 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,16 @@ build target .DS_Store _site +.Rproj.user +.RData +.Rhistory +.Rapp.history + +# knitr and R markdown default cache directories +/*_cache/ +/cache/ + +# Temporary files created by R markdown +*.utf8.md +*.knit.md + diff --git a/README.md b/README.md index efdc9e9e..3c526365 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,14 @@ Matthew B. Jones, Margaret O'Brien, Bryce Mecum, Carl Boettiger, Mark Schildhau *Abstract:* The Ecological Metadata Language (EML) defines a comprehensive, vocabulary and a readable XML markup syntax for documenting research data. It is in widespread use in the earth and environmental sciences, and increasingly in other research disciplines as well. EML is a community-maintained specification, and evolves to meet the data documentation needs of researchers who want to openly document, preserve, and share data and outputs. EML includes modules for identifying and citing data packages, for describing the spatial, temporal, taxonomic, and thematic extent of data, for describing research methods and protocols, for describing the structure and content of data within sometimes complex packages of data, and for precisely annotating data with semantic vocabularies. EML includes metadata fields to fully detail data papers that are published in journals specializing in scientific data sharing and preservation. +- **EML 2.2.0 Specification** + - [Read it online](docs/) + - [Download EML](https://knb.ecoinformatics.org/software/dist) - The download consists of the + EML modules, described in the [XML Schema](http://www.w3.org/XML/Schema) language. + In addition, the full documentation on the modules is provided in HTML format. + - [Changes to EML in version 2.1.1](docs/eml-211info.md) + - [EML Frequently Asked Questions (FAQ)](docs/eml-faq.md) + - **Version**: 2.2.0 (**In development, not yet released**) - **DOI**: (**NOT YET ISSUED**) - **Feedback**: [eml-dev@ecoinformatics.org](mailto:eml-dev@ecoinformatics.org) @@ -19,241 +27,39 @@ The Ecological Metadata Language (EML) defines a comprehensive, vocabulary and a - **Validation service**: https://knb.ecoinformatics.org/emlparser/ - **Slack Discussion channel**: #eml on http://slack.nceas.ucsb.edu -- **EML 2.2.0 Specification** - - [Read it online](docs/) - - [Download EML](https://knb.ecoinformatics.org/software/dist) - The download consists of the - EML modules, described in the [XML Schema](http://www.w3.org/XML/Schema) language. - In addition, the full documentation on the modules is provided in HTML format. - -## DOCUMENTATION - -Please see the docs/index.html directory for a list of the relevant documents pertaining to EML. In particular, this release ships with a full version of the EML Specification, which is the definitive document explaining the rules associated with the Ecological Metadata Language. - -## HISTORY OF EML +## History EML was originally based on work done by the [ESA Committee on the Future of Long-Term Ecological Data](https://web.archive.org/web/20040213204322/http://esa.sdsc.edu/FLED/FLED.html) and on a related paper on ecological metadata by Michener et al. (see Michener, William K., et al., 1997. Ecological Applications, "Nongeospatial metadata for the ecological sciences" Vol 7(1). pp. 330-342.). Version 1.0 was released at NCEAS in 1997, with further internal releases of versions 1.2, 1.3, and 1.4, all of which followed the FLED recommendations closely in its content implementation. Version 2 was modified substantially after experience using the specification and from feedback from the ecological community, and versions 2.1 and 2.2 introduce significant new features like internationalization, semantic annotations, and support for data papers. -## VALIDATION +## Validation Some of the rules regarding EML that are important are expressed only in the EML specification, not in the XML Schema files. This is because XML Schema was not able to express some of the constraints that we felt were important to creating a coherent metadata document, particularly with respect to identifiers and references to identifiers. Thus, we have included a EML Validity Parser. It checks both EML rules and the schema rules to be sure an XML document is a valid EML document. It is included with the release, and provided as an online service. See docs/index.html. -## FILES +## Files The files in this directory include a "docs" directory that contains the EML Specification and all documentation for the modules, and an xsd directory with an XML Schema document for each of the modules that make up EML. Also included is a schema for supporting documentation, and an instance document defining standard attribute units for EML. The "lib/sample/eml-sample.xml" file is a sample document illustrating the use of EML. The "test" directory contains a number of sample instance documents used for testing the schemas, and an application for checking document validity under JUnit (see http://junit.org). -## CONTRIBUTORS - -Matthew B. Jones (jones@nceas.ucsb.edu), Chad Berkley (berkley@nceas.ucsb.edu), Jivka Bojilova (bojilova@nceas.ucsb.edu), Dan Higgins (higgins@nceas.ucsb.edu), Chris Jones (cjones@lifesci.ucsb.edu), Corinna Gries (corinna@asu.edu), Peter McCartney (peter.mccartney@asu.edu), James Brunt (jbrunt@lternet.edu), David Blankman (dblankman@lternet.edu), Owen Eddins (oeddins@lternet.edu), Mark Schildhauer (schild@nceas.ucsb.edu), John Harris (harris@nceas.ucsb.edu), Matthew Brooke (brooke@nceas.ucsb.edu), Scott Chapal (scott.chapal@jonesctr.org), Tim Bergsma (tbergsma@kbs.msu.edu), Ken Ramsey (kramsey@jornada.nmsu.edu), Saurabh Garg (sgarg@nceas.ucsb.edu), Margaret O'Brien (mob@msi.ucsb.edu), Mark Servilla (servilla@lternet.edu), James Brunt (brunt@lternet.edu), Bryce Mecum (mecum@nceas.ucsb.edu), Carl Boettiger (cboettig@berkeley.edu), Mitchell Maier, Timothy Whitaker (whiteaker@utexas.edu) - -## RELEASE NOTES -- (see also http://github.com/NCEAS/eml/issues) - -### 2.2.0 - -#### Major New Features - -#### Schema changes: - -### 2.1.1 - -#### Internationalization in EML 2.1.1 -EML 2.1.1 introduces internationalization capabilities that can be used in most -text-based elements. Version 2.1.1 remains backward-compatible with the previous -2.1.0 release. Authors can safely upgrade existing 2.1.0 documents to 2.1.1 -without altering any content, though adding additional language translations is -encouraged. - -By allowing mixed element content, nested translation elements can be included -without altering or introducing ambiguity with respect to EML element -cardinality. Translation elements use standard xml:lang attributes to specify -the language used for their content. Translation elements can be nested such -that child elements may inherit or override the language used by their -ancestors. The top-level EML element may include an xml:lang attribute which -will apply to every element in the document unless a child element includes a -different xml:lang attribute to override the document default. - -Multi-lingual authors of EML should carefully consider their primary target -audience when deciding the default document language. Early adopters should be -aware search tools like Metacat will require custom configuration in order to -search arbitrarily nested translations. - -The internationalization feature allows authors to place any language in -tags nested within most EML text fields. The xml:lang attribute should be used -to explicitly declare the language used. - -Additional documentation and examples are available in the EML specification. -The i18nNonEmptyStringType is used for simple text, while i18nString for more -structured text elements. - -#### Schema changes: - - [76](https://github.com/NCEAS/eml/issues/76): internationalization needed in EML - -### 2.1.0 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) -This release addresses bugs which caused the schema to be invalid with -respect to the W3C specifications using modern validators -(e.g., http://www.w3.org/2001/03/webdata/xsv). Although the changes were minor, -one was incompatible with 2.0 releases, which necessitated the version -number "2.1". In the 2.0 series, the content model for additionalMetadata -included an element `` whose cardinality was 0..many, alongside -``. This construct is non-deterministic, and so a child element -was added to the additionalMetadata section to contain the `` content. -Additionally, several elements of txt:TypeText required additional -definition so that mixed content could be accommodated. These errors -were not apparent with validation software available in 2004-2005, but -were brought to light more recently. Several small changes were made to -the enumeration list and unitTypes for standard units and stmml descriptions -of customUnits. Two elements in the literature schema were allowed to be -optional so that articles-in-press could be described. The named type for -element gRing was changed to GRingType. - -EML makes use of the STMML schema (stmml.xsd) for describing custom units -and describing its included list of standardUnits (unitList). The STMML -schema was also found to be non-deterministic, and the most reasonable fix -for this bug was not compatible with earlier versions. This error -was NOT related to elements used by EML (unitList or unitType). However, -given that authors of EML instance documents may have made use of other -parts of stmml.xsd, it was decided to the advance the namespace used for -stmml-related files to "stmml-1.1", in keeping with the pattern of version -naming in EML. The stmml authors have been contacted. - -- Schema changes: - - 1132: eml.xsd, physical.xsd: fix access rule ambiguities - - 2054: eml.xsd: added the tag to additionalMetadata - - 1154: resource.xsd: required element offline has no required children - - 3480: resource.xsd, physical.xsd: nearly duplicate complexTypes, DistributionType and PhysicalDistributionType - - 3165: resource.xsd: provide a place for a url description - - 3227: coverage.xsd: gRing was declared as GRingPointType, is now GRingType - - 1019: coverage.xsd: altitudeUnits should use eml-unitDictionary - - 3500: coverage.xsd: restrict boundingCoordinates to realistic lat/lon ranges - - 1152: attribute.xsd: dateTime elements are named inconsistently; standarized on dateTime - - 2272: attribute.xsd: base types in BoundsGroup changed to xs:float - - 3051: attribute.xsd: missing units were added to enumeration list to match eml-unitDitionary - - 2568: attribute.xsd, entity.xsd: inconsistent naming of methods elements, standardized to - - 2703: text.xsd: refined element declarations in txt:TextType for para, section; added ulink, citetitle - - 3163: literature.xsd: cardinality of volume and pageRange is now 0..1 - - 3164: literature.xsd: literature needs a contact tree - - 3445: stmml.xsd: non-deterministic - - 2083: stmml.xsd: dimension 'current' was wrongly entered as 'charge' -- Parser : - - 3232: EML parser should use full-schema-checking - - 3836: runEMLParser script should include sax-validate -- Stylesheets: - - 3508: create a stylesheet for EML2.0.x to EML 2.1.0 - - 3590: eml-documentation stylesheet problem with derived content. - - 2048: param attributeindex defined twice in eml-settings.xsl - - 2085: Access control rules adapted for 2.0.1 and 2.1 (currently not shown) - - 2147: EML Stylesheet problem with web address URL's - - 2226: EML2 style sheet double the number of complex delimited f... - - 3492: the word 'unit' should be pluralized by default - - -### 2.0.1 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) -- 249: Update XSLT stylesheets for EML 2.0 modules -- 939: spelling errors for 'its' in index -- 960: parser not correctly parsing tag in additiona... -- 1008: inline element doesn't support character child -- 1017: documentation error in eml-methods -- 1031: enumeratedDomain doesn't define value order for ordinals -- 1035: Technical documentation on eml-methods has an error -- 1124: update precision field definition and cardinality -- 1129: Change temporalCoverage calendarDate type -- 1132: fix access control rule ambiguities -- 1136: kelvin conversion incorrect in unit dictionary -- 1149: BoundsGroup bounds min & max have incorrect cardinality -- 1150: documentation for KeyTypeCode is wrong -- 1151: misspelled element name -- 1153: dateTimeDomain element should be optional -- 1155: Documentation incorrect for dateTimeDomainType bounds -- 1195: tracking bug for 2.0.1 release -- 1233: dateTime formatString Documentation contains incorrect ex... -- 1529: no tag to specify how to handle mutltiple, repeated delimimeters -- 1652: eml-constraint documentation error +## About the EML Project -### 2.0.0 - (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) -- 670: DateTimeDomain id/reference validation -- 924: make date time its own measurement scale -- 661: spell check eml-attribute.xsd and synchronize with unitDi -- 918: example tag in eml:documentation +The EML project is an open source, community oriented project dedicated to providing a high-quality metadata specification for describing data relevant to the ecological discipline. The project is completely comprised of [voluntary project members](docs/contributors.md) who donate their time and experience in order to advance information management for ecology. Project decisions are made by consensus according to the voting procedures described in the [ecoinformatics.org Charter](http://www.ecoinformatics.org/charter.html). -### 2.0.0rc3 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) -- 471: eml spec overview document -- 624: eml-methods/methodsType needs clarification on choice/seq... -- 627: links broken in EML FAQ -- 629: unit conversion coefficients need checking -- 637: attributeDomain should be required -- 638: request for id/ref in attributeDomain -- 654: scope of the unit element -- 655: need better model for numeric domains for attributes -- 625: Cardinality regarding eml-methods should be corrected in ... -- 626: ProcedureStepType schema needs revision to protect sequen... -- 628: eml-physical has lit: rather than cit: references -- 632: broken link in faq -- 634: Documentation of reference elements in the schemas -- 656: physical should be repeatable +We welcome contributions to this work in any form. Individuals who invest substantial amounts of time and make valuable contributions to the development and maintenance of EML (in the opinion of current project members) will be invited to become EML project members according to the rules set forth in the [ecoinformatics.org Charter](http://www.ecoinformatics.org/charter.html). Contributions can take many forms, including the development of the EML schemas, writing documentation, and helping with maintenance, among others. -### RC2 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) -- 568: accommodate of stateful connection information -- 586: resolve validation problem with missing keys -- 588: Remove lineage tags in documentation stylesheets -- 589: eml-coverage: convert element references to types -- 592: fix validation error with xs:anyType -- 594: change cardinality for designDescription and studyAreaDes... -- 596: Proposal: make attribute optional in OtherEntityType. -- 597: In eml-dataTable caseSensitive and orientation are modele... -- 598: literature namespace references are inconsistent -- 599: storageType is repeatable in eml-attribute -- 600: eml-storedProcedure - problems & proposal -- 601: element names in spatial modules do not follow guidelines -- 602: eml-physical fixed textFormat to allow mixed fixed/delimited -- 608: release preparation tasks for EML2.0.0rc2 -- 622: redundancy in eml-physical/binaryRaster +## Development Information -### RC1 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) -- 471: created an EML specification overview document -- 495: created FAQ for EML -- 588: removed lineage tags from documentation stylesheet -- 484: eml-attribute changes to unit and attributeDomain -- 579: fixed eml-docbook validation problems -- 491: eml-coverage changed to correctly import types and to fix singleDateTime model -- 485: eml-physical changed to fix fixed ascii descriptors and distribution -- 477: complexTypes imports changed to consistent model -- 486: fixed spelling errors in eml-constraint -- 492: eml-literature changed for EndNote consistency -- 496: copyright updated throughout -- 557: textual elements changed to use docbook subset define in eml-text.xsd -- 563: changed id types from xs:ID to xs:string to allow numeric ids -- 482: eml-dataset changed to include method element -- 489: eml-protocol completely revised based on feedback, eml-method.xsd created -- 544: eml-attribute storageType and attributeDomain documentation clarified -- 556: format of eml namespaces changed to include ecoinformatics.org -- 539: added additionalInfo and alternateIdentifier to eml-dataTable.xsd -- 568: redesigned DistributionType to allow richer connection descriptions -- 566: changed imports in eml-resource to import resource types not elements -- 567: created eml sample documents and XML validation framework using ant/junit +Developers may be interested in browsing the [source code repository](https://github.com/NCEAS/eml/) that we use in developing EML. This always contains the most recent development version of EML, and therefore may be in flux, or otherwise broken. It is unlikely that it will contain the same files that are in the current release (@version@). Use at your own risk. Write access to this repository is reserved for current project maintainers. Please submit contributions as pull requests. We welcome contributions to this work in any form. Contributions can take many forms, including the development of the EML schemas, writing documentation, and helping with maintenance, among others. Non-project members can contribute by submitting their feedback, revisions, fixes, code, or any other contribution through pull requests at GitHub. Discussion of issues occurs on the [eml-dev@ecoinformatics.org](https://groups.google.com/a/ecoinformatics.org/forum/#!forum/ecoinfoeml-dev) mailing list, or through the [EML Issue Tracking system](http://github.com/NCEAS/eml/issues). The preferred way to submit problems with EML or feature requests is the issue tracking system. -### Beta9 Fixes- -1. Changed packaging concept to use internal id and references instead - of triples -2. Review and revised all modules according to agreed upon changes from - the April, 2002 EML meeting at Sevilleta Field Station +## Older versions (deprecated) -### Beta 8 Fixes- -1. Fixed illegal declaration of type and extension in eml-entity -2. Updated all PNG image files +The following versions are still available for reference purposes, although they have been superseded by the current version (2.2.0). Please make every effort to use the current version. -### Beta 7 Fixes- -1. Added a 'style' subdirectory with a style sheet for most modules - . to translate the metadata to HTML -2. Changed names of coverage elements to be human readable -3. Updated the namespaces to reflect the current version number of EML -4. Added an eml-data module for the in-lining of data. -5. Added the eml module for creating packages all in one file. It is a single - node with a model of ANY so any of the eml modules can be put into it. -6. Numerous bug fixes (see bugzilla.ecoinformatics.org) +- [EML 2.1.1](http://knb.ecoinformatics.org/software/dist/eml-2.1.1.tar.gz) +- [EML 2.1.0](http://knb.ecoinformatics.org/software/dist/eml-2.1.0.tar.gz) +- [EML 2.0.1](http://knb.ecoinformatics.org/software/dist/eml-2.0.1.tar.gz) +- [EML 2.0.0](http://knb.ecoinformatics.org/software/dist/eml-2.0.0.tar.gz) +- [EML 1.4.1](http://knb.ecoinformatics.org/software/dist/eml-1.4.1.tar.gz) ## Copyright and License -Copyright: 1997-2017 Regents of the University of California, - University of New Mexico, and - Arizona State University +Copyright: 1997-2018 Regents of the University of California This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by diff --git a/docs/_output.yml b/docs/_output.yml new file mode 100755 index 00000000..c59c2f50 --- /dev/null +++ b/docs/_output.yml @@ -0,0 +1,10 @@ +bookdown::gitbook: + css: style.css + config: + toc: + collapse: section + before: | +
  • EML Specification
    • +
  • ← Back to main website
    • + after: | +
  • Made with support from NCEAS
    • diff --git a/docs/book.bib b/docs/book.bib new file mode 100644 index 00000000..f52f3d22 --- /dev/null +++ b/docs/book.bib @@ -0,0 +1,10 @@ +@Book{xie2015, + title = {Dynamic Documents with {R} and knitr}, + author = {Yihui Xie}, + publisher = {Chapman and Hall/CRC}, + address = {Boca Raton, Florida}, + year = {2015}, + edition = {2nd}, + note = {ISBN 978-1498716963}, + url = {http://yihui.name/knitr/}, +} diff --git a/docs/members.md b/docs/contributors.md similarity index 69% rename from docs/members.md rename to docs/contributors.md index cb49d02c..a1d1b346 100644 --- a/docs/members.md +++ b/docs/contributors.md @@ -1,21 +1,4 @@ - -# EML Project Maintainers - -[Back to EML Contents](index.html) +# Contributors The EML project is an open source, community oriented project dedicated to providing a high-quality metadata specification @@ -40,27 +23,36 @@ Write access to the EML source code repository is reserved for EML project members. Contributions should be submitted as pull requests, and will be reviewed and merged by an EML project member. -## Current maintainers +## Current contributors + Name | Organization | Email ----|---------------|------ Matthew Jones | NCEAS, UCSB | jones@nceas.ucsb.edu Mark Schildhauer | NCEAS, UCSB | schild@nceas.ucsb.edu Chris Jones | NCEAS, UCSB | cjones@nceas.ucsb.edu Corinna Gries | EDI, UW | gries@ecoinformatics.org -Ken Ramsey | LTER JRN, NMSU | ramsey@ecoinformatics.org -Margaret O'Brien | EDI, UCSB | obrien@ecoinformatics.org -Mark Servilla | EDI, UNM | servilla@ecoinformatics.org +Margaret O'Brien | EDI, UCSB | mob@msi.ucsb.edu +Bryce Mecum | NCEAS, UCSB | mecum@nceas.ucsb.edu +Carl Boettiger |Berkeley | cboettig@berkeley.edu +Mitchell Maier | NCEAS, UCSB | +Timothy Whitaker | | whiteaker@utexas.edu + +## Past contributors -## Past maintainers Name | Organization | Email ----|---------------|------ Chad Berkley | NCEAS, UCSB | berkley@nceas.ucsb.edu +Jivka Bojilova | NCEAS, UCSB | bojilova@nceas.ucsb.edu James Brunt | LTER, UNM | brunt@ecoinformatics.org David Blankman | LTER-Israel, Ma'arg | blankman@ecoinformatics.org +Owen Eddins | LTER LNO, UNM | oeddins@lternet.edu Daniel Higgens | NCEAS, UCSB | higgins@nceas.ucsb.edu Peter McCartney | LTER CAP, ASU | mccartney@ecoinformatics.org Matthew Brooke | NCEAS, UCSB | brooke@ecoinformatics.org +John Harris | NCEAS, UCSB | harris@nceas.ucsb.edu Scott Chapal | Jones Ecological Research Center | chapal@ecoinformatics.org Tim Bergsma | LTER KBS, MSU | bergsma@ecoinformatics.org -Sid Garg | NCEAS, UCSB | sgarg@ecoinformatics.org +Ken Ramsey | LTER JRN, NMSU | ramsey@ecoinformatics.org +Saurabh Garg | NCEAS, UCSB | sgarg@ecoinformatics.org +Mark Servilla | EDI, UNM | servilla@ecoinformatics.org diff --git a/docs/eml-220info.md b/docs/eml-220info.md index 58330eb8..836e1e08 100644 --- a/docs/eml-220info.md +++ b/docs/eml-220info.md @@ -1,6 +1,4 @@ -[EML Schema Documentation](./index.html) - -[EML FAQs](./eml-faq.html) +# Changes and New Features 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 @@ -16,8 +14,6 @@ relabled as EML 2.2 without violating the schema. However, some predefined value See the 'Readme' that accompanies the distribution for a complete list of the bugs addressed, and for information of interest to developers. -Changes and New Features in EML 2.2.0 -===================================== **Q:** Unit Additions and Changes @@ -350,12 +346,7 @@ external identifiers, e.g., to a code from a system like ITIS or WoRMS. ``` -Converting EML documents from v2.1.0/1 to v2.2.0 -================================================ - -IS THIS GOING TO HAPPEN FOR 2.2.0??? - -**Q:** About the EML conversion stylesheet +**Q:** How can I convert from earlier versions of EML? **A:** An XSL stylesheet is provided with the EML Utilities to convert valid EML 2.1-series documents to EML 2.2.0 (see diff --git a/docs/emldocs.Rproj b/docs/emldocs.Rproj new file mode 100644 index 00000000..86a963c3 --- /dev/null +++ b/docs/emldocs.Rproj @@ -0,0 +1,18 @@ +Version: 1.0 + +RestoreWorkspace: Default +SaveWorkspace: Default +AlwaysSaveHistory: Default + +EnableCodeIndexing: Yes +UseSpacesForTab: Yes +NumSpacesForTab: 4 +Encoding: UTF-8 + +RnwWeave: Sweave +LaTeX: pdfLaTeX + +AutoAppendNewline: Yes +StripTrailingWhitespace: Yes + +BuildType: Website diff --git a/docs/index.Rmd b/docs/index.Rmd new file mode 100644 index 00000000..b02bb8a2 --- /dev/null +++ b/docs/index.Rmd @@ -0,0 +1,11 @@ +--- +title: "Ecological Metadata Language (EML)" +date: "`r Sys.Date()`" +site: "bookdown::bookdown_site" +output: bookdown::gitbook +documentclass: book +bibliography: [book.bib] +biblio-style: apalike +link-citations: yes +always_allow_html: yes +--- diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 46edea15..00000000 --- a/docs/index.md +++ /dev/null @@ -1,43 +0,0 @@ -# Ecological Metadata Language (EML) - -Ecological Metadata Language (EML) is a metadata specification 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. - -Send any comments, errors, or suggestions to or by filing an Issue on [GitHub](https://github.com/NCEAS/eml/issues). The preferred way to submit problems with EML or feature requests is via GitHub Issues. - -## EML Version 2.2.0 - -You can access the EML specification online by reading it in HTML format, or you can download the entire specification, including both the HTML documentation and the XML Schema files. - -- [EML Specification](docs/eml-2.2.0/index.html) -- Read it online - - OR - -- [Download EML](https://knb.ecoinformatics.org/software/dist) - - The download consists of the EML modules, described in the [XML Schema](http://www.w3.org/XML/Schema) language. In addition, the full documentation on the modules is provided in HTML format. - -- [Changes to EML in version 2.1.1](docs/eml-211info.md) - -- [EML Frequently Asked Questions (FAQ)](docs/eml-faq.md) - -- [Validation service for EML](/@servletdir@/) - - In addition to the online service found at the previous link, the EML distribution itself contains the validation software for your use (see "lib/runEMLParser" for details on how to run it). - -## About the EML Project - -The EML project is an open source, community oriented project dedicated to providing a high-quality metadata specification for describing data relevant to the ecological discipline. The project is completely comprised of [voluntary project members](members.md) who donate their time and experience in order to advance information management for ecology. Project decisions are made by consensus according to the voting procedures described in the [ecoinformatics.org Charter](http://www.ecoinformatics.org/charter.html). - -We welcome contributions to this work in any form. Individuals who invest substantial amounts of time and make valuable contributions to the development and maintenance of EML (in the opinion of current project members) will be invited to become EML project members according to the rules set forth in the [ecoinformatics.org Charter](http://www.ecoinformatics.org/charter.html). Contributions can take many forms, including the development of the EML schemas, writing documentation, and helping with maintenance, among others. - -## Development Information - -Developers may be interested in browsing the [source code repository](https://github.com/NCEAS/eml/) that we use in developing EML. This always contains the most recent development version of EML, and therefore may be in flux, or otherwise broken. It is unlikely that it will contain the same files that are in the current release (@version@). Use at your own risk. Write access to this repository is reserved for current project maintainers. Please submit contributions as pull requests. We welcome contributions to this work in any form. Contributions can take many forms, including the development of the EML schemas, writing documentation, and helping with maintenance, among others. Non-project members can contribute by submitting their feedback, revisions, fixes, code, or any other contribution through pull requests at GitHub. Discussion of issues occurs on the [eml-dev@ecoinformatics.org](https://groups.google.com/a/ecoinformatics.org/forum/#!forum/ecoinfoeml-dev) mailing list, or through the [EML Issue Tracking system](http://github.com/NCEAS/eml/issues). The preferred way to submit problems with EML or feature requests is the issue tracking system. - -## Older versions (deprecated) - -The following versions are still available for reference purposes, although they have been superseded by the current version (2.2.0). Please make every effort to use the current version. - -- [EML 2.1.1](http://knb.ecoinformatics.org/software/dist/eml-2.1.1.tar.gz) -- [EML 2.1.0](http://knb.ecoinformatics.org/software/dist/eml-2.1.0.tar.gz) -- [EML 2.0.1](http://knb.ecoinformatics.org/software/dist/eml-2.0.1.tar.gz) -- [EML 2.0.0](http://knb.ecoinformatics.org/software/dist/eml-2.0.0.tar.gz) -- [EML 1.4.1](http://knb.ecoinformatics.org/software/dist/eml-1.4.1.tar.gz) diff --git a/docs/release-notes.md b/docs/release-notes.md new file mode 100644 index 00000000..a6ad202c --- /dev/null +++ b/docs/release-notes.md @@ -0,0 +1,205 @@ +# Release Notes +- (see also http://github.com/NCEAS/eml/issues) + +### 2.2.0 + +#### Major New Features + +#### Schema changes: + +### 2.1.1 + +#### Internationalization in EML 2.1.1 +EML 2.1.1 introduces internationalization capabilities that can be used in most +text-based elements. Version 2.1.1 remains backward-compatible with the previous +2.1.0 release. Authors can safely upgrade existing 2.1.0 documents to 2.1.1 +without altering any content, though adding additional language translations is +encouraged. + +By allowing mixed element content, nested translation elements can be included +without altering or introducing ambiguity with respect to EML element +cardinality. Translation elements use standard xml:lang attributes to specify +the language used for their content. Translation elements can be nested such +that child elements may inherit or override the language used by their +ancestors. The top-level EML element may include an xml:lang attribute which +will apply to every element in the document unless a child element includes a +different xml:lang attribute to override the document default. + +Multi-lingual authors of EML should carefully consider their primary target +audience when deciding the default document language. Early adopters should be +aware search tools like Metacat will require custom configuration in order to +search arbitrarily nested translations. + +The internationalization feature allows authors to place any language in +tags nested within most EML text fields. The xml:lang attribute should be used +to explicitly declare the language used. + +Additional documentation and examples are available in the EML specification. +The i18nNonEmptyStringType is used for simple text, while i18nString for more +structured text elements. + +#### Schema changes: + - [76](https://github.com/NCEAS/eml/issues/76): internationalization needed in EML + +### 2.1.0 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) +This release addresses bugs which caused the schema to be invalid with +respect to the W3C specifications using modern validators +(e.g., http://www.w3.org/2001/03/webdata/xsv). Although the changes were minor, +one was incompatible with 2.0 releases, which necessitated the version +number "2.1". In the 2.0 series, the content model for additionalMetadata +included an element `` whose cardinality was 0..many, alongside +``. This construct is non-deterministic, and so a child element +was added to the additionalMetadata section to contain the `` content. +Additionally, several elements of txt:TypeText required additional +definition so that mixed content could be accommodated. These errors +were not apparent with validation software available in 2004-2005, but +were brought to light more recently. Several small changes were made to +the enumeration list and unitTypes for standard units and stmml descriptions +of customUnits. Two elements in the literature schema were allowed to be +optional so that articles-in-press could be described. The named type for +element gRing was changed to GRingType. + +EML makes use of the STMML schema (stmml.xsd) for describing custom units +and describing its included list of standardUnits (unitList). The STMML +schema was also found to be non-deterministic, and the most reasonable fix +for this bug was not compatible with earlier versions. This error +was NOT related to elements used by EML (unitList or unitType). However, +given that authors of EML instance documents may have made use of other +parts of stmml.xsd, it was decided to the advance the namespace used for +stmml-related files to "stmml-1.1", in keeping with the pattern of version +naming in EML. The stmml authors have been contacted. + +- Schema changes: + - 1132: eml.xsd, physical.xsd: fix access rule ambiguities + - 2054: eml.xsd: added the tag to additionalMetadata + - 1154: resource.xsd: required element offline has no required children + - 3480: resource.xsd, physical.xsd: nearly duplicate complexTypes, DistributionType and PhysicalDistributionType + - 3165: resource.xsd: provide a place for a url description + - 3227: coverage.xsd: gRing was declared as GRingPointType, is now GRingType + - 1019: coverage.xsd: altitudeUnits should use eml-unitDictionary + - 3500: coverage.xsd: restrict boundingCoordinates to realistic lat/lon ranges + - 1152: attribute.xsd: dateTime elements are named inconsistently; standarized on dateTime + - 2272: attribute.xsd: base types in BoundsGroup changed to xs:float + - 3051: attribute.xsd: missing units were added to enumeration list to match eml-unitDitionary + - 2568: attribute.xsd, entity.xsd: inconsistent naming of methods elements, standardized to + - 2703: text.xsd: refined element declarations in txt:TextType for para, section; added ulink, citetitle + - 3163: literature.xsd: cardinality of volume and pageRange is now 0..1 + - 3164: literature.xsd: literature needs a contact tree + - 3445: stmml.xsd: non-deterministic + - 2083: stmml.xsd: dimension 'current' was wrongly entered as 'charge' +- Parser : + - 3232: EML parser should use full-schema-checking + - 3836: runEMLParser script should include sax-validate +- Stylesheets: + - 3508: create a stylesheet for EML2.0.x to EML 2.1.0 + - 3590: eml-documentation stylesheet problem with derived content. + - 2048: param attributeindex defined twice in eml-settings.xsl + - 2085: Access control rules adapted for 2.0.1 and 2.1 (currently not shown) + - 2147: EML Stylesheet problem with web address URL's + - 2226: EML2 style sheet double the number of complex delimited f... + - 3492: the word 'unit' should be pluralized by default + + +### 2.0.1 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) +- 249: Update XSLT stylesheets for EML 2.0 modules +- 939: spelling errors for 'its' in index +- 960: parser not correctly parsing tag in additiona... +- 1008: inline element doesn't support character child +- 1017: documentation error in eml-methods +- 1031: enumeratedDomain doesn't define value order for ordinals +- 1035: Technical documentation on eml-methods has an error +- 1124: update precision field definition and cardinality +- 1129: Change temporalCoverage calendarDate type +- 1132: fix access control rule ambiguities +- 1136: kelvin conversion incorrect in unit dictionary +- 1149: BoundsGroup bounds min & max have incorrect cardinality +- 1150: documentation for KeyTypeCode is wrong +- 1151: misspelled element name +- 1153: dateTimeDomain element should be optional +- 1155: Documentation incorrect for dateTimeDomainType bounds +- 1195: tracking bug for 2.0.1 release +- 1233: dateTime formatString Documentation contains incorrect ex... +- 1529: no tag to specify how to handle mutltiple, repeated delimimeters +- 1652: eml-constraint documentation error + +### 2.0.0 - (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) +- 670: DateTimeDomain id/reference validation +- 924: make date time its own measurement scale +- 661: spell check eml-attribute.xsd and synchronize with unitDi +- 918: example tag in eml:documentation + +### 2.0.0rc3 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) +- 471: eml spec overview document +- 624: eml-methods/methodsType needs clarification on choice/seq... +- 627: links broken in EML FAQ +- 629: unit conversion coefficients need checking +- 637: attributeDomain should be required +- 638: request for id/ref in attributeDomain +- 654: scope of the unit element +- 655: need better model for numeric domains for attributes +- 625: Cardinality regarding eml-methods should be corrected in ... +- 626: ProcedureStepType schema needs revision to protect sequen... +- 628: eml-physical has lit: rather than cit: references +- 632: broken link in faq +- 634: Documentation of reference elements in the schemas +- 656: physical should be repeatable + +### RC2 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) +- 568: accommodate of stateful connection information +- 586: resolve validation problem with missing keys +- 588: Remove lineage tags in documentation stylesheets +- 589: eml-coverage: convert element references to types +- 592: fix validation error with xs:anyType +- 594: change cardinality for designDescription and studyAreaDes... +- 596: Proposal: make attribute optional in OtherEntityType. +- 597: In eml-dataTable caseSensitive and orientation are modele... +- 598: literature namespace references are inconsistent +- 599: storageType is repeatable in eml-attribute +- 600: eml-storedProcedure - problems & proposal +- 601: element names in spatial modules do not follow guidelines +- 602: eml-physical fixed textFormat to allow mixed fixed/delimited +- 608: release preparation tasks for EML2.0.0rc2 +- 622: redundancy in eml-physical/binaryRaster + +### RC1 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) +- 471: created an EML specification overview document +- 495: created FAQ for EML +- 588: removed lineage tags from documentation stylesheet +- 484: eml-attribute changes to unit and attributeDomain +- 579: fixed eml-docbook validation problems +- 491: eml-coverage changed to correctly import types and to fix singleDateTime model +- 485: eml-physical changed to fix fixed ascii descriptors and distribution +- 477: complexTypes imports changed to consistent model +- 486: fixed spelling errors in eml-constraint +- 492: eml-literature changed for EndNote consistency +- 496: copyright updated throughout +- 557: textual elements changed to use docbook subset define in eml-text.xsd +- 563: changed id types from xs:ID to xs:string to allow numeric ids +- 482: eml-dataset changed to include method element +- 489: eml-protocol completely revised based on feedback, eml-method.xsd created +- 544: eml-attribute storageType and attributeDomain documentation clarified +- 556: format of eml namespaces changed to include ecoinformatics.org +- 539: added additionalInfo and alternateIdentifier to eml-dataTable.xsd +- 568: redesigned DistributionType to allow richer connection descriptions +- 566: changed imports in eml-resource to import resource types not elements +- 567: created eml sample documents and XML validation framework using ant/junit + +### Beta9 Fixes- +1. Changed packaging concept to use internal id and references instead + of triples +2. Review and revised all modules according to agreed upon changes from + the April, 2002 EML meeting at Sevilleta Field Station + +### Beta 8 Fixes- +1. Fixed illegal declaration of type and extension in eml-entity +2. Updated all PNG image files + +### Beta 7 Fixes- +1. Added a 'style' subdirectory with a style sheet for most modules + . to translate the metadata to HTML +2. Changed names of coverage elements to be human readable +3. Updated the namespaces to reflect the current version number of EML +4. Added an eml-data module for the in-lining of data. +5. Added the eml module for creating packages all in one file. It is a single + node with a model of ANY so any of the eml modules can be put into it. +6. Numerous bug fixes (see bugzilla.ecoinformatics.org)