write() API

[adrianVmariano]

text = can be a string or an array of strings. The string can have newline characters, in which case it is treated as an array of strings

width = (maximum) width the text can occupy. If no font size is given then the size is chosen to fit this width in one line. If a font size is given the text is wrapped to fit in this width.

height = (maximum) height the text can occupy. If no font size is given, the text size is chosen to fit this height. If a font size is given the text is wrapped to produce the shortest width constrained by this height

box=[width,height], alternative parameter for passing width and height more compactly.

If width and height are given together with no font size then the text is fit into the specified box with wrapping at the largest possible font size. If font size is given then the text is

font_size = Size of the font in conventional font size, adjusted by the 0.72 factor. (So 0.72*font_size gets passed to OpenSCAD.)

Msize (Mheight?) = The font size is chosen so an upper case M has the specified size.

align= Set this to "left", "right", "center" or "justify". Note that prototype uses "justify=" but it seems that proper typographic terminology (and the way I've always heard it) was that "justify" means simultaneous right and left alignment. (practicaltypography.com says "justified text is spaced so the left and right sides...both have a clean edge. The alternative...is left-aligned text.") I also noticed that the book says not to use justification without hyphenation. Should align also accept LEFT, RIGHT and CENTER?

align_last= alignment of last line in multiline text. Defaults same as align except when align is "justify" in which case defaults to "left". If there is only one line then this method applies.

valign= "top", "center", "bottom". Vertical alignment to use when text doesn't fully fill a box in the vertical direction. Default: center. (As above, should TOP, CENTER, BOT, BACK, FWD work?)

vcenter_mode = control how Roman text, at least, is centered vertically. As noted by Jordan, at least for small texts with 1-2 lines, it matters if the actual text has ascenders or descenders, so there are different centering choices here. I'm not sure what exactly the modes should be. Actually this concept also connects to the question of margins and indeed how much room you think there is to fit the text, so maybe the name is wrong. That is, does the text end at its actual top or nominal top, and at the actual bottom? Or descender bottom? It seems like some possible choices for how to define the text extent are: nominal text box dimension, actual text size, actual text size ignoring descenders

letter_space= gives a space to add between letters. practicaltypography.com suggests that this be given in relative units, like 5%-12% of the font size, when applying to ALL CAPS. That would suggest accepting a fraction or percentage value. On the other hand, if the goal is to spread letters for 3d printability, maybe an absolute letter space is better? This has to be handled manually in the code by breaking up letters and inserting the space due to the broken letter spacing method used in OpenSCAD. If letterspacing is zero, do NOT break up words and insert zero, instead feed whole words to ensure that ligatures and kerning work optimally. Of course, letterspacing can be a negative value to squish letters together.

line_spacing = a multiplier that controls line spacing.

margin= (is this needed) specifies a margin based on the text somehow. The notes say (interline-ascender)/2. The point here is that an absolute margin is easily created by just changing the box size, so this parameter is needed only if it does something relative to the text.

1. Wrapping of text will apply only to horizontal text. Text written in the vertical direction does not get wrapped.
2. If text is an array (or contains explicit newlines) then no automatic wrapping will be done. (Including a length1 array.)
3. If text is at a specified size and doesn't fit in its width/height constraint then that's an error, ideally with a note on how much the text needs to shrink.
4. Jordan noticed an issue about spacing and balance having to do with the ascenders and descenders in texts which I tried to capture with the vcenter_mode concept above, but maybe it should be something about vboundary---how the boundary of text is defined vertically? I'm not sure. I've also somewhat forgotten the details of the examples, but it was really applicable to things with only 1-2 lines of text and probably not relevant to long texts. There's an example in the wiki for text() where "Foobar" is centered vertically and it looks wrong, presumably because it's centering on the abstract box which has a bunch of extra space above the text.

For anchoring the obvious simple thing is to anchor on the bounding box of the text. There is one point of uncertainty, which is, so you anchor on the actual bounding box of the realized text, or on the nominal requested bounding box. I guess there could be an anchor mode for that.

There is a second question about anchoring to the baseline. This is complicated because (1) there are multiple baselines in multiline text and (2) after saying "baseline" you still have to specify if you mean left, right, or center on the baseline, and for write3d you'd have 6 more directions to manage. My best idea for how to manage this is that we have a function like LINE(dir,n=0) that gives you the named anchor text string for a particular line (or the first line by default) located at the baseline in the direction given by dir. So LINE would produce some text that might look like "baseline_[1,0,0]_4" for LINE(RIGHT,4) and named anchors could be created for all those text strings. This would be easy to do if we had an array of coordinate values providing the baseline locations for each line and the left, right and center for each line (which would depend on whether we're doing actual text extent or bounding box).

[amatulic]

Approaches to letter spacing, for example letter_spacing=1.2:

1. Compute a space to add to each character equal to 20% of the width of uppercase N.
2. Compute a space to add to each character equal to 20% of the width of the normal-spaced text.
3. Compute a space to add to each character equal to 20% of the font size.
4. Add 1.2 units to the spacing of each character.

My preference is option 4. The first two add an element of unpredictability from the user's perspective. I don't like the third one because it uses font height to control horizontal spacing, ignoring the aspect ratio designed into the characters of the font (i.e. narrow vs wide).

You know exactly what you're going to get with option 4. In that case the default letter_spacing would be zero, and negative numbers would compress the spacing.

[adrianVmariano]

I would argue that options 1 and 2 are wrong. Options 1-3 are all relative-to-the-font options, and the standard way to be relative to the font is to work relative to the em, the font box size. Option 1 is going to be annoying for Hebrew...which even if the font has an N it may not be a meaningful referent. Option 2 sounds like it's relative to the text size which is catastrophic, reprising the current OpenSCAD bug.

As far as I can tell, the industry standard for letter spacing appears to be to compute a space to add as a percentage of font size. The typography book I found gives 3 examples of setting letterspacing in different software and they are all (including CSS) shown as a percentage of font size. This is predictable from the user's perspective. I'm not sure what you mean about ignoring aspect ratio. It is of course the case that you will choose different letterspacing for different fonts. The typography book does suggest that 5%-12% is correct for SMALL CAPS, which note is a range, not a single value.

I would say that the industry standard of relative spacing is clearly the right choice for general typography because it means you can make small font size adjustments and your letter spacing adjusts with it, e.g. if you switch your font size from 4 to 5. So if the goal is to produce good looking output, the relative measure makes more sense. If you're trying to letterspace ALL CAPS text because that's the typographically recommended thing to do you'll prefer having relative spacing.

The case for a constant option is that you are adding space not to make the font look good but to space the letters far enough apart for printability. If you really want 1mm spacing between letters this will get you there, though since you are adding space you still don't know exactly how to get there and the amount you need to insert depends on the font size. I suppose it would be possible to guarantee sufficient space with an option like this. This option is bad for someone interesting readability since you have no method for setting the letter spacing as a percentage like is usual, at least in the case where the font size was chosen automatically.

The upshot is that setting relative to font size is standard and easier to use for readability considerations. Within a range you probably wouldn't need to adjust the setting to achieve a desired look. Absolute sizing is bad for this application. You'd be somewhat in the dark about starting point and it would be impossible to make behavior reasonable if the text was being automatically sized and was not known in advance. Setting absolute size may be easier for the goal of creating large gaps to facilitate printing, but it doesn't disconnect you from the need to pay attention to font size, unless you completely dismiss font aesthetics. With relative size you'd potentially have issues about not knowing how to set the spacing to ensure a certain gap, so in dealing with variable text size you might run into problems, e.g. if the goal was to ensure a 1mm gap between letters. This seems to make a case for allowing the specification of letterspacing in two ways, both relative and absolute. But I think if only one is done it should be the typographer's standard relative measure.

One other observation: letter spacing should only be inserted in between letters in a word and not at the end of a word. Maybe this is obvious, but I saw an article about how web browsers do it wrong, so apparently not obvious enough.

[adrianVmariano]

Had an idea for dual units on letterspacing, that might be clever or maybe it's a kludge. Define EM=[1] and the user can say letterspace=.05*EM to get relative spacing or letterspace=1 to get absolute spacing, with the cases distinguishable because one is a number and one is a list.