build(meson): generate and install scdoc manpages

man/meson.build

@@ -0,0 +1,22 @@
+manpages = {
+  'pc': 5,
+  'pkgconf': 1
+}
+
+foreach page, section : manpages
+  name = '@0@.@1@'.format(page, section)
+  input =  name + '.scd'
+  tgt = custom_target(
+    input,
+    input: files(input),
+    output: name,
+    capture: true,
+    feed: true,
+    command: scdoc,
+    install: true,
+    install_dir: get_option('mandir') / 'man@0@'.format(section),
+  )
+endforeach
+
+install_man('pkg.m4.7')
+install_man('pkgconf-personality.5')

man/pc.5

@@ -1,177 +0,0 @@
-.\" Copyright (c) 2017 pkgconf authors (see AUTHORS).
-.\"
-.\" Permission to use, copy, modify, and/or distribute this software for any
-.\" purpose with or without fee is hereby granted, provided that the above
-.\" copyright notice and this permission notice appear in all copies.
-.\"
-.\" This software is provided 'as is' and without any warranty, express or
-.\" implied.  In no event shall the authors be liable for any damages arising
-.\" from the use of this software.
-.Dd December 15, 2017
-.Dt PC 5
-.Os
-.Sh NAME
-.Nm file.pc
-.Nd pkg-config file format
-.Sh DESCRIPTION
-pkg-config files provide a useful mechanism for storing various information
-about libraries and packages on a given system.
-Information stored by
-.Nm .pc
-files include compiler and linker flags necessary to use a given library, as
-well as any other relevant metadata.
-.Pp
-These
-.Nm .pc
-files are processed by a utility called
-.Nm pkg-config ,
-of which
-.Nm pkgconf
-is an implementation.
-.\"
-.Ss FILE SYNTAX
-The
-.Nm .pc
-file follows a format inspired by RFC822.
-Comments are prefixed by a pound sign, hash sign or octothorpe (#), and variable
-assignment is similar to POSIX shell.
-Properties are defined using RFC822-style stanzas.
-.\"
-.Ss VARIABLES
-.\"
-Variable definitions start with an alphanumeric string, followed by an equal sign,
-and then the value the variable should contain.
-.Pp
-Variable references are always written as "${variable}".
-It is possible to escape literal "${" as "$${".
-.\"
-.Ss PROPERTIES
-.\"
-Properties are set using RFC822-style stanzas which consist of a keyword, followed
-by a colon (:) and then the value the property should be set to.
-Variable substitution is always performed regardless of property type.
-.Pp
-There are three types of property:
-.\"
-.Bl -tag -width indent
-.\"
-.It Literal
-The property will be set to the text of the value.
-.\"
-.It Dependency List
-The property will be set to a list of dependencies parsed from the
-text.
-Dependency lists are defined by this ABNF syntax:
-.Bd -literal
-package-list = *WSP *( package-spec *( package-sep ) )
-package-sep  = WSP / ","
-.\"
-package-spec = package-key [ ver-op package-version ]
-ver-op       = "<" / "<=" / "=" / "!=" / ">=" / ">"
-.Ed
-.\"
-.It Fragment List
-The property will be set to a list of fragments parsed from the text.
-The input text must be in a format that is suitable for passing to a POSIX
-shell without any shell expansions after variable substitution has been done.
-.\"
-.El
-.Ss PROPERTY KEYWORDS
-.Bl -tag -width indent
-.\"
-.It Name
-The displayed name of the package.
-(mandatory; literal)
-.It Version
-The version of the package.
-(mandatory; literal)
-.It Description
-A description of the package.
-(mandatory; literal)
-.It URL
-A URL to a webpage for the package.
-This is used to recommend where newer versions of the package can be acquired.
-(mandatory; literal)
-.It Cflags
-Required compiler flags.
-These flags are always used, regardless of whether static compilation is requested.
-(optional; fragment list)
-.It Cflags.private
-Required compiler flags for static compilation.
-(optional; fragment list; pkgconf extension)
-.It Copyright
-A copyright attestation statement.
-(optional; literal; pkgconf extension)
-.It Libs
-Required linking flags for this package.
-Libraries this package depends on for linking against it, which are not
-described as dependencies should be specified here.
-(optional; fragment list)
-.It Libs.private
-Required linking flags for this package that are only required when linking
-statically.
-Libraries this package depends on for linking against it statically, which are
-not described as dependencies should be specified here.
-(optional; fragment list)
-.It License
-The asserted SPDX license tag that should be applied to the given package.
-(optional; literal; pkgconf extension)
-.It Maintainer
-The preferred contact for the maintainer.  This should be in the format of a
-name followed by an e-mail address or website.
-(optional; literal; pkgconf extension)
-.It Requires
-Required dependencies that must be met for the package to be usable.
-All dependencies must be satisfied or the pkg-config implementation must not use
-the package.
-(optional; dependency list)
-.It Requires.private
-Required dependencies that must be met for the package to be usable for static linking.
-All dependencies must be satisfied or the pkg-config implementation must not use
-the package for static linking.
-(optional; dependency list)
-.It Conflicts
-Dependencies that must not be met for the package to be usable.
-If any package in the proposed dependency solution match any dependency in the
-Conflicts list, the package being considered is not usable.
-(optional; dependency list)
-.It Provides
-Dependencies that may be provided by an alternate package.
-If a package cannot be found, the entire package collection is scanned for
-providers which can match the requested dependency.
-(optional; dependency list; pkgconf extension)
-.El
-.Ss EXTENSIONS
-Features that have been marked as a pkgconf extension are only guaranteed to work
-with the pkgconf implementation of pkg-config.
-Other implementations may or may not support the extensions.
-.Pp
-Accordingly, it is suggested that
-.Nm .pc
-files which absolutely depend on these extensions declare a requirement on the
-pkgconf virtual.
-.Sh EXAMPLES
-An example .pc file:
-.Bd -literal
-# This is a comment
-prefix=/home/kaniini/pkg   # this defines a variable
-exec_prefix=${prefix}      # defining another variable with a substitution
-libdir=${exec_prefix}/lib
-includedir=${prefix}/include
-
-Name: libfoo                                  # human-readable name
-Description: an example library called libfoo # human-readable description
-Copyright: Copyright (c) 2022 pkgconf project authors
-License: Apache-2.0
-Maintainer: the pkgconf project <http://www.pkgconf.org>
-Version: 1.0
-URL: http://www.pkgconf.org
-Requires: libbar > 2.0.0
-Conflicts: libbaz <= 3.0.0
-Libs: -L${libdir} -lfoo
-Libs.private: -lm
-Cflags: -I${includedir}/libfoo
-.Ed
-.Sh SEE ALSO
-.Xr pkgconf 1 ,
-.Xr pkg.m4 7

man/pc.5.scd

@@ -0,0 +1,166 @@
+PC(5)
+
+; TODO: old manpages often have two spaces after a full stop, as a newline in
+; mdoc seem to mean no newline but two spaces in the output.
+; Should I do the same?
+
+# NAME
+
+*file.pc* — pkg-config file format
+
+# DESCRIPTION
+
+pkg-config files provide a useful mechanism for storing various information
+about libraries and packages on a given system. Information stored by *.pc*
+files include compiler and linker flags necessary to use a given library, as
+well as any other relevant metadata.
+
+These *.pc* files are processed by a utility called pkg-config, of which pkgconf
+is an implementation.
+
+## FILE SYNTAX
+
+The *.pc* file follows a format inspired by RFC822. Comments are prefixed by a
+pound sign, hash sign or octothorpe (#), and variable assignment is similar to
+POSIX shell. Properties are defined using RFC822-style stanzas.
+
+## VARIABLES
+
+Variable definitions start with an alphanumeric string, followed by an equal
+sign, and then the value the variable should contain.
+
+Variable references are always written as "${variable}".  It is possible to
+escape literal "${" as "$${".
+
+## PROPERTIES
+
+Properties are set using RFC822-style stanzas which consist of a keyword,
+followed by a colon (:) and then the value the property should be set to.
+Variable substitution is always performed regardless of property type.
+
+There are three types of property:
+
+Literal
+	The property will be set to the text of the value.
+
+Dependency List
+	The property will be set to a list of dependencies parsed from the text.
+	Dependency lists are defined by this ABNF syntax:
+
+	```
+	package-list = *WSP *( package-spec *( package-sep ) )
+	package-sep  = WSP / ","
+	package-spec = package-key [ ver-op package-version ]
+	ver-op       = "<" / "<=" / "=" / "!=" / ">=" / ">"
+	```
+
+Fragment List
+	The property will be set to a list of fragments parsed from the text. The
+	input text must be in a format that is suitable for passing to a POSIX shell
+	without any shell expansions after variable substitution has been done.
+
+## PROPERTY KEYWORDS
+
+Name
+	The displayed name of the package. (mandatory; literal)
+
+Version
+	The version of the package. (mandatory; literal)
+
+Description
+	A description of the package. (mandatory; literal)
+
+URL
+	A URL to a webpage for the package. This is used to recommend where newer
+	versions of the package can be acquired. (mandatory; literal)
+
+Cflags
+	Required compiler flags.  These flags are always used, regardless of whether
+	static compilation is requested. (optional; fragment list)
+
+Cflags.private
+	Required compiler flags for static compilation.  (optional; fragment list;
+	pkgconf extension)
+
+Copyright
+	A copyright attestation statement.  (optional; literal; pkgconf extension)
+
+Libs
+	Required linking flags for this package. Libraries this package depends on
+	for linking against it, which are not described as dependencies should be
+	specified here. (optional; fragment list)
+
+Libs.private
+	Required linking flags for this package that are only required when linking
+	statically.  Libraries this package depends on for linking against it
+	statically, which are not described as dependencies should be specified
+	here.  (optional; fragment list)
+
+License
+	The asserted SPDX license tag that should be applied to the given package.
+	(optional; literal; pkgconf extension)
+
+Maintainer
+	The preferred contact for the maintainer.  This should be in the format of a
+	name followed by an e-mail address or website.  (optional; literal; pkgconf
+	extension)
+
+Requires
+	Required dependencies that must be met for the package to be usable.  All
+	dependencies must be satisfied or the pkg-config implementation must not use
+	the package.  (optional; dependency list)
+
+Requires.private
+	Required dependencies that must be met for the package to be usable for
+	static linking.  All dependencies must be satisfied or the pkg-config
+	implementation must not use the package for static linking.  (optional;
+	dependency list)
+
+Conflicts
+	Dependencies that must not be met for the package to be usable.  If any
+	package in the proposed dependency solution match any dependency in the
+	Conflicts list, the package being considered is not usable.  (optional;
+	dependency list)
+
+Provides
+	Dependencies that may be provided by an alternate package.  If a package
+	cannot be found, the entire package collection is scanned for providers
+	which can match the requested dependency.  (optional; dependency list;
+	pkgconf extension)
+
+## EXTENSIONS
+
+Features that have been marked as a pkgconf extension are only guaranteed to
+work with the pkgconf implementation of pkg-config. Other implementations may or
+may not support the extensions.
+
+Accordingly, it is suggested that *.pc* files which absolutely depend on these
+extensions declare a requirement on the pkgconf virtual.
+
+# EXAMPLES
+
+An example *.pc* file:
+
+```
+# This is a comment
+prefix=/home/kaniini/pkg   # this defines a variable
+exec_prefix=${prefix}      # defining another variable with a substitution
+libdir=${exec_prefix}/lib
+includedir=${prefix}/include
+
+Name: libfoo                                  # human-readable name
+Description: an example library called libfoo # human-readable description
+Copyright: Copyright (c) 2022 pkgconf project authors
+License: Apache-2.0
+Maintainer: the pkgconf project <http://www.pkgconf.org>
+Version: 1.0
+URL: http://www.pkgconf.org
+Requires: libbar > 2.0.0
+Conflicts: libbaz <= 3.0.0
+Libs: -L${libdir} -lfoo
+Libs.private: -lm
+Cflags: -I${includedir}/libfoo
+```
+
+# SEE ALSO
+	*pkgconf*(1), *pkg.m4*(7)

man/pkgconf.1.scd

@@ -5,7 +5,7 @@ PKGCONF(1)
 
 # NAME
 
-pkgconf - a system for configuring build dependency information
+pkgconf — a system for configuring build dependency information
 
 # SYNOPSIS
 

meson.build

@@ -1,7 +1,7 @@
 project('pkgconf', 'c',
   version : '1.9.3',
   license : 'ISC',
-  meson_version : '>=0.49',
+  meson_version : '>=0.59',
   default_options : ['c_std=c99'],
 )
 
@@ -124,10 +124,13 @@ kyuafile = configure_file(input : 'Kyuafile.in', output : 'Kyuafile', configurat
 test('kyua', kyua_exe, args : ['--config=none', 'test', '--kyuafile', kyuafile, '--build-root', meson.current_build_dir()])
 subdir('tests')
 
-install_man('man/pkgconf.1')
-install_man('man/pkg.m4.7')
-install_man('man/pc.5')
-install_man('man/pkgconf-personality.5')
+# https://github.com/mesonbuild/meson/issues/1550
+# https://github.com/mesonbuild/meson/pull/9342
+scdoc = find_program('scdoc', required: false)
+if scdoc.found()
+  subdir('man')
+endif
+
 install_data('pkg.m4', install_dir: 'share/aclocal')
 install_data('AUTHORS', install_dir: 'share/doc/pkgconf')
 install_data('README.md', install_dir: 'share/doc/pkgconf')