bitclust-core 1.6.1 → 1.8.0

data/lib/bitclust/searcher.rb

@@ -9,10 +9,12 @@
 #
 
 require 'bitclust/methoddatabase'
+require 'bitclust/remote'
 require 'bitclust/functiondatabase'
 require 'bitclust/nameutils'
 require 'bitclust/methodid'
 require 'bitclust/exception'
+require 'bitclust/user_dirs'
 require 'uri'
 require 'rbconfig'
 require 'optparse'
@@ -36,6 +38,7 @@ module BitClust
       @target_type = nil
       @listen_url = nil
       @foreground = false
+      @remote = Remote.default
       @parser = OptionParser.new {|parser|
         parser.banner = "Usage: #{@name} <pattern>"
         unless cmd == 'bitclust'
@@ -91,6 +94,10 @@ module BitClust
 
     attr_reader :parser
 
+    # ローカル DB が無いときに使うリモート検索(BitClust::Remote)。nil なら
+    # DB が無いことをエラーにする
+    attr_accessor :remote
+
     def parse(argv)
       @parser.parse! argv
       if @listen_url   # server mode
@@ -121,6 +128,22 @@ module BitClust
       @parser.help
     end
 
+    # irb プラグインなど組み込み利用向けの入口。argv のパターンを db から
+    # 検索し、結果を view(TerminalView)へ出力する。db が nil なら
+    # 既定の場所(環境変数 BITCLUST_DATADIR など・設定ファイル(UserDirs))
+    # から探す
+    def run_query(db, argv, view)
+      @view = view
+      search_pattern db, argv
+    end
+
+    # 既定の場所(環境変数 BITCLUST_DATADIR など・設定ファイル(UserDirs))に
+    # ローカル DB があるか。irb プラグインが HTTP フォールバックへ切り替える
+    # 判定に使う。環境変数が不正な DB を指していれば InvalidDatabase
+    def local_database?
+      !find_dblocation().nil?
+    end
+
     private
 
     def server_mode_check(argv)
@@ -243,15 +266,23 @@ module BitClust
       [ "#{datadir}/refe2", "#{datadir}/bitclust" ].each do |path|
         return path if MethodDatabase.datadir?(path)
       end
-      config_path = Pathname(ENV.fetch('HOME')) + ".bitclust" + "config"
-      if config_path.exist?
-        config = YAML.load_file(config_path)
+      config = UserDirs.load_config
+      if config
         return "#{config[:database_prefix]}-#{config[:default_version]}"
       end
       nil
     end
 
     def search_pattern(db, argv)
+      if db.nil? && !find_dblocation
+        remote = @remote
+        unless remote
+          raise InvalidDatabase, "no database found: run `bitclust setup` to create one (remote search is disabled by BITCLUST_REMOTE_URL)"
+        end
+        remote.lookup(argv, @view.io, describe_all: @describe_all, line: @linep,
+                      class_only: @target_type == :class)
+        return
+      end
       db ||= new_database()
       @view.database ||= db if @view
       # FIXME なぜか else 節にきかないのでここに書いておく
@@ -352,16 +383,6 @@ module BitClust
       find_method db, cnames.join('::'), '::', name
     end
 
-    # 区切りは反転文字列上で探す。"?." は 4.0 以降の module function の
-    # 表示形式(反転すると ".?")で、内部表記の ".#" に正規化する
-    def parse_method_spec_pattern(pat)
-      _m, _t, _c = pat.reverse.split(/([\#,]\.|\.[\#,]|\.\?|[\#\.\,])/, 2)
-      c = (_c || raise).reverse
-      t = (_t || raise).tr(',', '#').sub(/\#\.|\.\?/, '.#')
-      m = (_m || raise).reverse
-      return c, t, m
-    end
-
   end
 
 
@@ -374,16 +395,34 @@ module BitClust
 
   class TerminalView
 
-    def initialize(compiler, opts)
+    # io を省略すると出力先は呼び出し時点の $stdout(従来挙動)
+    def initialize(compiler, opts, io: nil)
       @compiler = compiler
       @describe_all = opts[:describe_all]
       @line = opts[:line]
       @encoding = opts[:encoding]
       @database = nil
+      @io = io
     end
 
     attr_accessor :database
 
+    # 出力先(io: 省略時は $stdout)
+    def io
+      @io || $stdout
+    end
+
+    # 名前の一覧を表示する(-l なら 1 行 1 件、それ以外は端末幅に詰める)
+    def print_names(names)
+      if @line
+        names.sort.each do |n|
+          puts n
+        end
+      else
+        print_packed_names names.sort
+      end
+    end
+
     def show_class(cs)
       if cs.size == 1
         if @line
@@ -440,16 +479,6 @@ module BitClust
 
     private
 
-    def print_names(names)
-      if @line
-        names.sort.each do |n|
-          puts n
-        end
-      else
-        print_packed_names names.sort
-      end
-    end
-
     def print_packed_names(names)
       max = terminal_column()
       buf = +''
@@ -546,7 +575,7 @@ module BitClust
     end
 
     def puts(*args)
-      super(*args.collect {|arg| convert(arg)})
+      (@io || $stdout).puts(*args.collect {|arg| convert(arg)})
     end
 
     def convert(string)

data/lib/bitclust/subcommands/chm_command.rb

@@ -102,7 +102,7 @@ EOS
           end
 
           def to_html
-            str = "<LI> <OBJECT type=\"text/sitemap\">\n"
+            str = +"<LI> <OBJECT type=\"text/sitemap\">\n"
             str << "        <param name=\"Name\" value=\"<%=h @name%>\">\n"
             if @local
               str << "        <param name=\"Local\" value=\"<%=@local%>\">\n"

data/lib/bitclust/subcommands/epub_command.rb

@@ -12,7 +12,7 @@ module BitClust
       def initialize
         super
         @verbose = true
-        @catalogdir = nil
+        @catalogdir = srcdir_root + "data/bitclust/catalog"
         @templatedir = srcdir_root + "data/bitclust/template.epub"
         @themedir = srcdir_root + "theme/default"
         @filename = "rurema-#{Date.today}.epub"
@@ -54,7 +54,7 @@ module BitClust
         generator = BitClust::Generators::EPUB.new(:prefix           => options[:prefix],
                                                    :capi             => options[:capi],
                                                    :outputdir        => @outputdir,
-                                                   :catalog          => @catalog,
+                                                   :catalog          => @catalogdir,
                                                    :templatedir      => @templatedir,
                                                    :themedir         => @themedir,
                                                    :fs_casesensitive => @fs_casesensitive,

data/lib/bitclust/subcommands/extract_command.rb

@@ -25,6 +25,7 @@ module BitClust
       def exec(argv, options)
         success = true
         argv.each do |path|
+          reject_markdown_source(path)
           begin
             lib = RRDParser.parse_stdlib_file(path)
             if @check_only
@@ -41,6 +42,12 @@ module BitClust
         exit success
       end
 
+      # 旧 RD ソース(refm)専用なので、Markdown は未対応として案内する
+      def reject_markdown_source(path)
+        return unless path.end_with?('.md')
+        error "#{path}: extract は旧 RD ソース(refm)専用で、Markdown(manual/ の .md)には未対応です。manual/ の内容は doctree の rake generate:X.Y と bitclust server で確認してください"
+      end
+
       def show_library(lib)
         puts "= Library #{lib.name}"
         lib.classes.each do |c|

data/lib/bitclust/subcommands/htmlfile_command.rb

@@ -47,6 +47,7 @@ module BitClust
         end
         @capi = options[:capi]
         target_file = argv[0]
+        reject_markdown_source(target_file)
         if /refm\/doc\// =~ target_file
           @rd_file = true if @rd_file.nil?
         end
@@ -88,6 +89,12 @@ module BitClust
 
       private
 
+      # 旧 RD ソース(refm)専用なので、Markdown は未対応として案内する
+      def reject_markdown_source(path)
+        return unless path && path.end_with?('.md')
+        error "#{path}: htmlfile は旧 RD ソース(refm)専用で、Markdown(manual/ の .md)には未対応です。manual/ の内容は doctree の rake generate:X.Y と bitclust server(または rake statichtml:X.Y)で確認してください"
+      end
+
       def lookup(lib, key)
         case
         when @capi && NameUtils.functionname?(key)

data/lib/bitclust/subcommands/methods_command.rb

@@ -29,16 +29,9 @@ module BitClust
           @mode = :diff
           @target = path
         }
-        @parser.on('-c', '') {
-          @content = true
-          require 'bitclust/ridatabase'
-        }
         @parser.on('--ruby=[VER]', "The version of Ruby interpreter"){|version|
           @version = version
         }
-        @parser.on('--ri-database', 'The path of ri database'){|path|
-          @ri_path = path
-        }
       end
 
       def parse(argv)
@@ -67,27 +60,11 @@ module BitClust
           list0 = c.entries + list0
           # @type var list: Array[String]
           list = list0.map {|ent| ent.labels.map {|n| expand_mf(n) } }.flatten
-          if @content
-            ri = @ri_path ? RiDatabase.open(@ri_path, nil) : RiDatabase.open_system_db
-            ri.current_class = c.name
-            mthds = ( ri.singleton_methods + ri.instance_methods )
-            fmt = Formatter.new
-            (keys - list).sort.each do |name|
-              mthd = mthds.find{|m| name == m.fullname }
-              if mthd
-                puts fmt.method_info(mthd.entry)
-              else
-                name = name.sub(/\A\w+#/, '')
-                puts "--- #{name}\n#%todo\n\n"
-              end
-            end
-          else
-            (keys - list).sort.each do |name|
-              puts "-#{name}"
-            end
-            (list - keys).sort.each do |name|
-              puts "+#{name}"
-            end
+          (keys - list).sort.each do |name|
+            puts "-#{name}"
+          end
+          (list - keys).sort.each do |name|
+            puts "+#{name}"
           end
         else
           raise "must not happen: #{@mode.inspect}"

data/lib/bitclust/subcommands/query_command.rb

@@ -19,6 +19,7 @@ module BitClust
       end
 
       def exec(argv, options)
+        super   # @db を用意する(スクリプトからは @db で参照する)
         argv.each do |query|
           # pp eval(query)   # FIXME: causes ArgumentError
           p eval(query)

data/lib/bitclust/subcommands/rbssig_command.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+#
+# bitclust/subcommands/rbssig_command.rb
+#
+# RBS 型シグネチャを DB のメソッドエントリに書き込む(rbs_sig property):
+#
+#   bitclust rbssig --sig-root=RBS_CHECKOUT <dbpath>
+#   bitclust rbssig --sig-dir=DIR [--sig-dir=DIR ...] <dbpath>
+#
+# DB 構築(update)後・statichtml 前に実行する(methodsince と同じ位置)。
+# --sig-root には対象 Ruby バージョンに同梱される rbs のチェックアウト
+# (core/ と stdlib/ を含む)を渡す。表示は 4.0 以降のドキュメント専用
+# なので、DB の version が 4.0 未満ならエラーにする。
+
+require 'bitclust'
+require 'bitclust/subcommand'
+require 'bitclust/rbs_sig_importer'
+require 'tmpdir'
+require 'fileutils'
+
+module BitClust
+  module Subcommands
+    class RbssigCommand < Subcommand
+      MINIMUM_VERSION = Gem::Version.new('4.0')
+
+      def initialize
+        super
+        @sig_root = nil
+        @sig_dirs = []
+        @dry_run = false
+        @parser.banner = "Usage: #{File.basename($0, '.*')} rbssig [options] <dbpath>"
+        @parser.on('--sig-root=PATH', 'ruby/rbs checkout containing core/ and stdlib/.') {|path|
+          @sig_root = path
+        }
+        @parser.on('--sig-dir=PATH', 'Directory of extra .rbs files (repeatable).') {|path|
+          @sig_dirs.push path
+        }
+        @parser.on('--dry-run', 'Compute and print stats without saving.') {
+          @dry_run = true
+        }
+      end
+
+      # DB パスは位置引数で受けるのでグローバル --database は不要
+      def needs_database?
+        false
+      end
+
+      def exec(argv, options)
+        error('no --sig-root or --sig-dir given') if @sig_root.nil? && @sig_dirs.empty?
+        error("wrong number of arguments (#{argv.size} for 1)") unless argv.size == 1
+        path = argv.first
+        version = check_version(path)
+
+        sig_root = @sig_root
+        importer = RbsSigImporter.new(
+          core_root: sig_root && File.join(sig_root, 'core'),
+          repository_root: sig_root && File.join(sig_root, 'stdlib'),
+          sig_dirs: @sig_dirs)
+        stats =
+          if @dry_run
+            apply_dry_run(importer, path)
+          else
+            importer.apply(MethodDatabase.new(path))
+          end
+        puts "#{File.basename(path)} (version #{version}): " \
+             "entries_updated=#{stats[:entries_updated]} sigs_matched=#{stats[:sigs_matched]} " \
+             "methods_missed=#{stats[:methods_missed]}"
+      end
+
+      private
+
+      # RBS シグネチャ表示は 4.0 以降のドキュメント専用。比較は
+      # display_typemark(nameutils.rb)と同じく Gem::Version で行う
+      # (文字列比較だと "10.0" が "4.0" より小さく見える)
+      def check_version(path)
+        version = MethodDatabase.new(path).propget('version') or
+          error("#{path}: no version property (not a bitclust database?)")
+        begin
+          if Gem::Version.new(version) < MINIMUM_VERSION
+            error("#{path}: version #{version} is before 4.0; RBS signatures are only for 4.0+ databases")
+          end
+        rescue ArgumentError
+          error("#{path}: malformed version property: #{version.inspect}")
+        end
+        version
+      end
+
+      # --dry-run: 実 DB には書き込まず、複製に apply した統計だけを見せる
+      # (methodsince の apply_dry_run と同じ手口)
+      def apply_dry_run(importer, path)
+        Dir.mktmpdir do |tmp|
+          copy = File.join(tmp, 'db')
+          FileUtils.cp_r(path, copy)
+          importer.apply(MethodDatabase.new(copy))
+        end
+      end
+    end
+  end
+end

data/lib/bitclust/subcommands/server_command.rb

@@ -9,6 +9,7 @@ require 'uri'
 
 require 'bitclust'
 require 'bitclust/subcommand'
+require 'bitclust/user_dirs'
 
 module BitClust
   module Subcommands
@@ -50,7 +51,7 @@ module BitClust
         @parser.on('--baseurl=URL', 'The base URL to host.') {|url|
           @baseurl = url
         }
-        @parser.on('--database=PATH', 'MethodDatabase root directory.') {|path|
+        @parser.on('-d', '--database=PATH', 'MethodDatabase root directory.') {|path|
           @dbpath = path
         }
         @parser.on('--srcdir=PATH', 'BitClust source directory.') {|path|
@@ -85,17 +86,20 @@ module BitClust
         }
       end
 
+      # DB はサブコマンド自身の -d/--database か、グローバル --database
+      # (options[:prefix])のどちらでも受ける。runner にはグローバル側を
+      # 要求させない(ancestors と同じ扱い)
+      def needs_database?
+        false
+      end
+
       def parse(argv)
         super
         load_config_file
         set_srcdir(srcdir_root) unless @srcdir
 
         unless @baseurl
-          $stderr.puts "missing base URL.  Use --baseurl or check ~/.bitclust/config"
-          exit 1
-        end
-        unless @dbpath || @autop
-          $stderr.puts "missing database path.  Use --database"
+          $stderr.puts "missing base URL.  Use --baseurl or check the config file (bitclust setup)"
           exit 1
         end
         unless @datadir
@@ -116,6 +120,7 @@ module BitClust
       end
 
       def exec(argv, options)
+        @dbpath = resolve_dbpath(options)
         begin
           require 'webrick'
         rescue LoadError
@@ -210,11 +215,17 @@ module BitClust
         @themedir ||= "#{@srcdir}/theme"
       end
 
+      # サブコマンド側の --database が無ければグローバル --database
+      # (runner の options[:prefix])を使う。--auto のときは不要
+      def resolve_dbpath(options)
+        dbpath = @dbpath || options[:prefix]
+        abort "missing database path.  Use --database (-d)" unless dbpath || @autop
+        dbpath
+      end
+
       def load_config_file
-        home_directory = Pathname(ENV.fetch('HOME'))
-        config_path = home_directory + ".bitclust/config"
-        if config_path.exist?
-          config = YAML.load_file(config_path)
+        config = UserDirs.load_config
+        if config
           @baseurl  ||= config[:baseurl]
           @dbpath   ||= "#{config[:database_prefix]}-#{config[:default_version]}"
           @port     ||= config[:port]

data/lib/bitclust/subcommands/setup_command.rb

@@ -8,6 +8,7 @@ require 'yaml'
 
 require 'bitclust'
 require 'bitclust/subcommand'
+require 'bitclust/user_dirs'
 
 module BitClust
   module Subcommands
@@ -20,7 +21,10 @@ module BitClust
         @prepare = nil
         @cleanup = nil
         @purge = nil
-        @versions = ["3.3.0", "3.4.0", "4.0.0"]
+        # teeny は付けない。#%if (version == "V") や #%version V の等値ゲートは
+        # 文字列一致なので、teeny 付きの版名で DB を作ると doctree CI・
+        # 生成済みドキュメントとゲートの判定がずれる
+        @versions = ["3.3", "3.4", "4.0"]
         @update = true
         @parser.banner = "Usage: #{File.basename($0, '.*')} setup [options]"
         @parser.on('--prepare', 'Prepare config file and checkout repository. Do not create database.') {
@@ -40,7 +44,9 @@ module BitClust
         }
       end
 
-      # DB は ~/.bitclust 配下に自前で作るのでグローバル --database は不要
+      # DB は設定ファイル(UserDirs)が示す場所(既定は $XDG_DATA_HOME/bitclust、
+      # 旧 ~/.bitclust があればそちら)に自前で作るのでグローバル --database
+      # は不要
       def needs_database?
         false
       end
@@ -65,22 +71,37 @@ module BitClust
       private
 
       def purge
-        home_directory = Pathname(ENV.fetch("HOME"))
-        config_dir = home_directory + ".bitclust"
         print "Remove all generated files..."
-        FileUtils.rm_rf(config_dir.to_s)
+        puts
+        [UserDirs.legacy_dir, UserDirs.config_home, UserDirs.data_home, UserDirs.cache_home].each do |dir|
+          next unless dir.exist?
+          FileUtils.rm_rf(dir.to_s)
+          puts "  removed #{dir}"
+        end
         puts "done!"
         exit 0
       end
 
+      # 設定ファイル・DB・doctree checkout の置き場所を選ぶ。既に旧
+      # ~/.bitclust/config があり、まだ XDG 側の設定ファイルが無ければ
+      # 互換のため旧レイアウトを維持する。それ以外は XDG レイアウトを使う
+      def layout
+        legacy_config = UserDirs.legacy_dir + "config"
+        xdg_config = UserDirs.config_home + "config"
+        if legacy_config.exist? && !xdg_config.exist?
+          config_dir = UserDirs.legacy_dir
+          [config_dir + "config", (config_dir + "db").to_s, config_dir + "rubydoc"]
+        else
+          [xdg_config, (UserDirs.data_home + "db").to_s, UserDirs.data_home + "rubydoc"]
+        end
+      end
+
       def prepare
-        home_directory = Pathname(ENV.fetch("HOME")).expand_path
-        config_dir = home_directory + ".bitclust"
-        config_dir.mkpath
-        config_path = config_dir + "config"
-        rubydoc_dir = config_dir + "rubydoc"
+        config_path, database_prefix, rubydoc_dir = layout
+        config_path.dirname.mkpath
+        rubydoc_dir.dirname.mkpath
         @config = {
-          :database_prefix => (config_dir + "db").to_s,
+          :database_prefix => database_prefix,
           :encoding        => "utf-8",
           :versions        => @versions,
           :default_version => @versions.max,

data/lib/bitclust/subcommands/statichtml_command.rb

@@ -13,6 +13,7 @@ require 'bitclust/subcommand'
 require 'bitclust/progress_bar'
 require 'bitclust/silent_progress_bar'
 require 'bitclust/search_index_generator'
+require 'bitclust/markdown_exporter'
 
 module BitClust
   module Subcommands
@@ -125,6 +126,7 @@ module BitClust
         @run_ruby_wasm = nil
         @sitemap_baseurl = nil
         @sitemap_paths = []
+        @markdown_output = false
         @parser.banner = "Usage: #{File.basename($0, '.*')} statichtml [options]"
         @parser.on('-o', '--outputdir=PATH', 'Output directory') do |path|
           begin
@@ -170,6 +172,9 @@ module BitClust
         @parser.on('--sitemap-baseurl=URL', 'Generate sitemap.xml under the output directory, with <loc> built from this base URL (e.g. https://docs.ruby-lang.org/ja/3.4/). Omit to skip sitemap.xml generation (default)') do |url|
           @sitemap_baseurl = url
         end
+        @parser.on('--markdown-output', 'Also write each page as Markdown (.md next to the .html), assembled from the preprocessed Markdown sources. Ignored for databases not created from a Markdown tree') do
+          @markdown_output = true
+        end
         @parser.on('--no-stop-on-syntax-error', 'Do not stop on syntax error') do |boolean|
           @stop_on_syntax_error = boolean
         end
@@ -185,8 +190,10 @@ module BitClust
         db = MethodDatabase.new(prefix.to_s)
         fdb = FunctionDatabase.new(prefix.to_s)
         manager = ScreenManager.new(@manager_config)
+        @markdown_exporter = MarkdownExporter.new(@urlmapper, @suffix) if @markdown_output
 
         db.transaction do
+          warn_markdown_output_skipped(db, "the method database")
           methods = {} #: Hash[String, Array[MethodEntry]]
           db.methods.each_with_index do |entry, i|
             next if entry.undefined?
@@ -203,6 +210,7 @@ module BitClust
         end
 
         fdb.transaction do
+          warn_markdown_output_skipped(fdb, "the function database")
           create_html_entries("capi", fdb.functions, manager, fdb)
         end
 
@@ -234,6 +242,7 @@ module BitClust
         FileUtils.cp(@manager_config[:themedir] + "script.js",
                      @outputdir.to_s, :verbose => @verbose, :preserve => true)
         copy_run_ruby_wasm_script if @run_ruby_wasm
+        copy_version_switcher_script
         FileUtils.cp(@manager_config[:themedir] + @manager_config[:favicon_url],
                      @outputdir.to_s, :verbose => @verbose, :preserve => true)
         Dir.mktmpdir do |tmpdir|
@@ -412,6 +421,19 @@ HERE
         end
       end
 
+      # Copy the version-switcher script. A themedir without it is
+      # tolerated: warn and skip instead of aborting the whole build.
+      def copy_version_switcher_script
+        src = @manager_config[:themedir] + "js" + "version_switcher.js"
+        unless src.file?
+          $stderr.puts "warning: #{src} not found; version switcher script not copied"
+          return
+        end
+        jsdir = @outputdir + "js"
+        FileUtils.mkdir_p(jsdir) unless jsdir.directory?
+        FileUtils.cp(src.to_s, jsdir.to_s, :verbose => @verbose, :preserve => true)
+      end
+
       def create_html_file(entry, manager, outputdir, db)
         e = entry.is_a?(Array) ? entry.sort.first : entry
         case e.type_id
@@ -419,6 +441,7 @@ HERE
           @urlmapper.bitclust_html_base = '..'
           path = outputdir + e.type_id.to_s + html_filename(encodename_package(e.name), @suffix)
           create_html_file_p(entry, manager, path, db)
+          create_markdown_file_p(e, path, db)
         when :function
           create_html_function_file(entry, manager, outputdir, db)
         else
@@ -435,6 +458,11 @@ HERE
         path = outputdir + e.type_id.to_s + encodename_package(e.klass.name) +
           e.typechar + html_filename(encodename_package(name), @suffix)
         create_html_file_p(entries, manager, path, db)
+        if markdown_export?(db)
+          create_file(markdown_path(path),
+                      @markdown_exporter.method_page(method_name, entries.sort),
+                      :verbose => @verbose)
+        end
       end
 
       def create_html_function_file(entry, manager, outputdir, db)
@@ -442,6 +470,7 @@ HERE
         @urlmapper.bitclust_html_base = '..'
         path = outputdir + entry.type_id.to_s + html_filename(entry.name, @suffix)
         create_html_file_p(entry, manager, path, db)
+        create_markdown_file_p(entry, path, db)
       end
 
       def create_html_file_p(entry, manager, path, db)
@@ -453,6 +482,36 @@ HERE
         record_sitemap_path(path)
       end
 
+      # --markdown-output は Markdown ツリー由来の DB でのみ有効。
+      # ソースが md でない(凍結版 RD など)DB では何も出力しない
+      def markdown_export?(db)
+        @markdown_output && db.properties['source_format'] == 'markdown'
+      end
+
+      def warn_markdown_output_skipped(db, label)
+        return if !@markdown_output || db.properties['source_format'] == 'markdown'
+        $stderr.puts "warning: --markdown-output is ignored for #{label}: it was not created from a Markdown tree"
+      end
+
+      def create_markdown_file_p(entry, html_path, db)
+        return unless markdown_export?(db)
+        content =
+          case entry.type_id
+          when :library then @markdown_exporter.library_page(_ = entry)
+          when :class then @markdown_exporter.class_page(_ = entry)
+          when :doc then @markdown_exporter.doc_page(_ = entry)
+          when :function then @markdown_exporter.function_page(_ = entry)
+          else return
+          end
+        create_file(markdown_path(html_path), content, :verbose => @verbose)
+      end
+
+      def markdown_path(html_path)
+        s = html_path.to_s
+        s = s.end_with?(@suffix) ? s[0, s.length - @suffix.length].to_s : s
+        Pathname.new("#{s}.md")
+      end
+
       def create_file(path, str, options = {})
         verbose = options[:verbose]
         $stderr.print("creating #{path} ...") if verbose