Re: [ubl-ndrsc] Embedded documentation writeup draft

[Dave Carlson <dcarlson@ontogenics.com>]

Here's my understanding of the difference between xsd:appinfo and
xsd:documentation, also based on the way I've seen them used in other
schemas.

xsd:documentation should only be used for human readable documentation.

xsd:appinfo is for program readable metadata used by other applications.
Usually, a separate XML namespace is defined for app-specific or
vendor-specific values. For example,  define the Java class name used to
bind a complexType to code, used when the Java class name is different from
the complexType name.  Similarly, record the database table name used to
store the data.  Both of these are too application/tool specific for UBL's
purposes.

xsd:appinfo has also been used to hold Schematron constraints that go beyond
the XSD's capabilities.  A downstream processor would parse out the
Schematron rules and apply them to doc instances.

Thus, you might consider using both appinfo and documentation.  Assuming
that XHTML is only for humans, put it in xsd:documentation.  If some of the
Core Components metadata from the spreadsheet might be used by downstream
processors or context engines, you might put it in xsd:appinfo using tags
derived from the core components metamodel that Bill was working on.

Cheers,
  Dave Carlson

----- Original Message -----
From: "Eve L. Maler" <eve.maler@sun.com>
To: <ubl-ndrsc@lists.oasis-open.org>
Sent: Monday, August 05, 2002 2:43 PM
Subject: [ubl-ndrsc] Embedded documentation writeup draft


> Please find below Arofan's draft writeup on embedded documentation, and
> also some issues he's raised on the subject.  Let's discuss on Wednesday
> (look for an agenda from me by the end of the day Tuesday...).
>
> Another question to consider on embedded documentation: Should we be
> using xsd:documentation or xsd:appinfo?  Here's some background from a
> thread between Arofan and me:
>
> Eve:
> "Another question that came up when I presented UBL last week was: Why
> xsd:documentation rather than xsd:appinfo?  I couldn't give the
> questioner a good answer to this one...  Especially if we imagine that
> non-normative schemas will be produced directly from our normative XSD
> rather than from the spreadsheet (and there's a lot to be said for that,
> since it would be an XML->XML transformation rather than a
> spreadsheet->XML one), xsd:appinfo could make a lot of sense."
>
> Arofan:
> "As for AppInfo - well, hey - I thought it was documentation originally,
> but it could as easily be AppInfo, I suppose. On what basis should we
> make this decision? There isn't a difference technically, if I remember
> right. If we can determine that one or the other is more correct, then
> that's what I'll vote for. I guess we should put this to the group, no?"
>
> Eve
>
> -------- Original Message --------
> Date: Mon, 5 Aug 2002 12:44:39 -0700
> From: "Gregory, Arofan" <arofan.gregory@commerceone.com>
> To: "Maler, Eve" <eve.maler@commerceone.com>
> CC: "'xmlgeek@gmi.net'" <xmlgeek@gmi.net>
>
>
>
> <<draft-gregory-embedded-01.doc>>
>
> Eve:
>
> Here is the embedded documentation draft for discussion this week.
> However, I wanted to point out some things that emerged as I was working
> on it, so that you could advise/adjust if you think it needs it:
>
> (1) I think we need to be more specific about what documentation we
> allow where, since so many of the fields in the Methodology are specific
> values, and allowing any XHTML Basic markup is neither beneficial nor
> advisable - not even desirable, I don't think.
>
> (2) I have assumed that there would be a section taht went through the
> UBL schema module structures type-by-type: simpleTypes. complexTypes,
> global elements, attributes, etc., and specified for each where the
> documentation element was used. This is already covered elsewhere in
> NDR, and either we should centralize all of the wording around how there
> modules are documented, or make a reference. This is critical in getting
> the right documentation in the right spots in the schema, and I think it
> would be useful for us to be as explicit as possible.
>
> Anyway, please distribute in whatever way you see fit, or write back if
> you have questions.
>
> Cheers,
>
> Arofan
>
>
> --
> Eve Maler                                        +1 781 442 3190
> Sun Microsystems                            cell +1 781 883 5917
> XML Web Services / Industry Initiatives      eve.maler @ sun.com
>