[DOC] Place a non-US-ASCII document in a document-specific script

2 files changed, 51 insertions, 0 deletions

diff --git a/doc/.document b/doc/.document
index f35cd4769b..b52a2104a7 100644
--- a/doc/.document
+++ b/doc/.document
@@ -1,4 +1,5 @@
 *.md
+*.rb
 *.rdoc
 NEWS-*
 syntax
diff --git a/doc/transcode.rb b/doc/transcode.rb
new file mode 100644
index 0000000000..2c70a250e9
--- /dev/null
+++ b/doc/transcode.rb
@@ -0,0 +1,50 @@
+class String
+  # call-seq:
+  #   encode(dst_encoding = Encoding.default_internal, **enc_opts) -> string
+  #   encode(dst_encoding, src_encoding, **enc_opts)   -> string
+  #
+  # Returns a copy of +self+ transcoded as determined by +dst_encoding+.
+  # By default, raises an exception if +self+
+  # contains an invalid byte or a character not defined in +dst_encoding+;
+  # that behavior may be modified by encoding options; see below.
+  #
+  # With no arguments:
+  #
+  # - Uses the same encoding if <tt>Encoding.default_internal</tt> is +nil+
+  #   (the default):
+  #
+  #     Encoding.default_internal # => nil
+  #     s = "Ruby\x99".force_encoding('Windows-1252')
+  #     s.encoding                # => #<Encoding:Windows-1252>
+  #     s.bytes                   # => [82, 117, 98, 121, 153]
+  #     t = s.encode              # => "Ruby\x99"
+  #     t.encoding                # => #<Encoding:Windows-1252>
+  #     t.bytes                   # => [82, 117, 98, 121, 226, 132, 162]
+  #
+  # - Otherwise, uses the encoding <tt>Encoding.default_internal</tt>:
+  #
+  #     Encoding.default_internal = 'UTF-8'
+  #     t = s.encode              # => "Ruby™"
+  #     t.encoding                # => #<Encoding:UTF-8>
+  #
+  # With only argument +dst_encoding+ given, uses that encoding:
+  #
+  #   s = "Ruby\x99".force_encoding('Windows-1252')
+  #   s.encoding            # => #<Encoding:Windows-1252>
+  #   t = s.encode('UTF-8') # => "Ruby™"
+  #   t.encoding            # => #<Encoding:UTF-8>
+  #
+  # With arguments +dst_encoding+ and +src_encoding+ given,
+  # interprets +self+ using +src_encoding+, encodes the new string using +dst_encoding+:
+  #
+  #   s = "Ruby\x99"
+  #   t = s.encode('UTF-8', 'Windows-1252') # => "Ruby™"
+  #   t.encoding                            # => #<Encoding:UTF-8>
+  #
+  # Optional keyword arguments +enc_opts+ specify encoding options;
+  # see {Encoding Options}[rdoc-ref:encoding.rdoc@Encoding+Options].
+  def encode(dst_encoding = Encoding.default_internal, **enc_opts)
+    # Pseudo code
+    Builtin.str_transcode!(...)
+  end
+end