You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by jv...@locus.apache.org on 2000/09/30 22:11:48 UTC
cvs commit: jakarta-velocity/xdocs code-standards.xml design.xml getting-started.xml install.xml script-elements.xml
jvanzyl 00/09/30 13:11:48
Modified: xdocs code-standards.xml design.xml getting-started.xml
install.xml script-elements.xml
Log:
Edits.
PR from:
Revision Changes Path
1.3 +24 -30 jakarta-velocity/xdocs/code-standards.xml
Index: code-standards.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/code-standards.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- code-standards.xml 2000/09/30 17:35:25 1.2
+++ code-standards.xml 2000/09/30 20:11:47 1.3
@@ -15,26 +15,21 @@
<s1 title="Coding Standards">
<p>
- This document describes coding conventions that are required
- for code submissions to the Velocity project.
-
-</p>
-
-<p>
- <strong>If you commit code that does not follow the existing conventions and you
- are caught, you will be responsible for fixing your own code.</strong>
+ Code submissions to the Velocity project must follow the conventions
+ listed in this document. Velocity developers
+ are asked to follow coding conventions already present in the code.
+ For example, if the existing code has the bracket on
+ the same line as the if statement, then all subsequent code
+ should also follow that convention. Anything not
+ explicitly mentioned in this document should follow the official
+ <link href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Sun
+ Java Coding Conventions</link>.
</p>
<p>
- Below is a list of coding conventions that are specific to Velocity.
- Anything not explicitly mentioned here should follow the official
- <link href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Sun
- Java Coding Conventions</link>.
- As in most Open Source Projects, developers are asked to follow
- coding conventions already in use in the code that you are working
- on. For example, if the existing code has the bracket on
- the same line as the if statement, then your code
- should also follow that convention.
+ <strong>If you are caught commiting code that does not follow
+ the existing conventions, you will be responsible for fixing
+ it.</strong>
</p>
<p>
@@ -70,8 +65,8 @@
</p>
<p>
-2. Spaces between parentheses are optional. The preference
-is to exclude extra spaces. For example, both of these conventions are acceptable:
+2. Spaces between parentheses are optional. The preference is to exclude
+extra spaces. For example, both of these conventions are acceptable:
</p>
<p>
@@ -86,9 +81,9 @@
</p>
<p>
-3. 4 spaces. <strong>NO</strong> tabs. Period. Velocity is being developed in a distributed development
-enviroment. The Velocity mailing list receives cvs commit messages
-that are almost impossible to read if tabs are used.
+3. Four spaces. <strong>NO</strong> tabs. Period. The Velocity
+mailing list receives cvs commit messages that are almost impossible
+to read if tabs are used.
</p>
<p>
@@ -98,20 +93,19 @@
</p>
<p>
-4. Unix linefeeds for all .java source code files. Only platform-specific
-files (e.g. .bat files for Windows) should have the platform-specific linefeeds.
+4. Use Unix linefeeds for all .java source code files. Only platform-specific
+files (e.g. .bat files for Windows) should contain non-Unix linefeeds.
</p>
<p>
-5. Javadoc <strong>MUST</strong> exist on all your methods. If you are working
-on existing code and there currently isn't a javadoc for that method/class/variable
-(or whatever), please contribute and add it. This will help to improve the
-Velocity project.
+5. Javadoc <strong>MUST</strong> exist on all your methods. Contributing
+a missing javadoc for any method, class, variable, etc., will be greatly
+appreciated as this will help to improve the Velocity project.
</p>
<p>
-6. The Jakarta Apache/Velocity License <strong>MUST</strong> be placed at the top
-of each and every file.
+6. The Jakarta Apache/Velocity License <strong>MUST</strong> be placed
+at the top of every file.
</p>
</s1>
1.3 +28 -15 jakarta-velocity/xdocs/design.xml
Index: design.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/design.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- design.xml 2000/09/30 17:36:10 1.2
+++ design.xml 2000/09/30 20:11:47 1.3
@@ -25,20 +25,31 @@
</p>
<p>
- Velocity allows web page designers to embed simple and useful script
- elements in HTML code. These script elements work in conjunction with
- a Context object that is populated in your Java code. A context object--
- essentially a Hashtable that provides get and set methods for retrieving and setting
- objects by name within the Context--provides a "hook" from your
- Java code to your Velocity code. These script elements allow a web
- designer to retrieve objects from the Context and
- put them into a web page as text values. The web designer has some control over
- looping (for each) and conditional statements (if/else).
+ Velocity has a myriad of potential uses--generating SQL from XML schemas,
+ creating postscript output from XML files, generating Java source
+ code for Java files--but it is expected to be most widely used
+ by web developers looking for a better alternative to
+ <link href="http://www.php.org/">PHP</link> and
+ <link href="http://java.sun.org/products/jsp/">Java
+ Server Pages</link> (JSPs).
+ </p>
+
+ <p>
+ Velocity allows web page designers to embed simple
+ and useful script elements in their web pages. These script elements work
+ in conjunction with a Context object, which is defined in Java code.
+ A context object--essentially a Hashtable that provides get and set
+ methods for retrieving and setting objects by name within the Context
+ --provides a "hook" from the Java code to the Velocity script
+ elements. These script elements allow a web designer to retrieve
+ objects from the Context and insert these into a web page as text
+ values. The web designer has some control over looping (for each)
+ and conditional statements (if/else).
</p>
<p>
Velocity enforces a Model-View-Controller (MVC) style of development
- by separating Java code from HTML template code. Unlike Java Servlet Pages (JSPs),
+ by separating Java code from HTML template code. Unlike JSPs,
Velocity does not allow Java code to be embedded in pages. Unlike PHP,
Velocity does not implement features with other functions. The MVC
approach is one of Velocity's great strengths, and allows for more
@@ -51,14 +62,16 @@
to MVC, this approach saves time over the long term (believe us, we have
been doing this for a long time now). The MVC abstraction prevents web page
designers from messing with a software engineer's Java code, and
- programmers from unduly influencing the look of web sites. This enforces
- a contract that defines what roles people play in the web site development process.
+ programmers from unduly influencing the look of web sites. Velocity enforces
+ a contract that defines what roles people play in the web site development
+ process.
</p>
<p>
- The concept for Velocity was borrowed from WebMacro, and those involved in
- the Velocity project acknowledge and appreciates the development and design
- work that went into the WebMacro project.
+ The concept for Velocity was borrowed from
+ <link href="http://www.webmacro.org/">WebMacro</link>,
+ and those involved in the Velocity project acknowledge and appreciate
+ the development and design work that went into the WebMacro project.
</p>
</s1>
1.2 +11 -9 jakarta-velocity/xdocs/getting-started.xml
Index: getting-started.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/getting-started.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- getting-started.xml 2000/09/30 17:04:30 1.1
+++ getting-started.xml 2000/09/30 20:11:47 1.2
@@ -15,19 +15,21 @@
<s1 title="Getting Started">
<p>
- The purpose of this document is to define simple documentation on getting
+ This document provides developers with simple documentation for getting
started with Velocity. For information about the overall structure of
- Velocity, please refer to the <a href="design.html">Design Document
- </a>. The composition of this document will be written from the
- perspective of what you should do in order to start a newly functional system.
+ Velocity, please refer to the <a href="design.html">Design Document</a>.
</p>
<p>
- The first thing that you should do is download and install Velocity.
- This step is documented in the <a href="install.html">INSTALL</a>
- document, so it will not be covered here. If you would like to view the detailed API documentation
- run "build-velocity.sh|bat javadocs" from the "build" directory.
- This will create a full set of Velocity API docs in the "docs/apidocs" directory.
+ Instructions for downloading and installing Velocity can be found on the
+ <a href="install.html">INSTALL</a> document.
+</p>
+
+<p>
+ If you would like to view the detailed API documentation, run
+ "build-velocity.sh|bat javadocs" from the "build" directory.
+ This will create a full set of Velocity API docs in
+ the "docs/apidocs" directory.
</p>
</s1>
1.3 +19 -9 jakarta-velocity/xdocs/install.xml
Index: install.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/install.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- install.xml 2000/09/30 17:36:10 1.2
+++ install.xml 2000/09/30 20:11:47 1.3
@@ -23,27 +23,37 @@
<s1 title="Compiling">
<p>
- Execute the following script in the velocity/build directory:
+ On Unix/Linux, execute the following script in the velocity/build directory:
</p>
<p>
<source><![CDATA[
-./build-velocity
+./build-velocity.sh
]]></source>
</p>
<p>
- Executing the above script will create a "bin" directory within the Velocity
- distribution directory. The bin directory will contain the compiled class files (inside a
- "classes" directory) as well as a "velocity.jar" file. You can either use
- the .jar file directly or copy the org directory into your classpath.
+ On Windows, execute the following script in the velocity\build directory:
+
+<p>
+<source><![CDATA[
+
+build-velocity.bat
+]]></source>
+</p>
+
+<p>
+ Executing this script will create a "bin" directory within the Velocity
+ distribution directory. The bin directory will contain the compiled class
+ files (inside a "classes" directory) as well as a "velocity.jar" file.
+ Be sure to update your classpath to include Velocity's .jar file.
</p>
<p>
- If you get a compiler error about not being able to find some package, then
- ensure the scripts are edited to properly specify the paths
- to each of the packages.
+ If you get a compiler error related to one or more packages that could not
+ be found, ensure the build-velocity script is edited to properly specify
+ the paths to each of the packages that could not be found.
</p>
</s1>
1.2 +40 -40 jakarta-velocity/xdocs/script-elements.xml
Index: script-elements.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/script-elements.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- script-elements.xml 2000/09/30 17:04:30 1.1
+++ script-elements.xml 2000/09/30 20:11:47 1.2
@@ -44,9 +44,9 @@
<s1 title="Variables">
<p>
- Variables are referenced in a similar fashion to the way that they are in
- Perl (ie: they use a $), but they also take advantage of some Java
- principles that are easy for template designers to work with. For example:
+ Velocity references its variables in a fashion similar to Perl (i.e. they
+ use a $), but takes advantage of some Java principles that template
+ designers will find easy to use. For example:
</p>
<p>
@@ -58,16 +58,16 @@
</p>
<p>
- As you can see in a couple of the examples above there are alternative uses
- for the same variables. Velocity takes advantage of Java's introspection and
+ These examples illustrate alternative uses for the same variables.
+ Velocity takes advantage of Java's introspection and
bean features to resolve the variable names to both objects in the Context
as well as the objects methods. It is possible to embed the variables almost
- anywhere in your template and have them be evaluated.
+ anywhere in your template that can then be evaluated.
</p>
<p>
Everything coming to and from the variables is treated as a String object.
- If you have an object that is representing $foo such as an Integer object,
+ If you have an object that is representing $foo (such as an Integer object),
then Velocity will call its .toString() method in order to resolve the
object into a String.
</p>
@@ -90,16 +90,16 @@
</p>
<p>
- The variable $foo is evaluated to see if it is a boolean or not null and the
- content within the brackets is what is output if the evaluation is true. As
- you can see, this has the advantage over other systems because you do not
- need to wrap your HTML code within an out.println(), therefore enabling you
- to develop a more MVC solution. Of course there are other solutions to
- out.println() within JSP, but they are just as ugly as out.println().
+ The variable $foo is evaluated to see if it is a boolean or not null; the
+ content within the brackets becomes the output if the evaluation is true.
+ Unlike in JSP, Velocity does not force web developers to wrap HTML code
+ within an out.println(), or to delve into ugly workarounds to out.println().
+ This results in a more MVC solution.
</p>
<p>
- Another example is that you can include #else elements with your #if element.
+ Another example is that you can include #else elements with your #if
+ element.
</p>
<p>
@@ -115,8 +115,8 @@
</p>
<p>
- Note: In the current version of Velocity, it is not possible to do something like what
- is shown below. We will be adding this functionality quickly though.
+ Note: Logical operators, illustrated by an example below, are not yet
+ available in Velocity. This functionality is expected to be added soon.
</p>
<p>
@@ -128,10 +128,10 @@
</p>
<p>
- If you would like to emulate the functionality of #elseif, then you can do
- so by using nested #if statements. As you would expect, nesting elements
- works for all of the elements to an infinite level of nesting. For example,
- you can nest a #foreach within a #if. We will be considering in the future
+ Nested #if statements can be used to emulate the functionality of #elseif.
+ Nesting elements
+ works for all elements to an infinite level of nesting. For example,
+ you can nest a #foreach within an #if. We will be considering in the future
of adding a #elseif to simplify things.
</p>
</s1>
@@ -140,7 +140,7 @@
<s1 title="Loops">
<s1 title="Foreach Loop">
<p>
- The #foreach element allows you to create loops. For example:
+ The #foreach element allows for looping. For example:
</p>
<p>
@@ -162,10 +162,10 @@
<p>
The contents of the $allProducts variable is either a Vector, Hashtable or
- Array. Thus, the value that is assigned to the $product variable is a Java
- Object and can be referenced from the variable as so. For example, if $product
- was really a Product class in Java, you could get the name of the Product
- by referencing the $product.Name method (ie: Product.getName()).
+ Array. The value assigned to the $product variable is a Java
+ Object and can be referenced from a variable as such. For example, if
+ $product was really a Product class in Java, you could get the name of the
+ Product by referencing the $product.Name method (ie: Product.getName()).
</p>
</s1>
</s1>
@@ -187,9 +187,10 @@
<s1 title="Include">
<p>
- The #include script element allows you to import a local file that is
- inserted into the location where the #include directive is defined. The
- contents of the file are not rendered through the template engine.
+ The #include script element allows the template designer to import a
+ local file, which is then inserted into the location where the #include
+ directive is defined. The contents of the file are not rendered through
+ the template engine.
</p>
<p>
@@ -213,17 +214,16 @@
</p>
<p>
- One difference between Velocity and WebMacro is that the left hand side
- variable must be prefixed with a $. We felt that this is more appropriate
- for the script element language because you are effectively setting a
- variable and the references to variables should be consistent.
+ Unlike WebMacro, the variable on the left side of teh #param script element
+ must be prefixed with a $. This provides a consistent syntax for
+ referencing variables.
</p>
</s1>
<s1 title="Set">
<p>
- The #set script element allows the template designer to set variables within
- the Context.
+ The #set script element allows the template designer to set variables
+ within the Context.
</p>
<p>
@@ -233,15 +233,15 @@
</p>
<p>
- One difference between Velocity and WebMacro is that the left hand side
- variable must be prefixed with a $. We felt that this is more appropriate
- for the script element language because you are effectively setting a
- variable and the references to variables should be consistent.
+ Unlike WebMacro, when using the #set directive, the variable on the
+ left side must be prefixed with a $. This provides a consistent
+ syntax for referencing variables.
</p>
<p>
- Currently, the above example is the only thing that is supported. We will
- eventually be suporting the full range of WebMacro functionality here.
+ Currently, the above examples are the only directives that have been
+ implemented. We will eventually support the full range of WebMacro
+ functionality.
</p>
</s1>