docs/dev-config-naming.txt

   1 Configuration naming
   2
   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.
   9
  10 == Case studies ==
  11
  12 === Attr.* ===
  13
  14 We have a dead duck HTML.Attr.Name.UseCDATA which migrated before we decided
  15 to think this out thoroughly.
  16
  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:
  20
  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).
  26
  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.
  30
  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
  39
  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.
  44
  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
  57
  58 == AutoFormat.* ==
  59
  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:
  63
  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)
  68
  69 The AutoFormat string is a bit long, but is the only bit of repeated
  70 context.
  71
  72 == Core.* ==
  73
  74 Core is the potpourri of directives, mostly regarding some minor behavioral
  75 tweaks for HTML handling abilities.
  76
  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
  99
 100 == HTML.* ==
 101
 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
 133
 134 == Output.* ==
 135
 136 These directly affect the output of Generator. These are all advanced
 137 twiddles.
 138
 139 == URI.* ==
 140
 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)
 163
 164