From c361cf44c03275405989022054d7c20efcc2a2ce Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 11 Aug 2022 08:51:04 -0500 Subject: [PATCH 1/4] [ruby/rdoc] [DOC] Make example formats explicit and consistent (https://github.com/ruby/rdoc/pull/913) https://github.com/ruby/rdoc/commit/7e6ef6c855 --- doc/rdoc/markup_reference.rb | 153 ++++++++++++++++++++--------------- 1 file changed, 87 insertions(+), 66 deletions(-) diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index b3d1d97f4f61be..059511f478e009 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -29,16 +29,37 @@ # see :nodoc:, :doc:, and :notnew. # - \RDoc directives in single-line comments; # see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives]. -# - The Ruby code itself; -# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code] +# - The Ruby code itself (but not from C code); +# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code]. # # == Markup in Comments # -# A single-line or multi-line comment that immediately precedes -# the definition of a class, module, method, alias, constant, or attribute -# becomes the documentation for that defined object. +# The treatment of markup in comments varies according to the type of file: # -# (\RDoc ignores other such comments that do not precede definitions.) +# - .rb (Ruby code file): markup is parsed from Ruby comments. +# - .c (C code file): markup is parsed from C comments. +# - .rdoc (RDoc text file): markup is parsed from the entire file. +# +# The comment associated with +# a Ruby class, module, method, alias, constant, or attribute +# becomes the documentation for that defined object: +# +# - In a Ruby file, that comment immediately precedes +# the definition of the object. +# - In a C file, that comment immediately precedes +# the function that implements a method, +# or otherwise immediately precedes the definition of the object. +# +# In either a Ruby or a C file, +# \RDoc ignores comments that do not precede object definitions. +# +# In an \RDoc file, the text is not associated with any code object, +# but may (depending on how the documentation is built), +# become a separate page. +# +# Almost all examples on this page are all RDoc-like; +# that is, they have no comment markers like Ruby # +# or C /* ... */. # # === Margins # @@ -96,11 +117,11 @@ # # Example input: # -# # \RDoc produces HTML and command-line documentation for Ruby projects. -# # \RDoc includes the rdoc and ri tools for generating and displaying -# # documentation from the command-line. -# # -# # You'll love it. +# \RDoc produces HTML and command-line documentation for Ruby projects. +# \RDoc includes the rdoc and ri tools for generating and displaying +# documentation from the command-line. +# +# You'll love it. # # Rendered HTML: # >>> @@ -133,15 +154,15 @@ # # Example input: # -# # This is not verbatim text. -# # -# # This is verbatim text. -# # Whitespace is honored. # See? -# # Whitespace is honored. # See? -# # -# # This is still the same verbatim text block. -# # -# # This is not verbatim text. +# This is not verbatim text. +# +# This is verbatim text. +# Whitespace is honored. # See? +# Whitespace is honored. # See? +# +# This is still the same verbatim text block. +# +# This is not verbatim text. # # Rendered HTML: # >>> @@ -279,13 +300,13 @@ # # Example input: # -# # - An item. -# # - Another. -# # - An item spanning -# # multiple lines. -# # -# # * Yet another. -# # - Last one. +# - An item. +# - Another. +# - An item spanning +# multiple lines. +# +# * Yet another. +# - Last one. # # Rendered HTML: # >>> @@ -305,13 +326,13 @@ # # Example input: # -# # 100. An item. -# # 10. Another. -# # 1. An item spanning -# # multiple lines. -# # -# # 1. Yet another. -# # 1000. Last one. +# 100. An item. +# 10. Another. +# 1. An item spanning +# multiple lines. +# +# 1. Yet another. +# 1000. Last one. # # Rendered HTML: # >>> @@ -331,13 +352,13 @@ # # Example input: # -# # z. An item. -# # y. Another. -# # x. An item spanning -# # multiple lines. -# # -# # x. Yet another. -# # a. Last one. +# z. An item. +# y. Another. +# x. An item spanning +# multiple lines. +# +# x. Yet another. +# a. Last one. # # Rendered HTML: # >>> @@ -356,13 +377,13 @@ # # Example input: # -# # [foo] An item. -# # bat:: Another. -# # [bag] An item spanning -# # multiple lines. -# # -# # [bar baz] Yet another. -# # bam:: Last one. +# [foo] An item. +# bat:: Another. +# [bag] An item spanning +# multiple lines. +# +# [bar baz] Yet another. +# bam:: Last one. # # Rendered HTML: # >>> @@ -381,20 +402,20 @@ # # Examples: # -# # = Section 1 -# # == Section 1.1 -# # === Section 1.1.1 -# # === Section 1.1.2 -# # == Section 1.2 -# # = Section 2 -# # = Foo -# # == Bar -# # === Baz -# # ==== Bam -# # ===== Bat -# # ====== Bad -# # ============Still a Heading (Level 6) -# # \== Not a Heading +# = Section 1 +# == Section 1.1 +# === Section 1.1.1 +# === Section 1.1.2 +# == Section 1.2 +# = Section 2 +# = Foo +# == Bar +# === Baz +# ==== Bam +# ===== Bat +# ====== Bad +# ============Still a Heading (Level 6) +# \== Not a Heading # # A heading may contain only one type of nested block: # @@ -1147,10 +1168,10 @@ def dummy_instance_method(foo, bar); end; # # Here is the :call-seq: directive given for the method: # - # # :call-seq: - # # call_seq_directive(foo, bar) - # # Can be anything -> bar - # # Also anything more -> baz or bat + # :call-seq: + # call_seq_directive(foo, bar) + # Can be anything -> bar + # Also anything more -> baz or bat # def call_seq_directive nil From 49517b3bb436456407e0ee099c7442f3ab5ac53d Mon Sep 17 00:00:00 2001 From: Jeremy Evans Date: Fri, 26 Feb 2021 12:14:48 -0800 Subject: [PATCH 2/4] Fix inspect for unicode codepoint 0x85 This is an inelegant hack, by manually checking for this specific code point in rb_str_inspect. Some testing indicates that this is the only code point affected. It's possible a better fix would be inside of lower-level encoding code, such that rb_enc_isprint would return false and not true for codepoint 0x85. Fixes [Bug #16842] --- string.c | 10 +++++++++- test/ruby/test_string.rb | 5 +++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/string.c b/string.c index 85819e26a393a3..e74783cf923652 100644 --- a/string.c +++ b/string.c @@ -6777,7 +6777,15 @@ rb_str_inspect(VALUE str) prev = p; continue; } - if ((enc == resenc && rb_enc_isprint(c, enc)) || + /* The special casing of 0x85 (NEXT_LINE) here is because + * Oniguruma historically treats it as printable, but it + * doesn't match the print POSIX bracket class or character + * property in regexps. + * + * See Ruby Bug #16842 for details: + * https://bugs.ruby-lang.org/issues/16842 + */ + if ((enc == resenc && rb_enc_isprint(c, enc) && c != 0x85) || (asciicompat && rb_enc_isascii(c, enc) && ISPRINT(c))) { continue; } diff --git a/test/ruby/test_string.rb b/test/ruby/test_string.rb index d37924dec1904e..ab14a3c17bb7f2 100644 --- a/test/ruby/test_string.rb +++ b/test/ruby/test_string.rb @@ -2614,6 +2614,11 @@ def test_inspect_nul assert_equal '"\x0012"', s.inspect, bug8290 end + def test_inspect_next_line + bug16842 = '[ruby-core:98231]' + assert_equal '"\\u0085"', 0x85.chr(Encoding::UTF_8).inspect, bug16842 + end + def test_partition assert_equal(%w(he l lo), S("hello").partition(/l/)) assert_equal(%w(he l lo), S("hello").partition("l")) From a677aa0fcf6b43668b1e6ceac67b4a4121afd818 Mon Sep 17 00:00:00 2001 From: git Date: Fri, 12 Aug 2022 00:47:48 +0900 Subject: [PATCH 3/4] * 2022-08-12 [ci skip] --- version.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/version.h b/version.h index 780a93e8dcc0de..1b561623e94b58 100644 --- a/version.h +++ b/version.h @@ -15,7 +15,7 @@ #define RUBY_RELEASE_YEAR 2022 #define RUBY_RELEASE_MONTH 8 -#define RUBY_RELEASE_DAY 11 +#define RUBY_RELEASE_DAY 12 #include "ruby/version.h" #include "ruby/internal/abi.h" From 8a3f401b24e1b5f3e3a0f44c568a3e66ed595d42 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 11 Aug 2022 11:43:39 -0500 Subject: [PATCH 4/4] [ruby/rdoc] Improvements to Text Markup examples (https://github.com/ruby/rdoc/pull/915) https://github.com/ruby/rdoc/commit/d00ddfe57c --- doc/rdoc/markup_reference.rb | 104 ++++++++++++++++------------------- 1 file changed, 48 insertions(+), 56 deletions(-) diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index 059511f478e009..c7578f3581107f 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -649,27 +649,27 @@ # # Example input: # -# Two words in a paragraph. +# Italicized words in a paragraph. # # >>> -# Two words in a block quote. +# Italicized words in a block quote. # -# - Two words in a bullet list item. +# - Italicized words in a list item. # -# ====== Two words in a Heading +# ====== Italicized words in a Heading # # Italicized passage containing *bold* and +monofont+. # # Rendered HTML: # >>> -# Two words in a paragraph. +# Italicized words in a paragraph. # # >>> -# Two words in a block quote. +# Italicized words in a block quote. # -# - Two words in a bullet list item. +# - Italicized words in a list item. # -# ====== Two words in a Heading +# ====== Italicized words in a Heading # # Italicized passage containing *bold* and +monofont+. # @@ -678,29 +678,25 @@ # # Example input: # -# _Word_ in a paragraph. +# _Italic_ in a paragraph. # # >>> -# _Word_ in a block quote. +# _Italic_ in a block quote. # -# - _Word_ in a bullet list item. +# - _Italic_ in a list item. # -# [_word_] _Word_ in a labeled list item. -# -# ====== _Word_ in a Heading +# ====== _Italic_ in a Heading # # Rendered HTML: # >>> -# _Word_ in a paragraph. +# _Italic_ in a paragraph. # # >>> -# _Word_ in a block quote. -# -# - _Word_ in a bullet list item. +# _Italic_ in a block quote. # -# [_word_] _Word_ in a labeled list item. +# - _Italic_ in a list item. # -# ====== _Word_ in a Heading +# ====== _Italic_ in a Heading # # ===== Bold # @@ -708,28 +704,28 @@ # # Example input: # -# Two words in a paragraph. +# Bold words in a paragraph. # # >>> -# Two words in a block quote. +# Bold words in a block quote. # -# - Two words in a bullet list item. +# - Bold words in a list item. # -# ====== Two words in a Heading +# ====== Bold words in a Heading # # Bold passage containing _italics_ and +monofont+. # # Rendered HTML: # # >>> -# Two words in a paragraph. +# Bold words in a paragraph. # # >>> -# Two words in a block quote. +# Bold words in a block quote. # -# - Two words in a bullet list item. +# - Bold words in a list item. # -# ====== Two words in a Heading +# ====== Bold words in a Heading # # Bold passage containing _italics_ and +monofont+. # @@ -738,30 +734,26 @@ # # Example input: # -# *Word* in a paragraph. +# *Bold* in a paragraph. # # >>> -# *Word* in a block quote. +# *Bold* in a block quote. # -# - *Word* in a bullet list item. +# - *Bold* in a list item. # -# [*word*] *Word* in a labeled list item. -# -# ===== *Word* in a Heading +# ===== *Bold* in a Heading # # Rendered HTML: # # >>> -# *Word* in a paragraph. +# *Bold* in a paragraph. # # >>> -# *Word* in a block quote. -# -# - *Word* in a bullet list item. +# *Bold* in a block quote. # -# [*word*] *Word* in a labeled list item. +# - *Bold* in a list item. # -# ===== *Word* in a Heading +# ===== *Bold* in a Heading # # ===== Monofont # @@ -771,28 +763,28 @@ # # Example input: # -# Two words in a paragraph. +# Monofont words in a paragraph. # # >>> -# Two words in a block quote. +# Monofont words in a block quote. # -# - Two words in a bullet list item. +# - Monofont words in a list item. # -# ====== Two words in heading +# ====== Monofont words in heading # # Monofont passage containing _italics_ and *bold*. # # Rendered HTML: # # >>> -# Two words in a paragraph. +# Monofont words in a paragraph. # # >>> -# Two words in a block quote. +# Monofont words in a block quote. # -# - Two words in a bullet list item. +# - Monofont words in a list item. # -# ====== Two words in heading +# ====== Monofont words in heading # # Monofont passage containing _italics_ and *bold*. # @@ -801,26 +793,26 @@ # # Example input: # -# +Word+ in a paragraph. +# +Monofont+ in a paragraph. # # >>> -# +Word+ in a block quote. +# +Monofont+ in a block quote. # -# - +Word+ in a bullet list item. +# - +Monofont+ in a list item. # -# ====== +Word+ in a Heading +# ====== +Monofont+ in a Heading # # Rendered HTML: # # >>> -# +Word+ in a paragraph. +# +Monofont+ in a paragraph. # # >>> -# +Word+ in a block quote. +# +Monofont+ in a block quote. # -# - +Word+ in a bullet list item. +# - +Monofont+ in a list item. # -# ====== +Word+ in a Heading +# ====== +Monofont+ in a Heading # # ==== Escaping Text Markup #