[1.2.0] Rename so that docs have specific categories.

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@534 48356398-32a2-884e-a903-53898d9a118a

docs/proposal-config.txt

@@ -0,0 +1,35 @@
+
+Configuration
+
+Configuration is documented on a per-use case: if a class uses a certain
+value from the configuration object, it has to define its name and what the
+value is used for.  This means decentralized configuration declarations that
+are nevertheless error checking and a centralized configuration object.
+
+Directives are divided into namespaces, indicating the major portion of
+functionality they cover (although there may be overlaps.  Please consult
+the documentation in ConfigDef for more information on these namespaces.
+
+Since configuration is dependant on context, internal classes require a
+configuration object to be passed as a parameter.  (They also require a
+Context object).
+
+In relation to HTMLDefinition and CSSDefinition, there is a special class
+of directives that influence the *construction* of the Definition object.
+A standard call pattern would look like:
+
+1. Client calls Config->getHTMLDefinition()
+2. Config calls HTMLDefinition->createNew(this)
+3. HTMLDefinition constructs itself with base configuration
+4. HTMLDefinition calls Config->get('HTMLDefinition')
+5. Config returns array of directives that later construction
+6. HTMLDefinition performs operations and changes specified by directives
+7. HTMLPurifier returns constructed definition
+8. Config caches definition so it doesn't have to be generated again
+9. Config returns definition
+
+You could also override Config's copy of the definition with your own
+custom copy, which OVERRIDES all directives.  Only the base, vanilla copy
+is the Singleton, the object actually interfaced with is a operated-upon
+clone of that object.  Also, if an update to the directives would update
+the definition, you'd have to force reconstruction.