Fix misleading help in path.module

Ups, my last example was a bit shortsighted in that it translates all outgoing taxonomy/page URLs to forum/quickview pages :) That is not right... In my own implementation I have precached node type + vocabulary and taxonomy vocabulary relation arrays, so I can decide on what URL alias to use...

But that would be a bit too complicated example for such a simple patch :) for a simpler example, let's assume you would like to provide your special overview of the hottest topics per forum category, and that said, you need your own module, which you would like to fake under the forum URL space:

function conf_url_rewrite($path, $mode = 'incoming') {
  if ($mode == 'incoming') {
    return preg_replace("!^forum/hottest/(\\d+)$!", "hottest/\\1", $path);
  }
  else {
    return preg_replace("!^hottest/(\\d+)$!", "forum/hottest/\\1", $path);
  }
}

This will work without interfering with something else...

Wups, I have incorrectly used conf_get_path_map() here, which is essentially the same as the built-in drupal_get_path_map(). Here is a corrected patch...

Extended patch with documentation updates (to path.module). And taken url() as an example for if-elseif-else formatting, so the new code conforms better to already used code.

I am not entirely happy with you asking me to document something which will not be accepted afterwards... I have provided extensive explanation as well as the code for consideration without the added documentation so I need not put effort into writing documentation for something that will morf into a really different thing later after some discussion...

I would however be happy with enabling people to implement this as a module_url_alias() hook or something, but I am not sure that it would always be available to be called, since I am not familiar with the inner workings of module_invoke() now that we have bootstrapping, and throttling, which might influence what is loaded and executed.

BTW if we implement this as a new hook, then there is no reason to document it in path.module, since it becomes 'module developer documentation', and it should go into the hooks docs.

Thanks for committing. If you would decide to go on the hook route, a foreach() loop could be implemented to call all module_url_alias() functions, similarly to the filtering code.

As I have investigated, in bootstrap mode the original request URI is used to query the cache, so there is no need for aliasing. Otherwise a module file is included if it is not affected by throttle. An intelligent administrator should not set a module providing core URL aliasing features to be throttle controlled. So theoretically the code of modules defining such hooks should be in memory. Then only the question of performance remains, whether having a foreach and several module_invoke() calls worth the added benefit of allowing any module to add mass URL aliases...

Since the semantics of the outgoing mode was changed back to not returning anything if an alias does not exist, a corrected example would be:

function conf_url_rewrite($path, $mode = 'incoming') {
  if ($mode == 'incoming') {
    return preg_replace("!^dagboek/(\\d+)$!", "book/view/\\1", $path);
  }
  else {
    $aliased = preg_replace("!^book/view/(\\d+)$!", "dagboek/\\1", $path);
    if ($aliased != $path) { return $aliased; }
  }
}

This shuold be reflected in any example that might go into the documentation.

My patch on path.module seems to be accepted (as opposed to what Dries stated here). Since it has some minor backslash escaping problems and it refers to the semantics of the aliasing I tried to push into Drupal, this fixes the help text to reflect how the mass URL aliasing function should be written. Also added a note on the need of deep knowlegde about Drupal and regular expressions to make use of advanced mass URL aliasing.

Updated patch, which also fixes the .po extraction problems of dollar signs not escaped... This should be committed instead of the former patch...