From: "sawa (Tsuyoshi Sawada)" Date: 2022-11-07T16:58:31+00:00 Subject: [ruby-core:110641] [Ruby master Misc#19109] Documentation ambiguity in ERB Issue #19109 has been updated by sawa (Tsuyoshi Sawada). (1) > String containing zero or more of the following tokens: `%`, `<>`, `>`, `-`. is equivalent to simply saying "String". You can change the sentence to: > The value of `trim_mode` should be `nil` or a `String`. ERB will interpret the following tokens and modify its code generation according to the table below: (2) You have inconsistency/grammatical mistakes in the table, which is inherited from the original. "Enables" is in 3rd person singular present, and "omit" is in the base form. Depending on whether you interpret each line as a sentence (which is possible in the original) or as just a phrase describing the behavior, either may work, but it should be consistent, and since you separated the token and the behavior, using the base form would make sense in your case; use "enable" and "omit". (3) I do not think you need to worry about `<>` being interpreted simultaneously as the token `<>` and as a non-token `<` followed by the token `>`. No language is parsed like that. You may then say it is ambiguous between it being "the token `<>`" **or** "a non-token `<` followed by the token `>`". You can write that, but actually it cannot not be ambiguous. By nature, the more specific `<>` must always have precedence in matching over the less specific `>`. ---------------------------------------- Misc #19109: Documentation ambiguity in ERB https://bugs.ruby-lang.org/issues/19109#change-99979 * Author: otheus (Otheus S) * Status: Open * Priority: Normal ---------------------------------------- Ruby-doc and other sources provide a highly ambiguous explanation for ERB's `trim_mode` and fail to provide any functioning examples. There seems to be no other canonical source to report these errors. The documentation might also be hiding an implementation bug. See point 3 below. The documentation [for 2.5.0 states](https://ruby-doc.org/stdlib-2.5.0/libdoc/erb/rdoc/ERB.html) : "If trim_mode is passed a String containing one or more of the following modifiers" ... followed by a confusing block of text. First, "one or more of the following modifiers" sounds confusing in the context of a String. I've never heard of a String comprised of "modifiers". A "C"/Unix-y way to say this might be "flags". A lower-level way of saying this might be "tokens". But modifiers? Second, the block of text does not look like a list of modifiers. The spacing and typeface makes it appear at glance that the entire line is a modifier. Third, assuming the first token of each line is a modifier, the `<>` modifier is ambiguous with respect to `>`. This might be an implementation bug or a documentation bug -- it's impossible to say for sure. For instance, is `<>>` handled differently than `<>`? My proposal for a re-write (please fact-check the final line): The value of *trim_mode* should be `nil` or a String containing zero or more of the following tokens: `%`, `<>`, `>`, `-`. ERB will interpret these tokens and modify its code generation according to the table below: |token| behavior | |-----|----------| |`%` | enables Ruby code processing for lines beginning with `%` | |`<>` | omit newline for lines starting with `<%` and ending in `%>` | |`>` | omit newline for lines ending in `%>` | |`-` | omit blank lines ending in `-%>` | *Note* The token `<>` does not imply `>`, ie, with only `<>`, lines not beginning with `<%` but ending in `%>` are not trimmed. -- https://bugs.ruby-lang.org/ Unsubscribe: