From: adam Date: Mon, 22 Mar 2004 11:09:25 +0000 (+0000) Subject: latex support in org.ibex.util.Doc X-Git-Url: http://git.megacz.com/?p=org.ibex.core.git;a=commitdiff_plain;h=acbf688069a3aaabebb525dc9d35a5f79cb178ea latex support in org.ibex.util.Doc darcs-hash:20040322110925-5007d-ea6ee29fab0bc72e585c22f803cd414726e0ec33.gz --- diff --git a/Makefile b/Makefile index b549dc6..4229a71 100644 --- a/Makefile +++ b/Makefile @@ -378,3 +378,9 @@ propose-patch: commit: propose-patch darcs push --and-apply xwt@xwt.org:/var/www/org/ibex/core/ + +reference: build/class/org/ibex/util/Doc.class doc/reference.xml + cd doc; java -cp ../build/class org.ibex.util.Doc < reference.xml > reference.tex + cd doc; pdflatex reference.tex + open doc/reference.pdf + diff --git a/doc/reference.pdf b/doc/reference.pdf new file mode 100644 index 0000000..d03fad9 Binary files /dev/null and b/doc/reference.pdf differ diff --git a/doc/reference.xml b/doc/reference.xml index 37b410d..e0365aa 100644 --- a/doc/reference.xml +++ b/doc/reference.xml @@ -1,12 +1,15 @@ - - - Nitrogen Release - - by - + +
+ + If you are reading the html version of this document and are + thinking of printing it out, you might be interested in the nicely + typeset produced + with LaTeX. + + This document is a reference. It is not a specification or a tutorial. @@ -22,7 +25,7 @@ this is the right document to read. It is assumed that you are already familiar with XML and with either JavaScript or ECMAscript. If you are not familiar with ECMAscript, some reference materials are - provided in + provided in The shoehorn sequence (how the Ibex Core gets onto the client's computer, and how it knows where to download the initial .ibex @@ -87,7 +90,7 @@ We will use the terms JavaScript and ECMAScript interchangeably in this document. The Ibex interpreter is not completely ECMA-compliant, however (see for details). + appendix="C"/> for details).
@@ -126,7 +129,7 @@ "Object Representation"), and as an XML tag (the "XML Representation"). - FIXME: diagram here + FIXME: diagram here All three representations are equally valid, and being able to figure out what an action in one representation would mean in terms of the other @@ -155,16 +158,16 @@ Each box has two major visual components, each with subcomponents: - FIXME: diagram + FIXME: diagram - - + A path, which consists of zero or more lines and curves. The path may be filled with a color, gradient, or texture, and may be stroked with a line of a given thickness and color. If the path is not specified, it defaults to the perimiter of the box. + The path has an associated strokecolor, which is a color @@ -176,6 +179,7 @@ A single line of text, which can be rendered in different fonts, colors, and sizes. + The text has an associated font, which currently can be any font supported by the FIXME: - easier description. While this whole process sounds very + exact order in which each event happens. FIXME: + easier description. While this whole process sounds very complex, it actually works pretty intuitively. The description below is given in great detail since most applications will wind up being unintentionally dependent on subtle features of this process. @@ -268,14 +272,17 @@ order they appear in the document: For each text segment t: + Treat t a JavaScript script, and execute it with s as the root scope. + For each child element x of X: + Create a new box b. - If the name of tag x is not "box" (in the + If the name of tag x is not "box" (in the default XML namespace), prepend the tag's namespace identifier uri (if any) to the name of the tag, and use the result as a key to retrieve a property from the root @@ -293,18 +300,20 @@ of x into scope s. Append b as the last child of B. + Apply any attributes on X to B, except for id. Since XML specifies that the order of attributes cannot be significant, Ibex processes attributes in alphabetical order by attribute name. For example, if - X has the attribute foo="bar", then the + X has the attribute foo="bar", then the equivalent of the statement B.foo="bar"; will be performed, with the following exceptions: + If the value portion of the attribute is the string - "true", put the boolean true. If the - value is "false", put the boolean false. + "true", put the boolean true. If the + value is "false", put the boolean false. If the value is a valid ECMAscript number, put it as a number (instead of a string). @@ -317,6 +326,7 @@ attributes' namespace identifier uri (if any) and interpret the remainder as a property to be retrieved from the root stream (defined later). + The last two steps are referred to as the initialization of the @@ -356,9 +366,9 @@ properties of the user interface to change its appearance, thereby giving feedback to the user. - + DIAGRAM: graphic here showing the circular feedback cycle. - + The Ibex core quits when the last remaining surface has been destroyed. @@ -409,22 +419,22 @@ - If the align property is "center", then the + If the align property is "center", then the alignment point is the center of the box. - If the align property is "topleft", - "bottomleft", "topright", or - "bottomright", then the alignment point is + If the align property is "topleft", + "bottomleft", "topright", or + "bottomright", then the alignment point is corresponding corner of the box. - If the align property is "top", - "bottom", "right", or "left", then + If the align property is "top", + "bottom", "right", or "left", then the alignment point is middle of the corresponding edge of the box. - FIXME: diagram + FIXME: diagram When positioning a child box, the alignment point is determined by the parent's align property. When positioning a visual @@ -459,7 +469,7 @@ placed in column zero regardless, but only occupies the available set of cells (it does not "hang off the end" of the box). - + 
         
@@ -492,6 +502,7 @@
         Each box's minimum width is computed recursively as the
         maximum of:
 
+        
             Its minwidth
              
             The width of the box's text (after applying the
@@ -501,7 +512,7 @@
             transform) if the box is packed.
              
             The width of the bounding box enclosing the box's cells.
-            
+        
         
         The minimum width of each cell is computed as the minimum
         width of the box occupying it divided by the box's
@@ -549,7 +560,7 @@
         the resulting cells are placed such that the cells' alignment
         point coincides with the parent's alignment point (both
         alignment points are determined by the parent's align
-        property).  FIXME: diagram
+        property).  FIXME: diagram
     
         Packed boxes: Each packed box's actual position
         and size is then set to the aggregation of the actual sizes of
@@ -649,17 +660,17 @@
     
     
             The box's text; writing null to this property sets it
-            to "".
+            to "".
             
     
-    
+    
             When an object is written to this property, its stream is read
             using the , and the resulting font is used to render the
             box's text.
             
             
-    
+    
             The size (in points) to render the text.
             
             
@@ -671,42 +682,42 @@
 
   

     
-    
+    
         If set to true, this box will shrink
         (horizontally/vertically/both) to the smallest size allowed by
         its children and the bounding box of its path.
         
     
-    
+    
         If the box is a root box, this is the (x/y)-coordinate of the
         surface; otherwise it is the distance between the parent's
         alignment point and this box's alignment point.
         
     
-    
+    
         The distance between this box's (left/top) edge and the root
         box's (left/top) edge. A put to this property has the same
         effect as a put to the (x/y) property,
         except that it is relative to the root box rather than to this
-        box's parent. FIXME is this fakeable?  How is
-        distance measured?
+        box's parent. FIXME is this fakeable?  How is
+        distance measured?
         
     
-    
+    
         The desired minimum width and height.
         
     
-    
+    
         The desired maximum width and height.
         
     
-    
+    
         When read, this is the (width/height) of this box.  Writing to
         this property is equivalent to writing to both the
         minimum and maximum (width/height).
         
     
-    
+    
         The number of (columns/rows) in which to lay out the children of this
         box.  If set to zero, the number of (columns/rows) is unconstrained.
         Either rows or cols must be zero.  If
@@ -716,16 +727,16 @@
         rows is set to 0, and vice versa.
         
     
-    
+    
         The number of (columns/rows) that this box spans within its parent.
         
     
-    ">
+    
         Determines the box's alignment point for positioning its text,
         texture, path, and children.
         
     
-    
+    
         If set to false, this box will be rendered as if its width and
         height were zero. If this is a root box, the associated surface
         will be hidden.
@@ -736,7 +747,7 @@
         read back false.
         
     
-    
+    
          The layout strategy for this box.
         
     
@@ -784,24 +795,24 @@
         enumerate only the box's children and not any other properties.
         
     
-    
+    
         If true, the visual representation of this box's
         children will be clipped to the boundaries of this box.
         Note: setting this property to false imposes a
         substantial performance penalty.
         
     
-    
+    
         The number of children this box has.
         
     
-    
+    
         Writing to this property sets the box's redirect
         target. This property cannot be read from, and can only be
         written to once.
         
     
-    
+    
         If this box has a parent, this property returns
         parent.surface; otherwise it returns null.
         This property is a simple building block that the widget
@@ -813,30 +824,30 @@
 
   

     
-    
+    
         The shape that the cursor should take when inside this
-        box. Valid values are: "default", "wait",
-        "crosshair", "text", "hand", and
-        "move", as well as resizing cursors"east",
-        "west", "north", "south",
-        "northwest", "northeast",
-        "southwest", and "southeast". Note that on
+        box. Valid values are: "default  " , "wait",
+        "crosshair", "text", "hand", and
+        "move", as well as resizing cursors"east",
+        "west", "north", "south",
+        "northwest", "northeast",
+        "southwest", and "southeast". Note that on
         some platforms, resize cursors for opposite directions (such
         as northwest and southeast are the
         same).
         If a box's cursor is null, its parent's cursor will
         be used. If the root box's cursor is null, the
-        "default" cursor will be used.
+        "default" cursor will be used.
         
 
-    
+    
          The (horizontal/vertical) distance between the mouse cursor and this
          box's (left/top) edge. Puts to this property are ignored. This
          value will not be updated if the mouse is outside the root
          box of the surface and no button was pressed when it left.
         
     
-    
+    
         True if the mouse is inside the rendered region of this box or
         any of its children. This value will be false if the mouse is
         inside a portion of this box which is covered up by one of
@@ -850,7 +861,7 @@
         in which the currently-executing code resides.
         
        
-    
+    
        Returns a reference to the box itself.
        If null is written to this property, and this box is
        the root box of a surface, the box will be detached and the
@@ -858,7 +869,7 @@
        detached from its parent.
        
     
-    
+    
         This property is actually a function; invoking
         parent.indexof(child) will return the numerical index
         of child in parent if child is a
@@ -867,10 +878,9 @@
         has no effect.
         
 
-    
+    
 
-        These properties are meant to be trapped on FIXME defined later?. Placing a trap on
+        These properties are meant to be trapped on FIXME defined later?. Placing a trap on
         childadded/childremoved lets a box receive
         notification when a child is added/removed. In either
         situation, the child will be passed as an argument to the trap
@@ -949,7 +959,7 @@
     
         When the user attempts to close a surface, the value
         true will be put to this property. Scripts may trap
-        this property FIXME defined later? to
+        this property FIXME defined later? to
         prevent the window from closing. Putting the value
         true to this property on a root box has the same
         effect as putting null to the thisbox
@@ -1055,8 +1065,6 @@
     
     
       
-      
-          
               foo = 12;
       ...
       // elsewhere
@@ -1110,22 +1118,32 @@
     
   

 
-    
-    
-    
-    
-    
ibex.box                      reading from this property returns a new box
ibex.clone(o)                 creates a clone of object o
ibex.bless(s)                 returns a blessed clone of stream s

+    
+        reading from this property returns a new box
+        
+    
+        creates a clone of object
+        
+    
+        returns a blessed clone of stream
+        
 
     

 
   

 
-    
-    
-    
-    
-    
-    
ibex.date                     reading from this property returns a new date
ibex.math                     this object contains the ECMA math functions
ibex.regexp(s)                return a regexp object corresponding to string s
ibex.string                   this object contains the ECMA string manipulation functions

+    
+        reading from this property returns a new date
+        
+    
+        this object contains the ECMA math functions
+        
+    
+        return a regexp object corresponding to string s
+        
+    
+        this object contains the ECMA string manipulation functions
+        
 
     

 
@@ -1225,7 +1243,7 @@
   

 
     
-        not yet implemented
+        not yet implemented
         
 
     
@@ -1290,8 +1308,8 @@
         
 
     
+        treat s's stream as a string encoded as a UTF-8 byte stream and return the string
         
-        treat s's stream as a string encoded as a UTF-8 byte stream and return the string
 
     
         ibex.stream.tempdir
@@ -1302,22 +1320,22 @@
   

 
     
-        not implemented yet: return a
+        not implemented yet: return a
         stream which rsa-decrypts stream s with key k
         
 
     
-        not implemented yet: return a
+        not implemented yet: return a
         stream which rc4-decrypts stream s with key k
         
 
     
-        not implemented yet: immediately
+        not implemented yet: immediately
         MD5-hash stream s
         
 
     
-        not implemented yet: immediately
+        not implemented yet: immediately
         SHA1-hash stream s
         
 
@@ -1341,10 +1359,10 @@
         
     

 
-    If another script were to set the property "foo"
+    If another script were to set the property "foo"
     on the box above to the value 5, the function above would be
     invoked with the argument 5. The function would then log
-    the string "foo is 5".
+    the string "foo is 5".
     
     Within a trap, the expression trapee can be used to
     get a reference to the box on which the trap was placed.
@@ -1474,8 +1492,7 @@
     , , or  except for childadded,
-    childremoved and surface.  FIXME: remove?
+    childremoved and surface.  FIXME: remove?
     
     

 
@@ -1485,8 +1502,7 @@
     exception, but will not propagate it to the code which
     triggered the trap. If the trap was a read trap, the value
     null will be returned.
-    FIXME: is this right?
-    
+    FIXME: is this right?
     

 
   

@@ -1495,12 +1511,11 @@
     event/demand driven, traps eliminate the need for separate
     member/getter/setter declarations, often cutting the amount of typing
     you have to do to a third of what it would normally be.
-    
     

 
   

 
-    Cloning is a companion technique for traps; together they can
+    Cloning is a companion technique for traps; together they can
     be used to simulate any sort of environment you might need.  When you
     call ibex.clone(o), Ibex returns a new object (called the
     clone) which compares with equality (==) to the
@@ -1560,15 +1575,17 @@
         This ensures that Ibex can automatically add filename
         extensions where needed, according to the following rules:
 
+        
             If the stream is a template to be applied, the string
-            ".ibex" is appended.
+            ".ibex" is appended.
         
-            If the stream is an image, the string ".png" is
-            appended.  If no stream is found, ".jpeg" and
-            ".gif" are tried, in that order.
+            If the stream is an image, the string ".png" is
+            appended.  If no stream is found, ".jpeg" and
+            ".gif" are tried, in that order.
         
-            If the stream is an font, the string ".ttf" is
+            If the stream is an font, the string ".ttf" is
             appended.
+        
         
         Every call to ibex.bless() returns a different object
         (which happens to be a clone of the object passed to it) with
@@ -1603,7 +1620,7 @@
     
     
 
-        Rendering Context (redrawing the screen)
+        Rendering Context -- (redrawing the screen)
         
         Event Context (executing javascript traps triggered by an event)
         
@@ -1853,13 +1870,14 @@
     

 
   
+
 
 

     
   

     
-    XML-RPC objects can be created by calling ibex.net.rpc.xml(<XML-RPC
-    URL>), and then invoking methods on that object. For example,
+    XML-RPC objects can be created by calling ibex.net.rpc.xml(XML-RPC
+    URL), and then invoking methods on that object. For example,
     
     
         Press1 += function(v) {
@@ -1873,7 +1891,7 @@
     contact the server xmlrpc.ibex.org, route to the
     /RPC2/ handler and invoke the getTodaysColor()
     method on the color object with a single string argument
-    "Friday". The return value will be used to change the color
+    "Friday". The return value will be used to change the color
     of the box the user clicked on.
     
     Note that in this example we spawned a background thread to handle the
@@ -1891,8 +1909,8 @@
     this string having any special structure or significance.
     
     If an object with an associated non-empty stream is passed as an
-    argument to an XML-RPC method, it will be sent as a 
-    element. If a  element is found in the XML-RPC reply, it
+    argument to an XML-RPC method, it will be sent as a 
+    element. If a  element is found in the XML-RPC reply, it
     will be returned as an object with a stream drawn from that byte sequence.
     
     Each object returned by ibex.net.rpc.xml() represents a
@@ -1910,8 +1928,7 @@
     authentication if the server supports it; otherwise it will use
     Basic authentication.  Please be aware that many XML-RPC server
     implementations contain a .
+    url="http://www.ibex.org/faq.html#auth" text="broken implementation of Basic authentication"/>.
     
     

 
@@ -2007,7 +2024,7 @@
         
     
         A piece of untrusted Ibex code attempted to contact a
-        restricted host.  See Appendix A for details.
+        restricted host.  See  for details.
         
     
         An attempt to resolve a hostname failed but it is not known
@@ -2056,7 +2073,6 @@
     
         A JavaScript attempted to call the null value
         
-    
     
     If an exception is thrown inside a trap, the exception will propagate
     to the script that triggered the trap.
@@ -2070,7 +2086,7 @@
   

 
 
-

+
     
     Due to the expense and hassle imposed by the commercial PKI code
     signing architecture, and the fact that it X-RequestOrigin header that the proxy needs in order
+    text="X-RequestOrigin"/> header that the proxy needs in order
     to maintain security.
     
     The only remaining possible attack is against a XML-RPC or SOAP
@@ -2171,10 +2187,10 @@
     
     

 
-  
+  
 
 
-

+
     
     Ibex's scripts are written in a modified subset of ECMA-262, revision 3
     (aka JavaScript 1.5). The interpreter strays from the spec in a few
@@ -2210,6 +2226,8 @@
     
     

 
+  
+
   

     
     
@@ -2229,7 +2247,7 @@
         Is equivalent to:
         
         } catch(e) {
-           if (e.propname != null && e.propname >= "foo.bar.baz" && e.propname < "foo.bar.baz/") {
+           if (e.propname != null && e.propname >= "foo.bar.baz" && e.propname < "foo.bar.baz/") {
                // ...
            }
         }
@@ -2239,8 +2257,8 @@
         if it does appear, it must be the last one.
     
         Since Ibex ECMAscripts are wrapped in XML, the lexical token
-        "lt" is be interpreted as <, the lexical
-        token "gt" is be interpreted as >, and the
+        "lt" is be interpreted as <, the lexical
+        token "gt" is be interpreted as >, and the
         token "and" is interpreted as &&.
         Thus these tokens cannot be used as variable names.
     
@@ -2281,13 +2299,10 @@
         technical document.
 
     
-    
     

 
-  
-
 
-

+
     
     Very early in the loading process, Ibex begins logging messages about
     what it is doing.  Where this output is logged to differs by platform;
@@ -2340,15 +2355,15 @@
     cause it to log lots of information to the log file. This
     option will also substantially decrease Ibex's performance.
     
-  

+