X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/b19d0d3d245c7c2b605ac6c972c73c909a941db4..586e6e33621916d5177f0493bad54810de3149dc:/doc/plugins/po.mdwn?ds=sidebyside diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn index eeeabe730..f6405f3b3 100644 --- a/doc/plugins/po.mdwn +++ b/doc/plugins/po.mdwn @@ -198,14 +198,18 @@ Also, when the plugin has just been enabled, or when a page has just been declared as being translatable, the needed POT and PO files are created, and the PO files are checked into version control. -Discussion pages ----------------- +Discussion pages and other sub-pages +------------------------------------ Discussion should happen in the language in which the pages are written for real, *i.e.* the "master" one. If discussion pages are enabled, "slave" pages therefore link to the "master" page's discussion page. +Likewise, "slave" pages are not supposed to have sub-pages; +[[WikiLinks|wikilink]] that appear on a "slave" page therefore link to +the master page's sub-pages. + Translating ----------- @@ -215,6 +219,22 @@ interface could also be implemented at some point). If [[tips/untrusted_git_push]] is setup, one can edit the PO files in one's preferred `$EDITOR`, without needing to be online. +Markup languages support +------------------------ + +Markdown is well supported. Some other markup languages supported by +ikiwiki mostly work, but some pieces of syntax are not rendered +correctly on the slave pages: + +* [[reStructuredText|rst]]: anonymous hyperlinks and internal + cross-references +* [[wikitext]]: conversion of newlines to paragraphs +* [[creole]]: verbatim text is wrapped, tables are broken +* [[html]] and LaTeX: not supported yet; the dedicated po4a modules + could be used to support them, but they would need a security audit +* other markup languages have not been tested. + + TODO ==== @@ -379,6 +399,10 @@ use in our case, I suggest we define `ENV{COLUMNS}` before loading `refreshpofiles()` runs this external program. A po4a developer answered he does "not expect any security issues from it". +### msgfmt + +`isvalidpo()` runs this external program. Its security should be checked. + ### Fuzzing input I was not able to find any public information about gettext or po4a @@ -499,63 +523,70 @@ gettext/po4a rough corners Better links ------------ -### Subpages - -On a translation page, links to subpages should actually be links to -the master page's subpages. They currently appear as broken links. - ### Page title in links -To use the page titles set with the [[meta|plugins/meta]] plugin when -rendering links would be very much nicer, than the current -"filename.LL" format. This is actually a duplicate for -[[bugs/pagetitle_function_does_not_respect_meta_titles]]. +Using the fix to +[[bugs/pagetitle_function_does_not_respect_meta_titles]] from +[[intrigeri]]'s `meta` branch, the generated links' text is based on +the page titles set with the [[meta|plugins/meta]] plugin. This has to +be merged upstream, though. -Going to work on this in my `meta` branch. +Translation quality assurance +----------------------------- -### Translation status in links +Modifying a PO file via the CGI is already forbidden if the new +version is not a valid PO file. As a bonus, check that it provides +a more complete translation than the existing one. -See [[contrib/po]]. +Note: committing to the underlying repository is a way to bypass +this check. -### Backlinks +Robustness tests +---------------- -They are not updated when the source page changes (e.g. meta title). +### Disabling the plugin -Page formats ------------- +- enabling the plugin with `po_translatable_pages` set +- enabling the plugin without `po_translatable_pages` set: **OK** +- disabling the plugin: **OK** -Markdown is well supported, great, but what about others? +### Changing the plugin config -The [[po|plugins/po]] uses `Locale::Po4a::Text` for every page format; -this can be expected to work out of the box with most other wiki-like -formats supported by ikiwiki. Some of their ad-hoc syntax might be -parsed in a strange way, but the worst problems I can imagine would be -wrapping issues; e.g. there is code in po4a dedicated to prevent -re-wrapping the underlined Markdown headers. +- adding existing pages to `po_translatable_pages`: **OK** +- removing existing pages from `po_translatable_pages`: **OK** +- adding a language to `po_slave_languages`: **OK** +- removing a language from `po_slave_languages`: **OK** +- changing `po_master_language`: **OK** +- replacing `po_master_language` with a language previously part of + `po_slave_languages`: needs two rebuilds, but **OK** (this is quite + a perverse test actually) -While it would be easy to better support formats such as [[html]] or -LaTeX, by using for each one the dedicated po4a module, this can be -problematic from a security point of view. +### Creating pages -**TODO**: test the more popular formats and write proper documentation -about it. +- creating a master page via RCS: **OK** +- creating a master page via CGI: **OK** -Translation quality assurance ------------------------------ +### Deleting pages -Modifying a PO file via the CGI must be forbidden if the new version -is not a valid PO file. As a bonus, check that it provides a more -complete translation than the existing one. +- removing a master page via RCS: **OK** +- removing a translation via RCS: **OK** +- removing a master page via CGI: **OK** +- removing a translation via CGI: **OK** -A new `cansave` type of hook would be needed to implement this. +### Renaming pages -Note: committing to the underlying repository is a way to bypass -this check. +- renaming a master page via RCS: **OK** (but the old translations + are lost, because not all RCS track file renaming) +- renaming a master page and its translations via RCS: **OK** +- renaming a master page via CGI: **OK** +- renaming a translation via RCS +- renaming a translation via CGI -Creating new pages on the web ------------------------------ +### Misc -See [[contrib/po]]. +- general test with `usedirs` disabled: **OK** +- general test with `indexpages` enabled +- general test with `po_link_to=default` Documentation ------------- @@ -563,3 +594,11 @@ Documentation Maybe write separate documentation depending on the people it targets: translators, wiki administrators, hackers. This plugin may be complex enough to deserve this. + +Gettext-ize the plugin code. + +Misc +---- + +* Can the form validation system be used instead of creating the + `cansave` hook?