Docs

---
 Signed-off-by: Peter Kriens <[email protected]>

Signed-off-by: Peter Kriens <[email protected]>

docs/_chapters/110-introduction.md

@@ -7,7 +7,7 @@ OSGi is arguably one of the best specifications in the Java world. It is a no co
 
 For some, the previous paragraph may come as a surprise because OSGi has had its share of people complaining about it. Surprisingly, the biggest complaint is often the Class Not Found Exception, which is always a perfect sign that people try to push a round peg in a too small square hole, and with all their might. You only see those exceptions when you're not doing engineering but when you are hacking. If you run head on into the walls that OSGi installs and it is giving you a headache, then just look around and find the elegant and easy to use doors: services.
 
-Though this is all true, I do not claim that OSGi is trivial to use; triviality has a way to clash with large system that must evolve over many years. The software profession has a brutal industry that lures us with the siren song of a 'few hours work' to devour us while trying to main gigantic hairballs. As Fred Brooks already said so many years ago in his seminal book 'The Mythical Man Month', there is no silver bullet. Even OSGi will require hard work to build evolvable systems. And though we cannot make building complex systems easy, bnd can at least make it easier (and considerably more fun).
+Though this is all true, I do not claim that OSGi is trivial to use; triviality has a way to clash with large system that must evolve over many years. The software profession is a brutal industry that lures us with the siren song of a 'few hours work' to devour us while trying to make gigantic hairballs. As Fred Brooks already said so many years ago in his seminal book 'The Mythical Man Month', there is no silver bullet. Even OSGi will require hard work to build evolvable systems. And though we cannot make building complex systems easy, bnd can at least make it easier (and considerably more fun).
 
 ## A Bit of History
 

docs/_chapters/150-build.md

@@ -15,7 +15,14 @@ A bndlib workspace is a _valid_ workspace when it contains a `cnf` file. If this
 
 However, the advised model is to use a directory with a `cnf/build.bnd` file. The purpose of the `cnf` directory is to provide a place for shared information. Though this includes bndlib setup information, it also can be used to define for example shared licensing, copyright, and vendor headers for your organization.
 
-The `cnf` directory can have an `ext` directory, this directory contains any extensions to bnd.
+The `cnf` directory can have an `ext` directory. Files in this directory are added to the properties
+of the workspace. They can have the following extensions:
+
+* `.bnd` – Contain bnd properties
+* `.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.
 
 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/620-template-fragments.md

@@ -0,0 +1,89 @@
+---
+title: Templates for Workspaces
+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.
+
+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 
+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).
+
+There is a single master index for all template fragments hosted on
+
+    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 
+a pull request (PR) to add it to this index file.
+
+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 ]]
+
+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, 
+it is possible to host multiple fragments in a single repository.
+
+The index has the following attributes for a clause:
+
+* `name` – The human readable name for the template fragment
+* `description` – A human readable description for the template fragment
+* `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:
+
+    -workspace-templates \
+        bndtools/workspace-templates/gradle; \
+            name=gradle; \
+            description="Setup gradle build for bnd workspace", \
+        bndtools/workspace-templates/maven; \
+            name=maven; \
+            description="Use the maven directory layout for sources and binaries", \
+        bndtools/workspace-templates/osgi; \
+            name=osgi; \
+            description="OSGi R8 with Felix distribution"
+
+
+The id must resolve to a folder in the repository. By default, bnd will recursively copy the
+content to the new workspace. However, if there is a file `tool.bnd` present it will use this to
+guide the copying process. This bnd file looks like:
+
+    -tool \
+        .*;tool.bnd;readme.md;skip=true, \
+        gradle.properties;macro=true;append=true,\
+        gradlew;exec=true, \
+        *
+
+The `-tool` instruction is a SELECT that is matched against the file paths (not names!) in the fragment template folder.
+The attributes that can be set are:
+
+* `skip=true` – Skip the selected file,
+* `append=true` – Allow duplicates, append
+* `exec=true` – Set the execute bit on non-windows systems
+* `preprocess=true` – Preprocess the file (this uses the tool file and the current workspace as domain.
+* `delete=true` – Deletes an existing file in the target. Cannot be wildcarded
+
+It is possible to define the [`-workspace-templates`][4] instruction in the `build.bnd` file.
+It must contain the same format as the index. This local index is merged with the main index. In the
+Bndtools GUI, it is possible to add an additional index from a URL or file.
+
+
+[2]: https://bnd.bndtools.org/releases/3.5.0/chapters/820-instructions.html#merged-instructions
+[3]: https://bnd.bndtools.org/instructions/library.html
+[4]: /instructions/workspace-templates.html

docs/_instructions/workspace-templates.md

@@ -0,0 +1,8 @@
+---
+layout: default
+class: Workspace
+title: -workspace-templates
+summary:  Define workspace templates for a new workspace
+---
+
+See [workspace templates](/chapters/620-template-fragments.html)