OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Bookmap notes


These notes go with the bookmap DTDs uploaded here:
http://www.oasis-open.org/committees/download.php/18181/bookprototype.zip
They are correspondence that did not get into the TC List record at the
time.  The DTD above reflects the input from notes 1 and 2 below. The input
of items 3 and 4 are NOT in the above DTDs.

1. From Robert Anderson, addressed to Chris Kravogel, May 15 (prior to last
week's meeting):

Unfortunately I am leaving tomorrow and will be gone for a couple of weeks,
so I will not be able to make all of these changes very quickly. However I
will put in some responses:

> 1: Do I understand it correct, compared to the previous bookmap, bkinfo
is
> now integrated into bookmap?
Yes, bkinfo no longer exists. Everything is in bookmap.

> 2. <authorinformation> (specialized from data) is used as container for
> namedetails, addressdetails etc.
> May I propose to modify that so it can be used within the elements
reviewed,
> edited, tested etc.
> May I propose to skip <authorinformation>. Instead we could specialize
data
> to the following three elements:
> namedetails (from xAL),
> addressdetails (from xNL) and
> personinfo (from xCIL), (see point 7. below)
> all three would come into the xNAL domain as <data> specializations.

I think that using the three separately will cause some problems, because
with domain specializations, those three elements will show up any place
that data shows up. I like having one container that can contain all of the
information about an author, rather than having a model of (data |
namedetails | addressdetails | personinfo)*. One thing that might work is
to have a different container, if you want to enter information without
declaring that somebody is an author - a model of (data | authorinformation
| contactinformation), or something like that? Another option would be to
have (data | authorinformation | namedetails) -- the author tag comes with
address and contact info, while the name tag just includes the person or
organization name.

The main thing is that any specialization we add for the <data> element
will show up in every location that uses <data>. Some of these will not
make a lot of sense to authors, so I like to try to include all of this in
one element if possible, rather than using several.

Also - the latest revision of bookmap does have authorinformation inside of
the elements like edited, tested, etc. It's in the most recent post to
OASIS, but I'll put a more recent version in this note.

> 3. As far as I remember we have used firstname and lastname in bkinfo.
And
> those are inline with xNL. I would not change to familyname and givenname

> yet. We may can add the proposed attribute nametype, but I am not sure if
we
> need it. But I would not use givenname and familyname, I am not sure that

> this pattern is used in all other cultures. We are more safe with
firstname,
> lastname.

I can make this change. Those elements cannot have a nametype attribute,
but they do have a type attribute (in the zip below, not in the one you
have). Users could put name information in the type attribute if they want.

> 4. <addressdetails> is the container for all addressinformation. It has
an
> element <address> (one line of free text and <addresslines><addressline>
for
> several lines of free text. Maybe we can skip both.

OK, for this, we can let addressdetails have any number of children, and
skip the addresslines element. Should addressdetails allow text as well? It
looks like this will not map exactly to the xnal model (see the third
question on the Wiki http://wiki.oasis-open.org/dita/xNAL_in_bookmap)

> 5. <locality> should be the container for <localityname> and <postalcode>

> and if someone needs for pobox also.

Ok - should those be optional? That is - you can use text or use the
elements? If you have to use the elements, then there is a question of
order (some locations might have the postalcode first, some second).

> 6. <thoroughfare> (I did a typo when writing <throughfare> in my
proposal.)
> Can we use here an element that can be specialized to an additional
level.
> Standard: e.g. <thoroughfare>Eichenstrasse 36</thoroughfare>
> and if required to be specialized to
>
<thoroughfare><throughfarename>Eichenstrasse</thoroughfarename><thoroughfarenumber>36</thoroughfarenumber></thoroughfare>?


Ok - same question as above. I do have a couple of comments. 1) If you
require an order, this may be a problem (Eichenstrasse 36 might be 36 Elm
Street in the US, so which do you require first). 2) If you specialize
thoroughfare then you have to change the name for the new specialization,
so you cannot actually create the <thoroughfare> element with different
children. You would need <thoroughfare-new> or <Thoroughfare>.

I will change the name to the correct spelling.

> 7. <personinfo>
> You are right, that one does not come from xNAL, it comes from xCIL which
is
> a wrapper arround xNAL.
> xCIL is going fare ahead and has another focus. But I like the content
> model. As xNAL provides no container for phone numbers, web addresses
etc.
> that could be the right one.
> In <personinfo> we can provide a similar pattern for different types of
> specialization. e.g. as included contactnumbers and emailaddresses, it
can
> also be used for specializations e.g. for webaddresses.

So - this would be a container that is even with the name and address
details. I can add that. I do have one question though. This will apply to
the name entered, but the name can be either a person or an organization.
So does it make sense to use <personinfo> to include contact information
for an organization?

> 8. <preceedingtitle> I selected the wrong one (we do not need His
Excellency
> etc.) it should be the xNAL element <title> for Dr. Mr. Ms. etc., but I
> guess we can not use here the element name <title>?

I think we should remove preceedingtitle and just use <honorific>. The DITA
<honorific> element will be the same as the xNAL <title> element.

***************
Other comments on the Excel sheet:
I see that you have a new wrapper <namedetails> that includes a person or
organization. I can add this to the DTD.

You show several <contactnumber> elements with the type attribute. The
current specialization has different elements for each value. Is that OK? I
think there are three options:
1. We do what is there now - an element for each type, and a generic
element for others.
2. We use the contactnumber element for all values, and list the allowable
values in the type attribute
3. We use the contactnumber element for all values, but leave the type
attribute empty (users can specify any type).

I like the first one best, because I think it's the easiest for users.

I've included the latest zip for the bookmap. It has the following xnal
related updates:
* Add namedetails as a container for personname and organizationname
* Add personinfo as a contaner for phone and email
* Change throughfare to thoroughfare
* Add resource as an optional child for personname (it was in your
spreadsheet, but not yet in the DTD)
* Remove <preceedingtitle>
* Change givenname and familyname to firstname and lastname, and fixed the
attributes so that @type is available.

Please let me know what you think. As I said, I'm heading out tomorrow, so
any changes after the TC meeting will not get to me for a while.


2. Response from Chris Kravogel, cc'd to the list but not in the record:
Robert

I checked the xNAL domain and would like to suggest the following
modifications:


******************


<!ELEMENT namedetails ((%personname; | %organizationname;)*)>


should be


<!ELEMENT namedetails ((%personname; | %organizationnamedetails;)*)>


******************


<!ELEMENT organizationnamedetails ((%organizationname;)?, (%address;)*,
(%resource;)*, (%summary;)?, (%otherinfo;)*) >


might be


<!ELEMENT organizationnamedetails ((%organizationname;)?, (%resource;)*,
(%summary;)?, (%otherinfo;)*) >


I am not sure here about resource and summary, it comes from the bkinfo
structure. I can not say if this is the right place? They are both not from
xNAL.


********************


<!ELEMENT addressdetails
(%address;|%locality;|%administrativearea;|%thoroughfare;|%postalcode;|%country;)?>


may go to


<!ELEMENT addressdetails
(%locality;|%administrativearea;|%thoroughfare;|%country;)?>


%postalcode is a child of %locality, %address is just a free text line. I
do not know if that is required.


********************


locality and thoroughfare should have a specializable content model with
PCDATA|%childelements


<!ELEMENT locality (#PCDATA;|%localityname;|%postalcode;)*> it should be
possible to add elements like %pobox; if required.


<!ELEMENT thoroughfare (#PCDATA;)*> I am not sure but we may have to build
it so it can be specialized with one additional level, so it can become
something like:


<!ELEMENT thoroughfare (#PCDATA;|%thoroughfarenumber;|%thoroughfarename;)*>


*******************


<contactnumbers><contactnumber> here I would suggest to use the xCIL model
with


<contactnumber type="xyz">


instead of


<contactnumbers>
     <officephone>
     <fax>
etc.


If we use <contactnumber type "xyz"> the user would not have to specialize
it. It is more simple, and xCIL conform and matches the element structures
of all others in personinfo.
If requried, the user can still specialize it to <officephone> etc. if
required.


********************


3. Later update from Chris:
In addition, I found an xNAL example, where addressdetails and namedetails
where childs of personinfo and organizationinfo. That would makes it even
more handy for the user.

So I will detail it within the next few hours.

4. That update:

I have now updated the xNAL proposal to addapt to the xCIL requirements as
well. We are now pretty close to the previous bkinfo structure, but
enhanced and xCIL and xNAL conform.

(See attached file: structure-proposal-v3.pdf)



Regards,
--
Don Day
Chair, OASIS DITA Technical Committee
IBM Lead DITA Architect
Email: dond@us.ibm.com
11501 Burnet Rd. MS9033E015, Austin TX 78758
Phone: +1 512-838-8550
T/L: 678-8550

"Where is the wisdom we have lost in knowledge?
 Where is the knowledge we have lost in information?"
   --T.S. Eliot

structure-proposal-v3.pdf



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]