Deprecate :main: directive

Author: st0012

lib/rdoc/markup/pre_process.rb

@@ -187,6 +187,12 @@ def handle_directive prefix, directive, param, code_object = nil,
       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.
+
+        Use `--main=#{param}` to specify the initial page displayed.
+        If you use `RDoc::Task`, use `rdoc.main = "#{param}"` instead.
+      MSG
 
       blankline
     when 'nodoc' then

lib/rdoc/parser/c.rb

@@ -1103,6 +1103,13 @@ def look_for_directives_in context, comment
       case directive
       when 'main' then
         @options.main_page = param
+
+        warn <<~MSG
+          The :main: directive is deprecated and will be removed in RDoc 7.
+
+          Use `--main=#{param}` to specify the initial page displayed.
+          If you use `RDoc::Task`, use `rdoc.main = "#{param}"` instead.
+        MSG
         ''
       when 'title' then
         @options.default_title = param if @options.respond_to? :default_title=

lib/rdoc/rdoc.rb

@@ -407,6 +407,7 @@ def parse_files files
 
     return [] if file_list.empty?
 
+    # This workaround can be removed after the :main: directive is removed
     original_options = @options.dup
     @stats.begin_adding