example readme's

examples/Bundle-Flat/README.md

@@ -0,0 +1,15 @@
+L3BUILD `bundle-flat` example
+=================================================
+
+This example demonstrates a bundle of two modules, with each module arranged in a ‘flat’
+structure. There is nothing noteworthy about the modules themselves; they are based on the
+`simple-flat` example.
+
+Note the importance of the nested `build.lua` scripts, especially the setting of `maindir`
+in the build script for each module.
+
+-----
+
+Copyright (C) 2014-2017 The LaTeX3 Project <br />
+<http://latex-project.org/> <br />
+All rights reserved.

examples/Bundle-Tree/README.md

@@ -0,0 +1,15 @@
+L3BUILD `bundle-tree` example
+=================================================
+
+This example demonstrates a bundle of two modules, with each module arranged in a ‘tree’
+structure. There is nothing noteworthy about the modules themselves; they are based on the
+`simple-tree` example.
+
+Note the importance of the nested `build.lua` scripts, especially the setting of `maindir`
+in the build script for each module.
+
+-----
+
+Copyright (C) 2014-2017 The LaTeX3 Project <br />
+<http://latex-project.org/> <br />
+All rights reserved.

examples/README.md

@@ -11,8 +11,10 @@ The examples are:
 
 | Example                 | Description                                    |
 | ---                     | ---                                            |
-| `Simple-Flat`           | Demonstrates a simple package in a flat layout |
-| `Simple-Tree`           | Demonstrates a simple package in a tree layout |
+| `Simple-Flat`           | A simple package in a flat layout |
+| `Simple-Tree`           | A simple package in a tree layout |
+| `Bundle-Flat`           | A bundle with two modules in a flat layout |
+| `Bundle-Tree`           | A bundle with two modules in a tree layout |
 
 
 -----

examples/Simple-Flat/README.md

@@ -0,0 +1,16 @@
+L3BUILD `simple-flat` example
+=================================================
+
+This is a good example demonstrating a generic use case for a simple package using `l3build`.
+
+This package is set up to produce two PDF files: one including the user documentation for the package, and the second, with ‘`-code`’ suffix, which includes both the user documentation and the typeset package code.
+Note that these are produced by the two `.tex` files, which simply set typesetting options and read in the `.dtx` docstrip file so only one source file needs to be maintained.
+
+A variety of alternative docstrip arrangements can be set up to similar effect; the arrangement here is chosen for simplicity.
+As the `.dtx` package file grows larger, it may be sensible to split it up into multiple files, including separating the user documentation from the code itself.
+
+-----
+
+Copyright (C) 2014-2017 The LaTeX3 Project <br />
+<http://latex-project.org/> <br />
+All rights reserved.

examples/Simple-Tree/README.md

@@ -0,0 +1,15 @@
+L3BUILD `simple-tree` example
+=================================================
+
+This is a simple example demonstrating a more complex package using `l3build`.
+Here, the code files are located in a `code/` subdirectory, and documentation files in `doc/`.
+
+In this simple case, the code and documentation consist of only one file each, which hardly seems necessary to subdivide.
+But as a package becomes larger it makes more sense to break the `.dtx` file into independent parts of the code, and the documentation can be broken itself into parts and chapters.
+This is left as an exercise to the energetic package writer studying these examples.
+
+-----
+
+Copyright (C) 2014-2017 The LaTeX3 Project <br />
+<http://latex-project.org/> <br />
+All rights reserved.