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 2020/07/12 10:08:40 UTC
[freemarker-docgen] branch master updated (7ce98b3 -> d8c5936)
This is an automated email from the ASF dual-hosted git repository.
ddekany pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/freemarker-docgen.git.
from 7ce98b3 (Test script adjustment)
new eded901 (Deleted unused file)
new d8c5936 Updated/improved README.md
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
README.md | 91 +++++++++++++++++++++++++++++++++----------------------
package-lock.json | 3 --
2 files changed, 54 insertions(+), 40 deletions(-)
delete mode 100644 package-lock.json
[freemarker-docgen] 02/02: Updated/improved README.md
Posted by dd...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ddekany pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/freemarker-docgen.git
commit d8c593639fdaf9fb39433f2d3626b47d3b158a48
Author: ddekany <dd...@apache.org>
AuthorDate: Sun Jul 12 12:06:45 2020 +0200
Updated/improved README.md
---
README.md | 91 +++++++++++++++++++++++++++++++++++++--------------------------
1 file changed, 54 insertions(+), 37 deletions(-)
diff --git a/README.md b/README.md
index d72a83e..0fb18b5 100644
--- a/README.md
+++ b/README.md
@@ -2,70 +2,87 @@
## About
-Docgen is used to generate HTML pages from the two DocBook 5 "book" XML-s that
-[the FreeMarker Manual](http://freemarker.org/docs/) and [the FreeMarker
-homepage](http://freemarker.org/) is written in. As such, it mostly only
-implements the subset of Docgen elements that we actually use, but otherwise
-it tries to be reusable in other projects as well.
+Apache FreeMarker Docgen is an *internal* project under the Apache FreeMarker TLP,
+used for generating [the FreeMarker Manual](https://freemarker.apache.org/docs/),
+[the FreeMarker homepage](https://freemarker.apache.org), and maybe some more.
+
+Docgen generates static web pages from the DocBook 5 "book" XML-s. But, it
+only implements the small subset of DocBook elements that we actually use, and
+it *has no backward compatibility guarantees*.
+
+
+### Usage
+
+For some examples see:
+* The [`freemarker-site` project](https://github.com/apache/freemarker-site)
+* [FreeMarker Manual source code](https://github.com/apache/freemarker/tree/2.3-gae/src/manual/en_US)
+* `legacy-tests` in this project
+
+For editing DocBook, we are using [XXE](http://www.xmlmind.com/xmleditor/),
+with the `xxe-addon` installed, that you can find in this project.
+
## Building
-Before building for the first time:
-* JDK 8 must be used (tried with 1.8.0_212)
+These tools must be installed:
+* JDK 8 must be installed (tried with 1.8.0_212)
* Apache Maven must be installed (tried with 3.6.1)
* [Node.js](https://nodejs.org/) must be installed (tried with v10.16.2).
-* Go to `freemarker-docgen-core`, and issue `npm install` there to install
- Node.js dependencies. Repeat this step if you add new dependencies to
- `gulpfile.js`.
+ (Node.js is only used to generate static content while building Docgen itself.)
+
+Run these to build:
+
+1. In the `freemarker-docgen-core` directory (*not* in the top directory) issue:
+
+ ```npm install```
+
+ This is to get our JavaScript dependencies, based on `package.json`.
+
+2. In the project *top* directory (`freemarker-docgen`) issue:
+
+ ```mvn install```
+
+### Node.js troubleshooting
Possible node.js related problems and solutions:
* "Error: ENOENT, stat <someDirectoryHere>": create that directory manually,
then retry.
* If the system doesn't find `npm`: Open a new terminal (command window) so
- that it pick up the "path" environment variable changes. Adjust it if
+ that it picks up the `PATH` environment variable changes. Adjust it if
necessary.
* If the build has once worked, but now keeps failing due to some missing
modules, or anything strange, delete the "node_modules" directory, and
issue `npm install` to recreate it.
-
-To build Docgen (again, do the npm npm installation first!):
-
-```sh
-mvn install
-```
-
-For some examples see:
-* `legacy-tests`
-* `src/manual` in [the `freemarker` project](https://git-wip-us.apache.org/repos/asf/incubator-freemarker.git)
-* `src/main/docgen` the [`site` project](https://git-wip-us.apache.org/repos/asf/incubator-freemarker-site.git)
-For editing DocBook, we are using [XXE](http://www.xmlmind.com/xmleditor/)
-with the `xxe-addon` installed.
-### Try your modifications
+### Running Docgen from your IDE
-If you want to try your modifications, let's say, by regenerating the
-FreeMarker Manual, just create a Run Configuration in you IDE, with main class
-`org.freemarker.docgen.TransformCommandLine`, then specify these command line
-arguments:
+If you develop/debug Docgen, it's convenient to launch it from your IDE.
+As an example, let's generate the FreeMarker Manual. For that, create a
+Run Configuration in you IDE, with main class
+`org.freemarker.docgen.cli.Main`, and these command line arguments
+(replace `<FREEMARKER_PROJECT_DIR>` with the actual directory):
- C:\work\freemarker\git\freemarker-2.3-gae\src\manual
- C:\work\freemarker\git\freemarker-2.3-gae\build\manual
+ <FREEMARKER_PROJECT_DIR>\src\manual
+ <FREEMARKER_PROJECT_DIR>\build\manual
offline=true
-To ease comparing outputs, you can set a fixed value for the last
-modification with a java argument like this:
+To ease comparing the outputs of different runs, you can set a fixed value
+for the last modification with a java argument like this:
-Ddocgen.generationTime=2020-07-15T17:00Z
### Compiling LESS and JS
-This happens automatically during build, in the `generate-resources`.
-The generated output is in `target\resources-gulp`.
+This happens automatically during build, in the `generate-resources` Maven phase.
+The generated output is in `target\resources-gulp`, which will be included in
+the core jar artifact.
-## Publishing a new Docgen version
+## Releasing a new Docgen version
-TODO Standard ASF release procedure. Binary release to Maven Central.
+\[TODO] Standard ASF release procedure (staging, voting, etc.), so that we can release
+to the Maven Central. Not advertised, no announcements, no backward compatibility
+promises, but makes building our dependent projects easier.
## Icon Font Attribution
[freemarker-docgen] 01/02: (Deleted unused file)
Posted by dd...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ddekany pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/freemarker-docgen.git
commit eded9012c72070e2883933b23bcebfbf9e52f1b1
Author: ddekany <dd...@apache.org>
AuthorDate: Sun Jul 12 12:06:05 2020 +0200
(Deleted unused file)
---
package-lock.json | 3 ---
1 file changed, 3 deletions(-)
diff --git a/package-lock.json b/package-lock.json
deleted file mode 100644
index 48e341a..0000000
--- a/package-lock.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
- "lockfileVersion": 1
-}