MHonArc v2.5.2 -->
ubl-ndrsc message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [Elist Home]
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
Attachment:
draft-gregory-embedded-01.doc
Description: MS-Word document
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [Elist Home]
Powered by eList eXpress LLC