'''Note: this is a transient page for documenting the upcoming change introducing wiki rendering contexts'''

See [source:sandbox/wiki-context-tmp wiki-context-tmp] branch and r4441.
----
Introduction of '''Wiki rendering contexts''' (`trac.wiki.api.Context`)

The changeset is a bit big, but that was the price to pay for doing a consistent and (hopefully) bug free transition.

[[PageOutline(3-6,inline)]]

=== Introduction ===

A Wiki rendering context contains all the information needed for properly rendering Wiki text in the Trac system:
 - the resource to which the wiki text belongs (`.env`, `.resource`, `.id`)
 - its parent context, if there's one (`.parent`)
 - how the rendered Wiki text is being accessed (`.req`, `.abs_urls`) so that the proper links can be generated (`.href`, `.self_href`)

Besides, it keeps a handle to a database connection (`.db`) the way the `Formatter` objects used to do.

Such a context can be used for generating wiki texts in different flavors, using the `.wiki_to_...` methods.

It's very easy to manipulate contexts, or create sub-contexts. Here are some examples:
 - `Context(env, req)`: a global context, not attached to a particular resource
 - `Context(env, req, 'wiki', 'WikiStart')`: a context for the WikiStart wiki page
 - assuming `ctxt` is a Context instance, `ctxt('ticket', ticket.id)` creates a subcontext focusing on a specific `ticket`.


=== Fixed Issues ===

Thanks to Wiki rendering contexts, the following issues could be solved:
 - relative attachments and comments TracLinks now always refer to the correct context resource, irrelevant from where they are displayed (ticket query with description #3711, headings #3842, timeline, etc.)
 - relative links (i.e. `[#anchor see this]` kind of TracLinks) are now always refering to the correct resource (#4144)

Besides, a few other fixes were done at the same time:
 - the formatter stores the wiki text it is currently parsing (`.source`), so that it can be made available to macros;  for example, this means that the rendering of !PageOutline macro is now consistent, and the outline is always the one of the text being currently formatted (#3936)
 - remove support for old wiki-macros (they were not going to work anymore since the HDF is gone)
 - fix the !TracGuideToc macro, which is now part of the default set of trac.wiki.macros (#3958)

Finally, rows in TracReports can now refer to other resources than just tickets, when specifying a `resource` column. That way, reports for changesets can now be linked to the corresponding changesets.

Example, for showing the last 10 changesets:
{{{
#!sql
select 'changeset' as _resource, rev as id, time, author, 
       message as description
from revision order by time desc limit 10;
}}}


=== API Changes ===

Besides the new trac.wiki.api.Context class, a few existing interfaces have been modified:
 - `IWikiMacroProvider.render_macro` now takes a `formatter` instead of a `req` as its first argument (#4139)
 - `IHTMLPreviewRenderer.render` takes a `context` instead of a `req` as its first argument
 - `TimelineEvent.set_context` takes a `context` first argument and a `wikitext` second argument. That wiki text can now be retrieved in the `.wikitext` property instead of the `.message` one.