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/17 11:28:14 UTC
[2/2] incubator-freemarker git commit: README to markdown from
2.3-gae branch
README to markdown from 2.3-gae branch
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/143ac873
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/143ac873
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/143ac873
Branch: refs/heads/3
Commit: 143ac8732434e2780bd26adf524ced7a5362c02d
Parents: e434fb9
Author: ddekany <dd...@apache.org>
Authored: Mon Apr 17 13:27:55 2017 +0200
Committer: ddekany <dd...@apache.org>
Committed: Mon Apr 17 13:27:55 2017 +0200
----------------------------------------------------------------------
README | 220 -------------------------------------------------------
README.md | 226 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 226 insertions(+), 220 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/143ac873/README
----------------------------------------------------------------------
diff --git a/README b/README
deleted file mode 100644
index 18ab3bf..0000000
--- a/README
+++ /dev/null
@@ -1,220 +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 (or Gradle, etc.), 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 3 has only one required dependency, slf4j-api. (Of course,
-it will be automatically downloaded by Maven, Gradle, and the like.)
-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 7. (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.) Note that the ivy-<version>.jar
-should be copied to your Ant home directory "lib" subfolder.
-
-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).
- - Press "Finish"
-- Eclipse will indicate many errors at this point; it's expected, read on.
-- Project -> Properties -> Java Compiler -> Errors/Warnings:
- Check in "Enable project specific settings", then set "Forbidden reference
- (access rules)" from "Error" to "Warning".
-- 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/143ac873/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..425b7aa
--- /dev/null
+++ b/README.md
@@ -0,0 +1,226 @@
+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 3 has only one required dependency, org.slf4j:slf4j-api. (Of
+course, it will be automatically downloaded by Maven, Gradle, and the like,
+and is already there in almost all projects anyway. If it wasn't there, note
+that adding slf4j-api is not enough, as it needs an implementation, which is
+not downloaded automatically by Maven, etc. The most popular is
+ch.qos.logback:logback-classic. FreeMarker 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 7. (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 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.).
+
+
+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, and you
+must 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 -> Errors/Warnings:
+ Check in "Enable project specific settings", then set "Forbidden reference
+ (access rules)" from "Error" to "Warning".
+- 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.