You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2017/04/13 12:41:43 UTC
[1/2] incubator-freemarker git commit: converted the readme from txt
to md and added the build status from travis
Repository: incubator-freemarker
Updated Branches:
refs/heads/2.3-gae 93dea88d4 -> fef04d8cd
converted the readme from txt to md and added the build status from travis
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/f871237b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/f871237b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/f871237b
Branch: refs/heads/2.3-gae
Commit: f871237b3101c9ce531b6b675a77d39793179644
Parents: 93dea88
Author: Pradeep Murugesan <pr...@outlook.com>
Authored: Thu Apr 13 12:30:54 2017 +0200
Committer: Pradeep Murugesan <pr...@outlook.com>
Committed: Thu Apr 13 12:30:54 2017 +0200
----------------------------------------------------------------------
README | 237 ----------------------------------------------------
README.md | 256 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
build.xml | 10 +--
3 files changed, 260 insertions(+), 243 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/f871237b/README
----------------------------------------------------------------------
diff --git a/README b/README
deleted file mode 100644
index c5cfc1e..0000000
--- a/README
+++ /dev/null
@@ -1,237 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-
-===============================================================================
-
- Apache FreeMarker {version}
-
- For the latest version or to report bugs visit:
-
- http://freemarker.org/
-
-===============================================================================
-
- DISCLAIMER
-
- Apache FreeMarker is an effort undergoing incubation at The Apache
- Software Foundation (ASF). Incubation is required of all newly accepted
- projects until a further review indicates that the infrastructure,
- communications, and decision making process have stabilized in a manner
- consistent with other successful ASF projects. While incubation status is
- not necessarily a reflection of the completeness or stability of the
- code, it does indicate that the project has yet to be fully endorsed by
- the ASF.
-
-
-What is Apache FreeMarker?
---------------------------
-
-FreeMarker is a "template engine"; a generic tool to generate text
-output (anything from HTML to auto generated source code) based on
-templates. It's a Java package, a class library for Java programmers.
-It's not an application for end-users in itself, but something that
-programmers can embed into their products. FreeMarker is designed to
-be practical for the generation of HTML Web pages, particularly by
-servlet-based applications following the MVC (Model View Controller)
-pattern.
-
-
-Licensing
----------
-
-FreeMarker is licensed under the Apache License, Version 2.0.
-
-See the LICENSE file for more details!
-
-
-Documentation
--------------
-
-Online: http://freemarker.org/docs/
-
-Offline: The full documentation is available in the binary distribution
-in the documentation/index.html directory.
-
-
-Installing
-----------
-
-If you are using Maven, just add this dependency:
-
- <!--
- Attention: Be sure nothing pulls in an old dependency with groupId
- "freemarker" (without the "org."), because then you will end up with
- two freemarker.jar-s and unpredictable behavior on runtime!
- -->
- <dependency>
- <groupId>org.freemarker</groupId>
- <artifactId>freemarker</artifactId>
- <version>{version}</version>
- </dependency>
-
-Otherwise simply copy freemarker.jar to a location where your Java
-application's ClassLoader will find it. For example, if you are using
-FreeMarker in a web application, you probably want to put
-freemarker.jar into the WEB-INF/lib directory of your web application.
-
-FreeMarker has no required dependencies. It has several optional
-dependencies, but usually you don't have to deal with them, because if
-you are using an optional feature that's certainly because your
-application already uses the related library.
-
-The minimum required Java version is currently Java SE 5. (The presence
-of a later version may be detected on runtime and utilized by
-FreeMarker.)
-
-
-Change log
-----------
-
-Online (for stable releases only):
-http://freemarker.org/docs/app_versions.html
-
-Offline:
-In the binary release, open documentation/index.html, and you will find the
-link.
-
-
-Building
---------
-
-First of all, if you haven't yet, download the source release, or check
-out FreeMarker from the source code repository.
-
-You need JDK 8(!), Apache Ant and Ivy to be installed. (As of this writing
-it was tested with Ant 1.8.1 and Ivy 2.3.0.) To install Ivy (but be sure
-it's not already installed), issue `ant download-ivy`, which will copy it
-under ~/.ant/lib. Alternatively, you can copy ivy-<version>.jar into your
-Ant home directory "lib" subfolder manually.
-
-It's recommended to copy build.properties.sample into build.properties, and
-edit its content to fit your system. (Although basic jar building should
-succeeds without the build.properties file too.)
-
-To build freemarker.jar, just issue "ant" in the project root
-directory, and it should download all dependencies automatically and
-build freemarker.jar.
-
-If later you change the dependencies in ivy.xml, or otherwise want to
-re-download some of them, it will not happen automatically anymore.
-You have to issue "ant update-deps" for that.
-
-
-Eclipse and other IDE setup
----------------------------
-
-Below you find the step-by-step setup for Eclipse Mars.1. If you are using a
-different version or an entierly different IDE, still read this, and try to
-apply it to your development environment:
-
-- Install Ant and Ivy, if you haven't yet; see earlier.
-- From the command line, run `ant clean jar ide-dependencies`. (Note that
- now the folders "ide-dependencies", "build/generated-sources" and "META-INF"
- were created.)
-- Start Eclipse
-- You may prefer to start a new workspace (File -> "Switch workspace"), but
- it's optional.
-- Window -> Preferences
- - General -> Workspace, set the text file encoding
- to "UTF-8". (Or, you can set the same later on project level instead.)
- - General -> Editors, set:
- - Insert space for tabs
- - Show print margin, 120 columns
- - Java -> Code Style -> Formatter -> Import...
- Select src\ide-settings\Eclipse\Formatter-profile-FreeMarker.xml
- inside the FreeMarker project directory.
- (On IntelliJ IDEA, import
- src/ide-settings/IntelliJ-IDEA/Java-code-style-FreeMarker.xml instead)
- This profile uses space-only indentation policy and 120 character line
- width, and formatting rules that are pretty much standard in modern Java.
- - Java -> Code Style -> Organize imports
- (On IntelliJ IDEA, this was already configured by the Java code style
- import earlier.)
- The order is this (the Eclipse default): java, javax, org, com.
- Number of imports required for .*: 99
- Number of static imports needed for .*: 1
- - Java -> Installed JRE-s:
- Ensure that you have JDK 8 installed, and that it was added to Eclipse.
- Note that it's not JRE, but JDK.
- - Java -> Compiler -> Javadoc:
- "Malformed Javadoc comments": Error
- "Only consider members as visible": Private
- "Validate tag argunebts": true
- "Missing tag descriptions": Validate @return tags
- "Missing Javadoc tags": Ignore
- "Missing Javadoc comments": Ignore
-- Create new "Java Project" in Eclipse:
- - In the first window popping up:
- - Change the "location" to the directory of the FreeMarker project
- - Press "Next"
- - In the next window, you see the build path settings:
- - On "Source" tab, ensure that exactly these are marked as source
- directories (be careful, Eclipse doesn't auto-detect these well):
- build/generated-sources/java
- src/main/java
- src/main/resources
- src/test/java
- src/test/resources
- - On the "Libraries" tab:
- - Delete everyhing from there, except the "JRE System Library [...]"
- - Edit "JRE System Library [...]" to "Execution Environment" "JavaSE 1.8"
- - Add all jar-s that are directly under the "ide-dependencies" directory
- (use the "Add JARs..." and select all those files).
- - On the "Order and Export" tab find dom4j-*.jar, and send it to the
- bottom of the list (becase, an old org.jaxen is included inside
- dom4j-*.jar, which casues compilation errors if it wins over
- jaxen-*.jar).
- - Press "Finish"
-- Eclipse will indicate many errors at this point; it's expected, read on.
-- Project -> Properties -> Java Compiler
- - Set "Compiler Compliance Level" to "1.5" (you will have to uncheck
- "Use compliance from execution environment" for that)
- - In Errors/Warnings, check in "Enable project specific settings", then set
- "Forbidden reference (access rules)" from "Error" to "Warning".
-- You will still have errors on these java files (because different java
- files depend on different versions of the same library, and Eclipse can't
- handle that). Exclude those java files from the Build Path (in the Package
- Explorer, right click on the problematic file -> "Build Path" -> "Exclude"):
- _Jython20*.java
- _Jython22*.java
- _FreeMarkerPageContext2.java
- FreeMarkerJspFactory2.java
- Java8*.java
- Also, close these files if they are open. Now you shouldn't have any errors.
-- At Project -> Properties -> Java Code Style -> Formatter, check in "Enable
- project specific settings", and then select "FreeMarker" as active profile.
-- At Project -> Properties -> Java Editor -> Save Actions, check "Enable project
- specific settings", then "Perform the selected actions on save", and have
- only "Organize imports" and "Additional actions" checked (the list for the
- last should contain "Add missing @Override annotations",
- "Add missing @Override annotations to implementations of interface methods",
- "Add missing @Deprecated annotations", and "Remove unnecessary cast").
-- Right click on the project -> Run As -> JUnit Test
- It should run without problems (all green).
-- It's highly recommened to use the Eclipse FindBugs plugin.
- - Install it from Eclipse Marketplace (3.0.1 as of this writing)
- - Window -> Preferences -> Java -> FindBugs:
- Set all bug marker ranks from Warning to Error. (For false alarms we add
- @SuppressFBWarnings(value = "...", justification = "...") annotations.)
- - Project -> Properties -> FindBugs -> [x] Run Automatically
- - There should 0 errors. But sometimes the plugin fails to take the
- @SuppressFBWarnings annotations into account; then use Project -> Clean.
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/f871237b/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7b1b039
--- /dev/null
+++ b/README.md
@@ -0,0 +1,256 @@
+```
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+```
+
+
+Apache FreeMarker {version} [](https://travis-ci.org/apache/incubator-freemarker)
+===========================
+ For the latest version or to report bugs visit:
+
+ http://freemarker.org/
+
+
+
+DISCLAIMER
+==========
+ Apache FreeMarker is an effort undergoing incubation at The Apache
+ Software Foundation (ASF). Incubation is required of all newly accepted
+ projects until a further review indicates that the infrastructure,
+ communications, and decision making process have stabilized in a manner
+ consistent with other successful ASF projects. While incubation status is
+ not necessarily a reflection of the completeness or stability of the
+ code, it does indicate that the project has yet to be fully endorsed by
+ the ASF.
+
+
+What is Apache FreeMarker?
+--------------------------
+
+FreeMarker is a "template engine"; a generic tool to generate text
+output (anything from HTML to auto generated source code) based on
+templates. It's a Java package, a class library for Java programmers.
+It's not an application for end-users in itself, but something that
+programmers can embed into their products. FreeMarker is designed to
+be practical for the generation of HTML Web pages, particularly by
+servlet-based applications following the MVC (Model View Controller)
+pattern.
+
+
+Licensing
+---------
+
+FreeMarker is licensed under the Apache License, Version 2.0.
+
+See the LICENSE file for more details!
+
+
+Documentation
+-------------
+
+Online: http://freemarker.org/docs/
+
+Offline: The full documentation is available in the binary distribution
+in the documentation/index.html directory.
+
+
+Installing
+----------
+
+If you are using Maven, just add this dependency:
+
+```xml
+ <!--
+ Attention: Be sure nothing pulls in an old dependency with groupId
+ "freemarker" (without the "org."), because then you will end up with
+ two freemarker.jar-s and unpredictable behavior on runtime!
+ -->
+ <dependency>
+ <groupId>org.freemarker</groupId>
+ <artifactId>freemarker</artifactId>
+ <version>{version}</version>
+ </dependency>
+```
+Otherwise simply copy freemarker.jar to a location where your Java
+application's ClassLoader will find it. For example, if you are using
+FreeMarker in a web application, you probably want to put
+freemarker.jar into the WEB-INF/lib directory of your web application.
+
+FreeMarker has no required dependencies. It has several optional
+dependencies, but usually you don't have to deal with them, because if
+you are using an optional feature that's certainly because your
+application already uses the related library.
+
+The minimum required Java version is currently Java SE 5. (The presence
+of a later version may be detected on runtime and utilized by
+FreeMarker.)
+
+
+Change log
+----------
+
+Online (for stable releases only):
+http://freemarker.org/docs/app_versions.html
+
+Offline:
+In the binary release, open documentation/index.html, and you will find the
+link.
+
+
+Local setup
+===========
+
+First of all, if you haven't yet, download the source release, or checkout FreeMarker from the source code repository.
+
+You need
+1. JDK 8(!),
+2. Apache Ant and
+3. Ivy
+
+to be installed. (As of this writing it was tested with Ant 1.8.1 and Ivy 2.3.0.).
+
+Ivy Installation
+---------------------------
+To install Ivy (but be sure it's not already installed).
+Issue
+```
+ant download-ivy
+```
+which will copy it under ~/.ant/lib. Alternatively, you can copy ivy-<version>.jar into your Ant home directory "lib" subfolder manually.
+
+
+Building
+---------------------------
+
+To build freemarker.jar, just issue
+```
+ant
+```
+in the project root directory, and it should download all dependencies automatically and build freemarker.jar.
+
+It's recommended to copy build.properties.sample into build.properties, and edit its content to fit your system. (Although basic jar building should succeeds without the build.properties file too.)
+
+Managing dependencies
+---------------------------
+If later you change the dependencies in ivy.xml, or otherwise want to re-download some of them, it will not happen automatically anymore. Issue
+```
+ant update-deps
+```
+
+
+Eclipse and other IDE setup
+===========================
+
+Below you find the step-by-step setup for Eclipse Mars.1. If you are using a different version or an entierly different IDE, still read this, and try to apply it to your development environment:
+
+- Install Ant and Ivy, if you haven't yet; see earlier.
+- From the command line, run
+ ```
+ ant clean jar ide-dependencies
+ ```
+ (Note that now the folders "ide-dependencies", "build/generated-sources" and "META-INF"
+ were created.)
+- Start Eclipse
+- You may prefer to start a new workspace (File -> "Switch workspace"), but
+ it's optional.
+- Window -> Preferences
+ - General -> Workspace, set the text file encoding
+ to "UTF-8". (Or, you can set the same later on project level instead.)
+ - General -> Editors, set:
+ - Insert space for tabs
+ - Show print margin, 120 columns
+ - Java -> Code Style -> Formatter -> Import...
+ Select src\ide-settings\Eclipse\Formatter-profile-FreeMarker.xml
+ inside the FreeMarker project directory.
+ (On IntelliJ IDEA, import
+ src/ide-settings/IntelliJ-IDEA/Java-code-style-FreeMarker.xml instead)
+ This profile uses space-only indentation policy and 120 character line
+ width, and formatting rules that are pretty much standard in modern Java.
+ - Java -> Code Style -> Organize imports
+ (On IntelliJ IDEA, this was already configured by the Java code style
+ import earlier.)
+ The order is this (the Eclipse default): java, javax, org, com.
+ Number of imports required for .*: 99
+ Number of static imports needed for .*: 1
+ - Java -> Installed JRE-s:
+ Ensure that you have JDK 8 installed, and that it was added to Eclipse.
+ Note that it's not JRE, but JDK.
+ - Java -> Compiler -> Javadoc:
+ "Malformed Javadoc comments": Error
+ "Only consider members as visible": Private
+ "Validate tag argunebts": true
+ "Missing tag descriptions": Validate @return tags
+ "Missing Javadoc tags": Ignore
+ "Missing Javadoc comments": Ignore
+- Create new "Java Project" in Eclipse:
+ - In the first window popping up:
+ - Change the "location" to the directory of the FreeMarker project
+ - Press "Next"
+ - In the next window, you see the build path settings:
+ - On "Source" tab, ensure that exactly these are marked as source
+ directories (be careful, Eclipse doesn't auto-detect these well):
+ build/generated-sources/java
+ src/main/java
+ src/main/resources
+ src/test/java
+ src/test/resources
+ - On the "Libraries" tab:
+ - Delete everyhing from there, except the "JRE System Library [...]"
+ - Edit "JRE System Library [...]" to "Execution Environment" "JavaSE 1.8"
+ - Add all jar-s that are directly under the "ide-dependencies" directory
+ (use the "Add JARs..." and select all those files).
+ - On the "Order and Export" tab find dom4j-*.jar, and send it to the
+ bottom of the list (becase, an old org.jaxen is included inside
+ dom4j-*.jar, which casues compilation errors if it wins over
+ jaxen-*.jar).
+ - Press "Finish"
+- Eclipse will indicate many errors at this point; it's expected, read on.
+- Project -> Properties -> Java Compiler
+ - Set "Compiler Compliance Level" to "1.5" (you will have to uncheck
+ "Use compliance from execution environment" for that)
+ - In Errors/Warnings, check in "Enable project specific settings", then set
+ "Forbidden reference (access rules)" from "Error" to "Warning".
+- You will still have errors on these java files (because different java
+ files depend on different versions of the same library, and Eclipse can't
+ handle that). Exclude those java files from the Build Path (in the Package
+ Explorer, right click on the problematic file -> "Build Path" -> "Exclude"):
+ _Jython20*.java
+ _Jython22*.java
+ _FreeMarkerPageContext2.java
+ FreeMarkerJspFactory2.java
+ Java8*.java
+ Also, close these files if they are open. Now you shouldn't have any errors.
+- At Project -> Properties -> Java Code Style -> Formatter, check in "Enable
+ project specific settings", and then select "FreeMarker" as active profile.
+- At Project -> Properties -> Java Editor -> Save Actions, check "Enable project
+ specific settings", then "Perform the selected actions on save", and have
+ only "Organize imports" and "Additional actions" checked (the list for the
+ last should contain "Add missing @Override annotations",
+ "Add missing @Override annotations to implementations of interface methods",
+ "Add missing @Deprecated annotations", and "Remove unnecessary cast").
+- Right click on the project -> Run As -> JUnit Test
+ It should run without problems (all green).
+- It's highly recommened to use the Eclipse FindBugs plugin.
+ - Install it from Eclipse Marketplace (3.0.1 as of this writing)
+ - Window -> Preferences -> Java -> FindBugs:
+ Set all bug marker ranks from Warning to Error. (For false alarms we add
+ @SuppressFBWarnings(value = "...", justification = "...") annotations.)
+ - Project -> Properties -> FindBugs -> [x] Run Automatically
+ - There should 0 errors. But sometimes the plugin fails to take the
+ @SuppressFBWarnings annotations into account; then use Project -> Clean.
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/f871237b/build.xml
----------------------------------------------------------------------
diff --git a/build.xml b/build.xml
index cf8be0a..861a1b5 100644
--- a/build.xml
+++ b/build.xml
@@ -54,8 +54,6 @@
</condition>
<condition property="has.all.explicit.boot.classpaths">
<and>
- <isset property="has.explicit.boot.classpath.j2se1.5"/>
- <isset property="has.explicit.boot.classpath.j2se1.6"/>
<isset property="has.explicit.boot.classpath.j2se1.8"/>
</and>
</condition>
@@ -670,7 +668,7 @@
<!-- Copy txt-s -->
<copy todir="${dist.bin.dir}" includeEmptyDirs="no">
<fileset dir="." defaultexcludes="no">
- <include name="README" />
+ <include name="README.md" />
<!-- LICENSE is binary-distribution-specific, and is copied later. -->
<include name="NOTICE" />
<include name="DISCLAIMER" />
@@ -678,7 +676,7 @@
</fileset>
</copy>
<replace
- file="${dist.bin.dir}/README"
+ file="${dist.bin.dir}/README.md"
token="{version}"
value="${version}"
/>
@@ -719,7 +717,7 @@
<!-- Copy extensionless files: -->
<copy todir="${dist.src.dir}" includeEmptyDirs="no">
<fileset dir="." defaultexcludes="no">
- <include name="README" />
+ <include name="README.md" />
<include name="LICENSE" />
<include name="NOTICE" />
<include name="DISCLAIMER" />
@@ -727,7 +725,7 @@
</fileset>
</copy>
<replace
- file="${dist.src.dir}/README"
+ file="${dist.src.dir}/README.md"
token="{version}"
value="${version}"
/>
[2/2] incubator-freemarker git commit: Converted the README from
plain txt to markdown, and added the build status from Travis
Posted by dd...@apache.org.
Converted the README from plain txt to markdown, and added the build status from Travis
Merge commit 'refs/pull/21/head' of https://github.com/apache/incubator-freemarker into 2.3-gae
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/fef04d8c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/fef04d8c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/fef04d8c
Branch: refs/heads/2.3-gae
Commit: fef04d8cd64966face55efb1b4cb1e4748a798c1
Parents: 93dea88 f871237
Author: ddekany <dd...@apache.org>
Authored: Thu Apr 13 14:34:04 2017 +0200
Committer: ddekany <dd...@apache.org>
Committed: Thu Apr 13 14:41:32 2017 +0200
----------------------------------------------------------------------
README | 237 ----------------------------------------------------
README.md | 256 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
build.xml | 10 +--
3 files changed, 260 insertions(+), 243 deletions(-)
----------------------------------------------------------------------