search

NCEAS / eml

Ecological Metadata Language (EML)
https://eml.ecoinformatics.org/
GNU General Public License v2.0
40 stars 15 forks source link

change in documentation structure #64

Closed mbjones closed 5 years ago

mbjones commented 7 years ago

Author Name: Chad Berkley (Chad Berkley) Original Redmine Issue: 501, https://projects.ecoinformatics.org/ecoinfo/issues/501 Original Date: 2002-05-09 Original Assignee: Saurabh Garg

We should change the structure of the documentation xsd so that each of the documentation tags (summary, tooltip and description) are inlined into one bit of text instead of sibling elements. The new documentation should look something like

The title field is used to generally describe the resource. It is typically 15 to 20 words long, and provides a concise yet thorough descrition of the resource.
mbjones commented 7 years ago

Original Redmine Comment Author Name: Peter McCartney (Peter McCartney) Original Date: 2002-05-17T18:28:56Z

Im not sure i follow this - is this a revision of the eml-documentation elements that are going into appinfo? is there a typo in this or is part of it missing- opening and closing elements dont match?

I have two perhaps related questions about eml-documentation.

1) im not sure i see why the elements are going into rather than

it seems like they are really more descriptive rather that metadata for applications. 2) if they remaine under appinfo, wouldnt it be tidier to nest them under a single element like so as to distinquish them from other appinfo content a developer might want to stick in there? if i were to add something specifically for one of our apps, i would want to do the same so that i dont have to tread around other people's element names. maybe this is what Chads bug is about - im not sure.....
mbjones commented 7 years ago

Original Redmine Comment Author Name: Matt Jones (Matt Jones) Original Date: 2002-05-17T19:37:16Z

We haven't implemented these changes yet, so you don't really have to worry about them in the current revs. There was a typo (mismatched tags) in the example, sorry.

The intent is to simplify the documentation and make it less redundant by making the documentation mixed content. This is because the tool tip is usually just a couple of words from the summary, and the summary is just one of the sentences from the desciption. The new structure allows these tags to be nested in one another so that we can reuse one of the sentences from the description as the summary, etc.

All of this is currently in xs:appInfo. Because the elements are in their own namespace, you can add other elements to xs:appInfo without any problems with interference. Just don't add them inside of doc: prefixed elements and you'll be all set.

Whether it goes in xs:appInfo or xs:documentation is based on how you intend to use the docs. We intend to machine process the doc: elements for use in applications, so we thought it belonged in appInfo (that's what the spec says). Its really kind of an arbitrary decision, and should not have any impact on functionality (both appInfo and documentation are defined as ANY models).

mbjones commented 7 years ago

Original Redmine Comment Author Name: Matt Jones (Matt Jones) Original Date: 2004-09-02T16:38:15Z

Changing QA contact to the list for all current EML bugs so that people can track what is happening.

mbjones commented 7 years ago

Original Redmine Comment Author Name: Redmine Admin (Redmine Admin) Original Date: 2013-03-27T21:14:29Z

Original Bugzilla ID was 501