[ruby/rdoc] Deprecate main and title directives

(https://github.com/ruby/rdoc/pull/1218)

* Deprecate :main: directive

* Deprecate :title: direcive

* Update documentation

* Remove :main: directive's usage

* Update test cases

* Add '.rdoc_options' to suggested alternatives

e2d4ac9dad

lib/rdoc/markup/pre_process.rb

@@ -187,6 +187,14 @@ class RDoc::Markup::PreProcess
       include_file filename, prefix, encoding
     when 'main' then
       @options.main_page = param if @options.respond_to? :main_page
+      warn <<~MSG
+        The :main: directive is deprecated and will be removed in RDoc 7.
+
+        You can use these options to specify the initial page displayed instead:
+        - `--main=#{param}` via the command line
+        - `rdoc.main = "#{param}"` if you use `RDoc::Task`
+        - `main_page: #{param}` in your `.rdoc_options` file
+      MSG
 
       blankline
     when 'nodoc' then
@@ -217,6 +225,15 @@ class RDoc::Markup::PreProcess
     when 'title' then
       @options.default_title = param if @options.respond_to? :default_title=
 
+      warn <<~MSG
+        The :title: directive is deprecated and will be removed in RDoc 7.
+
+        You can use these options to specify the title displayed instead:
+        - `--title=#{param}` via the command line
+        - `rdoc.title = "#{param}"` if you use `RDoc::Task`
+        - `title: #{param}` in your `.rdoc_options` file
+      MSG
+
       blankline
     when 'yield', 'yields' then
       return blankline unless code_object