doc/todo/format_escape.mdwn

   1 Since some preprocessor directives insert raw HTML, it would be good to
   2 specify, per-format, how to pass HTML so that it goes through the format
   3 OK. With Markdown we cross our fingers; with reST we use the "raw"
   4 directive.
   5
   6 I added an extra named parameter to the htmlize hook, which feels sort of
   7 wrong, since none of the other hooks take parameters. Let me know what
   8 you think. --Ethan
   9
  10 Seems fairly reasonable, actually. Shouldn't the `$type` come from `$page`
  11 instead of `$destpage` though? Only other obvious change is to make the
  12 escape parameter optional, and only call it if set. --[[Joey]]
  13
  14 > I couldn't figure out what to make it from, but thinking it through,
  15 > yeah, it should be $page. Revised patch follows. --Ethan
  16
  17 >> I've updated the patch some more, but I think it's incomplete. ikiwiki
  18 >> emits raw html when expanding WikiLinks too, and it would need to escape
  19 >> those. Assuming that escaping html embedded in the middle of a sentence
  20 >> works.. --[[Joey]]
  21
  22 >>> Revised again. I get around this by making another hook, htmlescapelink,
  23 >>> which is called to generate links in whatever language. In addition, it
  24 >>> doesn't (can't?) generate
  25 >>> spans, and it doesn't handle inlineable image links. If these were
  26 >>> desired, the approach to take would probably be to use substitution
  27 >>> definitions, which would require generating two bits of code for each
  28 >>> link/html snippet, and putting one at the end of the paragraph (or maybe
  29 >>> the document?).
  30 >>> To specify that (for example) Discussion links are meant to be HTML and
  31 >>> not rst or whatever, I added a "genhtml" parameter to htmllink. It seems
  32 >>> to work -- see <http://ikidev.betacantrips.com/blah.html> for an example.
  33 >>> --Ethan
  34
  35 ## Alternative solution
  36
  37 [Here](http://www.jk.fr.eu.org/ikiwiki/format-escapes-2.diff) is a patch
  38 largely inspired from the one below, which is up to date and written with
  39 [[todo/multiple_output_formats]] in mind. "htmlize" hooks are generalized
  40 to "convert" ones, which can be registered for any pair of filename
  41 extensions.
  42
  43 Preprocessor directives are allowed to return the content to be inserted
  44 as a hash, in any format they want, provided they provide htmlize hooks for it.
  45 Pseudo filename extensions (such as `"_link"`) can also be introduced,
  46 which aren't used as real extensions but provide useful intermediate types.
  47
  48 --[[JeremieKoenig]]
  49
  50 ## Original patch
  51 [[tag patch]]
  52
  53 <pre>
  54 Index: debian/changelog
  55 ===================================================================
  56 --- debian/changelog    (revision 3197)
  57 +++ debian/changelog    (working copy)
  58 @@ -24,6 +24,9 @@
  59      than just a suggests, since OpenID is enabled by default.
  60    * Fix a bug that caused link(foo) to succeed if page foo did not exist.
  61    * Fix tags to page names that contain special characters.
  62 +  * Based on a patch by Ethan, add a new htmlescape hook, that is called
  63 +    when a preprocssor directive emits inline html. The rst plugin uses this
  64 +    hook to support inlined raw html.
  65
  66    [ Josh Triplett ]
  67    * Use pngcrush and optipng on all PNG files.
  68 Index: IkiWiki/Render.pm
  69 ===================================================================
  70 --- IkiWiki/Render.pm   (revision 3197)
  71 +++ IkiWiki/Render.pm   (working copy)
  72 @@ -96,7 +96,7 @@
  73                 if ($page !~ /.*\/\Q$discussionlink\E$/ &&
  74                    (length $config{cgiurl} ||
  75                     exists $links{$page."/".$discussionlink})) {
  76 -                       $template->param(discussionlink => htmllink($page, $page, gettext("Discussion"), noimageinline => 1, forcesubpage => 1));
  77 +                       $template->param(discussionlink => htmllink($page, $page, gettext("Discussion"), noimageinline => 1, forcesubpage => 1, genhtml => 1));
  78                         $actions++;
  79                 }
  80         }
  81 Index: IkiWiki/Plugin/rst.pm
  82 ===================================================================
  83 --- IkiWiki/Plugin/rst.pm       (revision 3197)
  84 +++ IkiWiki/Plugin/rst.pm       (working copy)
  85 @@ -30,15 +30,36 @@
  86  html = publish_string(stdin.read(), writer_name='html',
  87         settings_overrides = { 'halt_level': 6,
  88                                'file_insertion_enabled': 0,
  89 -                              'raw_enabled': 0 }
  90 +                              'raw_enabled': 1 }
  91  );
  92  print html[html.find('<body>')+6:html.find('</body>')].strip();
  93  ";
  94
  95  sub import { #{{{
  96         hook(type => "htmlize", id => "rst", call => \&htmlize);
  97 +       hook(type => "htmlescape", id => "rst", call => \&htmlescape);
  98 +       hook(type => "htmlescapelink", id => "rst", call => \&htmlescapelink);
  99  } # }}}
 100
 101 +sub htmlescapelink ($$;@) { #{{{
 102 +       my $url = shift;
 103 +       my $text = shift;
 104 +       my %params = @_;
 105 +
 106 +       if ($params{broken}){
 107 +               return "`? <$url>`_\ $text";
 108 +       }
 109 +       else {
 110 +               return "`$text <$url>`_";
 111 +       }
 112 +} # }}}
 113 +
 114 +sub htmlescape ($) { #{{{
 115 +       my $html=shift;
 116 +       $html=~s/^/  /mg;
 117 +       return ".. raw:: html\n\n".$html;
 118 +} # }}}
 119 +
 120  sub htmlize (@) { #{{{
 121         my %params=@_;
 122         my $content=$params{content};
 123 Index: doc/plugins/write.mdwn
 124 ===================================================================
 125 --- doc/plugins/write.mdwn      (revision 3197)
 126 +++ doc/plugins/write.mdwn      (working copy)
 127 @@ -121,6 +121,26 @@
 128  The function is passed named parameters: "page" and "content" and should
 129  return the htmlized content.
 130
 131 +### htmlescape
 132 +
 133 +       hook(type => "htmlescape", id => "ext", call => \&htmlescape);
 134 +
 135 +Some markup languages do not allow raw html to be mixed in with the markup
 136 +language, and need it to be escaped in some way. This hook is a companion
 137 +to the htmlize hook, and is called when ikiwiki detects that a preprocessor
 138 +directive is inserting raw html. It is passed the chunk of html in
 139 +question, and should return the escaped chunk.
 140 +
 141 +### htmlescapelink
 142 +
 143 +       hook(type => "htmlescapelink", id => "ext", call => \&htmlescapelink);
 144 +
 145 +Some markup languages have special syntax to link to other pages. This hook
 146 +is a companion to the htmlize and htmlescape hooks, and it is called when a
 147 +link is inserted. It is passed the target of the link and the text of the
 148 +link, and an optional named parameter "broken" if a broken link is being
 149 +generated. It should return the correctly-formatted link.
 150 +
 151  ### pagetemplate
 152
 153         hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 154 @@ -355,6 +375,7 @@
 155  * forcesubpage  - set to force a link to a subpage
 156  * linktext - set to force the link text to something
 157  * anchor - set to make the link include an anchor
 158 +* genhtml - set to generate HTML and not escape for correct format
 159
 160  #### `readfile($;$)`
 161
 162 Index: doc/plugins/rst.mdwn
 163 ===================================================================
 164 --- doc/plugins/rst.mdwn        (revision 3197)
 165 +++ doc/plugins/rst.mdwn        (working copy)
 166 @@ -10,10 +10,8 @@
 167  Note that this plugin does not interoperate very well with the rest of
 168  ikiwiki. Limitations include:
 169
 170 -* reStructuredText does not allow raw html to be inserted into
 171 -  documents, but ikiwiki does so in many cases, including
 172 -  [[WikiLinks|WikiLink]] and many
 173 -  [[PreprocessorDirectives|PreprocessorDirective]].
 174 +* Some bits of ikiwiki may still assume that markdown is used or embed html
 175 +  in ways that break reStructuredText. (Report bugs if you find any.)
 176  * It's slow; it forks a copy of python for each page. While there is a
 177    perl version of the reStructuredText processor, it is not being kept in
 178    sync with the standard version, so is not used.
 179 Index: IkiWiki.pm
 180 ===================================================================
 181 --- IkiWiki.pm  (revision 3197)
 182 +++ IkiWiki.pm  (working copy)
 183 @@ -469,6 +469,10 @@
 184         my $page=shift; # the page that will contain the link (different for inline)
 185         my $link=shift;
 186         my %opts=@_;
 187 +       # we are processing $lpage and so we need to format things in accordance
 188 +       # with the formatting language of $lpage. inline generates HTML so links
 189 +       # will be escaped seperately.
 190 +       my $type=pagetype($pagesources{$lpage});
 191
 192         my $bestlink;
 193         if (! $opts{forcesubpage}) {
 194 @@ -494,12 +498,17 @@
 195         }
 196         if (! grep { $_ eq $bestlink } map { @{$_} } values %renderedfiles) {
 197                 return $linktext unless length $config{cgiurl};
 198 -               return "<span><a href=\"".
 199 -                       cgiurl(
 200 -                               do => "create",
 201 -                               page => pagetitle(lc($link), 1),
 202 -                               from => $lpage
 203 -                       ).
 204 +               my $url = cgiurl(
 205 +                                do => "create",
 206 +                                page => pagetitle(lc($link), 1),
 207 +                                from => $lpage
 208 +                               );
 209 +
 210 +               if ($hooks{htmlescapelink}{$type} && ! $opts{genhtml}){
 211 +                       return $hooks{htmlescapelink}{$type}{call}->($url, $linktext,
 212 +                                                              broken => 1);
 213 +               }
 214 +               return "<span><a href=\"". $url.
 215                         "\">?</a>$linktext</span>"
 216         }
 217
 218 @@ -514,6 +523,9 @@
 219                 $bestlink.="#".$opts{anchor};
 220         }
 221
 222 +       if ($hooks{htmlescapelink}{$type} && !$opts{genhtml}) {
 223 +         return $hooks{htmlescapelink}{$type}{call}->($bestlink, $linktext);
 224 +       }
 225         return "<a href=\"$bestlink\">$linktext</a>";
 226  } #}}}
 227
 228 @@ -628,6 +640,14 @@
 229                                 preview => $preprocess_preview,
 230                         );
 231                         $preprocessing{$page}--;
 232 +
 233 +                       # Handle escaping html if the htmlizer needs it.
 234 +                       if ($ret =~ /[<>]/ && $pagesources{$page}) {
 235 +                               my $type=pagetype($pagesources{$page});
 236 +                               if ($hooks{htmlescape}{$type}) {
 237 +                                       return $hooks{htmlescape}{$type}{call}->($ret);
 238 +                               }
 239 +                       }
 240                         return $ret;
 241                 }
 242                 else {
 243 </pre>