Preserve line breaks and white space in algorithm steps

[gibson042]

Temporal makes extensive use of line breaks in defining large Records, but they end up collapsed in rendered documentation (for example, ParseTemporalInstantString source vs. result). As noted in tc39/proposal-temporal#2290 (review) , that hinders readability.

This PR updates the CSS to preserve line breaks and whitespace while preserving wrapping of long lines.

[bakkot]

Hmm. I agree we need better formatting for large records, but I'm not totally convinced by the approach of preserving whitespace - I think I'd like to handle them explicitly. Right now I definitely assume whitespace will get collapsed when working with ecmarkdown text.

[ljharb]

I think that assumption is fine, but rather than forcing authors to set up the spacing, could ecmarkup not just explicitly format any record with more than, say, 3 fields, to be multiline?

[bakkot]

Yeah, that's what I meant by "handle them explicitly" (though it would be a little more complicated than that - you only want to expand a record at the end of a line, and you probably want to let the user control whether expansion happens by omitting or including a linebreak after the initial {).

[gibson042]

Hmm. I agree we need better formatting for large records, but I'm not totally convinced by the approach of preserving whitespace - I think I'd like to handle them explicitly. Right now I definitely assume whitespace will get collapsed when working with ecmarkdown text.

Do you have any concrete examples? All I can find in ECMA-262 are two cases of embedded tables¹, which can also be addressed with CSS like emu-alg figure { white-space: normal; margin-top: 0; } but should probably be refactored anyway.

I did consider something like Record auto-formatting, but ultimately came to the conclusion that the rendering of steps should generally match their source representation—the author of the latter is best-positioned to determine the appropriateness of forced line breaks etc. in the former.

Footnotes

1. Assignment Operators Evaluation and ApplyStringOrNumericBinaryOperator.

   $ awk '
     /<\/emu-alg>/       { alg = 0; next; }
     !alg                { alg = match($0, "<emu-alg"); prev = ""; next; }
     /^[[:space:]]*[1*]/ { prev = $0; next; }
                         { if (prev) printf "---\n%d: %s\n", NR - 1, prev; printf "%d: %s\n", NR, $0; prev = ""; }
   ' spec.html
   ---
   20239:         1. Let _opText_ be the sequence of Unicode code points associated with _assignmentOpText_ in the following table:
   20240:           <figure>
   20241:             <!-- emu-format ignore -->
   20242:             <table class="lightweight-table">
   20243:               <tr><th> _assignmentOpText_ </th><th> _opText_       </th></tr>
   20244:               <tr><td> `**=`              </td><td> `**`           </td></tr>
   20245:               <tr><td> `*=`               </td><td> `*`            </td></tr>
   20246:               <tr><td> `/=`               </td><td> `/`            </td></tr>
   20247:               <tr><td> `%=`               </td><td> `%`            </td></tr>
   20248:               <tr><td> `+=`               </td><td> `+`            </td></tr>
   20249:               <tr><td> `-=`               </td><td> `-`            </td></tr>
   20250:               <tr><td> `&lt;&lt;=`        </td><td> `&lt;&lt;`     </td></tr>
   20251:               <tr><td> `&gt;&gt;=`        </td><td> `&gt;&gt;`     </td></tr>
   20252:               <tr><td> `&gt;&gt;&gt;=`    </td><td> `&gt;&gt;&gt;` </td></tr>
   20253:               <tr><td> `&amp;=`           </td><td> `&amp;`        </td></tr>
   20254:               <tr><td> `^=`               </td><td> `^`            </td></tr>
   20255:               <tr><td> `|=`               </td><td> `|`            </td></tr>
   20256:             </table>
   20257:           </figure>
   ---
   20337:         1. Let _operation_ be the abstract operation associated with _opText_ and Type(_lnum_) in the following table:
   20338:           <figure>
   20339:             <!-- emu-format ignore -->
   20340:             <table class="lightweight-table">
   20341:               <tr><th> _opText_       </th><th> Type(_lnum_) </th><th> _operation_                </th></tr>
   20342:               <tr><td> `**`           </td><td> Number       </td><td> Number::exponentiate       </td></tr>
   20343:               <tr><td> `*`            </td><td> Number       </td><td> Number::multiply           </td></tr>
   20344:               <tr><td> `*`            </td><td> BigInt       </td><td> BigInt::multiply           </td></tr>
   20345:               <tr><td> `/`            </td><td> Number       </td><td> Number::divide             </td></tr>
   20346:               <tr><td> `%`            </td><td> Number       </td><td> Number::remainder          </td></tr>
   20347:               <tr><td> `+`            </td><td> Number       </td><td> Number::add                </td></tr>
   20348:               <tr><td> `+`            </td><td> BigInt       </td><td> BigInt::add                </td></tr>
   20349:               <tr><td> `-`            </td><td> Number       </td><td> Number::subtract           </td></tr>
   20350:               <tr><td> `-`            </td><td> BigInt       </td><td> BigInt::subtract           </td></tr>
   20351:               <tr><td> `&lt;&lt;`     </td><td> Number       </td><td> Number::leftShift          </td></tr>
   20352:               <tr><td> `&lt;&lt;`     </td><td> BigInt       </td><td> BigInt::leftShift          </td></tr>
   20353:               <tr><td> `&gt;&gt;`     </td><td> Number       </td><td> Number::signedRightShift   </td></tr>
   20354:               <tr><td> `&gt;&gt;`     </td><td> BigInt       </td><td> BigInt::signedRightShift   </td></tr>
   20355:               <tr><td> `&gt;&gt;&gt;` </td><td> Number       </td><td> Number::unsignedRightShift </td></tr>
   20356:               <tr><td> `&amp;`        </td><td> Number       </td><td> Number::bitwiseAND         </td></tr>
   20357:               <tr><td> `&amp;`        </td><td> BigInt       </td><td> BigInt::bitwiseAND         </td></tr>
   20358:               <tr><td> `^`            </td><td> Number       </td><td> Number::bitwiseXOR         </td></tr>
   20359:               <tr><td> `^`            </td><td> BigInt       </td><td> BigInt::bitwiseXOR         </td></tr>
   20360:               <tr><td> `|`            </td><td> Number       </td><td> Number::bitwiseOR          </td></tr>
   20361:               <tr><td> `|`            </td><td> BigInt       </td><td> BigInt::bitwiseOR          </td></tr>
   20362:             </table>
   20363:           </figure>
   

   ↩

[bakkot]

I don't know that I deliberately rely on whitespace collapsing; rather it's just that it's (kind of) HTML, and I assume whitespace always collapses when writing HTML.

Even if we did make it whitespace-sensitive, for formatting records in particular I'd still want emu-format to insist on a particular style for multi-line records (though it would not determine whether to multi-line). So we're not going to respect the source representation very much either way.

[gibson042]

I don't know that I deliberately rely on whitespace collapsing; rather it's just that it's (kind of) HTML, and I assume whitespace always collapses when writing HTML.

I don't disagree with you, but <emu-alg> acts a lot like <pre> in this respect (e.g., ecmarkdown is already sensitive to whitespace for list item indentation).

Even if we did make it whitespace-sensitive, for formatting records in particular I'd still want emu-format to insist on a particular style for multi-line records (though it would not determine whether to multi-line). So we're not going to respect the source representation very much either way.

Sure, but that's just linting—there'd be a relevant difference between single-line vs. multi-line Records and a programatically-enforcable opinion about which style is appropriate.

[bakkot]

Fair point about lists. I'm still not sure about fully general whitespace-sensitivity, though.

I guess my actual opinion is, I think explicitly supporting multi-line records is sufficient for the use case we actually have, and is a much more narrowly scoped change, so I'm more inclined in that direction. If there's some reason to want the more general thing I'd be happier going that way.

Still, maybe we can merge this as-is (once I review and upstream the prerequisite ecmarkdown PR) and maybe switch it out for the more narrow thing when I get around to actually implementing that.

[gibson042]

Works for me. As far as I know, large records and the aforementioned embedded tables are the only examples of line-oriented formatting inside <emu-alg> items, and the latter are already an escape hatch.

[gibson042]

P.S. This could actually be merged ahead of tc39/ecmarkdown#94 ; the only negative consequence would be a little bit of extra rendered whitespace. But I agree that there's no need to rush.