Deprecate main and title directives

[st0012]

Both main page and default title of a documentation should be global and immutable settings for the target project. Allowing users to override them in the middle of the documentation makes RDoc error-prone (see #426) and doesn't encourage the right behaviour.

We should deprecate these directives and remove them in the 7.0 release.

[colby-swandale]

I tried to do a quick test to see how the :title: directive currently works, but wasn't able to see where it comes out in the Darkish output.

Does the :title: directive allow a person to customise the title element in Darkish?

[st0012]

Does the :title: directive allow a person to customise the title element in Darkish?

Yes it's the same as the title option you can use in flags, .rdoc_options, and the rake task. These are their usages in the darkfish.

[colby-swandale]

It seems (please correct me if I'm wrong) that this directive allows you to customise the title for each document generated from RDoc, which could be pretty useful for SEO. I remember that we just merged something recently that now lets us customise keyboards and meta descriptions. Would the :title directive fall under the same sort of functionality?

[st0012]

Before #1091, :title: is only used in the ToC page and index page, not each document. So it's not designed for per-page usage from the beginning yet it allows individual pages to change the global value, which is why I think this directive is not a well-designed feature.

Even after #1091 started using it for SEO tags, the option.title value should still be considered a global value, not a way to customize each page's title by keep mutating it.

For SEO customization in the future, I think adding new :meta: or :meta-[keywords|description] directives which's value are attached to individual documents will be better.