doc/bugs/template_creation_error.mdwn

   1 Hi,
   2 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:
   3
   4 If i have this in the template code:
   5
   6 \[[!inline<br/>
   7 pages="\<TMPL_VAR SEL_PAGES\>"<br/>
   8 template=extract-entry<br/>
   9 \]]<br/>
  10
  11 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):
  12
  13 \[[!inline <br/>
  14 pages="\<TMPL_VAR SEL_PAGES>"<br/>
  15 template=extract-entry<br/>
  16 show=\<TMPL_VAR CNTPG><br/>
  17 \]]<br/>
  18
  19 I get this exception on the Git bash console:
  20
  21 <pre>
  22 $ git push
  23 Counting objects: 7, done.
  24 Delta compression using up to 8 threads.
  25 Compressing objects: 100% (4/4), done.
  26 Writing objects: 100% (4/4), 410 bytes, done.
  27 Total 4 (delta 3), reused 0 (delta 0)
  28 remote: From /home/b-odelama-com/source
  29 remote:    eb1421e..5e1bac5  master     -> origin/master
  30 remote: Argument "\x{3c}\x{54}..." isn't numeric in numeric lt (<) at /usr/share/perl5/IkiWiki/Plugin/inline.pm line 231.
  31 remote: Argument "\x{3c}\x{54}..." isn't numeric in numeric lt (<) at /usr/share/perl5/IkiWiki/Plugin/inline.pm line 231.
  32 To ssh://b-odelama-com@odelama-com.branchable.com/
  33    eb1421e..5e1bac5  master -> master
  34 </pre>
  35
  36 Please, let me know what to do to avoid this kind of error.
  37
  38 > When you add a template page `templates/foo.mdwn` for use
  39 > the [[ikiwiki/directive/template]] directive, two things happen:
  40 >
  41 > 1. `\[[!template id=foo ...]]` becomes available;
  42 > 2. a wiki page `templates/foo` is built, resulting in a HTML file,
  43 >    typically `templates/foo/index.html`
  44 >
  45 > The warnings you're seeing are the second of these: when ikiwiki
  46 > tries to process `templates/foo.mdwn` as an ordinary page, without
  47 > interpreting the `<TMPL_VAR>` directives, `inline` receives invalid
  48 > input.
  49 >
  50 > This is a bit of a design flaw in [[plugins/template]] and
  51 > [[plugins/edittemplate]], I think - ideally it would be possible to
  52 > avoid parts of the page being interpreted when the page is being
  53 > rendered normally rather than being used as a template.
  54 >
  55 > There *is* a trick to avoid parts of the page being interpreted when
  56 > the page is being used as a template, while having them appear
  57 > when it's rendered as a page:
  58 >
  59 >     <TMPL_IF FALSE>
  60 >     <!-- This part only appears when being used as a page.
  61 >          It assumes that you never set FALSE to a true value :-) -->
  62 >     \[[!meta robots="noindex,nofollow"]]
  63 >     This template is used to describe a thing. Parameters:
  64 >     * name: the name of the thing
  65 >     * size: the size of the thing
  66 >     </TMPL_IF>
  67 >
  68 >     The thing is called <TMPL_VAR name> and its size is <TMPL_VAR size>
  69 >
  70 > I suppose you could maybe extend that to something like this:
  71 >
  72 >     <TMPL_IF FALSE>
  73 >     <!-- This part only appears when being used as a page.
  74 >          It assumes that you never set FALSE to a true value :-) -->
  75 >     \[[!meta robots="noindex,nofollow"]]
  76 >     This template is used to describe a thing. Parameters:
  77 >     * name: the name of the thing
  78 >     * size: the size of the thing
  79 >     </TMPL_IF>
  80 >
  81 >     <TMPL_IF FALSE>
  82 >     \[[!if test="included() and !included()" then="""
  83 >     </TMPL_IF>
  84 >     <!-- This part only appears when being used as a template. It also
  85 >          assumes that you never set FALSE to a true value, and it
  86 >          relies on the [[ikiwiki/pagespec]] "included() and !included()"
  87 >          never being true. -->
  88 >     The thing is called <TMPL_VAR name> and its size is <TMPL_VAR size>
  89 >     <TMPL_IF FALSE>
  90 >     """]]
  91 >     </TMPL_IF>
  92 >
  93 > but that's far harder than it ought to be!
  94 >
  95 > Perhaps the right solution would be to change how the template plugin
  96 > works, so that templates are expected to contain a new `definetemplate`
  97 > directive:
  98 >
  99 >     This template is used to describe a thing. Parameters:
 100 >     * name: the name of the thing
 101 >     * size: the size of the thing
 102 >
 103 >     \[[!definetemplate """
 104 >     The thing is called <TMPL_VAR name> and its size is <TMPL_VAR size>
 105 >     """]]
 106 >
 107 > with templates not containing a `\[[!definetemplate]]` being treated
 108 > as if the whole text of the page was copied into a `\[[!definetemplate]]`,
 109 > for backwards compatibility?
 110 >
 111 > --[[smcv]]
 112
 113 >> [[!template id=gitbranch author="[[smcv]]" branch=smcv/definetemplate]]
 114 >> [[!tag patch]]
 115 >> OK, here is a branch implementing what I said. It adds the `definetemplate`
 116 >> directive to [[plugins/goodstuff]] as its last commit.
 117 >>
 118 >> Templates with the current strange semantics will still work, until
 119 >> IkiWiki breaks compatibility.
 120 >>
 121 >> Possible controversies:
 122 >>
 123 >> * Should the `definetemplate` plugin be core, or in goodstuff, or neither?
 124 >>
 125 >> * Should \[[!definetemplate]] be allowed on any page (with the implementation
 126 >>   of `template("foo")` looking for a `definetemplate` in `templates/foo`,
 127 >>   then a `definetemplate` in `foo`, then fall back to the current logic)?
 128 >>   If not, should \[[!definetemplate]] raise an error when used on a page not
 129 >>   in `templates/`, since it will have no practical effect there?
 130 >>
 131 >> * Is it OK to rely on `definetemplate` being enabled in the basewiki's
 132 >>   templates?
 133 >>
 134 >> * Should the "use definetemplate" wording in the documentation of
 135 >>   template and edittemplate be stronger? Should those plugins automatically
 136 >>   load definetemplate?
 137 >>
 138 >> --[[smcv]]
 139
 140 >>> this looks like a good idea to me.
 141 >>>
 142 >>> * i'd put it in core, and add a transition for the time compatibility gets
 143 >>>   broken, provided the transitioning system will be used in that. templates
 144 >>>   can't be expected to just work as markdown+ikiwiki too.
 145 >>>
 146 >>>   (it being in core would also solve my qualms about `section => "web"` /
 147 >>>   `\[[!tag type/web]]`).
 148 >>>
 149 >>> * if definetemplate gets deemed core, no "use definetemplate!" notes on the
 150 >>>   template/edittemplate pages will be required any more.
 151 >>>
 152 >>> * first i was sceptical of the approach of re-running scan to make sure the
 153 >>>   `my %templates` is filled, but it is indeed a practical solution.
 154 >>>
 155 >>> * the name "`definetemplate`" gives me the first impression that something
 156 >>>   is assigned (as in `#define`), but actually it highlights a region in the
 157 >>>   file. wouldn't "`templatebody`" be a better description of the meaning of
 158 >>>   the directive?
 159 >>>
 160 >>> --[[chrysn]]