man: add pc(5) mdoc (closes #148)

Makefile.am

@@ -135,7 +135,8 @@ libpkgconf_la_LDFLAGS = -no-undefined -version-info 2:0:0 -export-symbols-regex
 
 dist_man_MANS    = 		\
 	man/pkgconf.1		\
-	man/pkg.m4.7
+	man/pkg.m4.7		\
+	man/pc.5
 
 pkgconf_LDADD    = libpkgconf.la
 pkgconf_SOURCES  = main.c getopt_long.c renderer-msvc.c

man/pc.5

@@ -0,0 +1,142 @@
+.\" 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 an 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
+.\"
+.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
+.\"
+.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 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 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
+.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
+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/pkgconf.1

@@ -207,4 +207,5 @@ Displaying the CFLAGS of a package:
 .Dl $ pkgconf --cflags foo
 .Dl -fPIC -I/usr/include/foo
 .Sh SEE ALSO
-.Xr pkg.m4 7
+.Xr pkg.m4 7 ,
+.Xr pc 5