X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/0a809b2d3ac3db7a457a99e7d616429d766a2693..8e6274a2bd4f7b6f7398f3a489e37a2f1c85dbb2:/doc/bugs/template_creation_error.mdwn?ds=sidebyside

diff --git a/doc/bugs/template_creation_error.mdwn b/doc/bugs/template_creation_error.mdwn
index abf50cdc0..03641dd5b 100644
--- a/doc/bugs/template_creation_error.mdwn
+++ b/doc/bugs/template_creation_error.mdwn
@@ -34,3 +34,127 @@ To ssh://b-odelama-com@odelama-com.branchable.com/
 </pre>
 
 Please, let me know what to do to avoid this kind of error.
+
+> When you add a template page `templates/foo.mdwn` for use
+> the [[ikiwiki/directive/template]] directive, two things happen:
+>
+> 1. `\[[!template id=foo ...]]` becomes available;
+> 2. a wiki page `templates/foo` is built, resulting in a HTML file,
+>    typically `templates/foo/index.html`
+>
+> The warnings you're seeing are the second of these: when ikiwiki
+> tries to process `templates/foo.mdwn` as an ordinary page, without
+> interpreting the `<TMPL_VAR>` directives, `inline` receives invalid
+> input.
+>
+> This is a bit of a design flaw in [[plugins/template]] and
+> [[plugins/edittemplate]], I think - ideally it would be possible to
+> avoid parts of the page being interpreted when the page is being
+> rendered normally rather than being used as a template.
+>
+> There *is* a trick to avoid parts of the page being interpreted when
+> the page is being used as a template, while having them appear
+> when it's rendered as a page:
+>
+>     <TMPL_IF FALSE>
+>     <!-- This part only appears when being used as a page.
+>          It assumes that you never set FALSE to a true value :-) -->
+>     \[[!meta robots="noindex,nofollow"]]
+>     This template is used to describe a thing. Parameters:
+>     * name: the name of the thing
+>     * size: the size of the thing
+>     </TMPL_IF>
+>
+>     The thing is called <TMPL_VAR name> and its size is <TMPL_VAR size>
+>
+> I suppose you could maybe extend that to something like this:
+>
+>     <TMPL_IF FALSE>
+>     <!-- This part only appears when being used as a page.
+>          It assumes that you never set FALSE to a true value :-) -->
+>     \[[!meta robots="noindex,nofollow"]]
+>     This template is used to describe a thing. Parameters:
+>     * name: the name of the thing
+>     * size: the size of the thing
+>     </TMPL_IF>
+>
+>     <TMPL_IF FALSE>
+>     \[[!if test="included() and !included()" then="""
+>     </TMPL_IF>
+>     <!-- This part only appears when being used as a template. It also
+>          assumes that you never set FALSE to a true value, and it
+>          relies on the [[ikiwiki/pagespec]] "included() and !included()"
+>          never being true. -->
+>     The thing is called <TMPL_VAR name> and its size is <TMPL_VAR size>
+>     <TMPL_IF FALSE>
+>     """]]
+>     </TMPL_IF>
+>
+> but that's far harder than it ought to be!
+>
+> Perhaps the right solution would be to change how the template plugin
+> works, so that templates are expected to contain a new `definetemplate`
+> directive:
+>
+>     This template is used to describe a thing. Parameters:
+>     * name: the name of the thing
+>     * size: the size of the thing
+>     
+>     \[[!definetemplate """
+>     The thing is called <TMPL_VAR name> and its size is <TMPL_VAR size>
+>     """]]
+>
+> with templates not containing a `\[[!definetemplate]]` being treated
+> as if the whole text of the page was copied into a `\[[!definetemplate]]`,
+> for backwards compatibility?
+>
+> --[[smcv]]
+
+>> [[!template id=gitbranch author="[[smcv]]" branch=smcv/definetemplate]]
+>> [[!tag patch]]
+>> OK, here is a branch implementing what I said. It adds the `definetemplate`
+>> directive to [[plugins/goodstuff]] as its last commit.
+>>
+>> Templates with the current strange semantics will still work, until
+>> IkiWiki breaks compatibility.
+>>
+>> Possible controversies:
+>>
+>> * Should the `definetemplate` plugin be core, or in goodstuff, or neither?
+>>
+>> * Should \[[!definetemplate]] be allowed on any page (with the implementation
+>>   of `template("foo")` looking for a `definetemplate` in `templates/foo`,
+>>   then a `definetemplate` in `foo`, then fall back to the current logic)?
+>>   If not, should \[[!definetemplate]] raise an error when used on a page not
+>>   in `templates/`, since it will have no practical effect there?
+>>
+>> * Is it OK to rely on `definetemplate` being enabled in the basewiki's
+>>   templates?
+>>
+>> * Should the "use definetemplate" wording in the documentation of
+>>   template and edittemplate be stronger? Should those plugins automatically
+>>   load definetemplate?
+>>
+>> --[[smcv]]
+
+>>> this looks like a good idea to me.
+>>>
+>>> * i'd put it in core, and add a transition for the time compatibility gets
+>>>   broken, provided the transitioning system will be used in that. templates
+>>>   can't be expected to just work as markdown+ikiwiki too.
+>>>
+>>>   (it being in core would also solve my qualms about `section => "web"` /
+>>>   `\[[!tag type/web]]`).
+>>>
+>>> * if definetemplate gets deemed core, no "use definetemplate!" notes on the
+>>>   template/edittemplate pages will be required any more.
+>>>
+>>> * first i was sceptical of the approach of re-running scan to make sure the
+>>>   `my %templates` is filled, but it is indeed a practical solution.
+>>>
+>>> * the name "`definetemplate`" gives me the first impression that something
+>>>   is assigned (as in `#define`), but actually it highlights a region in the
+>>>   file. wouldn't "`templatebody`" be a better description of the meaning of
+>>>   the directive?
+>>>
+>>> --[[chrysn]]