--- /dev/null
+.\" -*-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).
~mdw / distorted-keys / commitdiff