[misc] / splitconf.1

.\" -*-nroff-*-
.de hP
.IP
.ft B
\h'-\w'\\$1\ 'u'\\$1\ \c
.ft P
..
.ie t .ds o \(bu
.el .ds o o
.
.TH splitconf 1 "9 October 2003" "Straylight/Edgeware"
.SH NAME
splitconf \- break a single configuration file out into small chunks
.
.SH SYNOPSIS
.B splitconf
.B \-u
.IR config
.I file
...
.br
.B splitconf
.B \-d
.I config
.br
.B splitconf
.RB [ \-s \]
.I config
.
.SH DESCRIPTION
The
.B splitconf
program breaks a configuration file into lots of small files, and
remembers what they are.  It is designed to be
.IR safe :
if writing any of the components fails, none of the files is changed.
Alas, the update is not quite atomic -- doing that involves messing with
symbolic links and is just too much like hard work.
.PP
The command-line arguments are as follows:
.TP
.B \-h, \-\-help
Print a very short help message to standard output and exit.
.TP
.B \-u, \-\-unsplit
Gather a list of
.IR file s
into a single
.BR splitconf -managed
configuration file
.IR config .
.TP
.B \-d, \-\-delete
Delete the files split out from
.IR config .
.TP
.B \-s, \-\-split
Split files out from
.IR config .
(This is the default.)
.
.SH SPLITCONF FILES
The input files to
.B splitconf
start with a
.I preamble
section, followed by a number of
.I file
sections.
.PP
The preamble section may contain:
.hP \*o
blank lines, which are ignored;
.hP \*o
meta-comments, which begin with a
.RB ` ## '
pair, and are also ignored;
.hP \*o
option settings, of the form
.RI ` option
.B =
.IR value '
(see below); and
.hP \*o
one-liner file contents descriptions, of the form
.RI ` name \c
.B :
.IR contents '.
.PP
A file section begins with a line of the form
.RB ` [ \c
.IR name \c
.BR ] '
and is followed by lines to write to the file.  In these lines, comments
(lines beginning with a
.RB ` ## '
are stripped out, and any trailing blank lines are removed.  Also, any
line beginning with an exclamation mark
.RB ` ! '
is written out with the leading exclamation mark removed.
.PP
A file section with an empty
.I name
is treated specially: its contents are scanned for more preamble
directives.
.PP
Options are as follows.
.TP
.B prefix
A string to attach to the front of all subsequent filenames, until
overridden.  (Default is empty.)
.TP
.B before
A shell command to execute before starting to write any files.  There is
only one before-command, which is the one current when the first file is
written.
.TP
.B after
A shell command to execute after committing the changes or backing out.
There is only one after-command, which is the last one set in the
configuration file.
.SH BUGS
None known.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
Commit	Line	Data
f342fce2	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
ed04d555	96	.RB ` ## '
f342fce2	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
ed04d555	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
f342fce2	107	Options are as follows.
	108	.TP
	109	.B prefix
ed04d555	110	A string to attach to the front of all subsequent filenames, until
ed04d555	111	overridden. (Default is empty.)
f342fce2	112	.TP
f342fce2	113	.B before
ed04d555	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.
f342fce2	117	.TP
	118	.B after
	119	A shell command to execute after committing the changes or backing out.
ed04d555	120	There is only one after-command, which is the last one set in the
ed04d555	121	configuration file.
f342fce2	122	.SH BUGS
	123	None known.
	124	.SH AUTHOR
71d8432e	125	Mark Wooding, <mdw@distorted.org.uk>