|
94 | 94 | # - {Directive}[rdoc-ref:RDoc::MarkupReference@Directives]: |
95 | 95 | # various special directions for the rendering. |
96 | 96 | # - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]: |
97 | | -# text to be rendered in italic, bold, or monofont. |
| 97 | +# text to be rendered in a special way. |
98 | 98 | # |
99 | 99 | # About the blocks: |
100 | 100 | # |
|
632 | 632 | # |
633 | 633 | # ==== Text Markup |
634 | 634 | # |
635 | | -# Text markup is metatext that marks text as: |
| 635 | +# Text markup is metatext that affects HTML rendering: |
636 | 636 | # |
637 | | -# - Italic. |
638 | | -# - Bold. |
639 | | -# - Monofont. |
| 637 | +# - Typeface: italic, bold, monofont. |
| 638 | +# - Character conversions: copyright, trademark, certain punctuation. |
| 639 | +# - Links. |
| 640 | +# - Escapes: marking text as "not markup." |
640 | 641 | # |
641 | | -# Text markup may contain only one type of nested block: |
| 642 | +# ===== Typeface Markup |
642 | 643 | # |
643 | | -# - More text markup: |
| 644 | +# Typeface markup can specify that text is to be rendered |
| 645 | +# as italic, bold, or monofont. |
| 646 | +# |
| 647 | +# Typeface markup may contain only one type of nested block: |
| 648 | +# |
| 649 | +# - More typeface markup: |
644 | 650 | # italic, bold, monofont. |
645 | 651 | # |
646 | | -# ===== Italic |
| 652 | +# ====== Italic |
647 | 653 | # |
648 | 654 | # Text may be marked as italic via HTML tag <tt><i></tt> or <tt><em></tt>. |
649 | 655 | # |
|
698 | 704 | # |
699 | 705 | # ====== _Italic_ in a Heading |
700 | 706 | # |
701 | | -# ===== Bold |
| 707 | +# ====== Bold |
702 | 708 | # |
703 | 709 | # Text may be marked as bold via HTML tag <tt><b></tt>. |
704 | 710 | # |
|
755 | 761 | # |
756 | 762 | # ===== *Bold* in a Heading |
757 | 763 | # |
758 | | -# ===== Monofont |
| 764 | +# ====== Monofont |
759 | 765 | # |
760 | 766 | # Text may be marked as monofont |
761 | 767 | # -- sometimes called 'typewriter font' -- |
|
814 | 820 | # |
815 | 821 | # ====== +Monofont+ in a Heading |
816 | 822 | # |
817 | | -# ==== Escaping Text Markup |
818 | | -# |
819 | | -# Text markup can be escaped with a backslash, as in \<tt>, which was obtained |
820 | | -# with <tt>\\<tt></tt>. Except in verbatim sections and between \<tt> tags, |
821 | | -# to produce a backslash you have to double it unless it is followed by a |
822 | | -# space, tab or newline. Otherwise, the HTML formatter will discard it, as it |
823 | | -# is used to escape potential links: |
824 | | -# |
825 | | -# * The \ must be doubled if not followed by white space: \\. |
826 | | -# * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space. |
827 | | -# * This is a link to {ruby-lang}[https://www.ruby-lang.org]. |
828 | | -# * This is not a link, however: \{ruby-lang.org}[https://www.ruby-lang.org]. |
829 | | -# * This will not be linked to \RDoc::RDoc#document |
830 | | -# |
831 | | -# generates: |
832 | | -# |
833 | | -# * The \ must be doubled if not followed by white space: \\. |
834 | | -# * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space. |
835 | | -# * This is a link to {ruby-lang}[https://www.ruby-lang.org] |
836 | | -# * This is not a link, however: \{ruby-lang.org}[https://www.ruby-lang.org] |
837 | | -# * This will not be linked to \RDoc::RDoc#document |
838 | | -# |
839 | | -# Inside \<tt> tags, more precisely, leading backslashes are removed only if |
840 | | -# followed by a markup character (<tt><*_+</tt>), a backslash, or a known link |
841 | | -# reference (a known class or method). So in the example above, the backslash |
842 | | -# of <tt>\S</tt> would be removed if there was a class or module named +S+ in |
843 | | -# the current context. |
844 | | -# |
845 | | -# This behavior is inherited from RDoc version 1, and has been kept for |
846 | | -# compatibility with existing RDoc documentation. |
847 | | -# |
848 | 823 | # ==== Character Conversions |
849 | 824 | # |
850 | 825 | # Certain combinations of characters may be converted to special characters; |
|
891 | 866 | # |
892 | 867 | # - On-page: <tt>::dummy_singleton_method</tt> links to ::dummy_singleton_method. |
893 | 868 | # - Off-page<tt>RDoc::TokenStream::to_html</tt> links to RDoc::TokenStream::to_html. |
894 | | -# to \RDoc::TokenStream::to_html. |
895 | 869 | # |
896 | 870 | # Note: Occasionally \RDoc is not linked to a method whose name |
897 | 871 | # has only special characters. Check whether the links you were expecting |
|
1068 | 1042 | # |
1069 | 1043 | # {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html] |
1070 | 1044 | # |
| 1045 | +# === Escaping Text |
| 1046 | +# |
| 1047 | +# Text that would otherwise be interpreted as markup |
| 1048 | +# can be "escaped," so that it is not interpreted as markup; |
| 1049 | +# the escape character is the backslash (<tt>'\\'</tt>). |
| 1050 | +# |
| 1051 | +# In a verbatim text block or a code block, |
| 1052 | +# the escape character is always preserved: |
| 1053 | +# |
| 1054 | +# Example input: |
| 1055 | +# |
| 1056 | +# This is not verbatim text. |
| 1057 | +# |
| 1058 | +# This is verbatim text, with an escape character \. |
| 1059 | +# |
| 1060 | +# This is not a code block. |
| 1061 | +# |
| 1062 | +# def foo |
| 1063 | +# 'String with an escape character.' |
| 1064 | +# end |
| 1065 | +# |
| 1066 | +# Rendered HTML: |
| 1067 | +# |
| 1068 | +# >>> |
| 1069 | +# This is not verbatim text. |
| 1070 | +# |
| 1071 | +# This is verbatim text, with an escape character \. |
| 1072 | +# |
| 1073 | +# This is not a code block. |
| 1074 | +# |
| 1075 | +# def foo |
| 1076 | +# 'This is a code block with an escape character \.' |
| 1077 | +# end |
| 1078 | +# |
| 1079 | +# In typeface markup (italic, bold, or monofont), |
| 1080 | +# an escape character is preserved unless it is immediately |
| 1081 | +# followed by nested typeface markup. |
| 1082 | +# |
| 1083 | +# Example input: |
| 1084 | +# |
| 1085 | +# This list is about escapes; it contains: |
| 1086 | +# |
| 1087 | +# - <tt>Monofont text with unescaped nested _italic_</tt>. |
| 1088 | +# - <tt>Monofont text with escaped nested \_italic_</tt>. |
| 1089 | +# - <tt>Monofont text with an escape character \</tt>. |
| 1090 | +# |
| 1091 | +# Rendered HTML: |
| 1092 | +# |
| 1093 | +# >>> |
| 1094 | +# This list is about escapes; it contains: |
| 1095 | +# |
| 1096 | +# - <tt>Monofont text with unescaped nested _italic_</tt>. |
| 1097 | +# - <tt>Monofont text with escaped nested \_italic_</tt>. |
| 1098 | +# - <tt>Monofont text with an escape character \ </tt>. |
| 1099 | +# |
| 1100 | +# In other text-bearing blocks |
| 1101 | +# (paragraphs, block quotes, list items, headings): |
| 1102 | +# |
| 1103 | +# - A single escape character immediately followed by markup |
| 1104 | +# escapes the markup. |
| 1105 | +# - A single escape character followed by whitespace is preserved. |
| 1106 | +# - A single escape character anywhere else is ignored. |
| 1107 | +# - A double escape character is rendered as a single backslash. |
| 1108 | +# |
| 1109 | +# Example input: |
| 1110 | +# |
| 1111 | +# This list is about escapes; it contains: |
| 1112 | +# |
| 1113 | +# - An unescaped class name, RDoc, that will become a link. |
| 1114 | +# - An escaped class name, \RDoc, that will not become a link. |
| 1115 | +# - An escape character followed by whitespace \ . |
| 1116 | +# - An escape character \that is ignored. |
| 1117 | +# - A double escape character \\ that is rendered |
| 1118 | +# as a single backslash. |
| 1119 | +# |
| 1120 | +# Rendered HTML: |
| 1121 | +# |
| 1122 | +# >>> |
| 1123 | +# This list is about escapes; it contains: |
| 1124 | +# |
| 1125 | +# - An unescaped class name, RDoc, that will become a link. |
| 1126 | +# - An escaped class name, \RDoc, that will not become a link. |
| 1127 | +# - An escape character followed by whitespace \ . |
| 1128 | +# - An escape character \that is ignored. |
| 1129 | +# - A double escape character \\ that is rendered |
| 1130 | +# as a single backslash. |
| 1131 | +# |
1071 | 1132 | # == Documentation Derived from Ruby Code |
1072 | 1133 | # |
1073 | 1134 | # [Class] |
|
0 commit comments