Bug #501
open
change in documentation structure
Added by Chad Berkley about 22 years ago.
Updated almost 20 years ago.
Category:
eml - general bugs
Description
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
<description><summary>The <tooltip>title field</tooltip> is used to generally
describe the resource.</summary> It is typically 15 to 20 words long, and
provides a concise yet thorough descrition of the resource.</documentation>
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 <xs:appinfo> rather than
<xs:documentation> 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 <doc:eml-documentation> 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.....
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).
Changing QA contact to the list for all current EML bugs so that people can
track what is happening.
Original Bugzilla ID was 501
Also available in: Atom
PDF