windup · sgilda · Mar 30, 2015 · Mar 30, 2015
diff --git a/README.adoc b/README.adoc
@@ -6,17 +6,33 @@ Windup project documentation is created collaboratively on the Windup project Wi
 This `windup-documentation` repository takes documentation from that site, makes minor modifications, and publishes the pages in single HTML page book format. 
 This repository will contain the source for the official documentation when the Windup 2.0 ships.
 
-== Procedure to Copy and Modify the Wiki Documentation
+== Procedure to Update the Documentation With the Latest Windup Wiki
 
-Run the scripts/windupDocUpdate.sh script to copy and modify the files. 
+Check out a branch to work in.
 
-. Copies the `.asciidoc` files to the `docs/` directory and renames them with the `.adoc` extension.
-. Replaces the `xref:` macros to other pages with `xref:` macros.
-. Uses AsciiDoctor to create the guides in the `html/` directory.
+Run the `scripts/windupDocUpdate.sh` script to copy the latest pages from the Wiki documentation and modify the files so they can be included in the Windup documentation guides. 
+
+* Copies the latest images and stylesheets.
+* Copies the `.asciidoc` files to the `docs/` directory and renames them with the `.adoc` extension. 
+* Replaces the `link:` macros to other pages with `xref:` macros since they are now included in the same book.
+* Uses AsciiDoctor to generate HTML versions the guides in the `html/` directory.
+
+You must manually verify the following.
+
+* Search the Guide to find pages that link to other pages and make sure the linked to pages are part of the book.
+* Make sure every referenced page and section has a header matching the reference.
++
+----
+[[section-header]]
+=== Section Header
+---
+
+Use Git to add files that have changed and issue the pull to merge them.
 
 == Procedure to Publish the Guides
 
-* The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream.
+* The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream. 
+In the following instructions, be sure to replace WINDUP_RELEASE with the actual release number.
 +
 ----
 git clone https://github.com/windup/windup.git
@@ -72,6 +88,18 @@ git commit -m "Update message..."
 git push upstream gh-pages
 ----
 
+* Update the symlink so the "latest" release points to the newly published documentation.
++
+----
+unlink latest
+ln -s WINDUP_RELEASE latest
+git add latest
+git commit -m 'Replace symlink for latest to point to WINDUP_RELEASE'
+git push origin HEAD
+git push upstream gh-pages
+firefox http://windup.github.io/windup/docs/latest/html/WindupUserGuide.html
+----
+
 == Access the Guides
 
 View the documentation at the following URLs.

diff --git a/docs/Core-Development-Guide.asciidoc b/docs/Core-Development-Guide.asciidoc
@@ -20,7 +20,6 @@ repository, IRC, Mailing lists, ...
 * link:Dev-Build-Windup-from-Source[Build Windup from Source]
 * link:Dev-Execute-Windup-Built-from-Source[Execute Windup Built from Source]
 * link:Review-the-Report[Review the Report]
-* link:Glossary[Glossary of Terms]
 
 ==== Developer Contributing Information
 
@@ -29,11 +28,15 @@ repository, IRC, Mailing lists, ...
 
 ==== Understand the Windup Architecture and Structure
 
+* link:Windup-Processing-Overview[Windup Processing Overview]
 * link:Windup-Architectural-Components[Windup Architectural Components]
 * link:Dev-Windup-Project-Structure[Windup Project Structure]
 
 ==== Rules and Rulesets
 
+* link:Rules-Rule-Execution-Lifecycle[Rules Execution Lifecyle]
+* link:Rules-Rule-Story-Points[Rule Story Points]
+
 
 ==== Debugging and Troubleshooting
 
@@ -53,6 +56,7 @@ repository, IRC, Mailing lists, ...
 * link:Dev-Variables-Stack[Variables Stack]
 * link:Dev-Port-WindRide-Functionality-to-Windup[Port WindRide Functionality to Windup]
 * link:Dev-Git-Rebasing[Git Rebasing]
+* link:Dev-Releasing-Windup[Releasing Windup]
 
 ==== Rules topics
 
@@ -74,9 +78,7 @@ repository, IRC, Mailing lists, ...
 ** link:Rules-Ops-Reporting-Hint[Rules Ops: Reporting: Hint]
 ** link:Rules-Ops-Reporting-TypeReference[Rules Ops: Reporting: TypeReference]
 ** link:Rules-Ops-Xml-XsltTrasformation[Rules Ops: XML: XSLT Transformation]
-* link:Rules-Rule-Execution-Lifecycle[Rules Execution Lifecyle]
 * link:Rules-Java-based-Rule-Structure[Java-Based Rule Structure]
-* link:Rules-Rule-Story-Points[Rule Story Points]
 
 ==== Wiki and Product Documentation
 
@@ -85,3 +87,11 @@ repository, IRC, Mailing lists, ...
 * link:Dev-Create-Windup-JavaDoc[Create Windup JavaDoc]
 * link:Dev-Windup-Documentation-Process[Windup Documentation Process]
 
+==== Additional Resources
+
+* link:Review-the-Windup-Quickstarts[Review the Windup Quickstarts]
+* link:Known-Issues[Known Issues] 
+* link:Glossary[Glossary]
+
+* link:Glossary[Glossary of Terms]
+
diff --git a/docs/Dev-Build-Windup-from-Source.adoc b/docs/Dev-Build-Windup-from-Source.adoc
@@ -119,8 +119,10 @@ Unzip the `dist/target/windup-distribution-2.0.0-SNAPSHOT-offline.zip` file into
 ==== Quick Build Review for Experienced Windup Developers
 
 ---------------
-git clone git@github.com:windup/windup.git Windup
-cd Windup
+git clone git@github.com:windup/windup.git windup
+## Or if you haven't set up github account:
+#git clone https://github.com/windup/windup.git
+cd windup
 mvn clean install -DskipTests
 rm -rf /tmp/windup-zip/ /tmp/windup/
 unzip -q dist/target/windup-distribution-*-offline.zip -d /tmp/windup-zip

diff --git a/docs/Dev-Classloading-Notes.adoc b/docs/Dev-Classloading-Notes.adoc
@@ -1,4 +1,3 @@
-[[Dev-Classloading-Notes]]
 === Classloading Notes
 
 .DRAFT
@@ -7,6 +6,23 @@ _Page contains temporary notes, to be edited._
 
 This covers the specific situations when the Windup core developer needs to look up certain runtime classes. Does not relate to rules authoring.
 
+==== Forge add-ons transitive dependencies
+
+Let A depend on B depend on C.
+Depending on scope of C in B's POM:
+-------
+<scope>provided</scope>
+-------
+
+`provided` will NOT export C, so A depending on B won't see C's classes.
+Only `compile` scope is exported.
+`compile` will export C, so A depending on B will also see C's classes.
+
+* `provided` == import
+* `compile` == import & export
+* `optional` == optional, not installed automatically
+* `runtime` == export only
+
 
 ==== Finding classes
 [source,java]
@@ -23,12 +39,11 @@ or
 --------
 
 ==== Instantiating
-If you want something from the current addon, you need to @Inject its ServiceRegistry and get services from that.
+If you want something from the current add-on, you can simply @Inject the type you wish to use. Alternately you can @Inject an Imported<T> instance, or also @Inject the AddonRegistry itself.
 
-==== Which classloader is used? Always the one of the current code?
+==== Which ClassLoader is used? Always the one of the current code?
 
-Depends, if you are in a Furnace Service, then yes, it will use the
-current code's addon's classloader.
+Depends, if you are in a Furnace Service, then yes, it will use the current code's add-on ClassLoader.
 
 ==== Reading annotations from classes
 
@@ -40,13 +55,13 @@ Supposedly, Furnace proxies should also be able to handle such call:
 
     Rules annotation1 = ((FurnaceProxy) proxy).getOriginalClass().getAnnotation(Rules.class);
 
-TODO: Find out how exactly this is done.
+TO_DO: Find out how exactly this is done.
 
 
 ==== How do I know if I am in a Furnace service?
 
 Every furnace service is wrapped in a proxy. If it came from another
-addon (not your current addon) and was not instantiated with new Blah(),
+add-on (not your current add-on) and was not instantiated with new Blah(),
 you are in a furnace service. So if it was `@Inject`ed or retrieved via
 `addonRegistry.getServices(...)`
 
@@ -56,7 +71,7 @@ you are in a furnace service. So if it was `@Inject`ed or retrieved via
 (16:33:41) LincolnBaxter: ozizka: using a shared Resource.open() APi will actually be sort of a no-op, and just introduce another layer, since you generally need to be able to specify a classloader anyway
 (16:33:53) jsightler: lincolnthree: Well...
 (16:34:09) LincolnBaxter: ozizka: unless I'm misunderstanding the point of this
-(16:34:10) jsightler: lincolnthree: In windup we frequently need resources from the caller's addon
+(16:34:10) jsightler: lincolnthree: In windup we frequently need resources from the caller's add-on
 (16:34:18) LincolnBaxter: ozizka: ah wait
 (16:34:27) LincolnBaxter: ozizka: the *caller*'s classloader
 (16:34:35) LincolnBaxter: ozizka: not the CL of the current operation
@@ -67,18 +82,18 @@ you are in a furnace service. So if it was `@Inject`ed or retrieved via
 (16:35:25) ozizka-FN: which classloader is used?
 (16:35:33) ozizka-FN: Always the one of the current code?
 (16:35:44) ozizka-FN: Implicitly
-(16:35:54) LincolnBaxter: ozizka: depends, if you are in a Furnace Service, then yes, it will use the current code's addon's classloader
+(16:35:54) LincolnBaxter: ozizka: depends, if you are in a Furnace Service, then yes, it will use the current code's add-on's classloader
 (16:36:00) ozizka-FN: Ah
 (16:36:11) ozizka-FN: How do I know if I am in a Furnace service?
 (16:36:14) LincolnBaxter: ozizka: because every furnace service is wrapped in a proxy
-(16:36:31) LincolnBaxter: ozizka: basically if it came from another addon (not your current addon), you are in a furnace service
+(16:36:31) LincolnBaxter: ozizka: basically if it came from another add-on (not your current add-on), you are in a furnace service
 (16:36:43) LincolnBaxter: ozizka: and if you didn't instantiate with new Blah()
 (16:37:00) LincolnBaxter: ozizka: so if it was @Injected or retrieved via addonRegistry.getServices(...)
-(16:37:43) LincolnBaxter: jsightler: ozizka: mbriskar: why do we need the classloader of the calling addon? just curious
+(16:37:43) LincolnBaxter: jsightler: ozizka: mbriskar: why do we need the classloader of the calling add-on? just curious
 (16:37:54) ozizka-FN: So here we would use TCCL right?
 LincolnBaxter lincolnthree 
 (16:38:28) ozizka-FN: lincolnthree:  To load it's resources
-(16:38:31) ozizka-FN: from other addon
+(16:38:31) ozizka-FN: from other add-on
 (16:38:32) ozizka-FN: .
 (16:38:35) ozizka-FN: Or is there other way?
 (16:38:42) LincolnBaxter: ozizka: that's a vague statement ;)
@@ -93,12 +108,12 @@ LincolnBaxter lincolnthree
 ==== Resources loading
 
 ```
-(16:48:30) ozizka-FN: lincolnthree:  Just a note - the potential collisions caused  by addon's CL span is not considered as a risk?
+(16:48:30) ozizka-FN: lincolnthree:  Just a note - the potential collisions caused  by add-on's CL span is not considered as a risk?
 (16:49:25) ozizka-FN: I mean, it could load the file from it's deps.
 (16:49:36) ozizka-FN: * file = resource
 (16:49:50) LincolnBaxter: ozizka1: so the way it works is actually very controlled
-(16:50:06) LincolnBaxter: ozizka1: classloader will always attempt to load its own resources before loading from another addon
-(16:50:23) LincolnBaxter: ozizka1: at which point the order is determined by the order of the addon dependency in the POM
+(16:50:06) LincolnBaxter: ozizka1: classloader will always attempt to load its own resources before loading from another add-on
+(16:50:23) LincolnBaxter: ozizka1: at which point the order is determined by the order of the add-on dependency in the POM
 
 (16:53:26) ozizka-FN: Q: Unwrapping proxies caused the code in invoke() not actually being called?
 (16:53:32) ozizka-FN: Since the method calls were not intercepted?
@@ -123,4 +138,3 @@ https://github.com/forge/furnace/blob/master/proxy/src/main/java/org/jboss/forge
 
 ==== What classloader is used by Freemarker to load resources?
 `org.jboss.windup.reporting.freemarker.FurnaceFreeMarkerTemplateLoader`
-
diff --git a/docs/Dev-Concepts-and-Philosophy.adoc b/docs/Dev-Concepts-and-Philosophy.adoc
@@ -1,7 +1,7 @@
 [[Dev-Concepts-and-Philosophy]]
 === Concepts & Philosophy
 
-_TODO - OZIZKA: Can this topic be marked obsolete and be replaced by this one: xref:Windup-Processing-Overview[Windup Processing Overview] ?_
+TO_DO: - OZIZKA: Can this topic be marked obsolete and be replaced by this one: xref:Windup-Processing-Overview[Windup Processing Overview] ?_
 
 Windup is a rule-based tool that allows users to write customized rules
 based on the needs, constructs, and custom APIs used in their
@@ -33,8 +33,8 @@ See also the list of xref:Rules-Windup-Models[Windup Models].
 
 . Finding all `@Entity`s which use `org.hibernate` extensions.
 +
-TODO
+TO_DO
 
 . Finding _MyBatis_ DAOs and classes using them.
 +
-TODO
+TO_DO
diff --git a/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc b/docs/Dev-Connect-to-the-Graph-via-Rexster.adoc
@@ -1,7 +1,7 @@
 [[Dev-Connect-to-the-Graph-via-Rexster]]
 === Connect to the Graph via Rexster
 
-There is a specific addon for running Rexster along your graph with 
+There is a specific add-on for running Rexster along your graph with 
 groupId *org.jboss.windup.rexster* and *artifactId* Rexster.
 
 ==== Running Rexster Within Your Test

diff --git a/docs/Dev-Decompiling.adoc b/docs/Dev-Decompiling.adoc
@@ -20,10 +20,10 @@
 
 * `windup.ProcyonConfiguration` contains `procyon.DecompilerSettings`.
 * `procyon.DecompilerSettings` contains `outputDir` (the others are not much important). 
-TODO: Make that a parameter to method call?
+TO_DO: Make that a parameter to method call?
 
 ===== TypeReference
-TODO: Check how we get info about Java files; perhaps cache the `TypeReference` results - if worth it?
+TO_DO: Check how we get info about Java files; perhaps cache the `TypeReference` results - if worth it?
 
 ===== ITypeLoader
 
@@ -34,4 +34,4 @@ TODO: Check how we get info about Java files; perhaps cache the `TypeReference`
 * `InputTypeLoader`
 * `CompoundTypeLoader` - 2 typeloaders, queried in succession
 
-TODO: Create a simple `FileSystemTypeLoader`.
+TO_DO: Create a simple `FileSystemTypeLoader`.
diff --git a/docs/Dev-Dependencies.adoc b/docs/Dev-Dependencies.adoc
@@ -12,11 +12,11 @@ discussion._
 The following is the typical structure of Maven `add-on` modules.
 
 -------------------------------------------
-myaddon-parent
-+--- myaddon - jar, classifier: forge-addon
-+--- myaddon-api - jar
-+--- myaddon-impl - jar
-+--- myaddon-tests - jar
+my-add-on-parent
++--- my-add-on - jar, classifier: forge-addon
++--- my-add-on-api - jar
++--- my-add-on-impl - jar
++--- my-add-on-tests - jar
 -------------------------------------------
 
 The `add-on` POM file can declare dependencies on other forge-addons. 
@@ -89,14 +89,14 @@ dependencies, and these are treated as normal.
 
 [NOTE]
 ==========================
-Add-on depends on API , scope `compile` > Addon
+Add-on depends on API , scope `compile` > Add-on
 depends on Impl , scope `compile` with `<optional>true</optional>` -
 prevents exporting this dependency to consumers of the add-on.
 ==========================
 
 ==== Test dependencies
 
-For test dependencies on add-ons: Any addon/sub-part requiring an addon
+For test dependencies on add-ons: Any add-on/sub-part requiring an add-on
 for testing purposes should use `<scope>test</scope>`.
 
 [source,xml]

diff --git a/docs/Dev-Development-Guidelines-and-Conventions.adoc b/docs/Dev-Development-Guidelines-and-Conventions.adoc
@@ -53,5 +53,5 @@ http://plugins.jetbrains.com/plugin/?id=6546[http://plugins.jetbrains.com/plugin
 The following are not really accurate at this time. This is still TBD! 
 
 * Lowercase with dashes. Start with `windup-`.
-* Ruleset addons start with `windup-rules-`.
+* Ruleset add-ons start with `windup-rules-`.