Release 4.9.3
[htmlpurifier.git] / docs / dev-config-naming.txt
blob66db5bce3c0cd4104b9db59c25266a6cacd30bb8
1 Configuration naming
3 HTML Purifier 4.0.0 features a new configuration naming system that
4 allows arbitrary nesting of namespaces.  While there are certain cases
5 in which using two namespaces is obviously better (the canonical example
6 is where we were using AutoFormatParam to contain directives for AutoFormat
7 parameters), it is unclear whether or not a general migration to highly
8 namespaced directives is a good idea or not.
10 == Case studies ==
12 === Attr.* ===
14 We have a dead duck HTML.Attr.Name.UseCDATA which migrated before we decided
15 to think this out thoroughly.
17 We currently have a large number of directives in the Attr.* namespace.
18 These directives tweak the behavior of some HTML attributes.  They have
19 the properties:
21 * While they apply to only one attribute at a time, the attribute can
22   span over multiple elements (not necessarily all attributes, either).
23   The information of which elements it impacts is either omitted or
24   informally stated (EnableID applies to all elements, DefaultImageAlt
25   applies to <img> tags, AllowedRev doesn't say but only applies to a tags).
27 * There is a certain degree of clustering that could be applied, especially
28   to the ID directives.  The clustering could be done with respect to
29   what element/attribute was used, i.e.
31     *.id -> EnableID, IDBlacklistRegexp, IDBlacklist, IDPrefixLocal, IDPrefix
32     img.src -> DefaultInvalidImage
33     img.alt -> DefaultImageAlt, DefaultInvalidImageAlt
34     bdo.dir -> DefaultTextDir
35     a.rel -> AllowedRel
36     a.rev -> AllowedRev
37     a.target -> AllowedFrameTargets
38     a.name -> Name.UseCDATA
40 * The directives often reference generic attribute types that were specified
41   in the DTD/specification.  However, some of the behavior specifically relies
42   on the fact that other use cases of the attribute are not, at current,
43   supported by HTML Purifier.
45     AllowedRel, AllowedRev -> heavily <a> specific; if <link> ends up being
46         allowed, we will also have to give users specificity there (we also
47         want to preserve generality) DTD %Linktypes, HTML5 distinguishes
48         between <link> and <a>/<area>
49     AllowedFrameTargets -> heavily <a> specific, but also used by <area>
50         and <form>. Transitional DTD %FrameTarget, not present in strict,
51         HTML5 calls them "browsing contexts"
52     Default*Image* -> as a default parameter, is almost entirely exlcusive
53         to <img>
54     EnableID -> global attribute
55     Name.UseCDATA -> heavily <a> specific, but has heavy other usage by
56         many things
58 == AutoFormat.* ==
60 These have the fairly normal pluggable architecture that lends itself to
61 large amounts of namespaces (pluggability may be the key to figuring
62 out when gratuitous namespacing is good.)  Properties:
64 * Boolean directives are fair game for being namespaced: for example,
65   RemoveEmpty.RemoveNbsp triggers RemoveEmpty.RemoveNbsp.Exceptions,
66   the latter of which only makes sense when RemoveEmpty.RemoveNbsp
67   is set to true. (The same applies to RemoveNbsp too)
69 The AutoFormat string is a bit long, but is the only bit of repeated
70 context.
72 == Core.* ==
74 Core is the potpourri of directives, mostly regarding some minor behavioral
75 tweaks for HTML handling abilities.
77     AggressivelyFixLt
78     ConvertDocumentToFragment
79     DirectLexLineNumberSyncInterval
80     LexerImpl
81     MaintainLineNumbers
82         Lexer
83     CollectErrors
84     Language
85         Error handling (Language is ostensibly a little more general, but
86         it's only used for error handling right now)
87     ColorKeywords
88         CSS and HTML
89     Encoding
90     EscapeNonASCIICharacters
91         Character encoding
92     EscapeInvalidChildren
93     EscapeInvalidTags
94     HiddenElements
95     RemoveInvalidImg
96         Lexing/Output
97     RemoveScriptContents
98         Deprecated
100 == HTML.* ==
102     AllowedAttributes
103     AllowedElements
104     AllowedModules
105     Allowed
106     ForbiddenAttributes
107     ForbiddenElements
108         Element set tuning
109     BlockWrapper
110         Child def advanced twiddle
111     CoreModules
112     CustomDoctype
113         Advanced HTMLModuleManager twiddles
114     DefinitionID
115     DefinitionRev
116         Caching
117     Doctype
118     Parent
119     Strict
120     XHTML
121         Global environment
122     MaxImgLength
123         Attribute twiddle? (applies to two attributes)
124     Proprietary
125     SafeEmbed
126     SafeObject
127     Trusted
128         Extra functionality/tagsets
129     TidyAdd
130     TidyLevel
131     TidyRemove
132         Tidy
134 == Output.* ==
136 These directly affect the output of Generator. These are all advanced
137 twiddles.
139 == URI.* ==
141     AllowedSchemes
142     OverrideAllowedSchemes
143         Scheme tuning
144     Base
145     DefaultScheme
146     Host
147         Global environment
148     DefinitionID
149     DefinitionRev
150         Caching
151     DisableExternalResources
152     DisableExternal
153     DisableResources
154     Disable
155         Contextual/authority tuning
156     HostBlacklist
157         Authority tuning
158     MakeAbsolute
159     MungeResources
160     MungeSecretKey
161     Munge
162         Transformation behavior (munge can be grouped)