Introduction
************
A buildout recipe to manage auto-populating portions of shared configuration 
files that cannot simply overwritten.

.. contents::

Overview
========
In complex buildouts, it is often necessary to create configuration files 
for various services, such as an Apache web server. Where a separate file 
is used for each instance, or where it is possible to add an independent 
file to a directory where it will be read and included in the configuration, 
this is quite straightforward.

But some services have only one file which may need to have entries for 
multiple applications or require manual editing. In this case generating 
a file automatically is simply asking for trouble. 

This recipe reads a configuration file and inserts the desired configuration 
between "marker" lines, which are comments in the configuration file. It also 
adds an optional comment identifying where these lines came from (and telling
people not to edit them). Upon update, the section is replaced with the 
updated configuration and any changes outside the markers are preserved. 
The section will also be removed if the part is removed.

Example::

    # A sample config file
    Existing_1 = One
    Existing_2 = Two
    # START: my-buildout-section
    # Text between these lines generated by buildout. Do not remove or edit
    custom_1 = ONE
    custom_2 = TWO
    # END: my-buildout-section
    # Manual comment
    Manual_3 = Three

Caveats
=======
While the marker format can be customised to accommodate different comment 
requirements, there are probably all sorts fo things that can trip it up.

The program should run under Python 2.4 and onwards. It has not been tested 
with Python 3, nor on a Windows platform, although it was written to be 
portable and platform independent. Feedback, test results, use cases and 
patches welcomed!
