From 5494e8a91aa339ec82003e1242b592741816d938 Mon Sep 17 00:00:00 2001 From: Andrea Pappacoda Date: Sun, 21 Aug 2022 22:18:58 +0200 Subject: [PATCH] docs: convert pc(5) to scdoc --- man/pc.5 | 177 ---------------------------------------------- man/pc.5.scd | 166 +++++++++++++++++++++++++++++++++++++++++++ man/pkgconf.1.scd | 2 +- 3 files changed, 167 insertions(+), 178 deletions(-) delete mode 100644 man/pc.5 create mode 100644 man/pc.5.scd diff --git a/man/pc.5 b/man/pc.5 deleted file mode 100644 index f4ec4eb..0000000 --- a/man/pc.5 +++ /dev/null @@ -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 -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 diff --git a/man/pc.5.scd b/man/pc.5.scd new file mode 100644 index 0000000..3eee269 --- /dev/null +++ b/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 +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) diff --git a/man/pkgconf.1.scd b/man/pkgconf.1.scd index d8d6ab8..ba298ff 100644 --- a/man/pkgconf.1.scd +++ b/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