From: "k0kubun (Takashi Kokubun)" Date: 2022-11-07T18:29:28+00:00 Subject: [ruby-core:110645] [Ruby master Misc#19109] Documentation ambiguity in ERB Issue #19109 has been updated by k0kubun (Takashi Kokubun). Status changed from Open to Feedback Can you make it a PR? I'll look into detail there, but at a glance, what you wrote doesn't look too off. ---------------------------------------- Misc #19109: Documentation ambiguity in ERB https://bugs.ruby-lang.org/issues/19109#change-99986 * Author: otheus (Otheus S) * Status: Feedback * 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: