*(Not to be confused with hygenic template arguments
<https://phabricator.wikimedia.org/T114432>.)*
As described in my Wikimania 2015 talk
<https://wikimania2015.wikimedia.org/wiki/Submissions/Templates_are_dead!_Long_live_templates!>
(starting at slide 27
<https://wikimania2015.wikimedia.org/w/index.php?title=File:Templates_are_dead!_Long_live_templates!.pdf&page=27>),
there are a number of reasons to mark certain templates as "hygienic".
Among them: to allow high-performance incremental update of page contents
after templates are modified, and to allow safe editing of template uses
using HTML-based tools such as Visual Editor or jsapi
<https://doc.wikimedia.org/Parsoid/master/#!/guide/jsapi>.
This means that the output of the template is a complete DocumentFragment
<https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment>: every
open tag is closed and there are no nodes which the HTML adoption agency
algorithm
<http://dev.w3.org/html5/spec-LC/tree-construction.html#adoptionAgency> will
reorder.
This can be enforced in practice by running tidy (or something like it:
T89331 <https://phabricator.wikimedia.org/T89331>) on the template output
before it is inserted into the document. We are likely to be doing
something like this already for T114072
<https://phabricator.wikimedia.org/T114072>.
The purpose of this RFC is to settle the bikeshed-color questions about how
templates will be marked hygienic/unhygienic. There are two main scenarios:
***Opt-in Hygiene***
In this scenario, unmarked templates are assumed "dirty", and will render
correctly (as before), just more slowly. Some of the unmarked templates
(the "actually dirty" ones) may be uneditable in VisualEditor.
In the opt-in scenario, it is expected that profiling the
"costliest"/"most
frequently used/changed" templates on wikimedia projects will be done, and
opt-in tags will be added first to those templates where the greatest
potential performance gain may be achieved. (Opting in will enable
incremental update of the parser cache after template modifications.)
Proposals:
1. An explicit tag surrounding "hygienic" contents; this tag will
exactly encapsulate the content which will be run through tidy. Proposed
names:
1. `<tidy>...</tidy>`
2. `<domscope>...</domscope>`
3. `<domparse>...</domparse>`
2. A magic word, present in templates known to be hygienic. Proposed
names:
1. `__SAFE__`
2. `__HYGIENIC__`
3. Some `TemplateData
<https://www.mediawiki.org/wiki/Extension:TemplateData>` property?
4. Others?
***Opt-out Hygiene***
In this scenario, all templates are assumed "hygienic", and an explicit
marker of some kind is required to opt-out of the usual tidy of the
contents. Templates which opt-out are not editable in Visual Editor, but
all other templates are (because the contents will have been automatically
cleaned to close any stray open tags).
In the opt-out scenario, it is expected that Parsoid (or other tools) will
be run against the wikimedia projects to automatically add opt-out tags
where possible; perhaps based on logging during the parse process.
Proposals:
1. Magic word, present in unhygienic templates
1. `__UNSAFE__`
2. Others?
Phabricator task for this RFC:
https://phabricator.wikimedia.org/T114445
--scott
--
(
http://cscott.net)