From a218eb121bc640b2821aa21f208f082881b7fc29 Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Sat, 2 May 2015 17:05:20 +0100 Subject: [PATCH] extract-profile: Add manpage. Organization: Straylight/Edgeware From: Mark Wooding --- Makefile.am | 1 + extract-profile.1 | 293 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 294 insertions(+) create mode 100644 extract-profile.1 diff --git a/Makefile.am b/Makefile.am index 2ab0769..aa7982b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -79,6 +79,7 @@ shamir: shamir.in Makefile ## Property expansion. bin_SCRIPTS += extract-profile EXTRA_DIST += extract-profile.in +dist_man_MANS += extract-profile.1 CLEANFILES += extract-profile extract-profile: extract-profile.in Makefile $(SUBST) $(srcdir)/extract-profile.in $(SUBSTVARS) \ diff --git a/extract-profile.1 b/extract-profile.1 new file mode 100644 index 0000000..2a82249 --- /dev/null +++ b/extract-profile.1 @@ -0,0 +1,293 @@ +.\" -*-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, +.SH SEE ALSO +.BR distorted-keys (7). -- [mdw]