[latex3-commits] [git/l3build] sourcedir: example readme's (78dee00)

[Will Robertson]

Repository : https://github.com/latex3/l3build
On branch  : sourcedir
Link       : https://github.com/latex3/l3build/commit/78dee00df1536b64c21e31f72e8fc090d2aed544

>---------------------------------------------------------------

commit 78dee00df1536b64c21e31f72e8fc090d2aed544
Author: Will Robertson <will at wspr.io>
Date:   Mon Dec 11 23:03:35 2017 +1030

    example readme's


>---------------------------------------------------------------

78dee00df1536b64c21e31f72e8fc090d2aed544
 examples/Bundle-Flat/README.md |   15 +++++++++++++++
 examples/Bundle-Tree/README.md |   15 +++++++++++++++
 examples/README.md             |    6 ++++--
 examples/Simple-Flat/README.md |   16 ++++++++++++++++
 examples/Simple-Tree/README.md |   15 +++++++++++++++
 5 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/examples/Bundle-Flat/README.md b/examples/Bundle-Flat/README.md
new file mode 100644
index 0000000..ce82506
--- /dev/null
+++ b/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.
diff --git a/examples/Bundle-Tree/README.md b/examples/Bundle-Tree/README.md
new file mode 100644
index 0000000..9d81b52
--- /dev/null
+++ b/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.
diff --git a/examples/README.md b/examples/README.md
index 654c334..4c7284e 100644
--- a/examples/README.md
+++ b/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 |
 
 
 -----
diff --git a/examples/Simple-Flat/README.md b/examples/Simple-Flat/README.md
new file mode 100644
index 0000000..56eecba
--- /dev/null
+++ b/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.
diff --git a/examples/Simple-Tree/README.md b/examples/Simple-Tree/README.md
new file mode 100644
index 0000000..f7b430d
--- /dev/null
+++ b/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.