6 files changed, 20 insertions, 18 deletions
diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md
index 1aa444a..66d090d 100644
--- a/docs/markdown/Installing.md
+++ b/docs/markdown/Installing.md
@@ -27,7 +27,8 @@ Other install commands are the following.
 ```meson
 install_headers('header.h', subdir : 'projname') # -> include/projname/header.h
 install_man('foo.1') # -> share/man/man1/foo.1
-install_data('datafile.dat', install_dir : join_paths(get_option('datadir'), 'progname')) # -> share/progname/datafile.dat
+install_data('datafile.dat', install_dir : get_option('datadir') / 'progname')
+# -> share/progname/datafile.dat
 ```
 
 `install_data()` supports rename of the file *since 0.46.0*.
diff --git a/docs/markdown/Porting-from-autotools.md b/docs/markdown/Porting-from-autotools.md
index b60ecfe..2170ffa 100644
--- a/docs/markdown/Porting-from-autotools.md
+++ b/docs/markdown/Porting-from-autotools.md
@@ -608,7 +608,7 @@ gsettings_SCHEMAS = foo.gschema.xml
 
 `meson.build`:
 ```meson
-install_data('foo.gschema.xml', install_dir: join_paths(get_option('datadir'), 'glib-2.0', 'schemas'))
+install_data('foo.gschema.xml', install_dir: get_option('datadir') / 'glib-2.0' / 'schemas')
 meson.add_install_script('meson_post_install.py')
 ```
 
@@ -668,7 +668,7 @@ i18n.merge_file(
   type: 'desktop',
   po_dir: 'po',
   install: true,
-  install_dir: join_paths(get_option('datadir'), 'applications')
+  install_dir: get_option('datadir') / 'applications'
 )
 
 i18n.merge_file(
@@ -676,7 +676,7 @@ i18n.merge_file(
   output: 'foo.appdata.xml',
   po_dir: 'po',
   install: true,
-  install_dir: join_paths(get_option('datadir'), 'appdata')
+  install_dir: get_option('datadir') / 'appdata'
 )
 ```
 
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 477790b..9484c28 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -568,7 +568,7 @@ be passed to [shared and static libraries](#library).
 - `install_dir` override install directory for this file. The value is
   relative to the `prefix` specified. F.ex, if you want to install
   plugins into a subdir, you'd use something like this: `install_dir :
-  join_paths(get_option('libdir'), 'projectname-1.0'`).
+  get_option('libdir') / 'projectname-1.0'`.
 - `install_mode` *(added 0.47.0)* specify the file mode in symbolic format
   and optionally the owner/uid and group/gid for the installed files.
 - `install_rpath` a string to set the target's rpath to after install
@@ -780,8 +780,7 @@ The only exceptions are: `sysconfdir`, `localstatedir`, and
 configuration as-is, which may be absolute, or relative to `prefix`.
 [`install_dir` arguments](Installing.md) handles that as expected, but
 if you need the absolute path to one of these e.g. to use in a define
-etc., you should use `join_paths(get_option('prefix'),
-get_option('localstatedir'))`
+etc., you should use `get_option('prefix') / get_option('localstatedir')`
 
 For options of type `feature` a special object is returned instead of
 a string.  See [`feature` options](Build-options.md#features)
diff --git a/docs/markdown/Release-notes-for-0.49.0.md b/docs/markdown/Release-notes-for-0.49.0.md
index 9889a39..9a5e5f5 100644
--- a/docs/markdown/Release-notes-for-0.49.0.md
+++ b/docs/markdown/Release-notes-for-0.49.0.md
@@ -234,16 +234,18 @@ endif
 
 ## Joining paths with /
 
-Joining two paths has traditionally been done with the `join_paths` function.
+For clarity and conciseness, we recommend using the `/` operator to separate
+path elements:
 
 ```meson
-joined = join_paths('foo', 'bar')
+joined = 'foo' / 'bar'
 ```
 
-Now you can use the simpler notation using the `/` operator.
+Before Meson 0.49, joining path elements was done with the legacy `join_paths`
+function, but the `/` syntax above is now recommended.
 
 ```meson
-joined = 'foo' / 'bar'
+joined = join_paths('foo', 'bar')
 ```
 
 This only works for strings.
diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md
index aadb14a..7802b92 100644
--- a/docs/markdown/Syntax.md
+++ b/docs/markdown/Syntax.md
@@ -214,12 +214,12 @@ pathsep = ':'
 path = pathsep.join(['/usr/bin', '/bin', '/usr/local/bin'])
 # path now has the value '/usr/bin:/bin:/usr/local/bin'
 
-# For joining paths, you should use join_paths()
+# For joining path elements, you should use path1 / path2
 # This has the advantage of being cross-platform
-path = join_paths(['/usr', 'local', 'bin'])
+path = '/usr' / 'local' / 'bin'
 # path now has the value '/usr/local/bin'
 
-# Don't use join_paths for sources files, use files for that:
+# For sources files, use files():
 my_sources = files('foo.c')
 ...
 my_sources += files('bar.c')
diff --git a/docs/markdown/Vala.md b/docs/markdown/Vala.md
index 9e95851..3550fa1 100644
--- a/docs/markdown/Vala.md
+++ b/docs/markdown/Vala.md
@@ -148,7 +148,7 @@ function:
 ```meson
 project('vala app', 'vala', 'c')
 
-vapi_dir = join_paths(meson.current_source_dir(), 'vapi')
+vapi_dir = meson.current_source_dir() / 'vapi'
 
 add_project_arguments(['--vapidir', vapi_dir], language: 'vala')
 
@@ -229,7 +229,7 @@ file and the VAPI is in the `vapi` directory of your project source files:
 ```meson
 project('vala app', 'vala', 'c')
 
-vapi_dir = join_paths(meson.current_source_dir(), 'vapi')
+vapi_dir = meson.current_source_dir() / 'vapi'
 
 add_project_arguments(['--vapidir', vapi_dir], language: 'vala')
 
@@ -309,9 +309,9 @@ program and a dependency on the library:
 ```meson
 g_ir_compiler = find_program('g-ir-compiler')
 custom_target('foo typelib', command: [g_ir_compiler, '--output', '@OUTPUT@', '@INPUT@'],
-              input: join_paths(meson.current_build_dir(), 'Foo-1.0.gir'),
+              input: meson.current_build_dir() / 'Foo-1.0.gir',
               output: 'Foo-1.0.typelib',
               depends: foo_lib,
               install: true,
-              install_dir: join_paths(get_option('libdir'), 'girepository-1.0'))
+              install_dir: get_option('libdir') / 'girepository-1.0')
 ```