search

usfm-bible / docs.usfm.bible

Antora playbook project for the USFM / USX end-user documentation site.
0 stars 0 forks source link

Give etymology for <char> and <para> #1

Open merchako opened 2 months ago

merchako commented 2 months ago

Problem: My co-worker and I were very confused as to why <char> would represent a string of characters! I believe most developers would be.

Solution: Give a longer description of what a <char> is, and include etymology.

In most of programming, a "char" is character, such as a value holding one byte in C (one ASCII char) or a unicode character. It took us a long to figure out that's not what USX <char> is.

As a designer, I have experience with layout programs in which every style is either a "Character Style" or a "Paragraph Style". Perhaps that's the reason why the keyword "char" was chosen—because it's a Character Style?

—

FWIW, if my etymology guess is right, I'd suggest doing the same for <para>. These days HTML semantics really dominates the mental space, especially now that Paratext 10 is being developed with web technologies.

In HTML, a paragraph <p> is specifically not a heading <h1–6>, but in USX, a heading h is a type of Paragraph Style. Could you help us out as we read the documentation by mentioning these kinds of differences? Even including phrases like "Paragraph Style" could help attach the mental model to the layout world instead of the many competing mental spaces developers are in.

__

P.S., I noticed that the Characters page says "span" parenthetically, which is an HTML reference. Consider also mentioning "inline" for <char> and "block" for <para> the conceptually pervasive formatting contexts of CSS.

Previously posted as UBS ICAP USX issue 57.

mhosken commented 1 month ago

I agree that it would be helpful to add some text aimed at those coming from an HTML world view.

One primary difference between USX and HTML is that where USX has <para style="s"> HTML has <s>. That is the typing of USX is simpler in that a node says what it is structurally rather than how it is laid out with the layout being an attribute of the node. HTML is a presentation layer, USX is a semantic layer at the document level. Thus it pushes the styling out of the document and into a styling layer. While it may not do this in the most friendly manner for CSS. CSS was not the target styling system during USX's design, given there are still next to no good CSS paged rendering engines. Mind you:

para[style="r"]

Is not a hard selector to use.

PS Hindsight is a wonderful thing.