extract-profile: Add manpage.

[distorted-keys] / extract-profile.1

.\" -*-nroff-*-
.ie t \{\
.  ds o \(bu
.  if \n(.g .fam P
.\}
.el \{\
.  ds o o
.\}
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.de VS
.sp 1
.RS
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.TH extract-profile 1 "3 May 2015" "distorted.org.uk key management"
.SH NAME
extract-profile \- determine configuration using inheritance and substitution
.SH SYNOPSIS
.B extract-profile
.I section
.IR file | directory ...
.SH DESCRIPTION
The
.B extract-profile
utility reads a number of
.BR .ini -style
configuration files from the named
.IR file s
and
.IR directori es,
combines the sections according to inheritance rules (described below),
performs substitutions on the values,
and writes the resulting effective contents of the named
.I section
to standard output.
.PP
A
.I directory
named on the command line
causes files within to be examined:
specifically, each file whose name consists only of
upper- and lowercase letters,
digits,
underscores
.RB (` _ '),
and
hyphens
.RB (` \- ')
will be processed;
other files are ignored,
as are objects in the
.I directory
which aren't files
(so, in particular, directories are not processed recursively).
The files within a directory are processed
in ascending lexicographic order.
It may be useful to prefix filenames with numbers
in order to ensure that they're read in the correct order.
.SS Command-line options
The following options are recognized.
.TP
.B \-h, \-\-help
Print an overview
of the options and commands
to standard output
and exit successfully.
.TP
.B \-\-version
Print the version number
of the
.B distorted-keys
package
to standard output
and exit successfully.
.SS Configuration data model
A
.I property
has a
.I name
and a
.IR value .
A property's name must consist only of
upper- and lowercase letters,
digits,
underscores
.RB (` _ '),
and
percent signs
.RB (` % ').
A property is
.I internal
if its name contains
a percent sign;
otherwise it is
.IR external .
.PP
A
.I direct section
has a name,
an
.I inclusion list
of other sections,
and a collection of
.I direct properties
with distinct names.
.PP
There is a special section 
named
.B @GLOBAL
which is implicitly included by every other section.
.SS Configuration syntax
Configuration files are line-oriented.
Leading and trailing whitespace is always ignored.
There is no line-continuation syntax.
There are four kinds of lines.
.hP \*o
.IR "Blank lines" ,
consisting only of whitespace,
are ignored.
.hP \*o
.IR Comments ,
beginning with 
hash
.RB (` # ')
or
semicolon
.RB (` ; '),
are also ignored.
.hP \*o
.IR "Section headings" ,
consisting of a name
surrounded by square brackets
.RB (` [ ... ] '),
cause the following assignments,
as far as the next section heading
or the end of the file,
to define or override properties in the named section.
.hP \*o
.IR Assignments ,
of the form
.I name
.B =
.I value
or
.I name
.B :
.IR value ,
define (or override) direct properties
or pseudoproperties
in the current section.
Spaces around the
.RB ` = '
or
.RB ` : '
are optional and, if present, ignored.
Hyphens
.RB (` - ')
in the
.I name
are converted to
underscores
.RB (` _ ').
Assignments preceding the first section header in a file
apply to the special section
.BR @GLOBAL .
.PP
The same property
or pseudoproperty
may be defined multiple times in a section:
only the last definition is significant;
earlier definitions are silently ignored.
.PP
Pseudoproperties have names beginning with an at sign
.RB (` @ ').
The following pseudoproperties are recognized.
.TP
.B @include
The value is a list of section names separated by whitespace.
The current section's inclusion list is set to
the corresponding named sections.
.PP
Sections may be defined in any order.
The same section may be defined more than once:
the effect is the same as a single section containing
all of the assignments of the individual sections
in the same order.
.SS Inheritance
The
.I inferiors
of a section
.I S
are the sections in
.IR S 's
inclusion list,
together with their inferiors.
It is an error if a section is its own inferior.
(Consequently, it is an error if
.B @GLOBAL
has a non-empty inclusion list.)
If
.I T
is an inferior of
.I S
then
.I S
is a
.I superior
of
.IR T .
.PP
A section
.I S
has an
.I effective property
named
.I P
if either
.I S
has a direct property named
.IR P ,
or any inferior of
.I S
has a direct property named
.IR P .
.PP
If
.I S
has an effective property named
.I P
then
.IR P 's
.I defining set
consists of those sections out of
.I S
and its inferiors
which have a direct property named
.IR P .
The
.I reduced defining set
for
.I P
consists of those sections in the
.I defining set
of
.I P
which have no superiors in the defining set.
.PP
If all of the sections in the reduced defining set for
.I P
assign the same value to
.I P
then that is the
.I effective value
for
.I P
in
.IR S ;
otherwise the configuration is erroneous.
.PP
Note that, 
according to these rules,
if
.I S
has a direct property
.I P
then
.I S
has an effective property
.I P
with the same value.
.SS Output
The
.B extract-profile
program's output consists of assignments
.IB name = value
for the effective properties of the named
.IR section ,
one per line,
in an arbitrary order.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
.SH SEE ALSO
.BR distorted-keys (7).