doc/plugins/contrib/pageversion.mdwn

   1 [[!meta author="spalax"]]
   2 [[!template id=plugin name=pageversion author="[[Louis|spalax]]"]]
   3
   4 This plugin makes it possible to manage different versions of the same page, allowing to:
   5
   6 - make older/newer versions available;
   7 - highlight the latest version.
   8
   9 [[!toc]]
  10
  11 # Rationale
  12
  13 On my personal website/blog, I publish articles which I sometimes update. Sometimes, I add a few lines of text with a ``Updated on DATE.`` message; other times, I rewrite the whole article. In this latter case, I want:
  14
  15 - the main version of the article to be the latest one;
  16 - oldest versions still to be available;
  17 - the main list of my articles to list only the latest version of each article.
  18
  19 # Example
  20
  21 For instance, on my personal website, article [one](//ababsurdo.fr/pedago/sismologie/20150110/) has been updated to [two](//ababsurdo.fr/pedago/sismologie/20150819/).
  22
  23 - They both contain the directive `\[[!versionof parent]]`, marking them as a version of the [main article](//ababsurdo.fr/pedago/sismologie) (which happens to be their parent page).
  24 - On the [old article](//ababsurdo.fr/pedago/sismologie/20150819/), links to the other articles (only one here) are available.
  25 - On the [page listing my articles](//ababsurdo.fr/pedago), only the latest article appears.
  26 - The [main page](//ababsurdo.fr/pedago/sismologie) lists all versions of this article, and redirects to the latest one.
  27
  28 # List of directives and pagespecs
  29
  30 Pages are marked as versions as other pages using tags (subtags of `_pageversion/*`). Directive ``\[[!versionof]]`` simply add the appropriate tag to the current page (thus, one can ignore this directive, but it makes things easier).
  31
  32 Pages can be marked as versions of another page (e.g. ``foo/version1`` and ``foo/version2`` are versions of page ``foo``), or versions of an arbitrary abstract page (called *label* later). There is no conflict between them (that is, pages marked as a version of page ``foo`` and as a version of label ``foo`` are not a version of the same page).
  33
  34 ## Directive `versionof`
  35
  36 Marks current page as a version of another page. Its main forms are:
  37
  38 - `\[[!versionof name=foo]]` Mark current page as a version of page ``foo`` (page ``foo`` is searched using the same [[linking rules|ikiwiki/SubPage/LinkingRules]] as a [[ikiwiki/WikiLink]]).
  39 - `\[[!versionof label=bar]]` Mark current page as a version of some abstract object labelled ``bar``.
  40
  41 It may be convenient to refer to some particular page. Thus, those alternative forms are also available:
  42
  43 - `\[[!versionof name]]` Mark current page as a version of itself.
  44 - `\[[!versionof parent]]` Mark current page as a version of its parent page.
  45
  46 ## Template `otherversions`
  47
  48 To add a list to the other versions of a page (both older and newer), a template is provided. It is called with:
  49
  50     \[[!template id=otherversions version=VERSION template=INLINETEMPLATE]]
  51
  52 Where:
  53
  54 - *(Required)* Pages that are a version of `VERSION` are listed (for instance ``\[[!template id=otherversions version=name=foo]]``).
  55 - *(Optional)* Template `INLINETEMPLATE` is used (instead of the default `otherversionpage` template) in the [[ikiwiki/directive/inline]] directive listing the other pages.
  56
  57 ## Pagespec `versionof`
  58
  59 A pagespec can match pages marked as a version of something using the pagespec `versionof`. It accepts the same arguments as the arguments as the ``versionof`` directive, that is:
  60
  61 - `versionof(name=foo)`: Match pages which are a version of page ``foo``.
  62 - `versionof(name)`: Match pages which are a version of the current page.
  63 - `versionof(parent)`: Match pages which are a version of the parent page.
  64 - `versionof(label=bar)`: Match pages which are a version of some abstract object labelled ``bar``.
  65
  66 Moreover, it takes one additional argument:
  67
  68 - `versionof(any)`: Match pages which are a version of anything.
  69
  70 ## Pagespec `latestversion`
  71
  72 An additional pagespec `latestversion` is provided. It accepts the same arguments as the `versionof` pagespec (that is:
  73 `latestversion(name=foo)`,
  74 `latestversion(name)`,
  75 `latestversion(parent)`,
  76 `latestversion(label=bar)`,
  77 `latestversion(any)`) but only the most recent page is matched.
  78
  79 ## Pagespec `latest_tagged`
  80
  81 As a side effect, this plugin also provides the `latest_tagged(TAG)` pagespec. It matches one single page: the most recent page tagged with the given tag.
  82
  83 ## Directive `redirect`
  84
  85 Directive ``\[[!redirect]]`` (from the [[redirect]] plugin) can be used together with this package. For instance, a page containing the directive ``\[[!redirect pages="versionof(page)"]]`` will redirect to the most recent page marked as a version of the current page.
  86
  87 # Download and Install
  88
  89 Code and documentation can be found here : [[https://atelier.gresille.org/projects/gresille-ikiwiki/wiki/PageVersion]].