Percent (%) symbol is being rendered in italics in the HTML SRS

[BilalM04]

The percent (%) symbol is being rendered in italics in the HTML SRS, when it should not be.

HTML: % is wrapped in an <em></em> tag. For example:

Drasil/code/stable/dblpend/SRS/HTML/DblPend_SRS.html

Line 2374 in 21ff358

<td>10<em>%</em></td>

From briefly looking at the Drasil code, it seems that % is defined as an operator, thus it is printed as an expression.

[smiths]

Is % implemented as the modulus operator?

[BilalM04]

Looking at the following code:

Drasil/code/drasil-printers/lib/Language/Drasil/Printing/AST.hs

Lines 9 to 16 in 21ff358

	-- | Different operators.
	data Ops = IsIn | Integer | Real | Rational | Natural | Boolean | Comma | Prime | Log
	| Ln | Sin | Cos | Tan | Sec | Csc | Cot | Arcsin | Arccos | Arctan | Not
	| Dim | Exp | Neg | Cross | Dot | Scale | Eq | NEq | Lt | Gt | LEq | GEq | Impl | Iff
	| Subt | And | Or | Add | Mul | Summ | Inte | Prod | Point | Perc | LArrow | RArrow | ForAll
	| VAdd | VSub | Partial

There doesn't seem to be an explicit modulus operator, just percent (labeled Perc). Thus, I'd assume in Drasil both percent and modulus are implemented together as Perc.

[JacquesCarette]

It seems weird to me that Perc is an operator. I would want to trace it some more (i.e. both upstream, as in who generates this Perc and downstream, i.e. how is it actually handled by the printers themselves.)

[balacij]

I would imagine that a % should be rendered in the same slice of code we use to render units -- @BilalM04 do you think that is possible? Do we think this is sensible?

[BilalM04]

To my knowledge, units are rendered as expressions; thus, it would still be italicized. All of the printers wrap expressions in some sort or italics or in-line equation wrappers. To add on to the original issue, I investigated the problem further.

For printing, the Perc operator is wrapped in an Expr, which is where the italicization begins:

Drasil/code/drasil-printers/lib/Language/Drasil/Printing/Import/Sentence.hs

Line 30 in 864e138

spec _ Percent = P.E $ P.MO P.Perc

Here is the Expr data type, which contains Ops:

Drasil/code/drasil-printers/lib/Language/Drasil/Printing/AST.hs

Lines 28 to 46 in 864e138

	-- | Redefine the 'Expr' type from Language.Drasil to be more suitable to printing.
	data Expr = Dbl Double
	| Int Integer
	| Str String
	| Case [(Expr, Expr)] -- ^ Case expressions
	| Mtx [[Expr]] -- ^ Matrix.
	| Row [Expr]
	| Ident String
	| Label String
	| Spec Special -- ^ Special characters.
	| Sub Expr -- ^ Subscript.
	| Sup Expr -- ^ Superscript.
	| MO Ops
	| Over OverSymb Expr -- ^ Holds an expression that needs a hat symbol "^"
	| Fenced Fence Fence Expr -- ^ Holds an expression that is surrounded with a 'Fence'.
	| Font Fonts Expr -- ^ Holds an expression with a font.
	| Div Expr Expr -- ^ Fractions are a layout thing.
	| Sqrt Expr -- ^ Roots are also a layout thing. Just sqrt for now.
	| Spc Spacing -- ^ Holds the 'Spacing'.

This Expr is then wrapped in a Spec:

Drasil/code/drasil-printers/lib/Language/Drasil/Printing/AST.hs

Lines 50 to 58 in 864e138

	-- | Redefine the 'Sentence' type from Language.Drasil to be more suitable to printing.
	data Spec = E Expr -- ^ Holds an expression.
	| S String -- ^ Holds a String.
	| Spec :+: Spec -- ^ Concatenation.
	| Sp Special -- ^ Special characters.
	| Ref LinkType String Spec -- ^ Holds the actual reference of form 'LinkType', reference address, and display name
	| EmptyS -- ^ Empty sentence.
	| Quote Spec -- ^ Quotes are different in different languages.
	| HARDNL -- Temp fix for multi-line descriptions;

Thus, when printing, since the top level data type is a Spec then an Expr, the contents are then italicized.

---

Two possible solutions I thought of were:

1. Render Percent as a String. This means it would no longer be an Expr.
   • Pros: easy to implement
   • Cons: String rendering currently errors out if it contains certain special characters, including %. We would need to allow %.
2. Render Percent as a Special.
   • I do not know much about rendering special characters. Currently, there only seems to be one special character defined in Language.Drasil.Unicode, which is Circle. There are TeX and HTML monads that then help with rendering. I am also not sure how implementing this would go.

[smiths]

@BilalM04 you got my attention with "units are rendered as expressions; thus, it would still be italicized". The problem you are discussing is actually deeper than just the percent symbol. I wonder if this is a chance to fix our rendering of units in Drasil? According to SI rules, units should NOT be in italics. This rule can be seen in the NIST checklist item 6. Some of the units in Drasil are not in italics, while others are. For instance, in the double pendulum example, $a_{x1}$ has the correct font, but $F$ does not. It seems like the units that require division are correct, but the straight units are not.

We should stop rendering units in italics. I think that is the bigger picture problem to try to solve. If we stop using italics, then it fixes the percentage symbol, and everything else that is currently wrong. 😄

If we can fix this, we should add it to our list of successes in Drasil. (When we do this we should also fix the spelling of cosmetic in the current example benefit.) I grade many SRS documents in my grad course every year and students struggle with the rule that units are not in italics. It is just too fiddly a detail for must people to keep track of consistently. We are currently doing the thing where it is wrong everywhere, but when we fix it, it will be right everywhere. 😄

[BilalM04]

@smiths and I discussed the rendering of units in italics in meeting #3791, I will reiterate the discussion here.

The reason % and units are being rendered in italics is due to the way HTML prints expressions. Due to previous issues on Mathjax being slow to render, the smaller expressions in HTML use plain HTML syntax rather than LaTeX. As a result, certain units and smaller expressions look visibly different, and are also in italics.

For certain expressions, it uses straight HTML, otherwise, it delegates to the TeX functions. Here is the code for rendering expressions in HTML:

Drasil/code/drasil-printers/lib/Language/Drasil/HTML/Print.hs

Lines 158 to 178 in 864e138

	-- | Renders expressions in the HTML document (called by multiple functions).
	pExpr :: Expr -> Doc
	pExpr (Dbl d) = text $ showEFloat Nothing d ""
	pExpr (Int i) = text $ show i
	pExpr (Str s) = doubleQuotes $ text s
	pExpr (Row l) = hcat $ map pExpr l
	pExpr (Ident s) = text s
	pExpr (Label s) = text s
	pExpr (Spec s) = text $ unPH $ L.special s
	--pExpr (Gr g) = unPH $ greek g
	pExpr (Sub e) = sub $ pExpr e
	pExpr (Sup e) = sup $ pExpr e
	pExpr (Over Hat s) = pExpr s <> text "&#770;"
	pExpr (MO o) = text $ pOps o
	pExpr (Fenced l r e) = text (fence Open l) <> pExpr e <> text (fence Close r)
	pExpr (Font Bold e) = bold $ pExpr e
	pExpr (Font Emph e) = text "<em>" <> pExpr e <> text "</em>" -- FIXME
	pExpr (Spc Thin) = text "&#8239;"
	-- Uses TeX for Mathjax for all other exprs
	pExpr e = mjDelimDisp $ printMath $ toMath $ TeX.pExpr e
	where mjDelimDisp d = text "\\(" <> d <> text "\\)"

Additionally, all expressions in HTML are wrapped in an <em></em> tag here:

Drasil/code/drasil-printers/lib/Language/Drasil/HTML/Print.hs

Line 131 in 864e138

pSpec (E e) = em $ pExpr e

This issue in HTML can be solved by using TeX for all expressions and removing the <em> wrapper. Solely removing the <em> wrapper (which I tested) does not work as Drasil has no way of differentiang regular variables, which should be italicized, with units, which should not. @JacquesCarette is using TeX for all expressions in HTML viable, or are the speed differences too noticeable for us to use TeX?

Now, regarding the issue for LaTeX/PDF. The problem with italicization is actually not present in the LaTeX/PDF SRS. After comparing the rendered % in the SRS, with an italic % I manually wrote, I found the % symbol is not being generated in italics after all. Additionally, units are wrapped in \text{} rendering it as normal. I would like to make a correction in the original post, that percent symbol is not italics in the LaTeX version. This issue is only present in the HTML.

[smiths]

Thank you for the summary @BilalM04. We talked about doing an experiment to see the performance hit for rending all units inside \text{} for the html version. If the performance hit is reasonable, then we can fix the fact that units are displayed with the wrong font in the html documents. This won't fix the percentage symbol, but it will be an improvement.

[BilalM04]

@smiths, using LaTeX for all expressions will actually fix the percentage issue as well. Please see the last paragraph of #3748 (comment).

To add on, here is the comparison:

The symbol on the left is $\%$, whereas the symbol on the right is \emph{\%}. Drasil renders the percent symbol as seen on the left hand side, which is the desired result; therefore, it is rendered correctly using LaTeX.

[BilalM04]

I conducted an experiment to evaluate the performance between the existing HTML SRS and an alternative HTML SRS, where all expressions are rendered using Mathjax LaTeX. The tests were executed locally on the Brave browser (Chromium based), on a laptop operating on battery power (unplugged). The rendering of assets like images were excluded from the local tests (as they were not in the path), which resulted in quicker performance times than those anticipated in a hosted environment. Additionally, I have a decently powerful processor (Intel® Core™ i7-13700H), which further influenced the test results. I think caching is disabled in these tests.

NOTE: tests are run on the Projectile SRS.

Current Generated HTML SRS (LOCAL)

Full TeX Expressions HTML SRS (LOCAL)

Current Generated HTML SRS (HOSTED)

For reference, here is the performance stats for the hosted HTML SRS, which currently uses a mix of HTML and Mathjax for expressions. It is the same SRS as the first test, however it is the one hosted on the website rather than run locally.

[JacquesCarette]

Fantastic data! All of these numbers are kind of large, i.e. more than 1s. Adding 300ms between current and full TeX is noticeable.

I'm wondering why the Scripting time is so large -- is it all MathJAX or do we have more scripting?

[balacij]

Some of my thoughts:

• It looks like the slowest part of the webpage loading for me is due to images not being lazy loaded -- 1.7s for the tracegraph SVGs.
• Is lazy typesetting enabled?
• According to pagespeed.dev, our major problem is the amount of HTML nodes we have (>16k for SWHS' SRS!) and scripting causing blocking on the main rendering thread. Splitting up the HTML-based SRS will almost assuredly fix a lot of the issues. Lazy loading of TeX should help with rendering on the main thread.
• I think KaTeX is an alternative to MathJaX. It might be worth exploring if all else fails. Pre-compiling the TeX also.
• If you want to really get into the weeds of performance, use Firefox's profiler (it's easier to use than Chromium's tools in my experience) as well as Google's lighthouse to get key results.

[smiths]

This is a really impressive analysis. It is great that it is based on data and the @balacij has theories that we can explore.

My personal preference is to not get distracted too much by this at this time. I think there are other issues that are more important at the moment.

Having said that, we could use this as a case study to highlight the benefits of Drasil. I'm fairly sure that if we improve the loading time of one webpage, we'll improve the loading time of all of them. Explaining the process of making this improvement would give us another anecdote to promote Drasil.