doc/todo/alias_directive.mdwn

   1 An alias directive could work like an inverse redirect, but in a more
   2 maintainable way. Currently, a page might have several redirects leading to it,
   3 without an easy way of enumerating them. Therefore, the following directive is
   4 suggested for addition (possibly by means of a plugin):
   5
   6 > The `alias` and `aliastext` directives implicitly create
   7 > redirect pages to the page they are used on. If two or more pages claim a
   8 > non-existing page to be an alias, a disambiguation page will automatically
   9 > generated. If an existing page is claimed as an alias, it will be prefixed
  10 > with a note that its topic is also an alias for other pages.
  11 >
  12 > All aliases to a page are automatically listed below the backlink and tag
  13 > lists at the bottom of a page by default. This can be configured globally by
  14 > setting the `alias_list` configuration option to `false`, or set explicitly
  15 > per alias by specifying `list=true` or `list=false`.
  16 >
  17 > Similar to the `taglink` directive, `aliastext` produces the alias name as
  18 > well as registering it.
  19 >
  20 > ## Usage example
  21 >
  22 > `Greece.mdwn`:
  23 >
  24 > >     Greece, also known as \[[!aliastext Hellas]] and officially the
  25 > >     \[[!aliastext "Hellenic Republic"]], is a …
  26 > >
  27 > >     <!-- there are so many people who misspell this, let's create a redirect -->
  28 > >     \[[!alias Grece list=false]]
  29 >
  30 > This page by itself will redirect from the "Hellas", "Hellenic Republic" and
  31 > "Grece" pages as if they both contained just:
  32 >
  33 > >     \[[!meta redir="Greece"]]
  34 >
  35 > If, on the other hand, `Hellas Planitia` also claims `[[!alias Hellas]]`, the
  36 > Hellas page will look like this:
  37 >
  38 > >     **Hellas** is an alias for the following pages:
  39 > >
  40 > >     * \[[Greece]]
  41 > >     * \[[Hellas Planitia]]
  42
  43 The proposed plugin/directive could be extended, eg. by also including
  44 old-style redirects in the alias list, but that might introduce unwanted
  45 coupling with the meta directive.
  46
  47 -----------------
  48
  49 On second thought, implementing this might have similarities with
  50 [[todo/auto-create tag pages according to a template]] -- the auto-created
  51 pages would, if the way of the alias directive is followed, not create physical
  52 files, though, but be created just when someone edits them.
  53
  54 If multiple plugins do such a trick, they would have to fight over who comes
  55 first. If, for example, we have a setup where not yet created tag pages are
  56 automatically generated as "\[[!inline  pages="link(<TMPL_VAR TAG>)"
  57 archive="yes"]]" and aliases are enabled, and a non-tag pages grabs a tag as an
  58 alias (as to redirect all taglinks of the tag to itself), there are two
  59 possibilities:
  60
  61 * The autotag plugin comes first:
  62     * autotag sees the missing tag and creates its "\[[!inline" stuff
  63     * alias sees that there is already content and adds its prefix
  64 * The alias plugin comes first (this is the prefered way):
  65     * alias sees the empty page, sees it is not contested by other alias
  66       directives and creates its "\[[!meta" redirect
  67     * autotag sees there is already content and doesn't do anything
  68
  69 That issue could be handled with "priority number" on the hook, with plugins
  70 with a lower number being called first.
  71
  72 [[!tag wishlist]]