Polish doc

README.adoc

@@ -25,8 +25,7 @@ of changes
 
 == Installation and Getting Started
 The {docs}/htmlsingle/[reference documentation] is published in
-{docs}/htmlsingle/[HTML], {docs}/pdf/spring-initializr-reference.pdf[PDF] and
+{docs}/htmlsingle/[HTML] and {docs}/epub/spring-initializr-reference.epub[EPUB] formats.
-{docs}/epub/spring-initializr-reference.epub[EPUB] formats.
 
 
 == Modules

initializr-docs/src/main/asciidoc/configuration-guide.adoc

@@ -117,7 +117,7 @@ versions.
 
 If that's not what you want, you need to override the `InitializrMetadataProvider` bean to
 provide your own metadata for the service. For instance, you could swap to an
-implementation that always returns the contents of your configuration file:
+implementation that always returns the contents of static `application.yml`:
 
 [source,java,indent=0]
 ----
@@ -150,8 +150,8 @@ By default, Spring Initializr exposes the following resources (all accessed via
 * `/starter.zip` generate a complete project structure archived in a zip
 * `/starter.tgz` generate a complete project structure archived in a tgz
 
-Each type also defines one or more *tags*, that is additional metadata entries to qualify
+Each type also defines one or more *tags* that provides additional metadata entries to
-the entry. The following standard tags exist:
+qualify the entry. The following standard tags exist:
 
 * `build`: the name of the build system to use (e.g. `maven`, `gradle`)
 * `format`: the format of the project (e.g. `project` for a full project, `build` for just
@@ -264,7 +264,7 @@ If no BOM is available you can specify a version directly:
 ----
 
 If you add this configuration and search for "acme" (or "solid"), you'll find this extra
-entry; generating a maven project with it should add the following to the pom
+entry; generating a maven project with it should add the following to the pom:
 
 [source,xml,indent=0,subs="verbatim"]
 ----
@@ -278,40 +278,129 @@ entry; generating a maven project with it should add the following to the pom
 The rest of this section will detail the other configuration options.
 
 
+
 [[dependencies-version-range]]
 ==== Availability (version range)
-
+By default, a dependency is available regardless of the Spring Boot version you have
-A dependency can have a `versionRange`, which is a range of versions of Spring Boot which
+selected. If you need to restrict a dependency to a certain Spring Boot generation you
-are valid in combination with it. The versions are *not* applied to the dependency itself,
+can add a `versionRange` attribute to its definition. A version range is a range of
-but rather used to filter out the dependency, or modify it, when different versions of
+versions of Spring Boot which are valid in combination with it. The versions are *not*
-Spring Boot are selected for the generated project.
+applied to the dependency itself, but rather used to filter out the dependency, or modify
+it, when different versions of Spring Boot are selected for the generated project.
 
 A version range has a lower and an upper bound, and if the bound is inclusive it is
-denoted as a square bracket ("[" or "]"), otherwise it is exclusive and denoted by a
+denoted as a square bracket (`[` or `]`), otherwise it is exclusive and denoted by a
-parenthesis ("(" or ")"). Example: "[1.1.6.RELEASE,1.3.0.M1)" means from all versions from
+parenthesis (`(` or `)`). For instance `[1.1.6.RELEASE,1.3.0.M1)` means from all versions
-1.1.6 up to but not including 1.3.0.M1 (no not including any of the 1.3.x line. 
+from `1.1.6.RELEASE` up to but not including `1.3.0.M1` (concretely no including the
+`1.3.x` line and after).
 
-A version range can be a single value, e.g. "1.2.0.RELEASE", which is short for "this
+A version range can be a single value, e.g. `1.2.0.RELEASE`, which is short for "this
 version or greater". It is an inclusive lower bound with an implied infinite upper bound.
 
-The other shorthand notation that is available is to use "x" for the micro-version label,
+If you need to specify "the latest release" in a given line, you can use a `x` rather than
-e.g. "1.3.x" means all versions beginning with "1.3". This is mainly used in inclusive
+an hard-coded version. For instance, `1.4.x.BUILD-SNAPSHOT` is the latest snapshot build
-bounds, like "[1.2.0.RELEASE,1.4.x.RELEASE)" for "all versions in 1.2.x and 1.3.x but not
+of the 1.4.x line. For instance, if you want to restrict a dependency from `1.1.0.RELEASE`
-1.4.0 or above".
+to the latest stable release of the 1.3.x line, you'd use `[1.1.0.RELEASE,1.3.x.RELEASE]`.
 
 Snapshots are naturally ordered higher than released versions, so if you are looking to
 match a dependency to only the latest snapshots of Spring Boot, you could use a version
-range of "1.5.x.BUILD-SNAPSHOT" (assuming 1.5 was the latest).
+range of `1.5.x.BUILD-SNAPSHOT` (assuming 1.5 was the latest).
 
-Remember to quote the values of a version range in YAML configuration files (with double
+TIP: Remember to quote the values of a version range in YAML configuration files (with
-quotes "").
+double quotes "").
 
 See below in the section on <<howto-link-boot-version,linking versions>> for more examples
 and idioms.
 
+
+
+[[dependencies-repository]]
+==== Repository
+If the dependency is not available on Maven Central (or whatever default repository that
+is configured on your end), you can also add a reference to a repository. A repository is
+declared at the top level (under `env`) and given an id via the key in the configuration:
+
+[source,yaml,indent=0]
+----
+initializr:
+  env:
+    repositories:
+      my-api-repo-1:
+        name: repo1
+        url: http://example.com/repo1
+----
+
+Once defined, the repository can then be referred back to in a dependency
+
+[source,yaml,indent=0]
+----
+initializr:
+  dependencies:
+    - name: Other
+      content:
+        - name: Foo
+          groupId: org.acme
+          artifactId: foo
+          version: 1.3.5
+          repository: my-api-repo-1
+----
+
+It is usually preferable to have a BOM for every dependency, and attach the repository to
+the BOM instead.
+
+TIP: The snapshots and milestones repositories on `repo.spring.io` are automatically
+available with the `spring-snapshots` and `spring-milestones` identifiers respectively.
+
+
+
+[[create-instance-boms]]
+=== Configuring Bill of Materials
+A Bill of Materials (BOM) is a special `pom.xml`, deployed to a Maven repository, and used
+to control dependency management for a set of related artifacts. In the Spring Boot
+ecosystem we usually use the suffix `-dependencies` on the artifact id of a BOM. In other
+projects we see `-bom`. It is recommended that all dependencies are included in a BOM of
+some sort, since they provide nice high level features for users of the dependency. It is
+also important that 2 BOMs used in a project do not contain conflicting versions for the
+same dependency, so the best practice is to look at the existing BOMs in the Initializr
+before you add a new one, and make sure that you aren't adding a conflict.
+
+In the Initializr a BOM is declared at the `env` level, and given an id through the
+configuration key. Example:
+
+[source,yaml,indent=0]
+----
+initializr:
+  env:
+    boms:
+      my-api-bom:
+        groupId: org.acme
+        artifactId: my-api-dependencies
+        version: 1.0.0.RELEASE
+        repositories: my-api-repo-1
+----
+
+If a BOM requires a special, non-default repository, then it can be referred to here,
+instead of having to explicitly list the repository again for each dependency. A
+dependency, or a dependency group, can declare that it requires the use of one or more
+BOMs by referring to the id:
+
+[source,yaml,indent=0]
+----
+initializr:
+  dependencies:
+    - name: Other
+      content:
+        - name: My API
+          id : my-api
+          groupId: org.acme
+          artifactId: my-api
+          bom: my-api-bom
+----
+
+
+
 [[dependencies-mappings]]
 ==== Map coordinates according to the Spring Boot version
-
 In addition to a Spring Boot version range for the dependency or a BOM, you can configure
 the version relationships at a finer grained level using version mappings. A dependency or
 BOM has a list of "mappings", each of which consists of a version range, and a set of one
@@ -327,37 +416,40 @@ initializr:
   env:
     boms:
       cloud-bom:
-        groupId: org.springframework.cloud
+        groupId: com.example.foo
-        artifactId: spring-cloud-dependencies
+        artifactId: acme-foo-dependencies
-        order: 50
         mappings:
           - versionRange: "[1.2.3.RELEASE,1.3.0.RELEASE)"
-            version: Angel.SR6
+            version: Arcturus.SR6
           - versionRange: "[1.3.0.RELEASE,1.4.0.RELEASE)"
-            version: Brixton.SR7
+            version: Botein.SR7
           - versionRange: "[1.4.0.RELEASE,1.5.x.RELEASE)"
-            version: Camden.SR6
+            version: Castor.SR6
           - versionRange: "[1.5.0.RELEASE,1.5.x.BUILD-SNAPSHOT)"
-            version: Dalston.RC1
+            version: Diadem.RC1
             repositories: spring-milestones
           - versionRange: "1.5.x.BUILD-SNAPSHOT"
-            version: Dalston.BUILD-SNAPSHOT
+            version: Diadem.BUILD-SNAPSHOT
             repositories: spring-snapshots,spring-milestones
 ----
 
 The primary use case here is to map Spring Boot versions to the preferred or supported
-versions of Spring Cloud. You can also see that for the milestone and snapshot BOMs,
+versions of the Foo project. You can also see that for the milestone and snapshot BOMs,
 additional repositories are declared because those artifacts are not in the default
 repository.
 
+TIP: We also use the `x` trick in version ranges to avoid updating the range every time
+a new Spring Boot 1.5 bug fix release is available
+
 See below in the section on <<howto-link-boot-version,linking versions>> for more examples.
 
+
+
 [[dependencies-alias]]
 ==== Aliases
-
+A dependency has an id (e.g. "web-services"), but it could be necessary to provide a new
-A dependency has an id (e.g. "web-services"), but it can also be referred to using
+id and still be able to serve request from client using the now deprecated id. To do so,
-aliases, if those are declared in the metadata. Aliases and ids for dependencies must be
+an alias can be defined for ths dependency;
-globally unique (this is not enforced by the software). For example:
 
 [source,yaml,indent=0]
 ----
@@ -374,222 +466,183 @@ initializr:
 The same project can now be generated with `dependencies=ws` or
 `dependencies=web-services`.
 
-[[dependencies-repository]]
-==== Repository
 
-If the dependency is not available on Maven Central (or whatever default repository that
-is configured on your end), you can also add a <<dependencies-repository,reference to a
-repository>>. A repository is declared at the top level (under `env`) and given an id via
-the key in the configuration. Example
-
-[source,yml,indent=0,subs="verbatim,attributes"]
-----
-initializr:
-  env:
-    repositories:
-      my-api-repo-1:
-        name: repo1
-        url: http://example.com/repo1
-----
-
-he repository can then be referred back to in a dependency
-
-[source,yml,subs="verbatim,attributes"]
-----
-initializr:
-  dependencies:
-    - name: Other
-      content:
-        - name: Foo
-          groupId: org.acme
-          artifactId: foo
-          version: 1.3.5
-          repository: my-api-repo-1
-----
-
-It is usually preferable to have a BOM for every dependency, and attach the repository to
-the BOM instead.
-
-[[create-instance-boms]]
-=== Configuring Bill of Materials
-
-A Bill of Materials (BOM) is a special `pom.xml`, deployed to a Maven repository, and use
-to control dependency management for a set of related artifacts. In the Spring Boot
-ecosystem we usually use the suffix "-dependencies" on the artifact id of a BOM. In other
-projects we see "-bom". It is recommended that all dependencies are included in a BOM of
-some sort, since they provide nice high level features for users of the dependency. It is
-also important that 2 BOMs used in a project do not contain conflicting versions for the
-same dependency, so the best practice is to look at the existing BOMs in the Initializr
-before you add a new one, and make sure that you aren't adding a conflict. Maven (3.5)
-will report conflicts when it builds a project containing the two BOMs, even if the
-dependency that conflicts is not used.
-
-In the Initializr a BOM is declared at the `env` level, and given an id through the
-configuration key. Example:
-
-[source,yml,subs="verbatim,attributes"]
-----
-initializr:
-  env:
-    boms:
-      my-api-bom:
-        groupId: org.acme
-        artifactId: my-api-dependencies
-        version: 1.0.0.RELEASE
-        repositories: my-api-repo-1
-----
-
-If a BOM requires a special, non-default repository, then it can be referred to here,
-instead of having to explicitly list the repository again for each dependency. A
-dependency, or a dependency group, can declare that it requires the use of one or more BOMs by referring to the id. Example:
-
-[source,yml,subs="verbatim,attributes"]
-----
-initializr:
-  dependencies:
-    - name: Other
-      content:
-        - name: My API
-          id : my-api
-          groupId: org.acme
-          artifactId: my-api
-          bom: my-api-bom
-----
 
 [[dependencies-facet]]
 ==== Facets
-
 A "facet" is a label on a dependency which is used to drive a code modification in the
 generated project. In the standard Initializr generator, there is only one facet that is
-actually used ("web"), but custom installations might choose to use it for their own
+actually used (`web`), but custom installations might choose to use it for their own
-purposes. The "web" facet is used to drive the inclusion of `spring-boot-starter-web` if
+purposes. The `web` facet is used to drive the inclusion of `spring-boot-starter-web` if
 any other dependency with that facet is included. The value of the "facets" property of a
 dependency is a list of strings.
 
+
+
 [[create-instance-dependencies-link]]
 ==== Links
-
 Links can be used to provide descriptive and hyperlink data to guide to user on how to
 learn more about a dependency. A dependency has a "links" property which is a list of
-`Link`. Each link has a "rel" label to identify it, an "href" and an optional (but
+`Link`. Each link has a `rel` label to identify it, an `href` and an optional (but
-recommended) description. In the web UI the links are not currently rendered.
+recommended) `description`.
+
+The following `rel` value are currently officially supported:
+
+* `guide`: the link points to a guide describing how to use the related dependency. It
+can be a tutorial, a how-to or typically a guide available on https://spring.io/guides
+* reference: the link points to a section of a developer guide typically or any page that
+documents how to use the dependency
+
+The url can be templated if its actual value can change according to the environment. An
+URL parameter is specified with curly braces, something like
+`https://example.com/doc/{bootVersion}/section` defines a `bootVersion` parameter.
+
+The following attributes are currently supported:
+
+* `bootVersion`: the Spring Boot version that is currently active
+
+Here is an example that adds two links to the `acme` dependency:
+
+[source,yaml,indent=0]
+----
+	initializr:
+	  dependencies:
+		- name: Tech
+		  content:
+			- name: Acme
+			  id: acme
+			  groupId: com.example.acme
+			  artifactId: acme
+			  version: 1.2.0.RELEASE
+			  description: A solid description for this dependency
+			  links:
+			    - rel: guide
+				  href: https://com.example/guides/acme/
+				  description: Getting started with Acme
+			    - rel: reference
+				  href: http://docs.example.com/acme/html
+----
+
+
 
 [[create-instance-dependencies-search]]
 ==== Improve search results
-
+Each dependency can have a `weight` (a number >=0) and also `keywords` (list of string)
-Each dependency can have a "weight" (a number >=0) and also "keywords" (list of string)
 that are used to prioritize them in the search feature in the web UI. If you type one of
 the keywords into the "Dependencies" box in the UI, those dependencies will be listed
 below, in order of decreasing weight, if they have one (unweighted dependencies come
 last).
 
 
+
 [[configuration-howto]]
 == '`How-to`' guides
-
 This section provides answers to some common '`how do I do that...`' type of questions
 that often arise when configuring Spring Initializr.
 
-[[howto-add-a-new-checkbox]]
-=== Add a new dependency checkbox
 
-To add a new checkbox, first identify the Maven co-ordinates of the dependency you want to
+
-add (`groupId:artifactId:version`) and then check which versions of Spring Boot it works
+[[howto-add-a-new-dependency]]
+=== Add a new dependency
+To add a new dependency, first identify the Maven co-ordinates of the dependency you want
+to add (`groupId:artifactId:version`) and then check which versions of Spring Boot it works
 with. If there are multiple versions that work with different versions of Spring Boot,
 then that's fine too.
 
 * If there is a published BOM that manages the version of you dependency, then add that
-  first, in the `env` section (see the <<create-instance-boms>> section above).
+  first, in the `env` section (see <<create-instance-boms>>).
-
 * Then configure the dependency, fitting it into an existing group if you can, otherwise
   creating a new group.
-
 * If there is a BOM then omit the version.
-
 * If there is a Spring Boot version range (or min or max) that you need for this
   dependency, add that as a <<howto-link-boot-version,linked version>>.
 
+
+
 [[howto-override-a-version]]
 === Override the version of a dependency
-
 Sometimes it happens that the BOM that normally manages your dependency version is in
 conflict with the newest version. Or maybe this is the case for only a range of Spring
 Boot versions. Or maybe there just is no BOM, or it's not worth creating one for just one
-dependency. In these cases you can specify the version manually for a dependency either at the top level, or in a <<howto-link-boot-version,version mapping>>. At the top level it looks like this (just a "version" property in a dependency):
+dependency. In these cases you can specify the version manually for a dependency either
+at the top level, or in a
+<<howto-link-boot-version,version mapping>>. At the top level it looks like this (just
+a `version` property in a dependency):
 
-[source,yml,subs="verbatim,attributes"]
+[source,yaml,indent=0]
 ----
-initializr:
+	initializr:
-  dependencies:
+	  dependencies:
-    - name: I/O
+		- name: Tech
-      content:
+		  content:
-        - name: Activiti
+			- name: Acme
-          id: activiti-basic
+			  id: acme
-          description: Activiti BPMN workflow engine
+			  groupId: com.example.acme
-          groupId: org.activiti
+			  artifactId: acme
-          artifactId: activiti-spring-boot-starter-basic
+			  version: 1.2.0.RELEASE
-          version: 5.21.0
+			  description: A solid description for this dependency
 ----
 
+
+
 [[howto-link-boot-version]]
 === Link a Boot version to a version of your dependency
-
 If your dependency requires a specific version of Spring Boot, ot different versions of
 Spring Boot require different versions of your dependency there are a couple of mechanisms
 to configure that.
 
-The simplest is to put a "versionRange" in the dependency declaration. This is a range of versions of Spring Boot, not or your dependency. For example:
+The simplest is to put a `versionRange` in the dependency declaration. This is a range of
+versions of Spring Boot, not of your dependency. For example:
 
-[source,yml,subs="verbatim,attributes"]
+[source,yaml,indent=0]
 ----
 initializr:
   dependencies:
     - name: Stuff
       content:
-        - name: Atomikos (JTA)
+        - name: Foo
-          id: jta-atomikos
+          id: foo
-          description: JTA distributed transactions via Atomikos
+          ...
           versionRange: 1.2.0.M1
-        - name: Stormpath
+        - name: Bar
-          id: stormpath
+          id: bar
-          groupId: com.stormpath.spring
+          ...
-          artifactId: stormpath-default-spring-boot-starter
           versionRange: "[1.5.0.RC1,2.0.0.M1)"
-          bom: stormpath-bom
 ----
 
-In this example Atomikos is available for Spring Boot 1.2.0 (or any milestone of 1.2.0) or
+In this example `Foo` is available for Spring Boot 1.2.0 (or any milestone of 1.2.0) or
-greater, and Stormpath is available for Spring Boot 1.5.0 up to, but not including 2.0.0.
+greater, and `Bar` is available for Spring Boot 1.5.0 up to, but not including 2.0.0.
 
 If different versions of your dependency work with different versions of Spring Boot,
-that's when you need the "mappings" property. A mapping is a combination of a `versionRange`
+that's when you need the `mappings` property. A mapping is a combination of a
-(for Spring Boot) and some or all of the other properties of the dependency, overriding
+`versionRange` and some or all of the other properties of the dependency, overriding
 the values defined at the top level. For example:
 
-[source,yml,subs="verbatim,attributes"]
+[source,yaml,indent=0]
 ----
 initializr:
   dependencies:
     - name: Stuff
       content:
-        - name: Cloud Task
+        - name: Foo
-          id: cloud-task
+          id: foo
-          groupId: org.springframework.cloud
+          groupId: org.acme.foo
-          artifactId: spring-cloud-starter-task
+          artifactId: foo-spring-boot-starter
           versionRange: 1.3.0.RELEASE
           bom: cloud-task-bom
           mappings:
             - versionRange: "[1.3.0.RELEASE,1.3.x.RELEASE]"
-              artifactId: spring-cloud-task-starter
+              artifactId: foo-starter
             - versionRange: "1.4.0.RELEASE"
 ----
 
-This dependency is available only for Spring Boot 1.3.0 and above, but up to 1.4.0
+In this example, The artifact of `foo` was changed to `foo-spring-boot-starter` as of the
-(i.e. for 1.3.x only) its `artifactId` was actually different.
+version that is compatible with Spring Boot 1.4. This mapping instruct that if Spring Boot
+1.3.x is selected, the artifact Id should be set to `foo-starter`.
 
 A mapping can also be applied to a BOM declaration. For example:
 
-[source,yml,subs="verbatim,attributes"]
+[source,yaml,indent=0]
 ----
 initializr:
   env:
@@ -611,46 +664,63 @@ In this example Spring Boot versions up to 1.1.6 select version 1.0.0 of the BOM
 a different repository. Spring Boot versions 1.2.1 and above select 2.0.0 of the BOM and
 yet another repository.
 
+
+
 [[howto-add-snapshot-repository]]
 === Configure a snapshot repository
-
 A dependency, or a BOM, might require the use of a specific repository, if the default one
 (usually Maven Central) does not contain the artifacts. Normally, the best place to
 declare that is in the BOM configuration, but if there isn't a BOM then you can put it in
 the dependency itself. You can also use a Spring Boot <<You can declare a
 repository,version mapping>> to override the default repository for a dependency or BOM.
 
+
+
 [[howto-dependency-starter-flag]]
 === Make sure a regular dependency brings the base starter
-
 If a dependency does not stand on its own (and specifically if it does not depend on an
-existing Spring Boot starter) you can flag it as "starter=false". When a project is
+existing Spring Boot starter) you can flag it as a "non starter":
-generated that only has dependencies with this flag set, then a Spring Boot starter is
+
-added as well (the vanilla `spring-boot-starter` or the `spring-boot-starter-web` if there
+[source,yaml,indent=0]
-is a dependency with the web facet).
+----
+initializr:
+  dependencies:
+    - name: Stuff
+      content:
+        - name: Lib
+          id: lib
+          groupId: com.acme
+          artifactId: lib
+          starter:false
+----
+
+When a project is generated that only has dependencies with this flag set, then the base
+Spring Boot starter is added as well.
+
+
 
 [[howto-group-share-settings]]
 === Share common dependency settings in a group
-
+A dependency group is a hint for user interface implementations, to group things together
-A dependency group is a hint for user interface implememtations, to group things together
 for users when they are selecting dependencies. It is also a convenient way to share
 settings between dependencies because every dependency inherits all the settings. The most
-common settings in a group are the group id, version range (for Spring Boot versions), and
+common settings in a group are the `groupId`, `versionRange` and `bom`:
-bom. Example:
 
-[source,yml,subs="verbatim,attributes"]
+[source,yaml,indent=0]
 ----
 initializr:
   dependencies:
     - name: Stuff
       bom: stuff-bom
-      versionRange: "[1.3.0.RELEASE,2.0.x)"
+      versionRange: "[1.3.0.RELEASE,2.0.0.M1)"
       content:
 ...
 ----
 
-These dependencies, by default, will be available only for Spring Boot versions 1.3 to
+These dependencies, by default, will be available only for Spring Boot versions 1.3 up to
-2.0, and will bring in a BOM already declared as "stuff-bom" in the `env` section.
+2.0 (excluded) and will bring in the `stuff-bom` BOM.
+
+
 
 [[create-instance-advanced-config]]
 == Advanced configuration

initializr-docs/src/main/asciidoc/documentation-overview.adoc

@@ -3,8 +3,8 @@
 
 [partintro]
 --
-This section provides a brief overview of Spring Initializr reference documentation. Think
+This section provides a brief overview of the Spring Initializr reference documentation:
-of it as map for the rest of the document. Some sections are targeted to a specific
+think of it as map for the rest of the document. Some sections are targeted to a specific
 audience so this reference guide is not meant to be read in a linear fashion.
 --
 
@@ -21,18 +21,17 @@ You can easily create your own instance of the Initializr, by using the jars as
 in your own app. There is minimal code involved and the service has a very rich
 configuration structure, allowing you to define not only the values of various project
 attributes but also the list of dependencies and the constraints to apply to them. If that
-sounds interesting, then the <<configuration-guide.adoc#configuration-guide>> section has
+sounds interesting, then <<configuration-guide.adoc#configuration-guide>> has all the
-all the details you need. You might only want to modify an existing instance of the
+details you need. You might only want to modify an existing instance of the Initializr,
-Initializr, e.g. to add a new dependency type, or update the version of an existing
+e.g. to add a new dependency type, or update the version of an existing
-one. For those and other simple and common use cases check out the
+one. For those and other simple and common use cases check out
-<<configuration-guide.adoc#configuration-howto>> section.
+<<configuration-guide.adoc#configuration-howto>>.
 
 The Initializr also provides an extensible API to generate quickstart projects, and to
 inspect the metadata used to generate projects, for instance to list the available
 dependencies and versions. The API can be used standalone or embedded in other tools
-(e.g. it is used in Spring Tool Suite, and in the IntelliJ and Netbeans plugins for Spring
+(e.g. it is used in Spring Tool Suite, and in the IntelliJ IDEA and Netbeans plugins for
-Boot). These features are covered in a separate <<api-guide.adoc#api-guide>> section of
+Spring Boot). These features are covered in <<api-guide.adoc#api-guide>>.
-this document.
 
 [[initializr-documentation-about]]
 == About the documentation

initializr-docs/src/main/asciidoc/user-guide.adoc

@@ -139,11 +139,23 @@ instance, the following URL changes the default to use Kotlin and Gradle:
 https://start.spring.io/#!language=kotlin&type=gradle-project
 ```
 
-TIP: `type` is the attribute of the first drop-down list where the type of project can
+The following attributes are supported:
-be selected and `gradle-project` is the id for the Gradle option. As you may guess,
-`maven-project` is the id of the default (Maven) option.
 
+* Programming language: `language` (`java`, `groovy` or `kotlin`)
+* Java version: `javaVersion` (`1.6`, `1.7`, `1.8`)
+* Project type: `type` (`maven-project`, `gradle-project`)
+* Packaging: `packaging` (`jar`, `war`)
+* Group: `groupId`
+* Artifact: `artifact`
+* Name: `name`
+* Description: `description`
+* Package Name: `packageName`
 
+TIP: The same default rules will apply if a property is overridden. For instance, if the
+Group is customized, it will automatically customize the root package as well.
+
+NOTE: The Spring Boot version and the list of dependencies cannot be customized that way
+as they evolve quite frequently.
 
 [[command-line]]
 == Command line support
@@ -152,7 +164,7 @@ available options of a particular instance, simply "curl it", i.e. if you have `
 installed invoke `curl start.spring.io` on the command-line (or alternatively
 `http start.spring.io` if you prefer to use `HTTPie`).
 
-This provides a textual representation of the capabilities of the service that are split
+The result is a textual representation of the capabilities of the service that are split
 in three sections:
 
 First, a table that describes the available project's types. On the default instance,
@@ -211,9 +223,10 @@ Spring Initializr is also integrated in all major Java IDEs and allows you to cr
 import a new project without having to leave the IDE for the command-line or the web UI.
 
 The following IDEs have dedicated support:
+
 * Eclipse/STS
 * IntelliJ IDEA (Ultimate Edition)
-* NetBeans (using the
+* NetBeans (using the http://plugins.netbeans.org/plugin/67888/nb-springboot[NB SpringBoot plugin])
 
 Refer to the documentation of your favorite IDE for more details.
 

initializr-docs/src/main/asciidoc/using-the-stubs.adoc

@@ -73,7 +73,7 @@ The wiremock fetaures come with Spring Cloud Contract Wiremock:
 			</dependency>
 		</dependencies>
 	</dependencyManagement>
----
+----
 
 === Using the Stub Runner
 
@@ -104,7 +104,7 @@ stubs declared as a dependency):
 			</dependency>
 		</dependencies>
 	</dependencyManagement>
----
+----
 
 
 [source,java,indent=0]