]> sipb.mit.edu Git - ikiwiki.git/blob - doc/plugins/po/discussion.mdwn
simplify formbuilder stylesheet specification
[ikiwiki.git] / doc / plugins / po / discussion.mdwn
1 [[!toc ]]
2
3 ----
4
5 # Security review
6
7 ## Probable holes
8
9 _(The list of things to fix.)_
10
11 ### po4a-gettextize
12
13 * po4a CVS 2009-01-16
14 * Perl 5.10.0
15
16 `po4a-gettextize` uses more or less the same po4a features as our
17 `refreshpot` function.
18
19 Without specifying an input charset, zzuf'ed `po4a-gettextize` quickly
20 errors out, complaining it was not able to detect the input charset;
21 it leaves no incomplete file on disk. I therefore had to pretend the
22 input was in UTF-8, as does the po plugin.
23
24         zzuf -c -s 13 -r 0.1 \
25             po4a-gettextize -f text -o markdown -M utf-8 -L utf-8 \
26              -m GPL-3 -p GPL-3.pot
27
28 Crashes with:
29
30         Malformed UTF-8 character (UTF-16 surrogate 0xdfa4) in substitution
31         iterator at /usr/share/perl5/Locale/Po4a/Po.pm line 1449.
32         Malformed UTF-8 character (fatal) at /usr/share/perl5/Locale/Po4a/Po.pm
33         line 1449.
34
35 An incomplete pot file is left on disk. Unfortunately Po.pm tells us
36 nothing about the place where the crash happens.
37
38 > It's fairly standard perl behavior when fed malformed utf-8. As long
39 > as it doesn't crash ikiwiki, it's probably acceptable. Ikiwiki can
40 > do some similar things itself when fed malformed utf-8 (doesn't
41 > crash tho) --[[Joey]]
42
43 ----
44
45 ## Potential gotchas
46
47 _(Things not to do.)_
48
49
50 ### Blindly activating more po4a format modules
51
52 The format modules we want to use have to be checked, as not all are
53 safe (e.g. the LaTeX module's behaviour is changed by commands
54 included in the content); they may use regexps generated from
55 the content.
56
57 ----
58
59 ## Hopefully non-holes
60
61 _(AKA, the assumptions that will be the root of most security holes...)_
62
63 ### PO file features
64
65 No [documented](http://www.gnu.org/software/gettext/manual/gettext.html#PO-Files)
66 directive that can be put in po files is supposed to cause mischief
67 (ie, include other files, run commands, crash gettext, whatever).
68
69 ### gettext
70
71 #### Security history
72
73 The only past security issue I could find in GNU gettext is
74 [CVE-2004-0966](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2004-0966),
75 *i.e.* [Debian bug #278283](http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=278283):
76 the autopoint and gettextize scripts in the GNU gettext package (1.14
77 and later versions) may allow local users to overwrite files via
78 a symlink attack on temporary files.
79
80 This plugin would not have allowed to exploit this bug, as it does not
81 use, either directly or indirectly, the faulty scripts.
82
83 Note: the lack of found security issues can either indicate that there
84 are none, or reveal that no-one ever bothered to find or publish them.
85
86 #### msgmerge
87
88 `refreshpofiles()` runs this external program.
89
90 * I was not able to crash it with `zzuf`.
91 * I could not find any past security hole.
92
93 #### msgfmt
94
95 `isvalidpo()` runs this external program.
96
97 * I was not able to make it behave badly using zzuf: it exits cleanly
98   when too many errors are detected.
99 * I could not find any past security hole.
100
101 ### po4a
102
103 #### Security history
104
105 The only past security issue I could find in po4a is
106 [CVE-2007-4462](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2007-4462):
107 `lib/Locale/Po4a/Po.pm` in po4a before 0.32 allowed local users to
108 overwrite arbitrary files via a symlink attack on the
109 gettextization.failed.po temporary file.
110
111 This plugin would not have allowed to exploit this bug, as it does not
112 use, either directly or indirectly, the faulty `gettextize` function.
113
114 Note: the lack of found security issues can either indicate that there
115 are none, or reveal that no-one ever bothered to find or publish them.
116
117 #### General feeling
118
119 Are there any security issues on running po4a on untrusted content?
120
121 To say the least, this issue is not well covered, at least publicly:
122
123 * the documentation does not talk about it;
124 * grep'ing the source code for `security` or `trust` gives no answer.
125
126 On the other hand, a po4a developer answered my questions in
127 a convincing manner, stating that processing untrusted content was not
128 an initial goal, and analysing in detail the possible issues.
129 The following analysis was done with his help.
130
131 #### Details
132
133 * the core (`Po.pm`, `Transtractor.pm`) should be safe
134 * po4a source code was fully checked for other potential symlink
135   attacks, after discovery of one such issue
136 * the only external program run by the core is `diff`, in `Po.pm` (in
137   parts of its code we don't use)
138 * `Locale::gettext` is only used to display translated error messages
139 * Nicolas Fran├žois "hopes" `DynaLoader` is safe, and has "no reason to
140   think that `Encode` is not safe"
141 * Nicolas Fran├žois has "no reason to think that `Encode::Guess` is not
142   safe". The po plugin nevertheless avoids using it by defining the
143   input charset (`file_in_charset`) before asking `TransTractor` to
144   read any file. NB: this hack depends on po4a internals.
145
146 ##### Locale::Po4a::Text
147
148 * does not run any external program
149 * only `do_paragraph()` builds regexp's that expand untrusted
150   variables; according to [[Joey]], this is "Freaky code, but seems ok
151   due to use of `quotementa`".
152
153 ##### Text::WrapI18N
154
155 `Text::WrapI18N` can cause DoS
156 ([Debian bug #470250](http://bugs.debian.org/470250)).
157 It is optional, and we do not need the features it provides.
158
159 If a recent enough po4a (>=0.35) is installed, this module's use is
160 fully disabled. Else, the wiki administrator is warned about this
161 at runtime.
162
163 ##### Term::ReadKey
164
165 `Term::ReadKey` is not a hard dependency in our case, *i.e.* po4a
166 works nicely without it. But the po4a Debian package recommends
167 `libterm-readkey-perl`, so it will probably be installed on most
168 systems using the po plugin.
169
170 `Term::ReadKey` has too far reaching implications for us to
171 be able to guarantee anything wrt. security.
172
173 If a recent enough po4a (>=2009-01-15 CVS, which will probably be
174 released as 0.35) is installed, this module's use is fully disabled.
175
176 ##### Fuzzing input
177
178 ###### po4a-translate
179
180 * po4a CVS 2009-01-16
181 * Perl 5.10.0
182
183 `po4a-translate` uses more or less the same po4a features as our
184 `filter` function.
185
186 Without specifying an input charset, same behaviour as
187 `po4a-gettextize`, so let's specify UTF-8 as input charset as of now.
188
189 `LICENSES` is a 21M file containing 100 concatenated copies of all the
190 files in `/usr/share/common-licenses/`; I had no existing PO file or
191 translated versions at hand, which renders these tests
192 quite incomplete.
193
194         zzuf -cv -s 0:10 -r 0.001:0.3 \
195           po4a-translate -d -f text -o markdown -M utf-8 -L utf-8 \
196             -k 0 -m LICENSES -p LICENSES.fr.po -l test.fr
197
198 ... seems to lose the fight, at the `readpo(LICENSES.fr.po)` step,
199 against some kind of infinite loop, deadlock, or any similar beast.
200
201 The root of this bug lies in `Text::WrapI18N`, see the corresponding
202 section.
203
204
205 ----
206
207 ## Fixed holes
208
209
210 ----
211
212 # original contrib/po page, with old commentary
213
214 I've been working on a plugin called "po", that adds support for multi-lingual wikis,
215 translated with gettext, using [po4a](http://po4a.alioth.debian.org/).
216
217 More information:
218
219 * It can be found in my "po" branch:
220   `git clone git://gaffer.ptitcanardnoir.org/ikiwiki.git`
221 * It is self-contained, *i.e.* it does not modify ikiwiki core at all.
222 * It is documented (including TODO and plans for next work steps) in
223   `doc/plugins/po.mdwn`, which can be found in the same branch.
224 * No public demo site is available so far, I'm working on this.
225
226 My plan is to get this plugin clean enough to be included in ikiwiki.
227
228 The current version is a proof-of-concept, mature enough for me to dare submitting it here,
229 but I'm prepared to hear various helpful remarks, and to rewrite parts of it as needed.
230
231 Any thoughts on this?
232
233 > Well, I think it's pretty stunning what you've done here. Seems very
234 > complete and well thought out. I have not read the code in great detail
235 > yet.
236
237 > Just using po files is an approach I've never seen tried with a wiki. I
238 > suspect it will work better for some wikis than others. For wikis that
239 > just want translations that match the master language as closely as
240 > possible and don't wander off and diverge, it seems perfect. (But what happens
241 > if someone edits the Discussion page of a translated page?)
242
243 > Please keep me posted, when you get closer to having all issues solved
244 > and ready for merging I can do a review and hopefully help with the
245 > security items you listed. --[[Joey]]
246
247 >> Thanks a lot for your quick review, it's reassuring to hear such nice words
248 >> from you. I did not want to design and write a full translation system, when
249 >> tools such as gettext/po4a already have all the needed functionality, for cases
250 >> where the master/slave languages paradigm fits.
251 >> Integrating these tools into ikiwiki plugin system was a pleasure.
252 >>
253 >> I'll tell you when I'm ready for merging, but in the meantime,
254 >> I'd like you to review the changes I did to the core (3 added hooks).
255 >> Can you please do this? If not, I'll go on and hope I'm not going to far in
256 >> the wrong direction.
257 >>
258 >>> Sure.. I'm not completly happy with any of the hooks since they're very
259 >>> special purpose, and also since `run_hooks` is not the best interface
260 >>> for a hook that modifies a variable, where only the last hook run will
261 >>> actually do anything. It might be better to just wrap
262 >>> `targetpage`, `bestlink`, and `beautify_urlpath`. But, I noticed
263 >>> the other day that such wrappers around exported functions are only visible by
264 >>> plugins loaded after the plugin that defines them.
265 >>> 
266 >>> Update: Take a look at the new "Function overriding" section of
267 >>> [[plugins/write]]. I think you can just inject wrappers about a few ikiwiki
268 >>> functions, rather than adding hooks. The `inject` function is pretty
269 >>> insane^Wlow level, but seems to work great. --[[Joey]]
270 >>>
271 >>>> Thanks a lot, it seems to be a nice interface for what I was trying to achieve.
272 >>>> I may be forced to wait two long weeks before I have a chance to confirm
273 >>>> this. Stay tuned. --[[intrigeri]]
274 >>>>
275 >>>>> I've updated the plugin to use `inject`. It is now fully self-contained,
276 >>>>> and does not modify the core anymore. --[[intrigeri]]
277 >>
278 >> The Discussion pages issue is something I am not sure about yet. But I will
279 >> probably decide that "slave" pages, being only translations, don't deserve
280 >> a discussion page: the discussion should happen in the language in which the
281 >> pages are written for real, which is the "master" one. --[[intrigeri]]
282 >> 
283 >> I think that's a good decision, you don't want to translate discussion,
284 >> and if the discussion page turns out multilingual, well, se la vi. ;-)
285 >> 
286 >> Relatedly, what happens if a translated page has a broken link, and you
287 >> click on it to edit it? Seems you'd first have to create a master page
288 >> and could only then translate it, right? I wonder if this will be clear
289 >> though to the user.
290 >>
291 >>> Right: a broken link points to the URL that allows to create
292 >>> a page that can either be a new master page or a non-translatable
293 >>> page, depending on `po_translatable_pages` value. The best
294 >>> solution I can thing of is to use [[plugins/edittemplate]] to
295 >>> insert something like "Warning: this is a master page, that must
296 >>> be written in $MASTER_LANGUAGE" into newly created master pages,
297 >>> and maybe another warning message on newly created
298 >>> non-translatable pages. It seems quite doable to me, but in order
299 >>> to avoid breaking existing functionality, it implies to hack a bit
300 >>> [[plugins/edittemplate]] so that multiple templates can be
301 >>> inserted at page creation time. [[--intrigeri]]
302 >>>
303 >>>> I implemented such a warning using the formbuilder_setup hook.
304 >>>> --[[intrigeri]]
305 >>
306 >> And also, is there any way to start a translation of a page into a new
307 >> lanauge using the web interface?
308 >>
309 >>> When a new language is added to `po_slave_languages`, a rebuild is
310 >>> triggered, and all missing PO files are created and checked into
311 >>> VCS. An unpriviledged wiki user can not add a new language to
312 >>> `po_slave_languages`, though. One could think of adding the needed
313 >>> interface to translate a page into a yet-unsupported slave
314 >>> language, and this would automagically add this new language to
315 >>> `po_slave_languages`. It would probably be useful in some
316 >>> usecases, but I'm not comfortable with letting unpriviledged wiki
317 >>> users change the wiki configuration as a side effect of their
318 >>> actions; if this were to be implemented, special care would be
319 >>> needed. [[--intrigeri]]
320 >>>
321 >>>> Actually I meant into any of the currently supported languages.
322 >>>> I guess that if the template modification is made, it will list those
323 >>>> languages on the page, and if a translation to a language is missing,
324 >>>> the link will allow creating it?
325 >>>>
326 >>>>> Any translation page always exist for every supported slave
327 >>>>> language, even if no string at all have been translated yet.
328 >>>>> This implies the po plugin is especially friendly to people who
329 >>>>> prefer reading in their native language if available, but don't
330 >>>>> mind reading in English else.
331 >>>>>
332 >>>>> While I'm at it, there is a remaining issue that needs to be
333 >>>>> sorted out: how painful it could be for non-English speakers
334 >>>>> (assuming the master language is English) to be perfectly able
335 >>>>> to navigate between translation pages supposed to be written in
336 >>>>> their own language, when their translation level is most
337 >>>>> often low.
338 >>>>>
339 >>>>> (It is currently easy to display this status on the translation
340 >>>>> page itself, but then it's too late, and how frustrating to load
341 >>>>> a page just to realize it's actually not translated enough for
342 >>>>> you. The "other languages" loop also allows displaying this
343 >>>>> information, but it is generally not the primary
344 >>>>> navigation tool.)
345 >>>>>
346 >>>>> IMHO, this is actually a social problem (i.e. it's no use adding
347 >>>>> a language to the supported slave ones if you don't have the
348 >>>>> manpower to actually do the translations), that can't be fully
349 >>>>> solved by technical solutions, but I can think of some hacks
350 >>>>> that would limit the negative impact: a given translation's
351 >>>>> status (currently = percent translated) could be displayed next
352 >>>>> to the link that leads to it; a color code could as well be used
353 >>>>> ("just" a matter of adding a CSS id or class to the links,
354 >>>>> depending on this variable). As there is already work to be done
355 >>>>> to have the links text generation more customizable through
356 >>>>> plugins, I could do both at the same time if we consider this
357 >>>>> matter to be important enough. --[[intrigeri]]
358 >>>>>
359 >>>>>> The translation status in links is now implemented in my
360 >>>>>> `po`branch. It requires my `meta` branch changes to
361 >>>>>> work, though. I consider the latter to be mature enough to
362 >>>>>> be merged. --[[intrigeri]]
363
364 >> FWIW, I'm tracking your po branch in ikiwiki master git in the po
365 >> branch. One thing I'd like to try in there is setting up a translated
366 >> basewiki, which seems like it should be pretty easy to do, and would be
367 >> a great demo! --[[Joey]]
368 >>
369 >>> I have a complete translation of basewiki into danish, available merged into
370 >>> ikiwiki at git://source.jones.dk/ikiwiki-upstream (branch underlay-da), and am working with
371 >>> others on preparing one in german.  For a complete translated user
372 >>> experience, however, you will also need templates translated (there are a few
373 >>> translatable strings there too).  My most recent po4a Markdown improvements
374 >>> adopted upstream but not yet in Debian (see
375 >>> [bug#530574](http://bugs.debian.org/530574)) correctly handles multiple
376 >>> files in a single PO which might be relevant for template translation handling.
377 >>> --[[JonasSmedegaard]]
378 >>
379 >>> I've merged your changes into my own branch, and made great
380 >>> progress on the various todo items. Please note my repository
381 >>> location has changed a few days ago, my user page was updated
382 >>> accordingly, but I forgot to update this page at the same time.
383 >>> Hoping it's not too complicated to relocated an existing remote...
384 >>> (never done that, I'm a Git beginner as well as a Perl
385 >>> newbie) --[[intrigeri]]
386 >>>>
387 >>>> Just a matter of editing .git/config, thanks for the heads up.
388 >>>>>
389 >>>>> Joey, please have a look at my branch, your help would be really
390 >>>>> welcome for the security research, as I'm almost done with what
391 >>>>> I am able to do myself in this area. --[[intrigeri]]
392 >>>>>>
393 >>>>>> I came up with a patch for the WrapI18N issue --[[Joey]]
394
395 I've set this plugin development aside for a while. I will be back and
396 finish it at some point in the first quarter of 2009. --[[intrigeri]]
397
398 > Abstract: Joey, please have a look at my po and meta branches.
399
400 > Detailed progress report:
401
402 > * it seems the po branch in your repository has not been tracking my
403 >   own po branch for two months. any config issue?
404 > * all the plugin's todo items have been completed, robustness tests
405 >   done
406 > * I've finished the detailed security audit, and the fix for po4a
407 >   bugs has entered upstream CVS last week
408 > * I've merged your new `checkcontent` hook with the `cansave` hook
409 >   I previously introduced in my own branch; blogspam plugin updated
410 >   accordingly
411 > * the rename hook changes we discussed elsewhere are also part of my
412 >   branch
413 > * I've introduced two new hooks (`canremove` and `canrename`), not
414 >   a big deal; IMHO, they extend quite logically the plugin interface
415 > * as highlighted on [[bugs/pagetitle_function_does_not_respect_meta_titles]],
416 >   my `meta` branch contains a new feature that is really useful in a
417 >   translatable wiki
418
419 > As a conclusion, I'm feeling that my branches are ready to be
420 > merged; only thing missing, I guess, are a bit of discussion and
421 > subsequent adjustments.
422
423 > --[[intrigeri]]
424
425 > I've looked it over and updated my branch with some (untested)
426 > changes.
427
428 >> I've merged your changes into my branch. Only one was buggy.
429
430 > Sorry, I'd forgotten about your cansave hook.. sorry for the duplicate
431 > work there.
432
433 > Reviewing the changes, mostly outside of `po.pm`, I have
434 > the following issues.
435 >  
436 > * renamepage to renamelink change would break the ikiwiki
437 >   3.x API, which I've promised not to do, so needs to be avoided
438 >   somehow. (Sorry, I guess I dropped the ball on not getting this
439 >   API change in before cutting 3.0..)
440 >> 
441 >> Fixed, see [[todo/need_global_renamepage_hook]].
442 >>
443 > * I don't understand the parentlinks code change and need to figure it
444 >   out. Can you explain what is going on there?
445 >> 
446 >> I'm calling `bestlink` there so that po's injected `bestlink` is
447 >> run. This way, the parent links of a page link to the parent page
448 >> version in the proper language, depending on the
449 >> `po_link_to=current` and `po_link_to=negotiated` settings.
450 >> Moreover, when using my meta branch enhancements plus meta title to
451 >> make pages titles translatable, this small patch is needed to get
452 >> the translated titles into parentlinks.
453 >> 
454 > * canrename's mix of positional and named parameters is way too
455 >   ugly to get into an ikiwiki API. Use named parameters
456 >   entirely. Also probably should just use named parameters
457 >   for canremove.
458 > * `skeleton.pm.example`'s canrename needs fixing to use either
459 >   the current or my suggested parameters.
460 >> 
461 >> Done.
462 >> 
463 > * I don't like the exporting of `%backlinks` and `$backlinks_calculated`
464 >   (the latter is exported but not used).
465 >> 
466 >> The commit message for 85f865b5d98e0122934d11e3f3eb6703e4f4c620
467 >> contains the rationale for this change. I guess I don't understand
468 >> the subtleties of `our` use, and perldoc does not help me a lot.
469 >> IIRC, I actually did not use `our` to "export" these variables, but
470 >> rather to have them shared between `Render.pm` uses.
471 >>
472 >>> My wording was unclear, I meant exposing. --[[Joey]]
473 >>>  
474 >>>> I guess I still don't know Perl's `our` enough to understand clearly.
475 >>>> No matter whether these variables are declared with `my` or `our`,
476 >>>> any plugin can `use IkiWiki::Render` and then access
477 >>>> `$IkiWiki::backlinks`, as already does e.g. the pagestat plugin.
478 >>>> So I guess your problem is not with letting plugins use these
479 >>>> variables, but with them being visible for every piece of
480 >>>> (possibly external) code called from `Render.pm`. Am I right?
481 >>>> If I understand clearly, using a brace block to lexically enclose
482 >>>> these two `our` declarations, alongside with the `calculate_backlinks`
483 >>>> and `backlinks` subs definitions, would be a proper solution, wouldn't
484 >>>> it? --[[intrigeri]]
485 >>>>
486 >>>>> No, %backlinks and the backlinks() function are not the same thing.
487 >>>>> The variable is lexically scoped; only accessible from inside
488 >>>>> `Render.pm` --[[Joey]] 
489 >>>> 
490 > * What is this `IkiWiki::nicepagetitle` and why are you
491 >   injecting it into that namespace when only your module uses it?
492 >   Actually, I can't even find a caller of it in your module.
493 >> 
494 >> I guess you should have a look to my `meta` branch and to
495 >> [[bugs/pagetitle_function_does_not_respect_meta_titles]] in order
496 >> to understand this :)
497 >>
498 >>> It would probably be good if I could merge this branch without 
499 >>> having to worry about also immediatly merging that one. --[[Joey]] 
500 >>> 
501 >>>> I removed all dependencies on my `meta` branch from the `po` one.
502 >>>> This implied removing the `po_translation_status_in_links` and
503 >>>> `po_strictly_refresh_backlinks` features, and every link text is now
504 >>>> displayed in the master language. I believe the removed features really
505 >>>> enhance user experience of a translatable wiki, that's why I was
506 >>>> initially supposing the `meta` branch would be merged first.
507 >>>> IMHO, we'll need to come back to this quite soon after `po` is merged.
508 >>>> --[[intrigeri]]
509 >>>>
510 >>>> Maybe you should keep those features in a meta-po branch?
511 >>>> I did a cursory review of your meta last night, have some issues with it, 
512 >>>> but this page isn't the place for a detailed review. --[[Joey]] 
513 >>>>
514 >>>>> Done. --[[intrigeri]]
515 >>> 
516 > * I'm very fearful of the `add_depends` in `postscan`. 
517 >   Does this make every page depend on every page that links
518 >   to it? Won't this absurdly bloat the dependency pagespecs
519 >   and slow everything down? And since nicepagetitle is given
520 >   as the reason for doing it, and nicepagetitle isn't used,
521 >   why do it?
522 >> 
523 >> As explained in the 85f865b5d98e0122934d11e3f3eb6703e4f4c620 log:
524 >> this feature hits performance a bit. Its cost was quite small in my
525 >> real-world use-cases (a few percents bigger refresh time), but
526 >> could be bigger in worst cases. When using the po plugin with my
527 >> meta branch changes (i.e. the `nicepagetitle` thing), and having
528 >> enabled the option to display translation status in links, this
529 >> maintains the translation status up-to-date in backlinks. Same when
530 >> using meta title to make the pages titles translatable. It does
531 >> help having a nice and consistent translated wiki, but as it can
532 >> also involve problems, I just turned it into an option.
533 >> 
534 >>> This has been completely removed for now due to the removal of
535 >>> the dependency on my `meta` branch. --[[intrigeri]]
536 >> 
537 > * The po4a Suggests should be versioned to the first version
538 >   that can be used safely, and that version documented in 
539 >   `plugins/po.mdwn`.
540 >>
541 >> Done.
542 >> 
543 >> --[[intrigeri]]
544
545 > --[[Joey]] 
546
547 I reverted the `%backlinks` and `$backlinks_calculated` exposing.
548 The issue they were solving probably will arise again when I'll work
549 on my meta branch again (i.e. when the simplified po one is merged),
550 but the po thing is supposed to work without these ugly `our`.
551 Seems like it was the last unaddressed item from Joey's review, so I'm
552 daring a timid "please pull"... or rather, please review again :)
553 --[[intrigeri]]
554
555 > Ok, I've reviewed and merged into my own po branch. It's looking very
556 > mergeable.
557
558 > * Is it worth trying to fix compatability with `indexpages`?
559 >> 
560 >> Supporting `usedirs` being enabled or disabled was already quite
561 >> hard IIRC, so supporting all four combinations of `usedirs` and
562 >> `indexpages` settings will probably be painful. I propose we forget
563 >> about it until someone reports he/she badly needs it, and then
564 >> we'll see what can be done.
565 >> 
566 > * Would it make sense to go ahead and modify `page.tmpl` to use
567 >   OTHERLANGUAGES and PERCENTTRANSLATED, instead of documenting how to modify it?
568 >> 
569 >> Done in my branch.
570 >> 
571 > * Would it be better to disable po support for pages that use unsupported
572 >   or poorly-supported markup languages?
573
574 >> I prefer keeping it enabled, as:
575 >> 
576 >> * most wiki markups "almost work"
577 >> * when someone needs one of these to be fully supported, it's not
578 >>   that hard to add dedicated support for it to po4a; if it were
579 >>   disabled, I fear the ones who could do this would maybe think
580 >>   it's blandly impossible and give up.
581 >> 
582  
583 > * What's the reasoning behind checking that the link plugin
584 >   is enabled? AFAICS, the same code in the scan hook should
585 >   also work when other link plugins like camelcase are used.
586 >> 
587 >> That's right, fixed.
588 >> 
589 > * In `pagetemplate` there is a comment that claims the code
590 >   relies on `genpage`, but I don't see how it does; it seems
591 >   to always add a discussion link?
592 >> 
593 >> It relies on IkiWiki::Render's `genpage` as this function sets the
594 >> `discussionlink` template param iff it considers a discussion link
595 >> should appear on the current page. That's why I'm testing
596 >> `$template->param('discussionlink')`.
597 >> 
598 >>> Maybe I was really wondering why it says it could lead to a broken
599 >>> link if the cgiurl is disabled. I think I see why now: Discussionlink
600 >>> will be set to a link to an existing disucssion page, even if cgi is
601 >>> disabled -- but there's no guarantee of a translated discussion page
602 >>> existing in that case. *However*, htmllink actually checks
603 >>> for this case, and will avoid generating a broken link so AFAICS, the
604 >>> comment is actually innacurate.. what will really happen in this case
605 >>> is discussionlink will be set to a non-link translation of
606 >>> "discussion". Also, I consider `$config{cgi}` and `%links` (etc)
607 >>> documented parts of the plugin interface, which won't change; po could
608 >>> rely on them to avoid this minor problem. --[[Joey]] 
609 >>>> 
610 >>>> Done in my branch. --[[intrigeri]]
611 >>>> 
612 >
613 > * Is there any real reason not to allow removing a translation?
614 >   I'm imagining a spammy translation, which an admin might not
615 >   be able to fix, but could remove.
616 >> 
617 >> On the other hand, allowing one to "remove" a translation would
618 >> probably lead to misunderstandings, as such a "removed" translation
619 >> page would appear back as soon as it is "removed" (with no strings
620 >> translated, though). I think an admin would be in a position to
621 >> delete the spammy `.po` file by hand using whatever VCS is in use.
622 >> Not that I'd really care, but I am slightly in favour of the way
623 >> it currently works.
624 >>
625 >>> That would definitly be confusing. It sounds to me like if we end up
626 >>> needing to allow web-based deletion of spammy translations, it will
627 >>> need improvements to the deletion UI to de-confuse that. It's fine to
628 >>> put that off until needed --[[Joey]] 
629 >> 
630 > * Re the meta title escaping issue worked around by `change`. 
631 >   I suppose this does not only affect meta, but other things
632 >   at scan time too. Also, handling it only on rebuild feels
633 >   suspicious -- a refresh could involve changes to multiple
634 >   pages and trigger the same problem, I think. Also, exposing
635 >   this rebuild to the user seems really ugly, not confidence inducing.
636 >   
637 >   So I wonder if there's a better way. Such as making po, at scan time,
638 >   re-run the scan hooks, passing them modified content (either converted
639 >   from po to mdwn or with the escaped stuff cheaply de-escaped). (Of
640 >   course the scan hook would need to avoid calling itself!)
641
642 >   (This doesn't need to block the merge, but I hope it can be addressed
643 >   eventually..)
644 >  
645 > --[[Joey]] 
646 >> 
647 >> I'll think about it soon.
648 >> 
649 >> --[[intrigeri]]
650 >>
651 >>> Did you get a chance to? --[[Joey]] 
652
653  * As discussed at [[todo/l10n]] the templates needs to be translatable too.  They
654    should be treated properly by po4a using the markdown option - at least with my
655    later patches in [bug#530574](http://bugs.debian.org/530574)) applied.
656
657  * It seems to me that the po plugin (and possibly other parts of ikiwiki) wrongly
658    uses gettext.  As I understand it, gettext (as used currently in ikiwiki) always
659    lookup a single language, That might make sense for a single-language site, but
660    multilingual sites should emit all strings targeted at the web output in each own
661    language.
662
663    So generally the system language (used for e.g. compile warnings) should be separated
664    from both master language and slave languages.
665
666    Preferrably the gettext subroutine could be extended to pass locale as optional
667    secondary parameter overriding the default locale (for messages like "N/A" as
668    percentage in po plugin).  Alternatively (with above mentioned template support)
669    all such strings could be externalized as templates that can then be localized.
670
671 # Robustness tests
672
673 ### Enabling/disabling the plugin
674
675 * enabling the plugin with `po_translatable_pages` set to blacklist: **OK**
676 * enabling the plugin with `po_translatable_pages` set to whitelist: **OK**
677 * enabling the plugin without `po_translatable_pages` set: **OK**
678 * disabling the plugin: **OK**
679
680 ### Changing the plugin config
681
682 * adding existing pages to `po_translatable_pages`: **OK**
683 * removing existing pages from `po_translatable_pages`: **OK**
684 * adding a language to `po_slave_languages`: **OK**
685 * removing a language from `po_slave_languages`: **OK**
686 * changing `po_master_language`: **OK**
687 * replacing `po_master_language` with a language previously part of
688   `po_slave_languages`: needs two rebuilds, but **OK** (this is quite
689   a perverse test actually)
690
691 ### Creating/deleting/renaming pages
692
693 All cases of master/slave page creation/deletion/rename, both via RCS
694 and via CGI, have been tested.
695
696 ### Misc
697
698 * general test with `usedirs` disabled: **OK**
699 * general test with `indexpages` enabled: **not OK**
700 * general test with `po_link_to=default` with `userdirs` enabled: **OK**
701 * general test with `po_link_to=default` with `userdirs` disabled: **OK**
702
703 Duplicate %links ?
704 ------------------
705
706 I notice code in the scan hook that seems to assume
707 that %links will accumulate duplicate links for a page.
708 That used to be so, but the bug was fixed. Does this mean
709 that po might be replacing the only link on a page, in error? 
710 --[[Joey]] 
711
712 > It would replace it. The only problematic case is when another
713 > plugin has its own reasons, in its `scan` hook, to add a page
714 > that is already there to `$links{$page}`. This other plugin's
715 > effect might then be changed by po's `scan` hook... which could
716 > be either good (better overall l10n) or bad (break the other
717 > plugin's goal). --[[intrigeri]]
718
719 >> Right.. well, the cases where links are added is very small.
720 >> Grepping for `add_link`, it's just done by link, camelcase, meta, and
721 >> tag. All of these are supposed to work just link regular links
722 >> so I'd think that is ok. We could probably remove the currently scary
723 >> comment about only wanting to change the first link. --[[Joey]] 
724
725 >>> Commit 3c2bffe21b91684 in my po branch does this. --[[intrigeri]]
726 >>>> Cherry-picked --[[Joey]]