[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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]