From 4a700f98a672a5367220e9c7aefb8353621b755e Mon Sep 17 00:00:00 2001
From: Willem Cazander <w.cazander@gmail.com>
Date: Fri, 21 Dec 2012 03:01:48 +0100
Subject: [PATCH] Added sorting to elddoc lists and updated site pages for
 better english.

---
 src/site/apt/download.apt                     |  5 +-
 src/site/apt/examples/load-modules.apt        | 22 +++++-
 src/site/apt/examples/sample-swixml.apt       | 74 ++++++++++++++++++-
 src/site/apt/examples/start-language.apt      | 28 ++++++-
 src/site/apt/examples/validation.apt          | 55 +++++++-------
 src/site/apt/features.apt                     |  6 +-
 src/site/apt/index.apt                        | 29 ++++----
 src/site/apt/usage.apt                        | 42 ++++++-----
 .../org/x4o/xml/eld/doc/EldDocHtmlWriter.java | 37 ++++++++--
 .../resources/META-INF/meta/meta-lang.eld     |  5 ++
 10 files changed, 225 insertions(+), 78 deletions(-)

diff --git a/src/site/apt/download.apt b/src/site/apt/download.apt
index 80bac86..a8f90c4 100644
--- a/src/site/apt/download.apt
+++ b/src/site/apt/download.apt
@@ -29,7 +29,7 @@ Downloading
    <dependency>
    		<groupId>org.x4o</groupId>
    		<artifactId>x4o-core</artifactId>
-   		<version>0.8-SNAPSHOT</version>
+   		<version>0.8.5-SNAPSHOT</version>
    </dependency>
 +--
 
@@ -38,8 +38,9 @@ Downloading
 * Download binary release.
   
   Sorry we still have not done any binany releases.
+  When completed it should be on the {{{http://download.savannah.gnu.org/releases/x4o/}release}} page.
   
 * Downloading source code
   
-  Sorry we still have no source access.  
+  see {{{./source-repository.html}repository}} page.
   
\ No newline at end of file
diff --git a/src/site/apt/examples/load-modules.apt b/src/site/apt/examples/load-modules.apt
index 058b3c5..f54c739 100644
--- a/src/site/apt/examples/load-modules.apt
+++ b/src/site/apt/examples/load-modules.apt
@@ -23,11 +23,12 @@
 
 Load Modules
 
-  The default language loader of x4o load all 'META-INF/<language>/<language>-modules.xml' in the classpath.
-  So every extension library has its own modules definition file. 
+  The default language loader of x4o loads all 'META-INF/<language>/<language>-modules.xml' resources found in the classpath.
   
+  So every extension library has its own modules definition file. 
   All options are allowed in multiple forms and order.
-  For xsd file see x4o-core classpath 'META-INF/language/modules-1.0.xsd'.
+  
+  The xsd file can be found in the x4o-core project classpath 'META-INF/language/modules-1.0.xsd'.
   
 +--
 <?xml version="1.0" encoding="UTF-8"?>
@@ -49,4 +50,17 @@ Load Modules
 		<eld-resource>foobar-lang-2.0.eld</eld-resource>
 	</language>
 </modules>
-+--
\ No newline at end of file
++--
+  
+ * eld-resource
+  
+  The eld-resource tag loads the eld resource relative from the modules xml resource.
+  
+ * module-loader
+  
+  The module-loader lets you define module extensions and namespaces in code.
+  
+ * sibling-loader
+  
+  The sibling-loader lets you load other languages into the language used.
+
diff --git a/src/site/apt/examples/sample-swixml.apt b/src/site/apt/examples/sample-swixml.apt
index e7904f6..8648121 100644
--- a/src/site/apt/examples/sample-swixml.apt
+++ b/src/site/apt/examples/sample-swixml.apt
@@ -275,7 +275,79 @@ public class BorderConverter extends AbstractStringObjectConverter {
 }
 +--
 
+* XML to parse
+
++--
+<frame name="mainframe" size="800,600" title="SWIXML-X4O" plaf="com.sun.java.swing.plaf.windows.WindowsLookAndFeel" defaultCloseOperation="3">
+	<menubar name="menubar">
+		<menu name="filemenu" text="File">
+			<menuitem name="mi_new" text="New" icon="icons/new.gif" mnemonic="VK_N" accelerator="control N" Action="newAction"/>
+			<menuitem name="mi_open" text="Open" icon="icons/open.gif" mnemonic="VK_O" Accelerator="control O" ActionCommand="open"/>
+			<menuitem name="mi_save" text="Save" icon="icons/save.gif" mnemonic="VK_S" ActionCommand="save"/>
+			<menu name="propmenu" text="Properties" icon="icons/new.gif" >
+				<menuitem name="mi_prop_edit" text="Edit" icon="icons/new.gif"/>
+				<menuitem name="mi_prop_clear" text="Clear" icon="icons/new.gif"/>	
+			</menu>
+			<separator/>
+			<menuitem name="mi_exit" text="Exit" icon="icons/exit.gif" mnemonic="VK_X" Accelerator="control X" ActionCommand="exit" Action="exitAction"/>
+		</menu>
+		<menu text="Help">
+			<menuitem name="mi_about" text="About" enabled="true" icon="icons/info.gif" Accelerator="alt A" Action="aboutAction" />
+		</menu>
+	</menubar>
+	<desktoppane>
+		<internalframe Title="Flow Layout (right aligned)" Bounds="10,10,150,150" Layout="FlowLayout(FlowLayout.RIGHT)" Visible="true" Resizable="true">
+			<button>1</button>
+			<button>2</button>
+			<button>3</button>
+			<button>4</button>
+		</internalframe>
+		<internalframe Title="Grid Layout" Bounds="200,10,170,170" Layout="GridLayout(4,3)" Visible="true" Resizable="true">
+			<button text="1"/><button text="2"/><button text="3"/>
+			<button text="4"/><button text="5"/><button text="6"/>
+			<button text="7"/><button text="8"/><button text="9"/>
+			<button text="*"/><button text="0"/><button text="#"/>
+		</internalframe>
+		<internalframe Title="Border Layout" Bounds="390,10,150,150" Layout="borderlayout" Visible="true" Resizable="true">
+			<button constraints="BorderLayout.NORTH" text="1"/>
+			<button constraints="BorderLayout.EAST"  text="2"/>
+			<button constraints="BorderLayout.SOUTH" text="3"/>
+			<button constraints="BorderLayout.WEST"  text="4"/>
+		</internalframe>
+		<internalframe Title="Tree Window" Bounds="10,170,350,360" Layout="borderlayout" Visible="true" Resizable="true">
+			<panel layout="borderlayout" constraints="BorderLayout.CENTER">
+				<splitpane oneTouchExpandable="true" dividerLocation="200">
+					<splitpane oneTouchExpandable="true" dividerLocation="140" orientation="VERTICAL">
+						<scrollPane background="blue" >
+							<tree name="tree"/>
+						</scrollPane>
+						<panel layout="borderlayout">
+							<panel constraints="BorderLayout.NORTH">
+								<button name="btn_copy" ToolTipText="JPanel" enabled="true" BorderPainted="false" FocusPainted="false" icon="icons/copy.gif" size="24,24"/>
+								<button name="btn_paste" ToolTipText="JButton" enabled="true" BorderPainted="false" FocusPainted="false" icon="icons/paste.gif" size="24,24"/>
+								<button name="btn_cut" ToolTipText="JLabel" enabled="true" icon="icons/cut.gif" BorderPainted="false" FocusPainted="false" size="24,24"/>
+							</panel>
+							<scrollPane constraints="BorderLayout.CENTER">
+								<table name="table"/>
+							</scrollPane>
+						</panel>
+					</splitpane>
+					<panel name="preview" border="LoweredBevelBorder">
+						<textarea name="ta" text="Tree Status Log....." background="red"/>
+					</panel>
+				</splitpane>
+			</panel>
+			<panel constraints="BorderLayout.SOUTH">
+				<label text="Status:"/>
+				<textfield text="OK"/>
+			</panel>
+		</internalframe>
+	</desktoppane>
+</frame>
++--
+
+
 * Source
 
-  This example is found in the x4o-core source package in the test path.
+  This example is found in the x4o-core source package in the test java and resouces path.
   
\ No newline at end of file
diff --git a/src/site/apt/examples/start-language.apt b/src/site/apt/examples/start-language.apt
index f42d219..e408ad6 100644
--- a/src/site/apt/examples/start-language.apt
+++ b/src/site/apt/examples/start-language.apt
@@ -55,6 +55,12 @@ public class FooBarParserSupport implements X4OParserSupport {
 		FooBarParser parser = new FooBarParser();
 		return parser.loadElementLanguageSupport();
 	}
+	
+	public TestBeanRoot getRoot() {
+		// Simple way to return single root object.
+		// note; element tree is cleared after parsing only root element is there. 
+		return (TestBeanRoot)getDriver().getElementLanguage().getRootElement().getElementObject();
+	}
 }
 +--
 
@@ -127,4 +133,24 @@ public class FooBarParserSupport implements X4OParserSupport {
 +--
 
   Now you can startup the parser to see it work.
-  
\ No newline at end of file
+  
+* Create xml to parse
+  
++--
+<?xml version="1.0" encoding="UTF-8"?>
+<r:root
+	xmlns:l="http://foobar.test.x4o.org/xml/ns/foobar-lang"
+	xmlns:r="http://foobar.test.x4o.org/xml/ns/foobar-root""
+	>
+	<l:testBean value="testing xml"/>
+</r:root>
++--
+  
+* Parse the xml
+  
++--
+FooBarParser p = new FooBarParser();
+p.parseFile("foobar/example.xml");
+TestBeanRoot root = p.getRoot();
++--
+
diff --git a/src/site/apt/examples/validation.apt b/src/site/apt/examples/validation.apt
index ee312fc..dcdf0d9 100644
--- a/src/site/apt/examples/validation.apt
+++ b/src/site/apt/examples/validation.apt
@@ -23,56 +23,57 @@
 
 Validation
 
-  Schema validation is just new feature and work in progress to have it support all different xml language formats.
-  With x4o there are currently two options howto validate your documents, it depends if the language is extended.
-
-* Validating parser
-
-+--
-	TestParser parser = new TestParser();
-	parser.setProperty(X4OLanguagePropertyKeys.VALIDATION_INPUT, true);
-	parser.parse(...);
-+--
+  Schema validation is just an new feature and work in progress.
+  There are still option being added so it can support all different xml languages.
+  
+  With x4o there are currently two options to validate your documents, it depends if the language is extended at runtime or not.
+  The actual grammer validation is done by the java jaxp parser.
 
 * Generate static languages
 
-  Store the generated xsd files in the (resource)classpath of project in META-INF/<language>/<ns-schemaResource>. 
+  When the xml language is not dynamicly extended at runtime all the schemas can be generated in the build process
+  and be included in the jar file.
+  
+  These generated xsd files are stored in the (resource)classpath of project in META-INF/foobar/foobar-1.0.xsd.
+  Then the validating parser will find the schema resources while loading the namespace contexts.
+   
   These schemas can be created or updates while package project or update manually by build script of profile.
+  For example see the profile in the pom.xml of the x4o-plugin-ant-schema module.
   
-  For example see the profile in the pom.xml of the x4o-plugin-ant-schema.
-  
-  * Validating parser
+  Use validating parser
   
 +--
-	TestParser parser = new TestParser();
-	parser.setProperty(X4OLanguagePropertyKeys.VALIDATION_INPUT, true);
-	parser.parse(...);
+TestParser parser = new TestParser();
+parser.setProperty(X4OLanguagePropertyKeys.VALIDATION_INPUT, true);
+parser.parse(...);
 +--
 
 * Generate dynamic languages
-
+  
   Generate the xsd files while all the language extensions are loaded in the classpath.
   
   Use the embedded java program in the x4o-core;
   
 +--
-  java -cp '...jar:x4o-core.jar' org.x4o.xml.eld.xsd.X4OLanguageEldXsdWriter -path /tmp -class org.foo.bar.TestParserSupport
+java -cp '...jar:x4o-core.jar' org.x4o.xml.eld.xsd.X4OLanguageEldXsdWriter -path /tmp -class org.foo.bar.TestParserSupport
 +--
   
   Or use the ant task in the x4o-plugin-ant-schema;
   
 +--
-	<taskdef name="eldXsdWriter" classname="org.x4o.plugin.ant.eld.xsd.EldXsdWriterTask"/>
-	<eldXsdWriter destdir="/tmp" supportclass="org.foo.bar.TestParserSupport"/>
+<taskdef name="eldXsdWriter" classname="org.x4o.plugin.ant.eld.xsd.EldXsdWriterTask"/>
+<eldXsdWriter destdir="/tmp" supportclass="org.foo.bar.TestParserSupport"/>
 +--
   
-  * Validating parser
+  Use validating parser
   
 +--
-	TestParser parser = new TestParser();
-	parser.setProperty(X4OLanguagePropertyKeys.VALIDATION_INPUT, true);
-	parser.setProperty(X4OLanguagePropertyKeys.VALIDATION_SCHEMA_PATH, "/tmp");
-	parser.parse(...);
+TestParser parser = new TestParser();
+parser.setProperty(X4OLanguagePropertyKeys.VALIDATION_INPUT, true);
+parser.setProperty(X4OLanguagePropertyKeys.VALIDATION_SCHEMA_PATH, "/tmp");
+parser.parse(...);
 +--
-
+  
+  Note; In future there will be an automatic schema generation option for dynamicly defined langauges so that parser can
+  be set always on full validating.
 
diff --git a/src/site/apt/features.apt b/src/site/apt/features.apt
index c043c1d..adf0d01 100644
--- a/src/site/apt/features.apt
+++ b/src/site/apt/features.apt
@@ -25,9 +25,9 @@ X4O Features
 
   * Advanced XML to Object tree parsing.
   
-  * Easy create an extensible xml language.
+  * Easy to create an extensible xml language.
   
-  * Dynamic module system for language loading.  
+  * Dynamic module system for language loading.
 
   * Fully namespace uri aware.
   
@@ -55,5 +55,5 @@ X4O Features
   
   * Basic XSD Schema generation from ELD.
   
-  
+  * Generate javadoc like documenation of the langauge.
   
\ No newline at end of file
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index 05602ca..f6657cb 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -28,7 +28,7 @@ Overview
   This is done by defining your own element language definitions in one or more xml files, which in 
   turn are also done by x4o recursively and so it can be extended.
   
-  The extension modules are dynamically loaded from the classpath to define new namespaces.
+  The extension modules are dynamically loaded from the classpath to define the namespaces.
   Besides the elements in the namespace, modules also define the object parent child relation
   binding interfaces which results in an object tree. 
   
@@ -49,20 +49,11 @@ Overview
 
 * Examples
 
-  There are two examples written out;
-
-  {{{./examples/sample-swixml.html}Sample SwiXml}}
+  There are two examples; {{{./examples/sample-swixml.html}SwiXml}} and {{{./examples/sample-jr4o.html}JR4O}}
+  
+  But at its core the main function of x4o is to translates the xml elements into beans and binds them to an tree. 
+  See this example of the FooBean class;
   
-  {{{./examples/sample-jr4o.html}Sample JR4O}}
-
-  But to put it simple, x4o translates the xml elements into beans;
-
-+--
-<my:fooBean test="hello wold"/>
-+--
-
-  Creates an instance and sets the name property of this bean;
-
 +--
 class FooBean {
 	private String name=null;
@@ -74,4 +65,12 @@ class FooBean {
 	}
 }
 +--
-
+  
+  When using this in xml is looks like;
+  
++--
+<my:fooBean test="hello wold"/>
++--
+  
+  So x4o has created an instance and sets the xml attributes as properties of this bean.
+  
diff --git a/src/site/apt/usage.apt b/src/site/apt/usage.apt
index 2b7a9f9..f305b7e 100644
--- a/src/site/apt/usage.apt
+++ b/src/site/apt/usage.apt
@@ -22,7 +22,9 @@
 ~~
 
 Usage
-   
+  
+  X4O had multiple modules the one which is most used is x4o-core which implements the full x4o framework.
+  
 * X4O maven modules
   
   * x4o = project base.
@@ -54,7 +56,7 @@ Usage
 
   Note: currently x4o is not in main maven repro, so build and install local yourself.
 
-* Setup ant task
+* Setup build task
 
   Append one or both of the x4o eld ant tasks;
 
@@ -71,26 +73,26 @@ Usage
   </dependency>
 +--
 
-  Use in ant and set the supportclass on the language you want todo the task for.
+  Use in ant and set the supportclass from the language you want to run the task for.
   
 +--
-	<taskdef name="eldDocWriter" classname="org.x4o.plugin.ant.eld.doc.EldDocWriterTask"/>
-	<taskdef name="eldXsdWriter" classname="org.x4o.plugin.ant.eld.xsd.EldXsdWriterTask"/>
+<taskdef name="eldDocWriter" classname="org.x4o.plugin.ant.eld.doc.EldDocWriterTask"/>
+<taskdef name="eldXsdWriter" classname="org.x4o.plugin.ant.eld.xsd.EldXsdWriterTask"/>
 
-	<target name="test-cel-schema-full" depends="init">
-		<mkdir dir="${test.dir}/cel-full"/>
-		<eldXsdWriter
-			destdir="${test.dir}/cel-full"
-			supportclass="org.x4o.xml.eld.EldParserSupportCore"
-			/>
-	</target>
-	<target name="test-elddoc-cel" depends="init">
-		<mkdir dir="${test.dir}/cel"/>
-		<eldDocWriter
-			destdir="${test.dir}/cel"
-			supportclass="org.x4o.xml.eld.EldParserSupportCore"
-			/>
-	</target>
-	
+<target name="build-cel-schema" depends="init">
+	<mkdir dir="${test.dir}/cel-schema"/>
+	<eldXsdWriter
+		destdir="${test.dir}/cel-schema"
+		supportclass="org.x4o.xml.eld.EldParserSupportCore"
+		/>
+</target>
+<target name="build-cel-elddoc" depends="init">
+	<mkdir dir="${test.dir}/cel-elddoc"/>
+	<eldDocWriter
+		destdir="${test.dir}/cel-elddoc"
+		supportclass="org.x4o.xml.eld.EldParserSupportCore"
+		/>
+</target>
 +--
 
+
diff --git a/x4o-elddoc/src/main/java/org/x4o/xml/eld/doc/EldDocHtmlWriter.java b/x4o-elddoc/src/main/java/org/x4o/xml/eld/doc/EldDocHtmlWriter.java
index d8df1e9..381c843 100644
--- a/x4o-elddoc/src/main/java/org/x4o/xml/eld/doc/EldDocHtmlWriter.java
+++ b/x4o-elddoc/src/main/java/org/x4o/xml/eld/doc/EldDocHtmlWriter.java
@@ -31,6 +31,8 @@ import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Collections;
+import java.util.Comparator;
 import java.util.Date;
 import java.util.List;
 
@@ -186,7 +188,9 @@ public class EldDocHtmlWriter {
 			printHeader(pw,"Overview Modules ("+title+")","");
 			printPageIndexTitle(pw,title,null,null);
 			printTableStart(pw,"Modules");
-			for (ElementLanguageModule mod:context.getElementLanguageModules()) {
+			List<ElementLanguageModule> mods = context.getElementLanguageModules();
+			Collections.sort(mods,new ElementLanguageModuleComparator());
+			for (ElementLanguageModule mod:mods) {
 				printTableRowOverview(pw,toSafeUri(mod.getId())+"/index.html",mod.getId(),mod.getName());
 			}
 			printTableEnd(pw);
@@ -205,7 +209,9 @@ public class EldDocHtmlWriter {
 			String title = context.getLanguageConfiguration().getLanguage()+" "+context.getLanguageConfiguration().getLanguageVersion()+" ELD";
 			printHeader(pw,"Overview Namespace("+title+")",pathPrefix);
 			printPageIndexTitle(pw,title,null,null);
-			for (ElementLanguageModule mod:context.getElementLanguageModules()) {
+			List<ElementLanguageModule> mods = context.getElementLanguageModules();
+			Collections.sort(mods,new ElementLanguageModuleComparator());
+			for (ElementLanguageModule mod:mods) {
 				printNamespaces(pw,mod.getElementNamespaceContexts(),pathPrefix,mod);
 			}
 			printBottom(pw,pathPrefix);
@@ -240,6 +246,7 @@ public class EldDocHtmlWriter {
 					}
 				}
 			}
+			Collections.sort(rootNodes,new TreeNodeComparator());
 			for (TreeNode rootNode:rootNodes) {
 				walkTree(rootNode,pw,pathPrefix);
 			}
@@ -326,7 +333,7 @@ public class EldDocHtmlWriter {
 				}
 			}
 		}
-		
+		Collections.sort(result,new TreeNodeComparator());
 		return result;
 	}
 	
@@ -384,7 +391,7 @@ public class EldDocHtmlWriter {
 				}
 			}
 		}
-		
+		Collections.sort(result,new TreeNodeComparator());
 		return result;
 	}
 	
@@ -421,7 +428,9 @@ public class EldDocHtmlWriter {
 			printPageTitle(pw,"Namespace",ns.getUri(),ns.getDescription());
 			
 			printTableStart(pw,"Element Summary");
-			for (ElementClass ec:ns.getElementClasses()) {
+			List<ElementClass> ecs = ns.getElementClasses();
+			Collections.sort(ecs,new ElementClassComparator());
+			for (ElementClass ec:ecs) {
 				printTableRowOverview(pw,toSafeUri(ec.getTag())+"/index.html",ec.getTag(),ec.getDescription());
 			}
 			printTableEnd(pw);
@@ -980,4 +989,22 @@ public class EldDocHtmlWriter {
 		pw.print("\t\t<td class=\"NavBarCell1\"><a href=\""+pathPrefix+"namespace-overview.html\">Namespaces</a>&nbsp;</td>\n");
 		pw.print("\t\t<td class=\"NavBarCell1\"><a href=\""+pathPrefix+"tree-overview.html\">Tree</a>&nbsp;</td>\n");
 	}
+	
+	class ElementLanguageModuleComparator implements Comparator<ElementLanguageModule> {
+		public int compare(ElementLanguageModule o1,ElementLanguageModule o2) {
+			return o1.getId().compareTo(o2.getId());
+		}
+	}
+	
+	class TreeNodeComparator implements Comparator<TreeNode> {
+		public int compare(TreeNode o1,TreeNode o2) {
+			return o1.elementClass.getTag().compareTo(o2.elementClass.getTag());
+		}
+	}
+	
+	class ElementClassComparator implements Comparator<ElementClass> {
+		public int compare(ElementClass o1,ElementClass o2) {
+			return o1.getTag().compareTo(o2.getTag());
+		}
+	}
 }
diff --git a/x4o-meta/src/main/resources/META-INF/meta/meta-lang.eld b/x4o-meta/src/main/resources/META-INF/meta/meta-lang.eld
index a7eddb2..bfadad6 100644
--- a/x4o-meta/src/main/resources/META-INF/meta/meta-lang.eld
+++ b/x4o-meta/src/main/resources/META-INF/meta/meta-lang.eld
@@ -32,6 +32,8 @@
 	providerName="x4o.org"
 	id="meta-lang"
 	>
+	<eld:description>The x4o meta language lets you do special xml tricks.</eld:description>
+	
 	<eld:attributeHandler id="global-el-id"	attributeName="el.id" bean.class="org.x4o.xml.meta.lang.ELIDAttributeHandler">
 		<eld:description>Lets you bind object into the expression language context.</eld:description>
 	</eld:attributeHandler>
@@ -39,8 +41,11 @@
 		uri="http://meta.x4o.org/xml/ns/meta-lang"
 		schemaUri="http://meta.x4o.org/xml/ns/meta-lang-1.0.xsd"
 		schemaResource="meta-lang-1.0.xsd"
+		schemaPrefix="meta-lang"
 		name="X4O Meta Language"
+		id="meta-lang"
 		>
+		<eld:description>Some special xml tags in this namespace.</eld:description>
 			
 		<eld:element tag="bean"				elementClass="org.x4o.xml.eld.lang.BeanElement">
 			<eld:description>