Edit docs for typography attributes

[nickmcintyre]

Addresses #6449

Changes:
I edited the inline documentation for functions that set typography attributes to bring them more in line with the style guide.

@davepagurek @dkessner @MsQCompSci @limzykenneth @Qianqianye @dhowe, @paulaxisabel, @SarveshLimaye, @SkylerW99, @hannahvy, @BamaCharanChhandogi, @singshris, @EarthIsHeavin, @skbhagat0502 I'd love to incorporate any feedback you may have!

textAscent() and textDescent() still confuse me, so I'd appreciate your guidance there.

[dhowe]

I noticed one typo (see comment), but otherwise looks good, thanks!

[limzykenneth]

In terms of textAscent and textDescent I'm unsure which aspects confused you so do clarify if you can but looking at the example for those two you created, I think you mostly got it. However I will probably suggest changing the examples to use instead of vertical line, to use horizontal lines instead, explained along with the following diagram

Where for textAscent we draw the baseline and the top ascent line only while for textDescent we draw baseline and the bottom descent line.

[dkessner]

Overall readability looks good. I like the suggestion from @limzykenneth to use horizontal lines in the diagrams to explain textAscent and textDescent.

[nickmcintyre]

@limzykenneth @dkessner I restored edited versions of the original examples for textAscent() and textDescent(). The originals were broken using the default system font on macOS, so I loaded Inconsolata for consistency.

Needing to multiply by scalar messes with my intuition. It feels like textAscent() and textDescent() should do this internally. We can table that for another time.

@dkessner @MsQCompSci here's a staging version of the docs for this pull request. Don't wander too far off the Reference pages or stuff will break–patched just enough of the site to get this working.

Please let me know if you'd like to see further revisions or if we should request a merge.

[dhowe]

Is there a problem with the image for textBounds()
Also, wondering if we should explain what 'tight bounds' means ?

[dkessner]

I'm not sure what "scalar" is supposed to be doing in this example. It's definitely confusing, and should be unnecessary based on my understanding of what textAscent() returns (the height of the 'd').

I looked at the Processing example, which has the same scalar. But weirdly, the example doesn't work when I run it in Processing on Mac (the line is in the wrong place). It does, however, work when I set the scalar to 1.0.
https://processing.org/reference/textAscent_.html

[MsQCompSci]

• I wonder if there is a simpler example for textWidth, textAscent, textDescent. Younger users might find it difficult to understand what it is being used for in the examples included here.

[nickmcintyre]

@dhowe revisions for the font.textBounds() documentation are part of #6453. You can preview them here.

@dkessner @MsQCompSci thanks for looking into this. Agreed that this should be simpler and will give the examples another go this evening.

[nickmcintyre]

@dkessner @MsQCompSci the staging version of the reference for this pull request has new examples. Please let me know if you have suggestions or would like to see further simplifications.

I've never taught these functions to beginners. They are precision tools for more advanced use cases. That said, textAscent() and textDescent() do seem overly complex. I'm probably missing some context for their design.

[dhowe]

Indeed, the fontScale argument does seem less than intuitive. At very least we were trying to match the API for processing at the time, but I'm not sure if there were other factors at play. Taking a very quick glance at the code below, it would seem that this argument could be omitted (and the renderer's current textSize used instead), and thus could be marked as optional. Has anyone tested this?

p5.js/src/typography/p5.Font.js

Line 529 in af34dc8

_textAscent(fontSize) {

[nickmcintyre]

@dhowe thanks for looking into this. I just tested the following changes with the textAscent() example:

// ...
textSize(24);
// ...
let a = textAscent(24);
// ...
textSize(48);
// ..
a = textAscent(48);
// ...

Passing the current font size to textAscent(), as in textAscent(24), didn't affect the ascender's height. It's still necessary to multiply textAscent(24) * fontScale. Calling font._textAscent(24) works the same way. It might be worth starting a separate discussion about textAscent() and textDescent().

@dhowe @Qianqianye @limzykenneth @davepagurek if these changes look good to you, please go ahead an merge this pull request.

[dhowe]

Passing the current font size to textAscent(), as in textAscent(24), didn't affect the ascender's height. It's still necessary to multiply textAscent(24) * fontScale. Calling font._textAscent(24) works the same way. It might be worth starting a separate discussion about textAscent() and textDescent().

If it were possible to include an appropriate fontScale as a default, this would seem to be more intuitive, though we'd then have to weigh it against a) backward compatibility and b) api-sync with processing

[nickmcintyre]

@davepagurek @limzykenneth @Qianqianye if these changes look good to you, please go ahead and merge them.

[Qianqianye]

Thank you all for reviewing. I will merge this PR for now and we can continue the conversation about fontScale.