[ubl-ndrsc] Embedded documentation writeup draft

["Eve L. Maler" <eve.maler@sun.com>]

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

Attachment: draft-gregory-embedded-01.doc
Description: MS-Word document