install_man locale support

Rather than having to manually build the locale aware man paths with

`install_data('foo.fr.1', install_dir: join_paths(get_option('mandir'), 'fr', 'man1'), rename: 'foo.1')`

Support doing

`install_man('foo.fr.1', locale: 'fr')`

9 files changed, 39 insertions, 6 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 4c30ddd..e299be8 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1133,6 +1133,11 @@ Accepts the following keywords:
   format and optionally the owner/uid and group/gid for the installed files.
   An example value could be `['rwxr-sr-x', 'root', 'root']`.
 
+- `locale` *(since 0.58.0)*: can be used to specify the locale into which the
+  man page will be installed within the manual page directory tree.
+  An example manual might be `foo.fr.1` with a locale of `fr`, such
+  that `{mandir}/{locale}/man{num}/foo.1` becomes the installed file.
+
 *(since 0.49.0)* [manpages are no longer compressed
  implicitly][install_man_49].
 
diff --git a/docs/markdown/snippets/install_man_locale.md b/docs/markdown/snippets/install_man_locale.md
new file mode 100644
index 0000000..76b7967
--- /dev/null
+++ b/docs/markdown/snippets/install_man_locale.md
@@ -0,0 +1,9 @@
+## Specify man page locale during installation
+
+Locale directories can now be passed to `install_man`:
+    
+```meson
+# instead of
+# install_data('foo.fr.1', install_dir: join_paths(get_option('mandir'), 'fr', 'man1'), rename: 'foo.1')`
+install_man('foo.fr.1', locale: 'fr')
+```
diff --git a/mesonbuild/backend/backends.py b/mesonbuild/backend/backends.py
index 8fe9189..9ac02d0 100644
--- a/mesonbuild/backend/backends.py
+++ b/mesonbuild/backend/backends.py
@@ -1399,9 +1399,15 @@ class Backend:
                 num = f.split('.')[-1]
                 subdir = m.get_custom_install_dir()
                 if subdir is None:
-                    subdir = os.path.join(manroot, 'man' + num)
+                    if m.locale:
+                        subdir = os.path.join(manroot, m.locale, 'man' + num)
+                    else:
+                        subdir = os.path.join(manroot, 'man' + num)
+                fname = f.fname
+                if m.locale: # strip locale from file name
+                    fname = fname.replace(f'.{m.locale}', '')
                 srcabs = f.absolute_path(self.environment.get_source_dir(), self.environment.get_build_dir())
-                dstabs = os.path.join(subdir, os.path.basename(f.fname))
+                dstabs = os.path.join(subdir, os.path.basename(fname))
                 i = InstallDataBase(srcabs, dstabs, m.get_custom_install_mode(), m.subproject)
                 d.man.append(i)
 
diff --git a/mesonbuild/build.py b/mesonbuild/build.py
index b6ded5e..8dc56c1 100644
--- a/mesonbuild/build.py
+++ b/mesonbuild/build.py
@@ -157,11 +157,13 @@ class Headers:
 class Man:
 
     def __init__(self, sources: T.List[File], install_dir: T.Optional[str],
-                 install_mode: T.Optional['FileMode'], subproject: str):
+                 install_mode: T.Optional['FileMode'], subproject: str,
+                 locale: T.Optional[str]):
         self.sources = sources
         self.custom_install_dir = install_dir
         self.custom_install_mode = install_mode
         self.subproject = subproject
+        self.locale = locale
 
     def get_custom_install_dir(self) -> T.Optional[str]:
         return self.custom_install_dir
diff --git a/mesonbuild/interpreter.py b/mesonbuild/interpreter.py
index 0225de4..5642242 100644
--- a/mesonbuild/interpreter.py
+++ b/mesonbuild/interpreter.py
@@ -778,6 +778,9 @@ class ManHolder(InterpreterObject, ObjectHolder[build.Man]):
     def get_custom_install_mode(self) -> T.Optional[FileMode]:
         return self.held_object.custom_install_mode
 
+    def locale(self) -> T.Optional[str]:
+        return self.held_object.locale
+
     def get_sources(self) -> T.List[mesonlib.File]:
         return self.held_object.sources
 
@@ -2371,7 +2374,7 @@ permitted_kwargs = {'add_global_arguments': {'language', 'native'},
                     'include_directories': {'is_system'},
                     'install_data': {'install_dir', 'install_mode', 'rename', 'sources'},
                     'install_headers': {'install_dir', 'install_mode', 'subdir'},
-                    'install_man': {'install_dir', 'install_mode'},
+                    'install_man': {'install_dir', 'install_mode', 'locale'},
                     'install_subdir': {'exclude_files', 'exclude_directories', 'install_dir', 'install_mode', 'strip_directory'},
                     'jar': build.known_jar_kwargs,
                     'project': {'version', 'meson_version', 'default_options', 'license', 'subproject_dir'},
@@ -4225,6 +4228,7 @@ This will become a hard error in the future.''' % kwargs['input'], location=self
         return HeadersHolder(h)
 
     @FeatureNewKwargs('install_man', '0.47.0', ['install_mode'])
+    @FeatureNewKwargs('install_man', '0.58.0', ['locale'])
     @permittedKwargs(permitted_kwargs['install_man'])
     def func_install_man(self, node, args, kwargs):
         sources = self.source_strings_to_files(args)
@@ -4237,10 +4241,11 @@ This will become a hard error in the future.''' % kwargs['input'], location=self
                 raise InvalidArguments('Man file must have a file extension of a number between 1 and 8')
         custom_install_mode = self._get_kwarg_install_mode(kwargs)
         custom_install_dir = kwargs.get('install_dir', None)
+        locale = kwargs.get('locale')
         if custom_install_dir is not None and not isinstance(custom_install_dir, str):
             raise InterpreterException('install_dir must be a string.')
 
-        m = build.Man(sources, custom_install_dir, custom_install_mode, self.subproject)
+        m = build.Man(sources, custom_install_dir, custom_install_mode, self.subproject, locale)
         self.build.man.append(m)
 
         return ManHolder(m)
diff --git a/mesonbuild/modules/rpm.py b/mesonbuild/modules/rpm.py
index 073e338..9612837 100644
--- a/mesonbuild/modules/rpm.py
+++ b/mesonbuild/modules/rpm.py
@@ -65,7 +65,10 @@ class RPMModule(ExtensionModule):
                     files_devel.add('%%{_includedir}/%s' % hdr_src)
         for man in coredata.man:
             for man_file in man.get_sources():
-                files.add('%%{_mandir}/man%u/%s.*' % (int(man_file.split('.')[-1]), man_file))
+                if man.locale:
+                    files.add('%%{_mandir}/%s/man%u/%s.*' % (man.locale, int(man_file.split('.')[-1]), man_file))
+                else:
+                    files.add('%%{_mandir}/man%u/%s.*' % (int(man_file.split('.')[-1]), man_file))
         if files_devel:
             devel_subpkg = True
 
diff --git a/test cases/common/10 man install/foo.fr.1 b/test cases/common/10 man install/foo.fr.1
new file mode 100644
index 0000000..647c097
--- /dev/null
+++ b/test cases/common/10 man install/foo.fr.1
@@ -0,0 +1 @@
+this is a man page of foo.1 its contents are irrelevant
diff --git a/test cases/common/10 man install/meson.build b/test cases/common/10 man install/meson.build
index 8262ffc..05c5278 100644
--- a/test cases/common/10 man install/meson.build
+++ b/test cases/common/10 man install/meson.build
@@ -1,6 +1,7 @@
 project('man install', 'c')
 m1 = install_man('foo.1')
 m2 = install_man('bar.2')
+m3 = install_man('foo.fr.1', locale: 'fr')
 install_man('vanishing/vanishing.2')
 subdir('vanishing')
 
diff --git a/test cases/common/10 man install/test.json b/test cases/common/10 man install/test.json
index cdcc81f..5ef673a 100644
--- a/test cases/common/10 man install/test.json
+++ b/test cases/common/10 man install/test.json
@@ -1,6 +1,7 @@
 {
   "installed": [
     { "type": "file", "file": "usr/share/man/man1/foo.1"       },
+    { "type": "file", "file": "usr/share/man/fr/man1/foo.1"    },
     { "type": "file", "file": "usr/share/man/man2/bar.2"       },
     { "type": "file", "file": "usr/share/man/man1/vanishing.1" },
     { "type": "file", "file": "usr/share/man/man2/vanishing.2" },