ikiwiki/doc/bugs/template_creation_error.mdwn

198 lines
8.1 KiB
Markdown

Hi,
I am trying to build a template. The compilation of this template results in a weird exception. I have isolated the cause of the exception to the following point:
If i have this in the template code:
\[[!inline<br/>
pages="\<TMPL_VAR SEL_PAGES\>"<br/>
template=extract-entry<br/>
\]]<br/>
There is no problem at all. I can use the template with the desired result. But if I try to use this (just adding the "show" parameter):
\[[!inline <br/>
pages="\<TMPL_VAR SEL_PAGES>"<br/>
template=extract-entry<br/>
show=\<TMPL_VAR CNTPG><br/>
\]]<br/>
I get this exception on the Git bash console:
<pre>
$ git push
Counting objects: 7, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 410 bytes, done.
Total 4 (delta 3), reused 0 (delta 0)
remote: From /home/b-odelama-com/source
remote: eb1421e..5e1bac5 master -> origin/master
remote: Argument "\x{3c}\x{54}..." isn't numeric in numeric lt (<) at /usr/share/perl5/IkiWiki/Plugin/inline.pm line 231.
remote: Argument "\x{3c}\x{54}..." isn't numeric in numeric lt (<) at /usr/share/perl5/IkiWiki/Plugin/inline.pm line 231.
To ssh://b-odelama-com@odelama-com.branchable.com/
eb1421e..5e1bac5 master -> master
</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]]
>>>> Thanks for your feedback!
>>>> Looking at its description on this wiki, I agree that `type/web` doesn't
>>>> fit, and core does seem better. I like your `templatebody` suggestion,
>>>> too, particularly if templates remain restricted to `/templates`.
>>>> I'll try to come up with better wording for the documentation to say
>>>> "use `templatebody`, like this", with a note about backwards
>>>> compatibility later.
>>>>
>>>> Rationale for `my %templates`: yes it does seem a bit odd, but
>>>> if I used `$pagestate{$tpage}{template}` instead of a `my` variable,
>>>> I'd sometimes _still_ have to force a `scan`, because
>>>> [[plugins/template]] has to expand the template at scan time so that
>>>> it can contain links etc. - so I have to make sure that if the
>>>> template has changed, it has already been scanned (scanning happens
>>>> in random order, so that can't be guaranteed). This means there's
>>>> no benefit in reading it back from the index, so it might as well
>>>> just be in-memory.
>>>>
>>>> I suppose an alternative way to do it would be to remember what was
>>>> passed to `needsbuild`, and only force a `scan` for templates that
>>>> were in that list - which potentially reduces CPU time and I/O a
>>>> little, in exchange for a bigger index. I could do that if Joey
>>>> wants me to, but I think the current approach is simpler,
>>>> so I'll stick with the current approach if it isn't vetoed.
>>>> --[[smcv]]
>>>>> @name: even outside `/templates`, `\[[!templatebody]]` would be
>>>>> interpreted as "when this page is used as a template, this is what its
>>>>> contents should be", and be suitable.
>>>>>
>>>>> @`%templates`: my surprise wasn't to it not being in `%pagestate`, but
>>>>> rather that the `scan` function was used for it at all, rather than plain
>>>>> directive parsing that ignores everything else -- but i agree that it's
>>>>> the right thing to do in this situation.
>>>>>
>>>>> --[[chrysn]]