[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[ff-cvs] alph doc/pegboard/refstring_dtd--tjl/peg.rst or...
|
From: |
Tuomas J. Lukka |
|
Subject: |
[ff-cvs] alph doc/pegboard/refstring_dtd--tjl/peg.rst or... |
|
Date: |
Sat, 04 Oct 2003 07:58:53 -0400 |
CVSROOT: /cvsroot/alph
Module name: alph
Branch:
Changes by: Tuomas J. Lukka <address@hidden> 03/10/04 07:58:52
Modified files:
doc/pegboard/refstring_dtd--tjl: peg.rst
org/nongnu/alph: Span.java Span1D.java
org/nongnu/alph/impl: AbstractSpan1D.java URN5SpanMaker.java
org/nongnu/alph/xml: SpanReader.java SpanSerializer.java
serialization.test
Added files:
. : LITE
data : tstring.xsd
doc/pegboard/deprecations1--tjl: peg.rst
org/nongnu/alph: FakeTextSpan.java RICCTextSpan.java
TString.java ricctextspan.test tstring.test
org/nongnu/alph/xml: schema.test
Removed files:
org/nongnu/alph/impl: FakeTextSpan.java URN5TextSpan.java
urn5textspan.test
Log message:
Arch sync
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/LITE?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/data/tstring.xsd?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/doc/pegboard/deprecations1--tjl/peg.rst?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/doc/pegboard/refstring_dtd--tjl/peg.rst.diff?tr1=1.1&tr2=1.2&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/FakeTextSpan.java?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/RICCTextSpan.java?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/TString.java?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/ricctextspan.test?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/tstring.test?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/Span.java.diff?tr1=1.3&tr2=1.4&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/Span1D.java.diff?tr1=1.2&tr2=1.3&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/impl/AbstractSpan1D.java.diff?tr1=1.2&tr2=1.3&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/impl/URN5SpanMaker.java.diff?tr1=1.3&tr2=1.4&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/xml/schema.test?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/xml/SpanReader.java.diff?tr1=1.11&tr2=1.12&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/xml/SpanSerializer.java.diff?tr1=1.12&tr2=1.13&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/alph/alph/org/nongnu/alph/xml/serialization.test.diff?tr1=1.15&tr2=1.16&r1=text&r2=text
Patches:
Index: alph/doc/pegboard/refstring_dtd--tjl/peg.rst
diff -u alph/doc/pegboard/refstring_dtd--tjl/peg.rst:1.1
alph/doc/pegboard/refstring_dtd--tjl/peg.rst:1.2
--- alph/doc/pegboard/refstring_dtd--tjl/peg.rst:1.1 Sun Sep 28 08:35:29 2003
+++ alph/doc/pegboard/refstring_dtd--tjl/peg.rst Sat Oct 4 07:58:51 2003
@@ -1,11 +1,11 @@
=============================================================
-PEG refstring_dtd--tjl: A DTD for refstrings
+PEG refstring_dtd--tjl: An XML schema for transcludable text
=============================================================
:Author: Tuomas J. Lukka
-:Last-Modified: $Date: 2003/09/28 12:35:29 $
-:Revision: $Revision: 1.1 $
-:Status: Current
+:Last-Modified: $Date: 2003/10/04 11:58:51 $
+:Revision: $Revision: 1.2 $
+:Status: Accepted
:Affects-PEGs: alph_lite--tjl
With Alph lite, we need to stabilize at least that data format.
@@ -40,13 +40,10 @@
In *all* semantics, these two lines should be equivalent.
-- What should be the public identifier of this DTD?
+- How should we define the TString DTD/Schema? DTD or Schema or other?
- RESOLVED: The best reference to public identifiers
- I've found on the web is http://docbook.kldp.net/stuff/tdg/ch02s03.html
-
- According to those rules, we should probably use
- ``+//IDN fenfire.org//DTD Transcludable String v1.0//EN
+ RESOLVED: XML Schemas seem the best option, due to proper namespace
+ support &c.
- What should be the URI for use with XML namespaces?
@@ -54,52 +51,189 @@
conventions,
``http://fenfire.org/xmlns/2003/09/tstring#``
-The Transcludable String XML DTD
-================================
+The Transcludable String XML Schema
+===================================
-Define a Transcludable String DTD as follows::
+Define a Transcludable String XML schema as follows::
-XXX Change to XML schema!
+ <schema xmlns="http://www.w3.org/2001/XMLSchema";
+ xmlns:alph="http://fenfire.org/xmlns/2003/09/tstring#";
+ targetNamespace="http://fenfire.org/xmlns/2003/09/tstring#";
+ elementFormDefault="qualified"
+ attributeFormDefault="qualified"
+ >
- <!-- [alph LGPL license] -->
+ <annotation>
+ <documentation xml:lang="en">
+ Transcludable String schema v1.0.
- <!-- A DTD for the Transcludable String XML representation.
+ * Copyright (c) 2003, Tuomas J. Lukka
+ * This file is part of Alph.
+ *
+ * Alph is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * Alph is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
+ * Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General
+ * Public License along with Alph; if not, write to the Free
+ * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ * MA 02111-1307 USA
+
+
+ * Written by Tuomas J. Lukka
+
+ * Designed by Tuomas J. Lukka and Benja Fallenstein
+
+ </documentation>
+ </annotation>
+
+ <element name="tstring" type="alph:TStringType"/>
+ <element name="tspan" type="alph:TSpanType"/>
+
+ <complexType mixed="true" name="TStringType">
+ <annotation>
+ <documentation xml:lang="en">
+
+ A transcludable string, consisting of transcludable spans
+ and also text content (which will not be
transclusion-sensitive).
+
+ This is just a container element - the magic is in the spans.
+
+ </documentation>
+ </annotation>
+ <sequence>
+ <element ref="alph:tspan" minOccurs="0" maxOccurs="unbounded"/>
+ </sequence>
+ </complexType>
+
+ <complexType name="TSpanType">
+ <annotation>
+ <documentation xml:lang="en"><![CDATA[
+
+ A transcludable span.
+
+ Transcludable spans are spans of text that identify themselves
+ through a URI and an offset.
+
+ Basic model
+ -----------
+
+ The basic model for TSpans is that there exists a single,
unique block
+ of letters denoted by the URI, and a TSpan contains a
contiguous
+ span of letters from that block.
+
+ However, to allow practical, non-centralized implementations,
+ the restrictions are relaxed: the ids only need
+ to be unique *with a high probability*.
+
+ Creating TSpans
+ ---------------
+
+ There are two possible situations for creating TSpans:
+ creating tspans from text being typed in by a user,
+ or creating TSpans from text that already exists somewhere.
+
+ Creating TSpans while the user types
+ """"""""""""""""""""""""""""""""""""
+
+ For the URIs, we recommend "urn-5" random IDs, or UUIDs.
+ The TSpans can be generated by creating a single random id
+ for the entire session and simply increasing the current offset
+ by one whenever the user types a new character.
+
+ In the resulting text, adjacent spans that have
+ contiguous ids and offsets should be combined.
+
+ Creating TSpans from text that already exists somewhere
+ """""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+ This is a more difficult situation, as this is a case of adding
+ extra information where there used to be none. If two people
+ separately do this to the same text, it can happen that
transclusions
+ will not be found.
+
+ If the text is stable and unique, we recommend using some
Hash-based
+ URI scheme, such as urn:sha-1 or urn:x-storm, or a permanent
stable
+ identifier for exactly those characters, if that exists.
+
+ If the text is changing, **in no case** should something like
+ the URL of a webpage be used for the URI, as this will cause
undesirable
+ effects.
+
+ Editing operations
+ ------------------
+
+ TSpans should never be edited except by splitting or by
+ removing: changes to the text inside the span are not permitted.
+ For inserting text, split the span first, then insert the text
+ between the spans. For removing text, split the span
appropriately
+ and remove one of the resulting spans.
+
+ The span-splitting operation works as follows: a TSPan with uri
X offset Y,
+ and N characters of content,
+
+ <tspan uri="X" offs="Y">N chars</tspan>
+
+ becomes
+
+ <tspan uri="X" offs="Y">S chars</tspan><tspan uri="X"
offs="Y+S">N-S chars</tspan>
+
+ for some S between 0 and N, exclusive.
+
+
+ Identifying transclusions
+ -------------------------
+
+ (Regions) spans are considered to be transclusions of each
other, if
+ the URI attributes match exactly and the text with the same
offset match.
+
+ The simplest way to explain the idea of "same offset" is to
split both spans
+ to one-character spans: the offsets in the resulting spans will
be consecutive,
+ and if **all** the one-character spans with the same offsets
match,
+ the two spans *overlap*. If even one one-character span does
not match,
+ the spans will not be considered overlapping.
- Public ID:
-
- +//IDN fenfire.org/DTD Transcludable String v1.0//EN
-
- -->
- <!-- A single referential string, to be parsed (in Java)
- into a single Transcludable String object
+ Interoperability
+ ----------------
- This element may contain text (interpreted as fake spans)
- and "tspan" elements, which are RICC text spans.
- -->
- <!ELEMENT tstring (#PCDATA|tspan)*>
+ The tspan element is defined through TSpanType in order to allow
+ other elements to take on this type: for instance, SVG ignores
text
+ inside "foreign elements" unlike HTML, where the default is to
show it.
+ In HTML, using tspan thus works out all right, but in SVG the
text
+ would not be shown. The solution is to use the alph:uri and
alph:offs
+ attributes on the SVG span element.
- <!-- A single RICC text span.
- The contents is the text of the span, directly.
- The attributes of tspan can be used on elements in other
- namespaces, to interoperate, e.g., with SVG.
- -->
- <!ELEMENT tspan (#CDATA)>
- <!-- The "random" Id of the span, as a string. To find transclusions,
- these strings are compared exactly character by character.
+ Rationale
+ ---------
- One interesting point: an XML file may be compacted by replacing
- all i attributes with entities pointing to the real strings.
- -->
- <!ATTLIST tspan uri CDATA #REQUIRED>
+ The idea of TSpans is to provide a simple way to get some of
the benefits
+ of Referential Fluid Media (see Nelson, "Xanalogical structure,
needed
+ now more than ever: parallel documents, deep links to content,
deep versioning,
+ and deep re-use", ACM Computing Surveys, 31(4es), 1999) by
providing an *identity*
+ for text.
- <!-- The numeric offset of this span inside the "virtual scrollblock".
- -->
- <!ATTLIST tspan offs CDATA #REQUIRED>
+ TSpans carry their own content and thus need no central servers
+ to "resolve" the text from, and can be added to normal
applications
+ with minimal effort.
-Publish the DTD and a start a short document of how it is used (follows).
+
+ ]]></documentation>
+ </annotation>
+ <simpleContent>
+ <extension base="string">
+ <attribute name="uri" type="anyURI" use="required"/>
+ <attribute name="offs" type="nonNegativeInteger"
use="required"/>
+ </extension>
+ </simpleContent>
+ </complexType>
-Using the DTD
-=============
+ </schema>
Index: alph/org/nongnu/alph/Span.java
diff -u alph/org/nongnu/alph/Span.java:1.3 alph/org/nongnu/alph/Span.java:1.4
--- alph/org/nongnu/alph/Span.java:1.3 Sun Apr 6 04:15:04 2003
+++ alph/org/nongnu/alph/Span.java Sat Oct 4 07:58:52 2003
@@ -28,15 +28,32 @@
package org.nongnu.alph;
-/** An address span in the stable media streams.
+/** An immutable fluid media span; referential or not, depending on
+ * subclasses.
* This is abstract since we have different kinds of spans for
* text, images and video, with different operations.
* <p>
* Spans are immutable, just like Strings: all the verb-like methods
* such as join and split return new Span objects.
* <p>
- * Spans are always of some type, like TextSpan or ImageSpan,
- * and belong to a particular ScrollBlock.
+ * Spans are always of some media type, like TextSpan or ImageSpan.
+ * <p>
+ * Alph supports true referential span using scrollblocks,
+ * and transcludable, but not referential,
+ * Random-Id, Content-Carrying (RICC) spans,
+ * and non-transcludable, Fake spans.
+ * For true referential spans, the getScrollBlock() method
+ * returns the scrollblock and getScrollId() returns
+ * its id. For RICC spans, getScrollBlock() returns null and
+ * getScrollId() returns the id of the RICC span. For Fake spans,
+ * getScrollBlock() returns null and getScrollId() return
+ * an empty string.
+ * <p>
+ * Alph Lite only supports RICC and Fake text spans,
+ * so the getScrollBlock() method is irrelevant.
+ *
+ *
+ *
* @see Span
* @see Span1D
* @see TextSpan
@@ -45,21 +62,28 @@
*/
public interface Span {
-String rcsid = "$Id: Span.java,v 1.3 2003/04/06 08:15:04 tjl Exp $";
+String rcsid = "$Id: Span.java,v 1.4 2003/10/04 11:58:52 tjl Exp $";
+ /** Get a string representation of this span.
+ * For text spans, this representation is <em>not</em>
+ * the text inside but also gives the type and, in fact,
+ * complete information to reconstruct the span object.
+ */
String toString();
/** Whether this span and the given span intersect.
*/
boolean intersects(Span s);
- /** Get the ScrollBlock that this span points to.
+ /** (Irrelevant for Alph Lite)
+ * Get the ScrollBlock that this span points to.
* May return null for URN5TextSpans - if getting
* the scrollblock for the identifier, use getScrollId().
*/
ScrollBlock getScrollBlock();
/** Get the scrollblock Id.
+ * Never null; for fake spans, an empty string.
*/
String getScrollId();
Index: alph/org/nongnu/alph/Span1D.java
diff -u alph/org/nongnu/alph/Span1D.java:1.2
alph/org/nongnu/alph/Span1D.java:1.3
--- alph/org/nongnu/alph/Span1D.java:1.2 Tue Mar 25 07:25:29 2003
+++ alph/org/nongnu/alph/Span1D.java Sat Oct 4 07:58:52 2003
@@ -28,16 +28,15 @@
package org.nongnu.alph;
-/** A 1-dimensional span inside one document.
+/** A 1-dimensional immutable span inside one document.
* The different routines use "natural units" the definition
* of which depends on the span type - see the appropriate subinterfaces.
- * <b>IMMUTABLE</b>
*/
public interface Span1D extends Span {
-String rcsid = "$Id: Span1D.java,v 1.2 2003/03/25 12:25:29 tjl Exp $";
+String rcsid = "$Id: Span1D.java,v 1.3 2003/10/04 11:58:52 tjl Exp $";
- /** Get the offset of this span inside the Mediaserver block,
+ /** Get the offset of this span inside the scrollblock,
* in natural units starting at zero.
*/
int offset();
@@ -58,18 +57,6 @@
* analogous to java.lang.String.substring().
*/
Span1D subSpan(int o1);
-
- /** Get the start of the given subspan, relative to the start of this.
- * subspan must be wholly contained in this span; otherwise, an error
- * is thrown.
- */
- int getRelativeStart(Span1D subspan);
-
- /** Get the end of the given subspan, relative to the start of this.
- * subspan must be wholly contained in this span; otherwise, an error
- * is thrown.
- */
- int getRelativeEnd(Span1D subspan);
/** Return the span that results from appending the other span
* to this span, <em>if</em> the resulting span is contiguous.
Index: alph/org/nongnu/alph/impl/AbstractSpan1D.java
diff -u alph/org/nongnu/alph/impl/AbstractSpan1D.java:1.2
alph/org/nongnu/alph/impl/AbstractSpan1D.java:1.3
--- alph/org/nongnu/alph/impl/AbstractSpan1D.java:1.2 Wed Jun 11 13:50:18 2003
+++ alph/org/nongnu/alph/impl/AbstractSpan1D.java Sat Oct 4 07:58:52 2003
@@ -32,7 +32,7 @@
/** An abstract base class for 1D spans.
*/
abstract class AbstractSpan1D extends AbstractSpan implements Span1D {
-private static final String rcsid = "$Id: AbstractSpan1D.java,v 1.2 2003/06/11
17:50:18 tjl Exp $";
+private static final String rcsid = "$Id: AbstractSpan1D.java,v 1.3 2003/10/04
11:58:52 tjl Exp $";
public static boolean dbg = false;
final static void pa(String s) { System.out.println(s); }
@@ -70,24 +70,6 @@
return subSpan(o1, length());
}
- public int getRelativeStart(Span1D subspan) {
- AbstractSpan1D sp = (AbstractSpan1D)subspan;
- if(!sp.getScrollBlock().equals(this.getScrollBlock())
- || sp.offs0 < offs0 || sp.offs1 > offs1)
- throw new Error("subspan "+subspan+" not wholly contained "+
- " in this span, "+this);
- return sp.offs0 - offs0;
- }
-
- public int getRelativeEnd(Span1D subspan) {
- AbstractSpan1D sp = (AbstractSpan1D)subspan;
- if(!sp.getScrollBlock().equals(this.getScrollBlock())
- || sp.offs0 < offs0 || sp.offs1 > offs1)
- throw new Error("subspan "+subspan+" not wholly contained "+
- " in this span, "+this);
- return sp.offs1 - offs0;
- }
-
public Span1D append(Span s) {
if(!(s instanceof AbstractSpan1D)) return null;
AbstractSpan1D sts = (AbstractSpan1D)s;
@@ -108,18 +90,6 @@
AbstractSpan1D t = isSame(s);
if(t == null) return false;
return (offs0 < t.offs1) && (offs1 > t.offs0);
- }
-
- public boolean intersectsAfter(Span s) {
- AbstractSpan1D t = isSame(s);
- if(t == null) return false;
- return (offs0 < t.offs1);
- }
-
- public boolean intersectsBefore(Span s) {
- AbstractSpan1D t = isSame(s);
- if(t == null) return false;
- return (offs1 > t.offs0);
}
public boolean equals(Object o) {
Index: alph/org/nongnu/alph/impl/URN5SpanMaker.java
diff -u alph/org/nongnu/alph/impl/URN5SpanMaker.java:1.3
alph/org/nongnu/alph/impl/URN5SpanMaker.java:1.4
--- alph/org/nongnu/alph/impl/URN5SpanMaker.java:1.3 Wed Jun 11 13:50:18 2003
+++ alph/org/nongnu/alph/impl/URN5SpanMaker.java Sat Oct 4 07:58:52 2003
@@ -42,7 +42,7 @@
return makeTextSpan(""+c);
}
public TextSpan makeTextSpan(String s) {
- TextSpan t = new URN5TextSpan(urn5, offset, s);
+ TextSpan t = new RICCTextSpan(urn5, offset, s);
offset += s.length();
return t;
}
Index: alph/org/nongnu/alph/xml/SpanReader.java
diff -u alph/org/nongnu/alph/xml/SpanReader.java:1.11
alph/org/nongnu/alph/xml/SpanReader.java:1.12
--- alph/org/nongnu/alph/xml/SpanReader.java:1.11 Mon Sep 8 08:28:30 2003
+++ alph/org/nongnu/alph/xml/SpanReader.java Sat Oct 4 07:58:52 2003
@@ -68,10 +68,10 @@
String b = attributes.getValue("b");
int o = Integer.parseInt(attributes.getValue("o"));
String t = attributes.getValue("t");
- spans.add(new org.nongnu.alph.impl.URN5TextSpan(b, o, t));
+ spans.add(new org.nongnu.alph.RICCTextSpan(b, o, t));
} else if(qName.equals("fts")) {
String t = attributes.getValue("t");
- spans.add(new org.nongnu.alph.impl.FakeTextSpan(t));
+ spans.add(new org.nongnu.alph.FakeTextSpan(t));
} else if(qName.equals("ps")) {
String b = attributes.getValue("b");
int s = Integer.parseInt(attributes.getValue("s"));
Index: alph/org/nongnu/alph/xml/SpanSerializer.java
diff -u alph/org/nongnu/alph/xml/SpanSerializer.java:1.12
alph/org/nongnu/alph/xml/SpanSerializer.java:1.13
--- alph/org/nongnu/alph/xml/SpanSerializer.java:1.12 Fri Sep 12 07:04:33 2003
+++ alph/org/nongnu/alph/xml/SpanSerializer.java Sat Oct 4 07:58:52 2003
@@ -38,14 +38,14 @@
public String namespace;
public String span2xml(Span s0) {
- if(s0 instanceof org.nongnu.alph.impl.FakeTextSpan) {
- org.nongnu.alph.impl.FakeTextSpan t =
- (org.nongnu.alph.impl.FakeTextSpan)s0;
+ if(s0 instanceof org.nongnu.alph.FakeTextSpan) {
+ org.nongnu.alph.FakeTextSpan t =
+ (org.nongnu.alph.FakeTextSpan)s0;
return "<fts t=\""+
XMLUtil.escapeXML(t.getText())+"\"/>";
- } else if(s0 instanceof org.nongnu.alph.impl.URN5TextSpan) {
- org.nongnu.alph.impl.URN5TextSpan t =
- (org.nongnu.alph.impl.URN5TextSpan)s0;
+ } else if(s0 instanceof org.nongnu.alph.RICCTextSpan) {
+ org.nongnu.alph.RICCTextSpan t =
+ (org.nongnu.alph.RICCTextSpan)s0;
return "<uts b=\""+t.getScrollId()+
"\" o=\""+t.offset()+
"\" t=\""+XMLUtil.escapeXML(t.getText())+"\"/>";
Index: alph/org/nongnu/alph/xml/serialization.test
diff -u alph/org/nongnu/alph/xml/serialization.test:1.15
alph/org/nongnu/alph/xml/serialization.test:1.16
--- alph/org/nongnu/alph/xml/serialization.test:1.15 Fri Sep 12 07:04:34 2003
+++ alph/org/nongnu/alph/xml/serialization.test Sat Oct 4 07:58:52 2003
@@ -180,7 +180,7 @@
def testReturn():
- str = SpanSerializer().span2xml(alph.impl.FakeTextSpan('a\nb'))
+ str = SpanSerializer().span2xml(alph.FakeTextSpan('a\nb'))
r = SpanReader(TestAlph())
parseString(str, r)
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [ff-cvs] alph doc/pegboard/refstring_dtd--tjl/peg.rst or...,
Tuomas J. Lukka <=