Merge branch 'master' of ssh://git.ikiwiki.info/srv/git/ikiwiki.info
[ikiwiki.git] / doc / todo / need_global_renamepage_hook.mdwn
1 As documented in [[plugins/write]], the current `renamepage` hook is
2 heavily oriented towards updating links in pages' content:  it is run
3 once per page linking to the renamed page.
4
5 That's fine, but it can't be used to trigger more general actions on
6 page rename. E.g. it won't be run at all if the page being renamed is
7 an orphan one.
8
9 This is a real issue for the [[plugins/contrib/po]] development: what
10 I'm about to achieve is:
11
12 - when a master page is renamed, the plugin takes notice of it (using
13   the `rename` hook), and later renames the translation pages
14   accordingly (in the `change` hook)
15 - when a master page is deleted, the plugin deletes its translations
16   (using the `delete` hook)
17
18 With the current `renamepage` hook behavior, combining these two goals
19 has an annoying drawback: a plugin can't notice an orphan master page
20 has been renamed, so instead of renaming (and preserving) its
21 translations, it considers the oldpage as deleted, and deletes its
22 translations. Game over.
23
24 It may seem like a corner case, but I want to be very careful when
25 deleting files automatically in `srcdir`, which is not always under
26 version control.
27
28 As a sad workaround, I can still disable any deletion in `srcdir`
29 when it is not under version control. But I think ikiwiki deserves
30 a global `renamepage` hook that would be run once per rename
31 operation.
32
33 My proposal is thus:
34
35 - keep the documented `renamepage` hook as it is
36 - use something inspired by the trick `preprocess` uses: when `hook`
37   is passed an optional "global" parameter, set to a true value, the
38   declared `renamepage` hook is run once per rename operation, and is
39   passed named parameters: `src`, `srcfile`, `dest` and `destfile`.
40
41 I'm of course volunteering to implement this, or anything related that
42 would solve my problem. Hmmm? --[[intrigeri]]
43
44 > I think it would be better to have a different hook that is called for
45 > renames, since the two hook actions are very different (unlike the
46 > preprocess hook, which does a very similar thing in scan mode).
47
48 > Just calling it `rename` seems like a reasonable name, by analogy with
49 > the `delete` and `change` hooks.
50
51 > It might make sense to rename `renamepage` to `renamelink` to make it
52 > clearer what it does. (I'm not very worried about this breaking things, at
53 > this point.) --[[Joey]]
54
55 >> In my `po` branch, I renamed `renamepage` to `renamelink`, and
56 >> created a `rename` hook that is passed a reference to `@torename`.
57 >> --[[intrigeri]]