Refactor the rendering for 9.x and 10.x

[oliverklee]

Triggered by these PRs/tickets …:

• Dependency loop OutputFormat/OutputFormatter #895
• [TASK] Mark OutputFormatter as @internal #896
• [TASK] Drop magic method forwarding in OutputFormat #898

… I've thought about how to proceed a bit. I've taken these guidelines into account:

• our deprecation and API poliy
• Circular dependencies are bad.
• When we do a breaking change, I'd like to the replacement code to be stable for some time.
• the single-responsibility principle

This is what I'd like to propose:

Moving the responsibility for rendering elements

Generally, I'd like to move the responsibility for rendering CSS elements (including the document) to a new class:

class CssRenderer {
  public function __construct(OutputFormat $outputFormat);

  public function render(Renderable $element, int $indentationLevel = 0): string;
}

I'd like to introduce this class sometime after releasing 9.0, and deprecate the Renderable::render() methods then (to be removed in 10.x).

This class should use the Visitor design pattern.

This would unburden the CSS element classes from the responsibility of rendering the CSS (for which they need the output format, the formatter etc., all of which should be of no concern to a CSS element).

The dependency loop OutputFormat/OutputFormatter

I propose we keep the loop for 9.x, and drop the format -> formatter dependency when we drop the Renderable::render() methods in 10.x (which AFAIK are the only places where this dependency is relevant).

OutputFormatter

As the new CssRenderer will take care of rendering (and formatting) the CSS, we will be able to drop the OutputFormatter class in 10.x.

Until then, we make it @internal so that users of our library only need to pass an `OutputFormat' instance to render elements.

Rendarable::render()

I propose we keep these methods with an unchanged signature in 9.x (to avoid breaking part of the interface which we're going to to remove anyway), mark them as @deprecated since V9.x, will be removed in 10.0.

@sabberworm @JakeQZ What do you think?

[JakeQZ]

See my comments in #895. If those are in line with a way forward, with OutputFornat being the settings and OutputFormatter being the engine, also retaining state, then I think the nextLevel method needs to be moved to the latter, and possibly this can be done independently of changing the API, since it's (surely) an internal method.

[oliverklee]

@sabberworm ping

[oliverklee]

I have created #921 for moving nextLevel.