3 files changed, 68 insertions, 0 deletions
diff --git a/docs/markdown/Fs-module.md b/docs/markdown/Fs-module.md
index d4945e9..df9f305 100644
--- a/docs/markdown/Fs-module.md
+++ b/docs/markdown/Fs-module.md
@@ -199,3 +199,14 @@ suffix
 fs.stem('foo/bar/baz.dll')  # baz
 fs.stem('foo/bar/baz.dll.a')  # baz.dll
 ```
+
+### read
+- `read(path, encoding: 'utf-8')` *(since 0.57.0)*:
+   return a [string](Syntax.md#strings) with the contents of the given `path`.
+   If the `encoding` keyword argument is not specified, the file specified by
+   `path` is assumed to be utf-8 encoded. Binary files are not supported. The
+   provided paths should be relative to the current `meson.current_source_dir()`
+   or an absolute path outside the build directory is accepted. If the file
+   specified by `path` changes, this will trigger Meson to reconfigure the
+   project. If the file specified by `path` is a `files()` object it
+   cannot refer to a built file.
diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md
index f05f3e8..8c8c0c0 100644
--- a/docs/markdown/howtox.md
+++ b/docs/markdown/howtox.md
@@ -139,6 +139,23 @@ cdata.set('SOMETHING', txt)
 configure_file(...)
 ```
 
+## Generate configuration data from files
+
+`The [fs module](#Fs-modules) offers the `read` function` which enables adding
+the contents of arbitrary files to configuration data (among other uses):
+
+```meson
+fs = import('fs')
+cdata = configuration_data()
+copyright = fs.read('LICENSE')
+cdata.set('COPYRIGHT', copyright)
+if build_machine.system() == 'linux'
+    os_release = fs.read('/etc/os-release')
+    cdata.set('LINUX_BUILDER', os_release)
+endif
+configure_file(...)
+```
+
 ## Generate a runnable script with `configure_file`
 
 `configure_file` preserves metadata so if your template file has
diff --git a/docs/markdown/snippets/fs_read.md b/docs/markdown/snippets/fs_read.md
new file mode 100644
index 0000000..05c215a
--- /dev/null
+++ b/docs/markdown/snippets/fs_read.md
@@ -0,0 +1,40 @@
+## Support for reading files at configuration time with the `fs` module
+
+Reading text files during configuration is now supported. This can be done at
+any time after `project` has been called
+
+```meson
+project(myproject', 'c')
+license_text = run_command(
+    find_program('python3'), '-c', 'print(open("COPYING").read())'
+).stdout().strip()
+about_header = configuration_data()
+about_header.add('COPYRIGHT', license_text)
+about_header.add('ABOUT_STRING', meson.project_name())
+...
+```
+
+There are several problems with the above approach:
+1. It's ugly and confusing
+2. If `COPYING` changes after configuration, Meson won't correctly rebuild when
+   configuration data is based on the data in COPYING
+3. It has extra overhead
+
+`fs.read` replaces the above idiom thus:
+```meson
+project(myproject', 'c')
+fs = import('fs')
+license_text = fs.read('COPYING').strip()
+about_header = configuration_data()
+about_header.add('COPYRIGHT', license_text)
+about_header.add('ABOUT_STRING', meson.project_name())
+...
+```
+
+They are not equivalent, though. Files read with `fs.read` create a
+configuration dependency on the file, and so if the `COPYING` file is modified,
+Meson will automatically reconfigure, guaranteeing the build is consistent. It
+can be used for any properly encoded text files. It supports specification of
+non utf-8 encodings too, so if you're stuck with text files in a different
+encoding, it can be passed as an argument. See the [`meson`
+object](Reference-manual.md#meson-object) documentation for details.