Text Wrapping Behavior in p5.js doesn't match the documentation

[SableRaf]

The text wrapping behavior in p5.js does not match the documentation for text() (or the documentation is ambiguous). The documentation states that specifying maxWidth and maxHeight in the text() function should automatically wrap text within those dimensions:

"The fourth and fifth parameters, maxWidth and maxHeight, are optional. They set the dimensions of the invisible rectangle containing the text...Text will wrap to fit within the text box."

While word wrapping occurs when boundaries are set, character-wise wrapping requires the additional textWrap(CHAR) call, which is not mentioned in the documentation.

This is also different from the way the text() function works in Processing, where text character-wise wrapping is enabled by default when setting the fourth and fifth parameters of the text() function (see: https://github.com/processing/processing-website/issues/544)

Steps to Resolve

I can think of two ways to resolve this:

A) Set text() to automatically wrap characters when setting the fourth and fifth parameters. This would have the advantage of matching the behavior of the function by the same name in Processing.

or

B) Update the documentation to clarify that "Text will wrap to fit within the text box" on words only and that an additional textWrap(CHAR) will be required to wrap on characters.

[dhowe]

Thanks for this @SableRaf

I'm not seeing the behavior you describe in processing, at least in 4.3:

I also don't see it in the docs:

[SableRaf]

Thanks for your question! I should have included examples/screenshots to clarify.

The issue is with the default behavior of p5.js being inconsistent with the text() documentation page.

The fourth and fifth parameters, maxWidth and maxHeight, are optional. They set the dimensions of the invisible rectangle containing the text. By default, they set its maximum width and height. See rectMode() for other ways to define the rectangular text box. Text will wrap to fit within the text box.

However the text doesn't wrap on characters but only on words by default.

An extra textWrap(CHAR) has to be added to get p5.js to behave as described in the doc.

In Processing, the text wraps on characters by default if setting the text box's width, without the need to call textWrap().

Since p5.js doesn't have the goal to match the behavior of Processing exactly, it could also be a case of updating the documentation to clarify that behavior.

[dhowe]

Understood. I'm wondering if this is a duplicate of https://github.com/processing/p5.js/issues/4652, which was marked as completed (but may not be). Is this only an issue when a single 'word' is wider than the bounding box, or are there other cases?

[SableRaf]

I only noticed a discrepancy on those "long words".

Also related is https://github.com/processing/p5.js/issues/5321 in which @limzykenneth said:

This has been address by https://github.com/processing/p5.js/pull/5146 with the addition of the textWrap() function.

If that's the case then the documentation could make clearer that the default wrapping behavior is word-wise as opposed to character-wise, especially since this differs from the default behavior in Processing.

[Mamatha1718]

Hi @SableRaf I tested this issue using the following p5.js code and confirmed that the default text wrapping only breaks at spaces. It does not wrap long words unless textWrap(CHAR) is explicitly called. This is the output

Thank You

[Mamatha1718]

Hi @SableRaf ,Is this issue is still open. I’d like to contribute by updating the documentation to clarify this behavior. I would like to adding a note under the text() function description explaining that word-based wrapping is the default and textWrap(CHAR) is required for character wrapping. Could you please guide me on where to update the documentation? Thank You!

[SableRaf]

@Mamatha1718 Before updating the text() documentation, we should decide whether to keep the current behavior or aligning it with the documentation.

As discussed in #4652, some users find it confusing that long words don’t automatically wrap within the specified dimensions of text().

A fix was merged in #4712, introducing character-wise wrapping with hyphens, but this change led to confusion for some people (#5081) and was later reverted in #5093.

My preference is for character-wrapping (without hyphens) to be the default, matching the documentation and the behaviour in Processing. That said, I'm open to other perspectives.

We should hear from others before making a decision. @ksen0, @dhowe, @limzykenneth, what do you think?

[dhowe]

My 2-centz is to opt for backwards-compatibility... Whatever the ideal solution (I don't remember why we did this the first time around), there are lots of 1.x sketches out there that would break if we were to change this now

[limzykenneth]

I would suggest maintaining backwards compatibility as well. @SableRaf I'm not entirely sure what you mean by "character-wrapping (without hyphens) to be the default, matching the documentation" as what I see in the documentation for p5.js is word based wrapping by default instead of character based wrapping?

For me the main case for character based wrapping is for languages that don't use spaces to delineate between words as these will not wrap in word based wrapping. For English and probably other Latin based language it usually isn't very readable so will likely only be used for text not meant to be read, eg. text as texture.

[Mamatha1718]

@Mamatha1718 Before updating the text() documentation, we should decide whether to keep the current behavior or aligning it with the documentation.

As discussed in #4652, some users find it confusing that long words don’t automatically wrap within the specified dimensions of text().

A fix was merged in #4712, introducing character-wise wrapping with hyphens, but this change led to confusion for some people (#5081) and was later reverted in #5093.

My preference is for character-wrapping (without hyphens) to be the default, matching the documentation and the behaviour in Processing. That said, I'm open to other perspectives.

We should hear from others before making a decision. @ksen0, @dhowe, @limzykenneth, what do you think?

@SableRaf , Thank you for your Response.

[ksen0]

Hi @SableRaf @dhowe @limzykenneth thank you for your input , sounds like the best way forward in this issue is to update the documentation to explain the expected behavior; and keep the current behavior as is for compatibility. Possible changes in behavior can be discussed in https://github.com/processing/p5.js/issues/4652

@Mamatha1718 thanks for your interest, do you want to work on the documentation updates? Let me know and I'll assign you if so!

You can make 2 PR on 1.x (PR merging to main), and on 2.x (PR merging to dev-2.0), but I'd suggest starting with 1.x first, so if there's review and iteration, it's in one place.

The documentation eventually ends up on the site looking the same, but it is created in 2 different places:

• in 1.x, src/typography/loading_displaying.js - ultimately shown here (make your first PR here)
• in 2.0, src/type/textCore.js - ultimately shown here (when your first PR is complete and merged, make the same changes on this branch)

If you do want to work on this, do you have enough to get started?

[Mamatha1718]

Hi @ksen0 Yes, I’d love to work on this! Thank you for the clear instructions. I’ll start with the 1.x branch and create a PR in src/typography/loading_displaying.js. Once that is reviewed and merged, I’ll apply the same changes to the 2.x branch as well.

Please assign me the issue, and I’ll get started right away!

[Mamatha1718]

Hi @SableRaf , @dhowe , @ksen0 , @limzykenneth , I have raised a PR #7780 for this — updated the documentation for textWrap() in src/typography/loading_displaying.js. Will you please let me know if any changes required. Thank you!