Merge pull request bndtools#6162 from chrisrueger/fix-template-fragme…

…nts-link

Fix template fragments link and tweak docu

docs/_chapters/150-build.md

@@ -22,7 +22,7 @@ of the workspace. They can have the following extensions:
 * `.pmvn` – An index file for a [Maven Bnd Repository](plugins/maven.html). The first lines can contain properties for this plugin in the format of `# key = value`, e.g. `# name = OSGi R8`. 
 * `.pobr` – An OSGi Repository file in XML.
 
-The `ext` directory is a convenient way to add add reusable components. See [template fragments](620-template-fragments.html] how they can be used to manage workspaces. When files change in this directory the workspace will be reloaded.
+The `ext` directory is a convenient way to add add reusable components. See [template fragments](620-template-fragments.html) how they can be used to manage workspaces. When files change in this directory the workspace will be reloaded.
 
 To cache some intermediate files, bndlib will create a `cnf/cache/` directory, this file should not be under source control. E.g. in Git it should be defined in the `.gitignore` file. 
 

docs/_chapters/600-developer.md

@@ -4,7 +4,6 @@ layout: default
 ---
 
 
-
 ## API
 It is quite easy to use bnd from Java, you only need to include biz.aQute.bndlib on your class path. This chapter shows you some samples of how to use bndlib.
 
@@ -66,3 +65,9 @@ If no such resource is found, bnd will look in the -make instruction. This instr
 The first name part of the clause is matched against the unfound resource. All plugins are called sequentially until one returns non-null. The arguments on the -make clause are given as parameters to the make plugin. Normally all Make Plugins should verify the type field.
 
 bnd has a bnd and a copy Make Plugin.
+
+
+## Workspace Template Fragments
+
+If, for example, you created a library for bnd and want to make it easy for the user to setup his functionality have a look at [template fragments](620-template-fragments.html).
+

docs/_chapters/620-template-fragments.md

@@ -5,25 +5,33 @@ layout: default
 
 A good workspace setup makes all the difference in the development cycle. Since a workspace can
 contain many projects, creating new workspaces is relatively rare. However, a workspace tends
-to consist of many aspects. There is the gradle setup, the OSGi release, maybe the maven
-layout etc. Initially, we attempted to use a single GitHub repository as a template for new workspaces, but this approach quickly became complex. 
-Instead, we developed _fragment_ templates. Fragments model one aspect of a workspace and are maintained in Github 
-repositories. One repository can hold many fragments.
+to consist of many aspects. There is the _gradle setup_, the _OSGi release_, maybe the _maven
+layout_ etc. Initially, we attempted to use a single GitHub repository as a template for new workspaces, but this approach quickly became complex.
 
 For example, if someone created a [library][3] for bnd, to make it easy for the
 user to setup his functionality, the author of the library had to maintain a full workspace 
 with gradle, etc. This put the burden on chasing the OSGi release, the gradle releases, on the
 people that were willing to spread the gospel around OSGi/bndtools.
 
-The workspace is already prepared for this model of fragments. The [merged instructions][2] mean that 
+
+## Template Fragments
+
+Instead, we developed _fragment_ templates. A fragment models one aspect of a workspace and is maintained in Github repository, but one repository can hold many fragments. Multiple template fragments can be combined by the end-user to enrich the workspace with various aspects.
+During workspace creation there is a wizard where one can select template fragments via checkboxes.
+
+<img src="{{'img/template-fragments.png'}}" width="100%">
+
+The [workspace](/chapters/123-tour-workspace.html) is already prepared for this model of fragments. The [merged instructions][2] mean that 
 we can extend the properties and instructions from many different sources. However, the most important
 feature here is the `cnf/ext` folder. Any `bnd` or special fragment file placed in this folder will automatically
 be ready before the `build.bnd` file is read. For example, a fragment could contain the 
 index for OSGi R8. See [build](150-build.html).
 
+## Providing template fragments as a developer
+
 There is a single master index for all template fragments hosted on
 
-    https://github.com/bndtools/workspace-templates/blob/master/index.bnd
+[https://github.com/bndtools/workspace-templates/blob/master/index.bnd](https://github.com/bndtools/workspace-templates/blob/master/index.bnd)
 
 This index is open for any person or organization that maintains one or more fragment and
 seeks an easy way to make them available to bndtools users. All that is needed is to host the fragment somewhere and provide 
@@ -33,7 +41,7 @@ The format of the index file is like all Parameters.
 
 * `key` – The key is the identity of the fragment. It is either a URL or provides the following structure:
 
-    id ::= [organization ['/' repository [ '/' path ] ['#' git-ref ]]
+    `id ::= [organization ['/' repository [ '/' path ] ['#' git-ref ]]`
 
 The id is resolved against `bndtools/workspace-templates#master`. Therefore, in the `example` organization,
 the `example` is a valid id that resolves to `example/workspace-templates#master`. Since the ID has a path, 
@@ -46,7 +54,9 @@ The index has the following attributes for a clause:
 * `require` – A comma separated list of fragment ids. Do not forget to quote when multiple fragments are required
 * `tag` – A comma separated list of tags, quotes are needed when there are multiple.
 
-For example:
+## Example
+
+For example consider this `index.bnd`:
 
     -workspace-templates \
         bndtools/workspace-templates/gradle; \

docs/_data/sidebar.yml

@@ -44,6 +44,7 @@ nav:
       - url: /chapters/395-generating-documentation.html
       - url: /chapters/400-commands.html
       - url: /chapters/600-developer.html
+      - url: /chapters/620-template-fragments.html
       - url: /chapters/650-windows.html
       - url: /chapters/700-tools.html
   - title: Reference Material