mdw@git.distorted.org.uk Git - misc/blob - splitconf.1

   1 .\" -*-nroff-*-
   2 .de hP
   3 .IP
   4 .ft B
   5 \h'-\w'\\$1\ 'u'\\$1\ \c
   6 .ft P
   7 ..
   8 .ie t .ds o \(bu
   9 .el .ds o o
  10 .
  11 .TH splitconf 1 "9 October 2003" "Straylight/Edgeware"
  12 .SH NAME
  13 splitconf \- break a single configuration file out into small chunks
  14 .
  15 .SH SYNOPSIS
  16 .B splitconf
  17 .B \-u
  18 .IR config
  19 .I file
  20 ...
  21 .br
  22 .B splitconf
  23 .B \-d
  24 .I config
  25 .br
  26 .B splitconf
  27 .RB [ \-s \]
  28 .I config
  29 .
  30 .SH DESCRIPTION
  31 The
  32 .B splitconf
  33 program breaks a configuration file into lots of small files, and
  34 remembers what they are.  It is designed to be
  35 .IR safe :
  36 if writing any of the components fails, none of the files is changed.
  37 Alas, the update is not quite atomic -- doing that involves messing with
  38 symbolic links and is just too much like hard work.
  39 .PP
  40 The command-line arguments are as follows:
  41 .TP
  42 .B \-h, \-\-help
  43 Print a very short help message to standard output and exit.
  44 .TP
  45 .B \-u, \-\-unsplit
  46 Gather a list of
  47 .IR file s
  48 into a single
  49 .BR splitconf -managed
  50 configuration file
  51 .IR config .
  52 .TP
  53 .B \-d, \-\-delete
  54 Delete the files split out from
  55 .IR config .
  56 .TP
  57 .B \-s, \-\-split
  58 Split files out from
  59 .IR config .
  60 (This is the default.)
  61 .
  62 .SH SPLITCONF FILES
  63 The input files to
  64 .B splitconf
  65 start with a
  66 .I preamble
  67 section, followed by a number of
  68 .I file
  69 sections.
  70 .PP
  71 The preamble section may contain:
  72 .hP \*o
  73 blank lines, which are ignored;
  74 .hP \*o
  75 meta-comments, which begin with a
  76 .RB ` ## '
  77 pair, and are also ignored;
  78 .hP \*o
  79 option settings, of the form
  80 .RI ` option
  81 .B =
  82 .IR value '
  83 (see below); and
  84 .hP \*o
  85 one-liner file contents descriptions, of the form
  86 .RI ` name \c
  87 .B :
  88 .IR contents '.
  89 .PP
  90 A file section begins with a line of the form
  91 .RB ` [ \c
  92 .IR name \c
  93 .BR ] '
  94 and is followed by lines to write to the file.  In these lines, comments
  95 (lines beginning with a
  96 .RB ` ## '
  97 are stripped out, and any trailing blank lines are removed.  Also, any
  98 line beginning with an exclamation mark
  99 .RB ` ! '
 100 is written out with the leading exclamation mark removed.
 101 .PP
 102 A file section with an empty
 103 .I name
 104 is treated specially: its contents are scanned for more preamble
 105 directives.
 106 .PP
 107 Options are as follows.
 108 .TP
 109 .B prefix
 110 A string to attach to the front of all subsequent filenames, until
 111 overridden.  (Default is empty.)
 112 .TP
 113 .B before
 114 A shell command to execute before starting to write any files.  There is
 115 only one before-command, which is the one current when the first file is
 116 written.
 117 .TP
 118 .B after
 119 A shell command to execute after committing the changes or backing out.
 120 There is only one after-command, which is the last one set in the
 121 configuration file.
 122 .SH BUGS
 123 None known.
 124 .SH AUTHOR
 125 Mark Wooding, <mdw@distorted.org.uk>