windup · sgilda · Dec 12, 2014 · Dec 12, 2014
diff --git a/About-the-WINDUP_HOME-Variable.adoc b/About-the-WINDUP_HOME-Variable.adoc
@@ -1,6 +1,7 @@
+[[About-the-WINDUP_HOME-Variable]]
 === About the WINDUP_HOME Variable
 
 This documentation uses the `WINDUP_HOME` *replaceable* value to denote the path to the Windup distribution. When you encounter this value in the documentation, be sure to replace it with the actual path to your Windup installation.
 
-* If you link:Install-Windup[download and install] the latest distribution of Windup from the JBoss Nexus repository, `WINDUP_HOME` refers to the `windup-distribution-2.0.0.VERSION` folder extracted from the downloaded ZIP file.
-* If you link:Dev:-Execute-Windup-Built-from-Source[build Windup from source], `WINDUP_HOME` refers to the `windup-distribution-2.0.0-<version>` folder extracted from the Windup source `dist/target/windup-distribution-2.0.0-VERSION.zip` file.
+* If you download and install the latest distribution of Windup from the JBoss Nexus repository, `WINDUP_HOME` refers to the `windup-distribution-2.0.0.VERSION` folder extracted from the downloaded ZIP file.
+* If you build Windup from GitHub source, `WINDUP_HOME` refers to the `windup-distribution-2.0.0-<version>` folder extracted from the Windup source `dist/target/windup-distribution-2.0.0-VERSION.zip` file.
diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,59 @@
+# Windup Documentation Contributing Guide
+
+## Wiki Asciidoc Syntax Guidelines
+
+The following guidelines make the transition from the Windup Wiki pages to the Windup documentation GitHub smoother.
+
+*   Be sure to add a level 3 page heading for each page. When compiled in a book, the Guide name is the top level, chapters are level 2, and the page is level  3.
+
+        === Build Windup from Source
+
+*   At the beginning of each new Wiki page, add an anchor with the exact page name, including the dashes. This is needed when the pages are combined into a book.
+
+        [[Dev-Build-Windup-from-Source]]
+        === Build Windup from Source
+
+*   Wiki generates anchors using dashes for spaces. AsciiDoctor generates a leading underscore and underscores for spaces. When referring to another section within the same page, do not use the `<<section-title-anchor>>` syntax. It does not generate correctly for the documentation books. Instead, create an anchor and use the 'xref:' syntax to provide the link. 
+
+    Create the anchor at the top of the page:
+
+        [_windup_command_examples]
+        ==== Windup Command Examples
+
+    Then use the `xref` to create the link. Note, the Wiki generates the name with dashes (-) for spaces.
+
+        See xref:windup-command-examples[Windup Command Examples] for more information.
+
+    Because Asciidoctor generates a leading underscore and underscores for spaces, we need to modify the `xref:` text when the documentation is copied to windup-documenation.
+
+        See xref:_windup_command_examples[Windup Command Examples] for more information.
+
+## Build the Windup Guides
+
+*   Install Ascidoctor
+
+        gem install sciidoctor
+
+*   Grab the latest changes from the Windup Wiki site
+
+   * Copy any updated pages from the Windup Wiki and replace the `.asciidoc` extension with `.adoc`
+
+            cp ../windup.wiki/Features-of-Windup-2.0.asciidoc Features-of-Windup-2.0.adoc
+
+   * Find the internal `link:` macros in pages that link to other pages.
+
+      * Make sure each linked page is added with an `include:` in the Guide template.
+
+      * Make sure the wiki page is copied and added to this GitHub.
+
+      * Replace the `link:` macros with a `xref:` macros.
+
+   * Find the internal `xref:` macros. Add a leading underscore and replace the dashes with underscores.
+
+           Old: See xref:windup-command-examples[Windup Command Examples] for more information.
+           New: See xref:_windup_command_examples[Windup Command Examples] for more information.
+
+* Build the HTML version of the guide
+
+        asciidoctor -dbook -a toc -o WindupUserGuide.html Windup-User-Guide.adoc
+
diff --git a/Dev-Debugging-and-Profiling.adoc b/Dev-Debugging-and-Profiling.adoc
@@ -0,0 +1,63 @@
+[[Dev-Debugging-and-Profiling]]
+=== Debugging and Profiling
+
+==== Debug the Windup Distribution Runtime
+
+You can debug the Windup distribution using one of the following approaches.
+
+. Pass the `--debug` argument on the command line when you execute Windup.
++
+--------
+For Linux:    WINDUP_HOME/bin $ ./windup --debug
+For Windows:  C:\WINDUP_HOME\bin> windup --debug
+--------
+
+. Configure the `FORGE_OPTS` for debugging.
++
+--------
+export FORGE_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000"
+--------
+
+==== Debug a Test Using NetBeans
+
+Click the `Debug Test File` button, or choose `Menu` → `Debug` → `Debug Test File`.
+
+==== Profile a Test Using NetBeans
+
+. Profiling requires a lot of memory, so be sure to increase the NetBeans memory settings. 
+* Open the `NETBEANS_HOME/etc/netbeans.conf` file
+* Find the line with `netbeans_default_options=`
+* Add the following option
++
+--------
+-J-Xmx5200m -J-XX:MaxPermSize=1024m
+--------
+* Restart NetBeans.
+
+. Click `Menu > Profile > Profile Test File`.
+. In the resulting dialog, enter the following.
++
+--------
+exec.args=-Djboss.modules.system.pkgs=org.netbeans
+--------
+
+==== Profile Forge Runtime Using YourKit
+
+
+. Download and unzip http://www.yourkit.com/[YourKit]. Be sure to get the trial license.
+. Configure the `FORGE_OPTS` for Yourkit:
++
+--------
+export YOURKIT_HOME=/home/ondra/sw/prog/YourKit-b14092
+export FORGE_OPTS="-Djboss.modules.system.pkgs=com.yourkit -agentpath:$YOURKIT_HOME/bin/linux-x86-64/libyjpagent.so=sampling,onexit=snapshot,delay=0"
+--------
+
+. Run `forge`. For details, see http://forge.jboss.org/1.x/docs/using/profiling-forge.html[Profiling
+Forge], but skip the first 2 points that direct you to copy the YourKit module and JAR into the Forge installation. Forge 2 already contains the YourKit module and JAR>.
+
+. Run `windup-analyze-app`.
++
+---------------------------
+forge -e windup-migrate-app
+---------------------------
+
diff --git a/Dev-Troubleshoot-Windup-Issues.adoc b/Dev-Troubleshoot-Windup-Issues.adoc
@@ -0,0 +1,21 @@
+[Dev-Troubleshoot-Windup-Issues]
+=== Troubleshoot Windup Issues
+
+==== Logging
+
+Logging is currently broken and will not be fixed any time soon. 
+
+See xref:Known-Issues[Known Issues] and https://issues.jboss.org/browse/WINDUP-73[WINDUP-73] for the current status.
+
+==== Debugging Exceptions
+
+Exceptions in Surefire reports are broken due to the way Forge wraps
+exceptions and the way Surefire handles them. You need to
+debug or rewrap exceptions using `TestUtil.rewrap(ex)`. 
+
+See xref:Known-Issues[Known Issues] and https://issues.jboss.org/browse/WINDUP-197[WINDUP-197] for the current status..
+
+==== Classloading Problems
+
+Configuring dependencies in a Forge-based project can be a little tricky.
+See xref:Dev-Dependencies[Dependencies] for some hints.
diff --git a/Dev-Windup-Architectural-Components.adoc b/Dev-Windup-Architectural-Components.adoc
@@ -10,7 +10,7 @@ familiar with them.
 
 Forge is an open source, extendable, rapid application development tool
 for creating Java EE applications using Maven. For more information
-about Forge, see: http://forge.jboss.org/[JBoss Forge].
+about Forge 2, see: http://forge.jboss.org/[JBoss Forge].
 
 ==== Forge Furnace
 
@@ -36,7 +36,7 @@ a collection of annotated Java Interfaces. For more information, see:
 https://github.com/tinkerpop/frames/wiki[TinkerPop Frames].
 
 Windup includes several Frames extensions, which are documented here:
-link:./Dev:-Frames-extensions[Frames Extensions].
+xref:Dev-Frames-extensions[Frames Extensions].
 
 ==== Gremlin
 

diff --git a/Execute-Windup.adoc b/Execute-Windup.adoc
@@ -1,3 +1,4 @@
+[[Execute-Windup]]
 === Execute Windup
 
 These instructions are for users who run Windup using the tool extracted from the ZIP download.
@@ -16,9 +17,7 @@ Before you begin, you must gather the following information.
 * While you can provide package names for standard Java EE 3rd party software like `org.apache`, it is usually best not to include them as they should not impact the migration effort.
 * If you omit the `--packages` argument, every package in the application is scanned, resulting in very slow performance. It is best to provide the argument with one or more packages.
 
-IMPORTANT: There is currently a bug in the parser that does not resolve the tilde (~) in a path name correctly. For now, you must fully spell out the complete path name when it is passed as an argument in the Windup command line. For example, use `/home/username/path-to-file` rather than `~/path-to-file`. For details, see https://issues.jboss.org/browse/WINDUP-305.
-
-==== Run Windup
+==== Start Windup
 
 . Open a terminal and navigate to the `WINDUP_HOME/bin` directory
 
@@ -71,7 +70,7 @@ Where:
 NOTE: If the *OUTPUT_REPORT_DIRECTORY* directory exists, it is deleted and recreated by Windup, so be careful not to specify a directory that contains important information!
 
 +
-See <<windup-command-examples>> below for concrete examples of Windup commands using source code directories and archives located in the Windup GitHub repository.
+See xref:_windup_command_examples[Windup Command Examples] below for concrete examples of Windup commands using source code directories and archives located in the Windup GitHub repository.
 
 . You should see the following result upon completion of the command:
 +
@@ -95,14 +94,15 @@ The following subdirectories in the `OUTPUT_REPORT_DIRECTORY` contain the suppor
             stats/
             index.html
 
-. For details on how to evaluate the report data, see xref:_review_the_report[Review the Report].
+. For details on how to evaluate the report data, see xref:Review-the-Report[Review the Report].
 
 ==== Windup Help
 
 To see the list of available parameters for the `windup-migrate-app` command, execute the following command in the Windup prompt:
 
     man windup-migrate-app
 
+[_windup_command_examples]
 ==== Windup Command Examples
 
 The following Windup command examples report against applications located in the https://github.com/windup/windup/tree/master/test-files[Windup source test-files] directory.

diff --git a/Features-of-Windup-2.0.adoc b/Features-of-Windup-2.0.adoc
@@ -1,8 +1,9 @@
-= Features of Windup 2.0
+[[Features-of-Windup-2.0]]
+=== Features of Windup 2.0
 
 [horizontal]
 
-Shared Data Model:: Windup 2.0 creates a shared data model graph that provides the following benefits:
+Shared Data Model:: Windup 2.0 creates a shared data model graph that provides the following benefits.
 
 * It enables complex rule interaction, allowing rules to pass findings to other rules.
 * It enables 3rd-party plug-ins to interact with other plugins, rules and reports.

diff --git a/Get-Involved.adoc b/Get-Involved.adoc
@@ -1,42 +1,23 @@
-= Get Involved
+[[Get-Involved]]
+=== Get Involved
 
-== How can you help?
+==== How can you help?
 
 To help us make Windup cover most application constructs and server configurations, including yours, you can help with any of the following items. Some items require only a few minutes of your time!
 
-* link:mailto:windup-users@redhat.com[Let us know] what Windup migration rules should cover.
+* mailto:windup-users@redhat.com[Let us know] what Windup migration rules should cover.
 * Provide example applications to test migration rules.
 * Identify application components and problem areas that may be difficult to migrate.
 ** Write a short description of these problem migration areas.
 ** Write a brief guide describing how to solve the problem migration areas.
 * link:Execute-Windup[Try Windup] on your application. Be sure to link:Report-Issues-with-Windup[report any issues] you encounter.
 * Write an Windup rule to automate the migration process.
 ** Create a test for the new rule.
-* You can <<contribute-windup-rules>>.
-* You can also <<contribute-to-the-project-source-code>>.
+* You can contribute Windup rules. For details, see the _Windup Rules Development Guide_.
+* You can also contribute to the project source code. See the _Windup Core Development Guide_ for information about how to configure your environment and set up the project.
 
-Any level of involvement is greatly appreciated.
+Any level of involvement is greatly appreciated!
 
-== Contribute Windup Rules
 
-Check back later for details about how to contribute rules to the Windup
-project. 
-
-For more information about how to contribute rules to the Windup
-project, see the link:Rules-Development-Guide[Rules Development Guide].
-
-== Contribute to the Project Source Code
-
-The Windup project source code is located in this GitHub repository:
-https://github.com/windup/windup.
-
-* For instructions on how to fork and clone the Windup source code, see
-link:./Dev:-Get-the-Windup-Source-Code[Get the Windup Source Code].
-* For instructions on how to build Windup, see
-link:./Dev:-Build-Windup-from-Source[Build Windup from Source]
-
-For more information about how to develop code for the Windup
-project, see the
-link:Dev:-Windup-Development-Guide[Windup Development Guide].
 
 
diff --git a/Glossary.adoc b/Glossary.adoc
@@ -1,3 +1,4 @@
+[[Glossary]]
 === Glossary of Terms Used in Windup
 
 ==== Rules Terms

diff --git a/Install-Windup.adoc b/Install-Windup.adoc
@@ -1,6 +1,7 @@
+[[Install-Windup]]
 === Install Windup
 
-. Download the latest Windup ZIP distribution from http://repository.jboss.org/nexus/content/groups/public/org/jboss/windup/windup-distribution. This is currently https://repository.jboss.org/nexus/service/local/artifact/maven/redirect?r=releases&g=org.jboss.windup&a=windup-distribution&v=2.0.0.Beta5&e=zip&c=offline[windup-distribution-2.0.0.Beta5].
+. Download the latest Windup ZIP distribution from http://repository.jboss.org/nexus/content/groups/public/org/jboss/windup/windup-distribution. This is currently http://repository.jboss.org/nexus/content/groups/public/org/jboss/windup/windup-distribution/2.0.0.Beta6/[windup-distribution-2.0.0.Beta6].
 . Extract the ZIP file in to a directory of your choice. 
 
-NOTE: The documentation uses the replaceable value `WINDUP_HOME` to denote the path to the Windup installation. When you encounter this value in the documentation, be sure to replace it with the actual path to your Windup installation. For more information, see link:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable].
+NOTE: The documentation uses the replaceable value `WINDUP_HOME` to denote the path to the Windup installation. When you encounter this value in the documentation, be sure to replace it with the actual path to your Windup installation. For more information, see xref:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable].