web commit by http://ethan.betacantrips.com/: revised patch (completely untested...
[ikiwiki.git] / 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 >>> Revised again. I get around this by making another hook, htmlescapelink,
23 >>> which is called to generate links in whatever language. This patch is
24 >>> completely untested, sorry. In addition, it 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 >>> --Ethan
31
32 <pre>
33 Index: debian/changelog
34 ===================================================================
35 --- debian/changelog    (revision 3182)
36 +++ debian/changelog    (working copy)
37 @@ -44,9 +44,12 @@
38    * Fix smiley plugin to scan smileys.mdwn after it's updated, which fixes
39      a bug caused by committing changes to smilies.mdwn.
40    * Fix display of escaped wikilinks containing anchors.
41 +  * Based on a patch by Ethan, add a new htmlescape hook, that is called
42 +    when a preprocssor directive emits inline html. The rst plugin uses this
43 +    hook to support inlined raw html.
44  
45    [ Josh Triplett ]
46    * Remove stray semicolon in linkmap.pm.
47  
48   -- Joey Hess <joeyh@debian.org>  Fri, 06 Apr 2007 17:28:22 -0700
49  
50 Index: IkiWiki/Plugin/rst.pm
51 ===================================================================
52 --- IkiWiki/Plugin/rst.pm       (revision 3182)
53 +++ IkiWiki/Plugin/rst.pm       (working copy)
54 @@ -30,15 +30,36 @@
55  html = publish_string(stdin.read(), writer_name='html', 
56         settings_overrides = { 'halt_level': 6, 
57                                'file_insertion_enabled': 0,
58 -                              'raw_enabled': 0 }
59 +                              'raw_enabled': 1 }
60  );
61  print html[html.find('<body>')+6:html.find('</body>')].strip();
62  ";
63  
64  sub import { #{{{
65         hook(type => "htmlize", id => "rst", call => \&htmlize);
66 +       hook(type => "htmlescape", id => "rst", call => \&htmlecape);
67 +       hook(type => "htmlescapelink", id => "rst", call => \&htmllink);
68  } # }}}
69  
70 +sub htmllink ($$;@) { #{{{
71 +       my $url = shift;
72 +       my $text = shift;
73 +       my %params = @_;
74 +
75 +       if ($params{broken}){
76 +               return "`? <$url>`_\ $text";
77 +       }
78 +       else {
79 +               return "`$text <$url>`_";
80 +       }
81 +} # }}}
82 +
83 +sub htmlescape ($) { #{{{
84 +       my $html=shift;
85 +       $html=~s/^/  /mg;
86 +       return ".. raw:: html\n\n".$html;
87 +} # }}}
88 +
89  sub htmlize (@) { #{{{
90         my %params=@_;
91         my $content=$params{content};
92 Index: doc/plugins/write.mdwn
93 ===================================================================
94 --- doc/plugins/write.mdwn      (revision 3182)
95 +++ doc/plugins/write.mdwn      (working copy)
96 @@ -121,6 +121,26 @@
97  The function is passed named parameters: "page" and "content" and should
98  return the htmlized content.
99  
100 +### htmlescape
101 +
102 +       hook(type => "htmlescape", id => "ext", call => \&htmlescape);
103 +
104 +Some markup languages do not allow raw html to be mixed in with the markup
105 +language, and need it to be escaped in some way. This hook is a companion
106 +to the htmlize hook, and is called when ikiwiki detects that a preprocessor
107 +directive is inserting raw html. It is passed the chunk of html in
108 +question, and should return the escaped chunk.
109 +
110 +### htmlescapelink
111 +
112 +       hook(type => "htmlescapelink", id => "ext", call => \&htmlescapelink);
113 +
114 +Some markup languages have special syntax to link to other pages. This hook
115 +is a companion to the htmlize and htmlescape hooks, and it is called when a
116 +link is inserted. It is passed the target of the link and the text of the 
117 +link, and an optional named parameter "broken" if a broken link is being
118 +generated. It should return the correctly-formatted link.
119 +
120  ### pagetemplate
121  
122         hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
123 Index: doc/plugins/rst.mdwn
124 ===================================================================
125 --- doc/plugins/rst.mdwn        (revision 3182)
126 +++ doc/plugins/rst.mdwn        (working copy)
127 @@ -10,10 +10,8 @@
128  Note that this plugin does not interoperate very well with the rest of
129  ikiwiki. Limitations include:
130  
131 -* reStructuredText does not allow raw html to be inserted into
132 -  documents, but ikiwiki does so in many cases, including
133 -  [[WikiLinks|WikiLink]] and many
134 -  [[PreprocessorDirectives|PreprocessorDirective]].
135 +* Some bits of ikiwiki may still assume that markdown is used or embed html
136 +  in ways that break reStructuredText. (Report bugs if you find any.)
137  * It's slow; it forks a copy of python for each page. While there is a
138    perl version of the reStructuredText processor, it is not being kept in
139    sync with the standard version, so is not used.
140 Index: IkiWiki.pm
141 ===================================================================
142 --- IkiWiki.pm  (revision 3182)
143 +++ IkiWiki.pm  (working copy)
144 @@ -469,6 +469,7 @@
145         my $page=shift; # the page that will contain the link (different for inline)
146         my $link=shift;
147         my %opts=@_;
148 +       my $type=pagetype($pagesources{$page});
149  
150         my $bestlink;
151         if (! $opts{forcesubpage}) {
152 @@ -494,12 +495,17 @@
153         }
154         if (! grep { $_ eq $bestlink } map { @{$_} } values %renderedfiles) {
155                 return $linktext unless length $config{cgiurl};
156 -               return "<span><a href=\"".
157 -                       cgiurl(
158 -                               do => "create",
159 -                               page => pagetitle(lc($link), 1),
160 -                               from => $lpage
161 -                       ).
162 +               my $url = cgiurl(
163 +                                do => "create",
164 +                                page => pagetitle(lc($link), 1),
165 +                                from => $lpage
166 +                               );
167 +
168 +               if ($hooks{htmlescapelink}{$type}){
169 +                       return $hooks{htmlescapelink}{$type}->($url, $linktext,
170 +                                                              broken => 1);
171 +               }
172 +               return "<span><a href=\"". $url.
173                         "\">?</a>$linktext</span>"
174         }
175         
176 @@ -514,6 +520,9 @@
177                 $bestlink.="#".$opts{anchor};
178         }
179  
180 +       if ($hooks{htmlescapelink}{$type}) {
181 +         return $hooks{htmlescapelink}{$type}->($bestlink, $linktext);
182 +       }
183         return "<a href=\"$bestlink\">$linktext</a>";
184  } #}}}
185  
186 @@ -628,6 +637,14 @@
187                                 preview => $preprocess_preview,
188                         );
189                         $preprocessing{$page}--;
190 +
191 +                       # Handle escaping html if the htmlizer needs it.
192 +                       if ($ret =~ /[<>]/ && $pagesources{$page}) {
193 +                               my $type=pagetype($pagesources{$page});
194 +                               if ($hooks{htmlescape}{$type}) {
195 +                                       return $ret = $hooks{htmlescape}{$type}->($ret);
196 +                               }
197 +                       }
198                         return $ret;
199                 }
200                 else {
201 </pre>