[legalxml-econtracts] FW: JMcClureListingContract.xml

[John McClure <jmcclure@hypergrove.com>]

(Long reply)

Alexander and Rinke,
You both make good points, clearly showing your proficiencies with the problems of multiple languages. Let me address some of your remarks.

1. I do propose that at a minimum a separate element for each 639-1 code be established. Although these can duplicate html tags, and undoubtedly duplicate tags in other XML applications, I don't care too much about that, because namespaces allow one to clearly distinguish these elements. I care much more about simplicity, programming-wise, standards-wise. There is no question in my mind that <en> is alot simpler to write, to parse, to program for, to understand, than <TextVersion xml:lang='en'>. Nevertheless, I take your point about the 639-2 codes, and suggest that we talk more about that later.

I don't stop with languages. I do also propose that financial amounts be encapsulated within elements that indicate their currencies (and scale), e.g., <usd>1000</usd> represents $1000 USD, which is equivalent to <usd3>1</usd3> .... this is SO much easier than attributes or elements that point to World Bank definitions of currencies, or ones that have a scale='3' attribute. I do also propose that measurements be encapsulated in elements that indicate their units (and scale), e.g. <sqft> means "square feet" and <m3> = "cubic meter", rather than (again) having attributes that point to ISO definitions of numeric units ... just how often are these definitions expected to change anyway (if not much, then what we're left with is pure 'metadata overhead') ... my point is that the acronyms SIMPLIFY our programming lives and data-entry lives, while also meeting the requirement to distinguish between dollars and euros. In other words, if society at large can meaningfully use "USD" and "SQFT" throughout its analog writings, why can't we, armed as we are with powerful processors, do the same? [I could also mention the ease of translating elements-->elements vs elements+attributes-->elements+attributes.]

2. The fact that xml:lang is a standard from W3C -- whose standards I completely respect and follow -- is accommodated by the parsing algorithm I spoke of that implies an <en> when it encounters xml:lang=en. I agree with you that few today are using xml:lang in the real world, but the need still exists to identify the language axis for text strings. So, it seems to me that that world-wide pushback is certain to be less if the language is identified by an element rather than a usually-vestigial attribute -- there's no way to avoid it then! 

3. I'm not really seeing the point about multiple languages within a block of text. I see no problem embedding <en>language elements within language elements <la>et alia</la></en>.  This is pithy, and thus it is good, to my eye at least!

4. The length of the file isn't a hill of beans as you point out. However, the performance of DOM parsers have been shown to be sensitive to the length of element names (parsers often index the XML file by element-name). I was thinking more about the manual typing of the darn tags when I wrote that it's alot shorter to write <en> rather than <TextVersion xml:lang='EN'>  (incidentally, I believe that the 639 standard to which xml:lang ascribes expects its values to be UPPERCASE....)

5. "I do not see the use of incorporating the dot-notation in XML files.Why not translate these things on-the-fly and keep the semantics of your XML notation explicit by using the more elaborate notation?"  -- The fundamental issue is that a "document" represents multiple information models co-incidentally. I noted that for the sample contract, there are three (3) models at work: (a) physical (b) document (c) legal property. Yes, there are others as well, but these were the ones interesting to ME. For ME, I don't care about a "contract model" that identifies promises, obligations, compensations, and contingencies -- all items totally sensible to attorneys looking at the document who might mark up the document (using the names attribute) with names that reflect those concepts. Having a names attribute as I propose allows as many models as one wishes to identify, or as few, for that matter.

Given the fact that there are multiple information models in a document, I think the primary "process" question for standards-making organizations is "should a standard focus on one selected information model, or should it accommodate multiple models simultaneously". You see, if a standard wants to define elements for multiple information models simultaneously, then it must be prepared to handle the (common) situation that XML rules will be broken by 

	<anElementForModel1>model 1 content
		<anElementForModel2>content in both model 1 and 2
	</anElementForModel1>model 2 content
		</anElementForModel2>

The only reasonable technique to overcome this problem that I've found is the "names" attribute, where the name entered allows multiple concepts to be associated with the content of the element. In the code below, the content for anElementForModel2 = anElementForModel2.en.1 + anElementForModel2.en.2. [The .1 and .2 suffixes, after the language indicator, identifies fragments of text that are to be reconstituted into an element of the suffixed name.]

	<en names='anElementForModel1.en'>model 1 content
		<en names='anElementForModel2.en.1'>content in both model 1 and 2</en>
	</en>
	<en names='anElementForModel2.en.2'>model 2 content</en>

Now, to answer the question. The dot-notation allows one to extract "views" of a document from the document itself, rather than as a result of subjecting the document to a transform (a transform that will usually not work anyway due to insufficient information). So, any one of these views can be constructed "on the fly" by DHTML (and other techniques). It is this "view-rich" document that I would like to be standardized, not any one's or any group's selected view-of-the-month. In other words, selecting one particular view for standardization has the (grave) impact of preventing other views to be expressed at the same time in the same document -- this would be a poor standard, to me anyway. 

As a note, the "dotted" notation represents a slight modification to EcmaScript (javascript) naming standards, the notable difference being the use of .idx, e.g., Document.Clause.2.en refers to the second clause in the document. That's necessary so as to avoid seeing Document.Clause[1].en in the names attribute, which of course is a non-conforming XML name, while <Document.Clause.2.en> is quite legal. In other words, I wantto preserve transparency between the value(s) of the "names" attribute and its (their) use as an XML element name. It is on this foundation that this approach precludes having XML attributes that carry semantic information (like xml:lang, or a units attribute, or a scale attribute) used in the interpretation of the data in the document.

6. "The dot-notation hides the structure of your document from an XML parser. " Yes and no. The fact that the EXCHANGED document hides its structure from an XML parser doesnt bother me. As noted, any one view (or all of them, simultaneously!) is easy to extract, creating XML elements, and that XML datastream may then be subjected to an XML (validating) parser.

7. "We prefer selecting the TextVersion on the basis of the xml:lang attribute because of multiple reasons:
a) you are only dependent on one standard (XSL) instead of two (XSL and CSS).
b) you can generate XML documents containing only one of the two textversions.
c) we don't have to be bothered by defining all languages you can use in (fairly large) CSS files."

a) LegalXM -- as I understand and as I support-- is concerned with a standard that works for both XSL and CSS stylings.
b) this doesnt seem to relate to the present xml:lang vs <iso639> question, but more to subsequent stages of document processing
c) there are only 187 639-1 codes. I don't see this as a problem. Yes there are around 800 639-2 codes, but so what -- unknown codes can be handled by default patterns in an XSL, and even so, another 800 templates doesnt bother me so very much. Bottom-line to me is, the document creator needs to anticipate the content of subject documents, what to write the stylesheets to. If there are only 5 languages constituting 99.9% of discourse, then maybe just do those five, and have software pre-process the datastreams for other languages, inserting as necessary styling directives that are applicable. There's alot of room for creative solutions here!

Whew! I hope I answered your questions. Lest anyone get the wrong impression, let me say that I have no interest in seeing <TextVersion> or any other tag in Metalex be modified -- I am not here about Metalex. I am here about the standard for eContracts at LegalXML. I forwarded the note to LexML because yours is a fraternal org to LegalXML, and yours has a decidedly advanced, coherent view of standards-making, one that seeks to use the RDF (which happens to be my starting-point also) and one that views XML Namespaces as a deployed, accepted, W3C standard that is meant to be used.

Thanks very much for your interest.
Regards,
John McClure

-----Original Message-----
From: Maiser@elaw.leiden.edu [mailto:Maiser@elaw.leiden.edu]On Behalf Of
Alexander Boer
Sent: Tuesday, October 08, 2002 8:19 AM
To: LEXML <lexml@law.leiden.edu>
Subject: RE: JMcClureListingContract.xml


Dear John,

You wrote:
> the length of the file. Why not just save everyone alot of energy 
> by having a simple <en> element or <nl> element? Doing so, CSS 

I designed that multiple language Text/TextVersion construct in 
Metalex. Because there may be more people on this mailing list 
interested in language issues I will explain my three reasons for 
distinguishing the xml:lang attribute from the element:

1) In my mind there is conceptual distinction between different 
TextVersions and mere different languages as in:

"'Of two evils, the lesser must always be chosen' is the English 
translation of: 'De duobus malis, minus est semper eligendum'."

"'Van twee kwaden, moet altijd de minste gekozen worden' is de 
Nederlandse vertaling van 'De duobus malis, minus est semper 
eligendum'."

I count two TextVersions (en, nl), and three languages here (en, nl, 
la). Metalex has no tags to indicate that the sentence contains a 
Latin quote of Thomas a Kempis, but it does allow elements from other 
namespaces in the TextVersion to assert that in a xml:lang attribute.
Note that two TextVersions may also have the same language value, but 
for instance different metalex:date-publication values.

2) How would you define these language tags in a schema (or dtd)? By 
enumerating them? ISO 639, ISO 3166, IANA-LANGCODES give 'nl', 'dut', 
and 'nld' as values for Dutch in xml:lang (and maybe low german 'nds', 
'allemand, bas', 'saxon, bas', 'bas allemand', 'bas saxon' are also 
defensible candidates for very old Dutch text). In addition, new 
proposals for language names can be submitted to IANA on a simple form. 
If you want a language-independent standard you cannot enumerate them 
at present. I don't want to change the schema just because someone 
decides to put a Metalex document in Kikuyu or Navajo on the web.

3) The xml:lang attribute is the standard way of doing such things 
and is to some extent transparent to search engines like Google.
It has been around for so long now, that it may even become useful 
someday.

> pick out the text for that element and (c) adds unnecessarily to 
> the length of the file. Why not just save everyone alot of energy 

If you are concerned about the length of the file why do you use XML?
Sorry, I just had to say that. 

If you like short element names, by the way, there is a good change you 
have regularly used official language values as element names without 
knowing it. In html for instance , <hr> is also  code for Croatian 
(Hrvatska) and <li> for minority language Limburgian in the 
Netherlands (the old proverb goes that every pair of Dutchmen is a 
separate church, but nowadays they may also register themselves as a 
separate language at IANA).

Regards,

Alexander Boer

-----Original Message-----
From: Maiser@elaw.leiden.edu [mailto:Maiser@elaw.leiden.edu]On Behalf Of
Rinke Hoekstra
Sent: Tuesday, October 08, 2002 6:50 AM
To: LEXML <lexml@law.leiden.edu>
Subject: RE: JMcClureListingContract.xml


--
A copy of this mail has been sent to the MetaLex mailing list.
--

Dear John,

Although I am not the direct author of the MetaLex styles and schemas, I would like to comment on your mail.
| For instance the name that I use in the markup
| "Document.Signature.4.LegalName.en" can be easily parsed to produce an XML
| datastream that uses the xml:lang attribute, which looks like
| 
| 	<Document>
| 		<Signature id='Signature.4'>
| 			<LegalName xml:lang='en'>qwerty</></></>

This I understand, but I do not see the use of incorporating the dot-notation in XML files. Why not translate these things on-the-fly and keep the semantics of your XML notation explicit by using the more elaborate notation. The dot-notation hides the structure of your document from an XML parser. 

| At the same time, the parsing software could respect any xml:lang
| attribute it discovers in the datastream, in the absence of finding <nl>
| for instance. However, you know that the xml:lang attribute has to be put
| as an attribute on SOME element. Fpr instance, I see on your site that you
| have put them on numerous <TextVersion> elements. This means (a) CSS
| selectors can't be used (you may also have experienced, the support for
| CSS attribute-oriented selectors is spotty at best, and is almost non-
| existent in IE 6.x) 

I agree. However, you could adapt a style-sheet (or create your own) to translate an custom attribute to the TextVersion element to a custom element in your HTML file. No need to make your data-structure (your XML document) dependent of the way you want to present it.

| (b) XSL predicates have to be something like
| select='TextVersion[@xml:lang="EN" or @xml:lang="en"]' to pick out the
| text for that element and 

The XSL stylesheets we developed (credits to Alexander Boer) for generating (X)HTML presentations of documents have 1 position in them where you select the language on the basis of which a TextVersion is selected.

| (c) adds unnecessarily to the length of the file. 

This is not a real problem, in my opinion. Since the XSL stylesheets are really very small (compared to a normal JPG or GIF image...).


| Why not just save everyone alot of energy by having a simple <en>
| element or <nl> element? Doing so, CSS selectors can be written to show
| the english and hide the Dutch eg nl {display:none} en {display:inline}.

We prefer selecting the textversion on the basis of the xml:lang attribute because of multiple reasons:
a) you are only dependent on one standard (XSL) instead of two (XSL and CSS).
b) you can generate XML documents containing only one of the two textversions. (This you can also do using the <en> and <nl> tags, I agree, but then you will need to rewrite your XSL file)
c) we don't have to be bothered by defining all languages you can use in (fairly large) CSS files. Using xml:lang, a user could define any language of his choosing, e.g. x38472, as spoken planet X, without us needing to include it in a CSS file. The only adaptation needed in the XSL file is the chaning of one attribute.

| Arguably the XSL is also alot easier to write --
| select='TextVersion/en'... So, this is an EASIER standard to use, from the
| view of a programmer. After all, that's who the standards are for. Your
| stylesheet could be faster and more robust if
| 	<xsl:template match="metalex:TextVersion">
| 	<xsl:choose>
| 		<xsl:when test="$selectedLang!=''">
| 			<xsl:if test="@xml:lang=$selectedLang">
| 				<xsl:apply-templates />
| 			</xsl:if>
| 		</xsl:when>
| 		<xsl:otherwise>
| 			<xsl:apply-templates />
| 		</xsl:otherwise>
| 	</xsl:choose>
| 	</xsl:template>
| 
| is changed to
| 	<xsl:template match="*[local-name()="en"] |
| metalex:TextVersion[@xml:lang='en' or @xml:lang='EN']">
| 		<span xml:lang='EN' class='en'><xsl:apply-templates /></span>
| 	</xsl:template>

I agree your solution is faster, but it is less general (with every language you add, you need to rewrite your XSL completely), and I doubt whether this is really much easier to write down.

| 
| and in the <style type='css'> element you say
| 	*.en {display:none}
| 	*.nl {display:none}
| 	<xsl:choose>
| 	<xsl:when test='$selectedLang="EN"'>
| 		*.en {display:inline}
| 	</xsl:when>
| 	<xsl:when test='$selectedLang="NL"'>
| 		*.nl {display:inline}
| 	</xsl:when>
| 	</xsl:choose>

We would like to keep the css (presentation) part independent of the XSL stylesheet (different file) because different publishers might have their own in-house presentation style.

| The advantages of this code are (a) keeps the language identifier,
| xml:lang, associated with the output element 

I do not really see your point, but this could be me ;)

| (b) outputs other languages, but doesnt show them 

The 'outputs' part of your remark is not really clear to me. In MetaLex you download the whole XML file, containing the entire document (in all languages), the XSL stylesheet translates this XML file on-the-fly to a XHTML presentation. 

| (c) allows a user interface to change the language
| shown without re-running the source through the stylesheet, and allows the
| user interface to elect to view multiple languages simultaneously.

I don't know whether CSS or XSL really differ that much in the way a document is parsed (speed-wise that is). This should not be a real problem, applying an XSL sheet is as easy as a page refresh in your browser. Regarding the multiple languages part of your remark, we have provided a stylesheet (standard_document2html_copy.xsl) that ignores the TextVersion part, thereby creating a multi-language HTML document.

| 
| I applaud your use of RDF -- I am squarely in the same camp. I want to
| take some time to review your site, and give you feedback. You may know
| that I have a close relationship with Murk, and have spoken to the Swiss
| Federal Chancellery
| (http://www.hypergrove.com/SwissFederalChancellery.pdf) about XML markup.

Thank you, I will read the document with much interest. And thank you for your remarks wrt MetaLex.

Regards,

	Rinke Hoekstra

------------------------------------
Rinke Hoekstra  rinke@lri.jur.uva.nl
Department of Computer Science & Law
University of Amsterdam, PO Box 1030 
1000 BA  Amsterdam,  the Netherlands
------------------------------------


> -----Oorspronkelijk bericht-----
> Van: Maiser@law-coo2.leidenuniv.nl
> [mailto:Maiser@law-coo2.leidenuniv.nl]Namens John McClure
> Verzonden: Monday, October 07, 2002 8:16 PM
> Aan: LEXML <lexml@law.leiden.edu>
> Onderwerp: RE: JMcClureListingContract.xml
> 
> 
> Rinke,
> Good question. The most important reason is due my work on the 
> relationships between MACRO LANGUAGES (ie EcmaScript) and XML 
> MARKUP, because I am developing a "power-user" macro language for 
> commercial real estate. The problems that I am solving require a 
> "name" to be assigned to arbitrary data elements -- that name can 
> then broken into separate XML elements, or the SAME NAME can be 
> used to reference a node in an EcmaScript model for the document 
> data. At the same time, we've enabled (re-)construction of XML 
> datastreams that are more "conventional". For instance the name 
> that I use in the markup "Document.Signature.4.LegalName.en" can 
> be easily parsed to produce an XML datastream that uses the 
> xml:lang attribute, which looks like
> 
> 	<Document>
> 		<Signature id='Signature.4'>
> 			<LegalName xml:lang='en'>qwerty</></></>
> 
> At the same time, the parsing software could respect any xml:lang 
> attribute it discovers in the datastream, in the absence of 
> finding <nl> for instance. However, you know that the xml:lang 
> attribute has to be put as an attribute on SOME element. Fpr 
> instance, I see on your site that you have put them on numerous 
> <TextVersion> elements. This means (a) CSS selectors can't be 
> used (you may also have experienced, the support for CSS 
> attribute-oriented selectors is spotty at best, and is almost 
> non-existent in IE 6.x) (b) XSL predicates have to be something 
> like select='TextVersion[@xml:lang="EN" or @xml:lang="en"]' to 
> pick out the text for that element and (c) adds unnecessarily to 
> the length of the file. Why not just save everyone alot of energy 
> by having a simple <en> element or <nl> element? Doing so, CSS 
> selectors can be written to show the english and hide the Dutch 
> eg nl {display:none} en {display:inline}. Arguably the XSL is 
> also alot easier to write -- select='TextVersion/en'... So, this 
> is an EASIER standard to use, from the view of a programmer. 
> After all, that's who the standards are for. Your stylesheet 
> could be faster and more robust if 
> 	<xsl:template match="metalex:TextVersion">
> 	<xsl:choose>
> 		<xsl:when test="$selectedLang!=''">
> 			<xsl:if test="@xml:lang=$selectedLang">
> 				<xsl:apply-templates /> 
> 			</xsl:if>
> 		</xsl:when>
> 		<xsl:otherwise>
> 			<xsl:apply-templates /> 
> 		</xsl:otherwise>
> 	</xsl:choose>
> 	</xsl:template>
> 
> is changed to 
> 	<xsl:template match="*[local-name()="en"] | 
> metalex:TextVersion[@xml:lang='en' or @xml:lang='EN']">
> 		<span xml:lang='EN' class='en'><xsl:apply-templates 
> /></span>
> 	</xsl:template>
> 
> and in the <style type='css'> element you say
> 	*.en {display:none}
> 	*.nl {display:none}
> 	<xsl:choose>
> 	<xsl:when test='$selectedLang="EN"'>
> 		*.en {display:inline}
> 	</xsl:when>
> 	<xsl:when test='$selectedLang="NL"'>
> 		*.nl {display:inline}
> 	</xsl:when>
> 	</xsl:choose>
> The advantages of this code are (a) keeps the language 
> identifier, xml:lang, associated with the output element (b) 
> outputs other languages, but doesnt show them (c) allows a user 
> interface to change the language shown without re-running the 
> source through the stylesheet, and allows the user interface to 
> elect to view multiple languages simultaneously.
> 
> I applaud your use of RDF -- I am squarely in the same camp. I 
> want to take some time to review your site, and give you 
> feedback. You may know that I have a close relationship with 
> Murk, and have spoken to the Swiss Federal Chancellery 
> (http://www.hypergrove.com/SwissFederalChancellery.pdf) about XML 
> markup. There is a german version at 
> http://www.hypergrove.com/SwissFederalChancellery.de.pdf.
> Regards,
> John McClure
> Hypergrove Engineering
> 211 Taylor Street, Suite 32-A
> Port Townsend, WA 98368
> 360-379-3838 (land)
> 
> >-----Original Message-----
> >From: Rinke Hoekstra [mailto:rinke@lri.jur.uva.nl]
> >Sent: Monday, October 07, 2002 6:27 AM
> >To: 'John McClure'
> >Subject: RE: JMcClureListingContract.xml
> >
> >
> >Dear John,
> >
> >Reading your email I wondered why you do not use the standard 
> xml:lang attribute to identify different languages inside a 
> >document. 
> >You might be interested in the MetaLex standard we developed. It 
> offers a language independent and easily extensible way 
> >to structure legal documents, and it will include markup for 
> contracts in the future. 
> >The website is at http://www.metalex.nl 
> >
> >Regards,
> >
> >	Rinke Hoekstra
> >
> >------------------------------------
> >Rinke Hoekstra  rinke@lri.jur.uva.nl
> >Department of Computer Science & Law
> >University of Amsterdam, PO Box 1030
> >1000 BA  Amsterdam,  the Netherlands
> >------------------------------------ 
> >
> >
> >-----Original Message-----
> >From: Maiser@law-coo2.leidenuniv.nl 
> [mailto:Maiser@law-coo2.leidenuniv.nl] On Behalf Of John McClure
> >Sent: Monday, October 07, 2002 1:21 AM
> >To: LEXML <lexml@law.leiden.edu>
> >Subject: JMcClureListingContract.xml
> >
> >Hello,
> >Attached is a sample of the simplest markup structure possible - 
> it is this that I am proposing be our standard for eContracts.
> >There are only 4 XML elements, and these contain a "names" 
> attribute whose values are defined within one or more RDF Dictionaries:
> >
> >1. <LegalXML> -  this element introduces the datastream
> >2, <LegalDocument> - this element introduces a document in the datastream
> >3. <en> - this element contains English text
> >4. <style> - this element contains the CSS styling directives 
> for the document
> >
> >The <en> element may contain mixed content -- english text plus 
> child <en> elements. This element contains a "names" attribute that
> >holds one or more names assigned to the element which accord 
> with the dictionary(s) specified for the datastream. This 
> >technique has
> >been shown to be effective when there are multiple information 
> models at work in a document. In this case, there are 3 coexisting
> >models:
> >
> >1. Document model -- identifies Dublin Core information for the 
> document, eg title, creator, date, and other metadata
> >2. Physical model - identifies the pagination of the document, 
> the layout of information on a page, the page number, etc
> >3. Property model - identifies information about the property, 
> such as address, sellers, broker and brokerage names, legal
> >descriptions, etc.
> >
> >With appropriate software, this datastream can be converted to 
> another format appropriate to INTERNAL processing by a document
> >recipient. For example, in this following snippet, TWO names are 
> assigned to some text content of the document. The first name says
> >that the text is "the english version of the legal name of the 
> 4th signatory to the document", and the second name indicates that
> >the same text is "the english version of the legal name of a 
> seller of legal property".
> >
> >	<en 	class='Seller2LegalName'
> >		names='Document.Signature.4.LegalName.en 
> Property.Seller.2.LegalName.en'
> >	>Seller #2 Legal Name</en>
> >
> >This markup can be converted into a form that is appropriate to 
> INTERNAL processing by a document recipient, e.g.,
> >
> >	<Document.Signature.4.LegalName.en>Seller #2 Legal 
> Name</Document.Signature.4.LegalName.en>
> >	<Property.Seller.2.LegalName.en>Seller #2 Legal 
> Name</Property.Seller.2.LegalName.en>
> >
> >or it could be converted into a range of alternative encodings 
> that are appropriate to INTERNAL processing by the recipient.
> >
> >The objective is to create a standard that accommodates evolving 
> information models, without creating the need to change the
> >standard whenever anyone needs to augment the 'standardized' 
> model, or wishes to create their own model. It keeps the 
> >metadata about
> >one's model in a single place -- a dictionary that is federated 
> with other dictionaries -- rather than haphazardly entwined with
> >one's legacy markup. But most important of all, it is SIMPLE, 
> while meeting all of our primary requirements, most specifically that
> >concerned with accommodating CSS styling -- a requirement in 
> particular one yet to be satisfied by sample markup posted thus far.
> >
> >My plans include adding the other 2 pages to this particular 
> contract -- these attachments provide detailed information about the
> >property being listed for sale, and would be a challenge for any 
> less open-ended encoding scheme than what is proposed here.
> >Thanks,
> >John McClure
> >US Contracts.com
> >
> >
> >
> 
>