Subject: [IPTEL] corrections to CPLv2 DTD and some text

From: "Nilo Mitra (EUS)" <[email-masked]>
Date: Tue, 2 May 2000 16:17:11 -0500

Here are some corrections to the DTD of the CPL version 2 document,
draft-ietf-iptel-cpl-01.txt, dated March 10, 2000.

I am working on the assumption that the text takes precedence over the DTD,
and therefore I have corrected the CPLv2 DTD to conform to the intent stated
in the text. I do realise that the CPL DTD is not sufficient for a cpl
script's validity but feel that it should accurately reflect the text as far
as is possible. Think of my efforts as making corrections to the CPL DTD
syntax using DTD and XML rules to allow for greater expressivity (if that's
a word).

1. The preamble <?xml version="1.0"...?> is not needed, as a DTD is not an
XML document.

2. Enclose the whole thing within: 
	<! DOCTYPE cpl [
	....
	]> 

3. Is it really intended that the timezone information can be included more
than once, as described by the asterisk (0 or more) in the definition of the
top level element
namely <!ELEMENT cpl (timezone*, subaction*, outgoing?, incoming? )> ?

I suspect it should be 0 or 1 in which case a "?" should be used to qualify
it so that it reads <!ELEMENT cpl (timezone?, subaction*, outgoing?,
incoming? )>.

4.  It would be good to write the top level element as 

	<!ELEMENT cpl ( (%Ancillary;)*, subaction*, outgoing?, incoming? )>

thereby not requiring any change to the top level structure when there are
additional items added to the ancillary information beyond the currently
supported "timezone".

As currently defined, namely <!ELEMENT cpl (timezone*, subaction*,
outgoing?, incoming? )>,
it allows for multiple timezone entries, which I don't believe is what is
intended. 

What I believe is intended is that there be the potential for multiple
ancillary entries but only one entry for timezone. My proposal doesn't
exactly solve the multiple time zone entries issue, but at least it is a
step in the right direction, and the intent of having only one timezone
entry could be indicated with a comment.

The other alternative is to make it 
	<!ELEMENT cpl (timezone?, subaction*, outgoing?, incoming? )>
which is not future-proof.

5. The address-switch node or element as currently written, namely

	<!ELEMENT address-switch ( (address | not-present)+, otherwise? )>

would suggest that the not-present element can potentially be present
multiple times. This element definition should be rewritten as

	<!ELEMENT address-switch (address+, not-present?, otherwise? )>

6.  The attribute list for <address> should contain only one of "is",
"subdomain-of" or "contains", but this limitation is not perfectly expressed
in the syntax
	<!ATTLIST address
	is 		CDATA	#IMPLIED
	contains	CDATA	#IMPLIED
	subdomain-of	CDATA	#IMPLIED
because it allows for each of these to appear. The way to express the
constraint might be

	<!ENTITY % is "is CDATA #IMPLIED">
	<!ENTITY % contains "contains CDATA #IMPLIED"> 	
	<!ENTITY % subdomain-of "subdomain-of CDATA #IMPLIED">

	<!ATTLIST address (%is; | %contains; | %subdomain-of;) >

7. The string-switch element should be rewritten, for the same reasons as in
item 5 above, as
	<!ELEMENT string-switch (string+, not-present?, otherwise? )>

8. The attribute list for <string> should be rewritten, for the same reasons
as in item 6 above, as

	<!ENTITY % is "is CDATA #IMPLIED">
	<!ENTITY % contains "contains CDATA #IMPLIED">
	<!ATTLIST string (%is; | %contains;) >

9. The time-switch element should be rewritten, for the same reasons as in
item 5 above, as
	<!ELEMENT time-switch (time+, not-present?, otherwise? )>

As the text says that the not-present output is never true for a
time-switch, why not leave it out altogether from the definition of the DTD
so that it becomes
	<!ELEMENT time-switch (time+, otherwise? )>

10. A propos the <time> element and its attributes, looking at the various
examples given, it seems to imply that the absence of some elements implies
a default value, for instance:
	timeofday absent => all day
	year absent => all year
	day absent => all week (btw, is it "weekday" as stated in fig 6 or
is it "day" as in the rest of the section?)
	month absent => every month

I have added a default for date, namely "any day of the month".

This could be expressed in the following syntax:

	<!ATTLIST time
		year		CDATA	"all year"
		month		CDATA	"every month"
		date		CDATA	"any day of the month"
		day		CDATA	"every day"
		timeofday 	CDATA 	"all day"

Does this seem a bit forced? I'm personally not too pleased with the way in
which the actual data, which typically will be a number or a range or a list
of numbers/ranges defaults to a character description, but what else can one
do? 

11. The priority-switch element should be rewritten, for the same reasons as
in item 5 above, as
	<!ELEMENT priority-switch (priority+, not-present?, otherwise? )>

12. Only one of the attributes of <priority> may be present. This fact is
not currently expressed correctly in the current cpl DTD (just as in item 6
above), but there is one additional complexity. One way to express this is:

<!ATTLIST priority (less %PriorityVal; | greater %PriorityVal; | equal CDATA
#IMPLIED) #REQUIRED>
	
The CPLv2 draft text seems to imply that one of these must be present, hence
the #REQUIRED.

13. A comparison of the text and the attribute list for <proxy> in the DTD
suggests that there needs to be a clarification of the words "optional", and
having a dfault value. The attribute list
	<!ATTLIST proxy
	...
	recurse	(yes|no) "yes"
	...
means that the attribute recurse is not really absent, even if it is not
actually written down. It's textual absence implies its presence with the
value "yes". And the same for the other attribute with a default value.

14. As the values for the status attribute in <reject> have been specified
in the text, the DTD should provide the enumerated list (where I have added
an additional value "other" as a catch all for the SIP-specific reject codes
4xx, 5xx, 6xx). Thus,
	<!ATTLIST reject
	status	(busy | notfound | reject | error | other) #REQUIRED
	reason	CDATA #IMPLIED

or, if one wised to expose the SIP-specific codes themselves, one could
write

	<!ENTITY % SIP-reject-code '(4xx | 5xx | 6xx)' >

	<!ATTLIST reject
	status	(busy | notfound | reject | error | %SIP-reject-code;)
#REQUIRED
	reason	CDATA #IMPLIED

15. The output of a log node can be any node; so it should be <!ELEMENT log
( %node; ) > rather than have child nodes as currently shown (which was in
version 1).

MISCELLANEOUS

1. Figure 1. Shouldn't "subaddress-of" be "subdomain-of"?

2. In section 4.1 and figure 6 the use of 'weekday" or 'day" should be
clarified.

3. In section 5.1 and Figure 8, shouldn't something be said about the
attribute 'clear"?

4. In Figure 11, the name of the node should be "proxy".

5. The text accompanying the description of the <time> element in section
4.3 does not make clear if at least one of the attributes (year, month,
date,...) must be present.

That's all for now

Nilo Mitra
[email-masked]

_______________________________________________
IPTEL mailing list
[email-masked]
http://lists.bell-labs.com/mailman/listinfo/iptel