Docs: Improve docs for -library instruction (add examples)

Here is a suggested for improving the -library instruction. I have heard it being mentioned a couple of times. But I think the current documentation is missing some examples to illustrate the usefulness (as in "what can I do with it, and when would I use it"?)

Signed-off-by: Christoph Rueger <[email protected]>


Signed-off-by: Christoph Rueger <[email protected]>

Author: chrisrueger

docs/_instructions/library.md

@@ -5,6 +5,69 @@ title: -library library ( ',' library )*
 summary: Apply a bnd library to the workspace, project, or bndrun file
 ---
 
+The main reason for the `-library` instruction is to let you package and share *bnd-related configuration* in a self-contained way so it can be reused across workspaces, projects, or run descriptions.
+
+Let's use some examples for explanation.
+
+## Example 1) Common bnd Configuration Across Multiple Projects
+
+### Scenario
+
+You have many projects that all need the same baseline OSGi or bnd settings—like default macros, a specific build plugin, or a certain analyzer configuration (e.g., “treat warnings as errors,” “export packages in a particular way,” etc.).
+
+### How a Library Helps
+
+1. Put these shared bnd instructions (i.e., the macros and plugin setups) in `project.bnd` (or `workspace.bnd`/`bndrun.bnd`) inside a “library bundle” in your repo.  
+2. In each project that wants these settings, just add:
+   ```
+   -library myconfig
+   ```
+3. All the macros and plugin instructions from that library will be included.  
+
+This avoids copying the same lines into each `bnd.bnd`. Instead, every project references the same library, ensuring consistency.
+
+
+## Example 2) Including Pre-Configured Tooling/Plugins
+
+### Scenario
+You have a plugin (e.g., for code generation) that always needs a certain set of properties to work properly—maybe a specific source folder or some environment variables.
+
+### How a Library Helps
+1. Provide a bundle that *contains* the plugin (or references it) plus a `bnd` file with the plugin’s configuration.  
+2. Other projects include that library:
+   ```
+   -library codegen
+   ```
+3. Now each project automatically has the plugin in its build plus the right plugin settings (class paths, macros, etc.).  
+
+This is particularly nice if you have multiple plugins or complex plugin settings that you do not want to replicate.
+
+
+## Creating a library
+
+A _library_ is stored in a _bundle_. A bundle can contain multiple libraries that are each described by a
+capability in the `bnd.library` name space. This capability looks like:
+
+    Provide-Capability: \
+        bnd.library; \
+            bnd.library     = foo; \
+            version         = 1.2.3; \
+            path           = lib/foo 
+
+The following attributes are defined for the `bnd.library` capabilities:
+
+* `bnd.library` – The name of the library. Names should be kept simple but the names are shared between all libraries. 
+* `version` – The version of the library.
+* `path` – A path to a directory in the bundle. The contents of this directory are the root of the library. This root
+  is copied to the workspace cache.
+
+The root of the library should contain the bnd files to be included. The defaults (`workspace.bnd`, `project.bnd`, and 
+`bndrun.bnd`) should only be there if it makes sense to include the library in that type.
+
+
+
+## Using a library
+
 A library can provide additional _named_ functionality to a workspace, a project, or a bndrun file. It does this by
 including a `bnd` file in the setup that originates from a bundle in the repositories. This included bnd file
 can refer and use any binary resources in this bundle.   Bundles can contain multiple libraries.
@@ -55,24 +118,3 @@ Projects and bndrun files can include libraries but they cannot define any new r
 
 NOTE: what about standalone bndruns? 
 
-## Creating a library
-
-A _library_ is stored in a _bundle_. A bundle can contain multiple libraries that are each described by a
-capability in the `bnd.library` name space. This capability looks like:
-
-    Provide-Capability: \
-        bnd.library; \
-            bnd.library     = foo; \
-            version         = 1.2.3; \
-            path           = lib/foo 
-
-The following attributes are defined for the `bnd.library` capabilities:
-
-* `bnd.library` – The name of the library. Names should be kept simple but the names are shared between all libraries. 
-* `version` – The version of the library.
-* `path` – A path to a directory in the bundle. The contents of this directory are the root of the library. This root
-  is copied to the workspace cache.
-
-The root of the library should contain the bnd files to be included. The defaults (`workspace.bnd`, `project.bnd`, and 
-`bndrun.bnd`) should only be there if it makes sense to include the library in that type.
-