freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject [2/2] incubator-freemarker git commit: README to markdown from 2.3-gae branch
Date Mon, 17 Apr 2017 11:28:14 GMT
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 <ddekany@apache.org>
Authored: Mon Apr 17 13:27:55 2017 +0200
Committer: ddekany <ddekany@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}
+===========================
+
+[![Build Status](https://travis-ci.org/apache/incubator-freemarker.svg?branch=3)](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. 


Mime
View raw message