As documented in [[plugins/write]], the current `renamepage` hook is
heavily oriented towards updating links in pages' content:  it is run
once per page linking to the renamed page.

That's fine, but it can't be used to trigger more general actions on
page rename. E.g. it won't be run at all if the page being renamed is
an orphan one.

This is a real issue for the [[plugins/contrib/po]] development: what
I'm about to achieve is:

- when a master page is renamed, the plugin takes notice of it (using
  the `rename` hook), and later renames the translation pages
  accordingly (in the `change` hook)
- when a master page is deleted, the plugin deletes its translations
  (using the `delete` hook)

With the current `renamepage` hook behavior, combining these two goals
has an annoying drawback: a plugin can't notice an orphan master page
has been renamed, so instead of renaming (and preserving) its
translations, it considers the oldpage as deleted, and deletes its
translations. Game over.

It may seem like a corner case, but I want to be very careful when
deleting files automatically in `srcdir`, which is not always under
version control.

As a sad workaround, I can still disable any deletion in `srcdir`
when it is not under version control. But I think ikiwiki deserves
a global `renamepage` hook that would be run once per rename
operation.

My proposal is thus:

- keep the documented `renamepage` hook as it is
- use something inspired by the trick `preprocess` uses: when `hook`
  is passed an optional "global" parameter, set to a true value, the
  declared `renamepage` hook is run once per rename operation, and is
  passed named parameters: `src`, `srcfile`, `dest` and `destfile`.

I'm of course volunteering to implement this, or anything related that
would solve my problem. Hmmm? --[[intrigeri]]

> I think it would be better to have a different hook that is called for
> renames, since the two hook actions are very different (unlike the
> preprocess hook, which does a very similar thing in scan mode).
> 
> Just calling it `rename` seems like a reasonable name, by analogy with
> the `delete` and `change` hooks.
> 
> It might make sense to rename `renamepage` to `renamelink` to make it
> clearer what it does. (I'm not very worried about this breaking things, at
> this point.) --[[Joey]]

>> In my `po` branch, I renamed `renamepage` to `renamelink`, and
>> created a `rename` hook that is passed a reference to `@torename`.
>> --[[intrigeri]]

>>> As Joey highlights it on [[plugins/contrib/po]], it's too late to
>>> merge such a change, as the 3.x plugin API is released and should
>>> not be broken. I will thus keep the existing `renamepage` as it
>>> is, and call `rename` the global hook I need. --[[intrigeri]]

>>>> Done in my `po` branch. --[[intrigeri]]

I think I see a problem in the rename hook. The hook is called
before the plugin adds any subpages to the set of pages to rename.
So, if the user choses to rename subpages, po will not notice
they are moving, and will not move their po files.
 
Perhaps the hooks should be moved to come after subpages are added.
This would, though, mean that if the hook somehow decides to add
entirely other pages to the list, their subpages would not be
automatically added.

I also have some qualms about the design of the hook. In particular,
passing the mutable array reference probably makes it impossible
to use from external plugins. Instead it could return any additional
rename hashes it wants to add. Or, if the ability to modify existing
hashes is desired, it could return the full set of hashes.

--[[Joey]]