doc/patchqueue/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 <pre>
  23 Index: debian/changelog
  24 ===================================================================
  25 --- debian/changelog    (revision 3158)
  26 +++ debian/changelog    (working copy)
  27 @@ -44,8 +44,11 @@
  28    * Fix smiley plugin to scan smileys.mdwn after it's updated, which fixes
  29      a bug caused by committing changes to smilies.mdwn.
  30    * Fix display of escaped wikilinks containing anchors.
  31 +  * Based on a patch by Ethan, add a new htmlescape hook, that is called
  32 +    when a preprocssor directive emits inline html. The rst plugin uses this
  33 +    hook to support inlined raw html.
  34
  35 - -- Joey Hess <joeyh@debian.org>  Fri, 06 Apr 2007 17:17:52 -0400
  36 + -- Joey Hess <joeyh@debian.org>  Fri, 06 Apr 2007 19:19:08 -0400
  37
  38  ikiwiki (1.48) unstable; urgency=low
  39
  40 Index: IkiWiki/Plugin/rst.pm
  41 ===================================================================
  42 --- IkiWiki/Plugin/rst.pm       (revision 3157)
  43 +++ IkiWiki/Plugin/rst.pm       (working copy)
  44 @@ -30,15 +30,22 @@
  45  html = publish_string(stdin.read(), writer_name='html',
  46         settings_overrides = { 'halt_level': 6,
  47                                'file_insertion_enabled': 0,
  48 -                              'raw_enabled': 0 }
  49 +                              'raw_enabled': 1 }
  50  );
  51  print html[html.find('<body>')+6:html.find('</body>')].strip();
  52  ";
  53
  54  sub import { #{{{
  55         hook(type => "htmlize", id => "rst", call => \&htmlize);
  56 +       hook(type => "htmlescape", id => "rst", call => \&htmlecape);
  57  } # }}}
  58
  59 +sub htmlescape ($) { #{{{
  60 +       my $html=shift;
  61 +       $html=~s/^/  /mg;
  62 +       return ".. raw:: html\n\n".$html;
  63 +} # }}}
  64 +
  65  sub htmlize (@) { #{{{
  66         my %params=@_;
  67         my $content=$params{content};
  68 Index: doc/plugins/write.mdwn
  69 ===================================================================
  70 --- doc/plugins/write.mdwn      (revision 3157)
  71 +++ doc/plugins/write.mdwn      (working copy)
  72 @@ -121,6 +121,16 @@
  73  The function is passed named parameters: "page" and "content" and should
  74  return the htmlized content.
  75
  76 +### htmlescape
  77 +
  78 +       hook(type => "htmlescape", id => "ext", call => \&htmlescape);
  79 +
  80 +Some markup languages do not allow raw html to be mixed in with the markup
  81 +language, and need it to be escaped in some way. This hook is a companion
  82 +to the htmlize hook, and is called when ikiwiki detects that a preprocessor
  83 +directive is inserting raw html. It is passed the chunk of html in
  84 +question, and should return the escaped chunk.
  85 +
  86  ### pagetemplate
  87
  88         hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
  89 Index: doc/plugins/rst.mdwn
  90 ===================================================================
  91 --- doc/plugins/rst.mdwn        (revision 3157)
  92 +++ doc/plugins/rst.mdwn        (working copy)
  93 @@ -10,10 +10,8 @@
  94  Note that this plugin does not interoperate very well with the rest of
  95  ikiwiki. Limitations include:
  96
  97 -* reStructuredText does not allow raw html to be inserted into
  98 -  documents, but ikiwiki does so in many cases, including
  99 -  [[WikiLinks|WikiLink]] and many
 100 -  [[PreprocessorDirectives|PreprocessorDirective]].
 101 +* Some bits of ikiwiki may still assume that markdown is used or embed html
 102 +  in ways that break reStructuredText. (Report bugs if you find any.)
 103  * It's slow; it forks a copy of python for each page. While there is a
 104    perl version of the reStructuredText processor, it is not being kept in
 105    sync with the standard version, so is not used.
 106 Index: IkiWiki.pm
 107 ===================================================================
 108 --- IkiWiki.pm  (revision 3158)
 109 +++ IkiWiki.pm  (working copy)
 110 @@ -628,6 +628,14 @@
 111                                 preview => $preprocess_preview,
 112                         );
 113                         $preprocessing{$page}--;
 114 +
 115 +                       # Handle escaping html if the htmlizer needs it.
 116 +                       if ($ret =~ /[<>]/ && $pagesources{$page}) {
 117 +                               my $type=pagetype($pagesources{$page});
 118 +                               if ($hooks{htmlescape}{$type}) {
 119 +                                       return $ret = $hooks{htmlize}{$type}{escape}->($ret);
 120 +                               }
 121 +                       }
 122                         return $ret;
 123                 }
 124                 else {
 125 </pre>