wiki-archive/twiki/temp-gjr/BDI/SDD/DebugrefAutomation.txt,v

head	1.13;
access;
symbols;
locks; strict;
comment	@# @;


1.13
date	2009.11.25.03.14.32;	author GarryJolleyRogers;	state Exp;
branches;
next	1.12;

1.12
date	2009.11.20.02.45.24;	author LeeBelbin;	state Exp;
branches;
next	1.11;

1.11
date	2007.03.06.17.30.00;	author TWikiGuest;	state Exp;
branches;
next	1.10;

1.10
date	2006.05.04.11.26.28;	author GregorHagedorn;	state Exp;
branches;
next	1.9;

1.9
date	2005.01.06.16.42.44;	author BobMorris;	state Exp;
branches;
next	1.8;

1.8
date	2004.06.21.11.30.03;	author GregorHagedorn;	state Exp;
branches;
next	1.7;

1.7
date	2003.12.16.09.15.59;	author GregorHagedorn;	state Exp;
branches;
next	1.6;

1.6
date	2003.12.16.06.06.57;	author BobMorris;	state Exp;
branches;
next	1.5;

1.5
date	2003.11.20.17.46.09;	author GregorHagedorn;	state Exp;
branches;
next	1.4;

1.4
date	2003.11.20.09.45.27;	author GregorHagedorn;	state Exp;
branches;
next	1.3;

1.3
date	2003.11.20.02.11.00;	author BobMorris;	state Exp;
branches;
next	1.2;

1.2
date	2003.11.19.20.39.00;	author BobMorris;	state Exp;
branches;
next	1.1;

1.1
date	2003.11.19.16.11.38;	author BobMorris;	state Exp;
branches;
next	;


desc
@none
@


1.13
log
@none
@
text
@%META:TOPICINFO{author="GarryJolleyRogers" date="1259118872" format="1.1" version="1.13"}%
%META:TOPICPARENT{name="ClosedTopicSchemaDiscussionSDD09"}%
---+!! %TOPIC%

Except for the background most of the discussion below is obsoleted by the completed debugref tool described on DebugRef. The tool can be used either standalone or by plugging your instance document into a web page mentioned there. 

-- Main.BobMorris - 16 Dec 2003

---

Background: In Descriptions and elsewhere, BDI.SDD_ makes extensive use of the XML Schema key/keyref mechanisms. For reasons that can, if desired, be argued elsewhere, the drafters decided that key uniqueness is best facilitated by using integers, not strings, as keys. (Roughly, the arguments arise from the fact that keys will be machine generated.)  One consequence of this is that wherever keyrefs are in use, they will have a value uninformative to a human attempting to debug an instance document. For this reason, any place there is a keyref (or an attribute whose type is derived from the keyref base data type), there is also a string-valued optional attribute named "debugref". Its precise semantics are unspecified, but the intention is to allow for something meaningful to be placed there to aid debugging.
For example, where the keyref might be the integer 783445, the debugref might have value "WingColor state = blue", signifying that the reference is to the "blue" state of a character named "WingColor". A typical use case for debugref would be a programmer and a biologist collaboratively trying to understand why a keyref points into something strange. Typically this would reflect a programming error that might arise because the programmer did not understand some context of a reference. (However, the Schema architecture is designed so that a great many such errors are detected by XML validation).

To aid debugging Main.JacobAsiedu has written an XSLT program that examines a keyref, traces back to the referenced key, uses some heuristics to choose one of the several bits of text that are associated with the thing that key is on, and puts it in the debugref.

This is not a terribly robust solution. It does not survive changes to the schema even as simple as renaming one of the objects mentioned in the heuristic. It also may be that the heuristics choose something that is optional and absent, whereas something else might have been a better choice. 

We are examining table-driven approaches to this, though they are not much better than saying "just modify the XSLT if the Schema changes." One alternative that comes to mind is an optional text-valued attribute named, say, "debugtext", on every keyed object. Then a program like Jacob's could look for that and use it if it is there, or if if not, use heuristics if the program so chooses. I call this the "printf" approach, following the practice of many programmers to insert output statements at the point at which they have or anticipate debugging needs.

Comments?

-- Main.BobMorris - 20 Nov 2003   
---

I am very grateful to Bob and Jacob for creating a first version of the XSL script. That will be very helpful when we try to debug our first applications!

As proposed, I have added optional debugkey attributes in addition to the already existing debugref attributes. Each debugref now uniquely corresponds with a debugkey. As a consequence, the place where a debugref points to can be found with a simple text search. Also it may make the creation of the debugrefs easier.

By design of BDI.SDD_, most keyed objects have a required and unique label (controlled by xml schema identity constraints). This is true for characters, states, Stat. measures, <nop>CodingStatus, modifiers, concept trees, key trees, all resources. In some cases the labels have to be derived. Most problematic are the node keys that we have.

I already have a document discussing the debugkey/ref issue and have added a lists all keyed objects and a method to derive human readable debugkey labels for them, see http://160.45.63.11/Projects/TDWG-BDI.SDD_/Docs/SDD_I_KeyKeyref.html

Gregor Hagedorn - 20 Nov 2003@


1.12
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="LeeBelbin" date="1258685124" format="1.1" reprev="1.12" version="1.12"}%
d11 1
a11 1
Background: In Descriptions and elsewhere, BDI.SDD makes extensive use of the XML Schema key/keyref mechanisms. For reasons that can, if desired, be argued elsewhere, the drafters decided that key uniqueness is best facilitated by using integers, not strings, as keys. (Roughly, the arguments arise from the fact that keys will be machine generated.)  One consequence of this is that wherever keyrefs are in use, they will have a value uninformative to a human attempting to debug an instance document. For this reason, any place there is a keyref (or an attribute whose type is derived from the keyref base data type), there is also a string-valued optional attribute named "debugref". Its precise semantics are unspecified, but the intention is to allow for something meaningful to be placed there to aid debugging.
d29 1
a29 1
By design of BDI.SDD, most keyed objects have a required and unique label (controlled by xml schema identity constraints). This is true for characters, states, Stat. measures, <nop>CodingStatus, modifiers, concept trees, key trees, all resources. In some cases the labels have to be derived. Most problematic are the node keys that we have.
d31 1
a31 1
I already have a document discussing the debugkey/ref issue and have added a lists all keyed objects and a method to derive human readable debugkey labels for them, see http://160.45.63.11/Projects/TDWG-BDI.SDD/Docs/SDD_I_KeyKeyref.html
d33 1
a33 1
Gregor Hagedorn - 20 Nov 2003
@


1.11
log
@Added topic name via script
@
text
@d1 2
a4 2
%META:TOPICINFO{author="GregorHagedorn" date="1146741988" format="1.0" version="1.10"}%
%META:TOPICPARENT{name="ClosedTopicSchemaDiscussionSDD09"}%
d11 1
a11 1
Background: In Descriptions and elsewhere, SDD makes extensive use of the XML Schema key/keyref mechanisms. For reasons that can, if desired, be argued elsewhere, the drafters decided that key uniqueness is best facilitated by using integers, not strings, as keys. (Roughly, the arguments arise from the fact that keys will be machine generated.)  One consequence of this is that wherever keyrefs are in use, they will have a value uninformative to a human attempting to debug an instance document. For this reason, any place there is a keyref (or an attribute whose type is derived from the keyref base data type), there is also a string-valued optional attribute named "debugref". Its precise semantics are unspecified, but the intention is to allow for something meaningful to be placed there to aid debugging.
d22 1
a22 1
-- Main.BobMorris - 20 Nov 2003	
d29 1
a29 1
By design of SDD, most keyed objects have a required and unique label (controlled by xml schema identity constraints). This is true for characters, states, Stat. measures, <nop>CodingStatus, modifiers, concept trees, key trees, all resources. In some cases the labels have to be derived. Most problematic are the node keys that we have.
d31 1
a31 1
I already have a document discussing the debugkey/ref issue and have added a lists all keyed objects and a method to derive human readable debugkey labels for them, see http://160.45.63.11/Projects/TDWG-SDD/Docs/SDD_I_KeyKeyref.html
a33 1

@


1.10
log
@none
@
text
@d1 2
@


1.9
log
@none
@
text
@d1 2
a2 2
%META:TOPICINFO{author="BobMorris" date="1105029764" format="1.0" version="1.9"}%
%META:TOPICPARENT{name="SchemaDiscussionSDD09"}%
@


1.8
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="GregorHagedorn" date="1087817403" format="1.0" version="1.8"}%
d3 28
a30 28
Except for the background most of the discussion below is obsoleted by the completed debugref tool described on ToolsForUseWithSDD. The tool can be used either standalone or by plugging your instance document into a web page mentioned there. 

-- Main.BobMorris - 16 Dec 2003

---

Background: In Descriptions and elsewhere, SDD makes extensive use of the XML Schema key/keyref mechanisms. For reasons that can, if desired, be argued elsewhere, the drafters decided that key uniqueness is best facilitated by using integers, not strings, as keys. (Roughly, the arguments arise from the fact that keys will be machine generated.)  One consequence of this is that wherever keyrefs are in use, they will have a value uninformative to a human attempting to debug an instance document. For this reason, any place there is a keyref (or an attribute whose type is derived from the keyref base data type), there is also a string-valued optional attribute named "debugref". Its precise semantics are unspecified, but the intention is to allow for something meaningful to be placed there to aid debugging.
For example, where the keyref might be the integer 783445, the debugref might have value "WingColor state = blue", signifying that the reference is to the "blue" state of a character named "WingColor". A typical use case for debugref would be a programmer and a biologist collaboratively trying to understand why a keyref points into something strange. Typically this would reflect a programming error that might arise because the programmer did not understand some context of a reference. (However, the Schema architecture is designed so that a great many such errors are detected by XML validation).

To aid debugging Main.JacobAsiedu has written an XSLT program that examines a keyref, traces back to the referenced key, uses some heuristics to choose one of the several bits of text that are associated with the thing that key is on, and puts it in the debugref.

This is not a terribly robust solution. It does not survive changes to the schema even as simple as renaming one of the objects mentioned in the heuristic. It also may be that the heuristics choose something that is optional and absent, whereas something else might have been a better choice. 

We are examining table-driven approaches to this, though they are not much better than saying "just modify the XSLT if the Schema changes." One alternative that comes to mind is an optional text-valued attribute named, say, "debugtext", on every keyed object. Then a program like Jacob's could look for that and use it if it is there, or if if not, use heuristics if the program so chooses. I call this the "printf" approach, following the practice of many programmers to insert output statements at the point at which they have or anticipate debugging needs.

Comments?

-- Main.BobMorris - 20 Nov 2003	
---

I am very grateful to Bob and Jacob for creating a first version of the XSL script. That will be very helpful when we try to debug our first applications!

As proposed, I have added optional debugkey attributes in addition to the already existing debugref attributes. Each debugref now uniquely corresponds with a debugkey. As a consequence, the place where a debugref points to can be found with a simple text search. Also it may make the creation of the debugrefs easier.

By design of SDD, most keyed objects have a required and unique label (controlled by xml schema identity constraints). This is true for characters, states, Stat. measures, <nop>CodingStatus, modifiers, concept trees, key trees, all resources. In some cases the labels have to be derived. Most problematic are the node keys that we have.

I already have a document discussing the debugkey/ref issue and have added a lists all keyed objects and a method to derive human readable debugkey labels for them, see http://160.45.63.11/Projects/TDWG-SDD/Docs/SDD_I_KeyKeyref.html

@


1.7
log
@none
@
text
@d1 2
a2 2
%META:TOPICINFO{author="GregorHagedorn" date="1071566157" format="1.0" version="1.7"}%
%META:TOPICPARENT{name="SchemaDiscussion"}%
@


1.6
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="BobMorris" date="1071554817" format="1.0" version="1.6"}%
d3 3
a5 1
Except for the Background ost of the discussion below is obsoleted by the completed debugref tool described on ToolsForUseWithSDD. The tool can be used either standalone or by plugging your instance document into a web page mentioned there. -- Main.BobMorris - 16 Dec 2003
d8 1
a12 3
---


d31 2
a32 1
Gregor Hagedorn - 20 Nov 2003
@


1.5
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="GregorHagedorn" date="1069350369" format="1.0" version="1.5"}%
d3 3
d9 3
a11 1
To aid debugging Main.JacobAsiedu has written an XSLT program that examines a keyref, traces back to the referenced key, uses some heuristics to choose one of the several bits of text that are associated with the thing that key is on, and puts it in the debugref. You can find this at http://www.cs.umb.edu/efg/SDD/sdd/debugSDD.xsl. 
d31 1
a31 2
Gregor Hagedorn - 20 Nov 2003

@


1.4
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="GregorHagedorn" date="1069321527" format="1.0" version="1.4"}%
d20 1
a20 1
However, I strongly dislike the debugkey/text proposal. By design of SDD, most keyed objects have a required and unique label (controlled by xml schema identity constraints). This is true for characters, states, Stat. measures, <nop>CodingStatus, modifiers, concept trees, key trees, all resources.
d22 1
a22 1
In some cases the labels have to be derived. Most problematic are the node keys that we have.
d24 1
a24 1
I will try to write a document that lists all keyed objects and a method to derive a human readable key for them.
d26 1
a26 1
Gregor Hagedorn - 20 Nov 2003	
@


1.3
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="BobMorris" date="1069294260" format="1.0" version="1.3"}%
a8 2


d13 1
d15 2
d18 1
a18 2
Comments?

d20 1
d22 1
d24 1
d26 2
a27 1
-- Main.BobMorris - 20 Nov 2003	
@


1.2
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="BobMorris" date="1069274340" format="1.0" version="1.2"}%
d6 3
a8 1
To aid debugging Main.JacobAsiedu has written an XSLT program that examines a keyref, traces back to the referenced key, uses some heuristics to choose one of the several bits of text that are associated with the thing that key is on, and puts it in the debugref. You can find this at http://www.cs.umb.edu/efg/SDD/sdd/debugSDD.xsl. At this writing, it carries a cvs version <verbatim> $Id: debugSDD.xsl,v 1.1.1.1 2003/11/19 20:10:42 ram Exp $</verbatim>
d23 1
a23 1
-- Main.BobMorris - 19 Nov 2003
@


1.1
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="BobMorris" date="1069258298" format="1.0" version="1.1"}%
d6 2
a7 1
To aid debugging Main.JacobAsiedu has written an XSLT program that examines a keyref, traces back to the referenced key, uses some heuristics to choose one of the several bits of text that are associated with the thing that key is on, and puts it in the debugref. 
d13 2
@