Draft mode for HTML

[Alex-Jordan]

What are your thoughts on this? For this one, I decided to make something, then discuss. Instead of the usual other way round.

With --stringparam draft yes, this hard codes "(Draft)" into the title in a draft-title span that could be styled. And it makes an empty draft-body div for a background image.

See http://spot.pcc.edu/~ajordan/temp/draft/interesting-corollary.html for what output looks like (once David would properly style it). Right now I'm using some stock "Draft" image for the background, but we'd probably want our own, hosted with the CSS.

[rbeezer]

This would be nice to have. I think we already have latex.draft and latex.watermark. Maybe latex.watermark.scale.

• It would be good to unify/collect switches in -common.
• That'd mean smoothly deprecating the LaTeX versions, while keeping them in use/recognized.
• Can your background image be manufactured to have arbitrary text? Maybe an SVG image gets created from author's stringparam and hard-coded as the background image on the right top-level element?

Like every change there is a bit of a snowball effect. You would only need to change switches on the LaTeX side, not functionality. But I'd like to see functionality on the HTML that is harmonious (not saying identical) with the LaTeX side.

Are you up for it? If so, be sure David has input on CSS, etc.

[Alex-Jordan]

Quick answer to one question, and I'm out for the day.

Can your background image be manufactured to have arbitrary text? Maybe an SVG image gets created from author's stringparam and hard-coded as the background image on the right top-level element?

I'd like that, but my exploration yesterday with background test came up with two ways to get it done:

1. Javascript has to make multiple copies of some text for tiling. Don't like this option because of the added JS, and the text is actual content, so could cause issues with copy/paste, accessibility.
2. CSS's background-image. Seemingly, one must use a URL to an image file to get "text" to tile (and it's not text, it's an image, of course). So no inline definition of an svg, for example. Either the image file is local (we could build it when this stringparam is used) or some central version stored with the .css files.

[davidfarmer]

Shouldn't it be possible to just put class="draft" on the body, and CSS takes care of it (assuming you are okay that "Draft" is the only option for the word in the background).

On Sat, 2 Mar 2019, Alex Jordan wrote:

Quick answer to one question, and I'm out for the day.

  Can your background image be manufactured to have arbitrary text? Maybe an SVG image gets created
  from author's stringparam and hard-coded as the background image on the right top-level element?

I'd like that, but my exploration yesterday with background test came up with two ways to get it done:

1. Javascript has to make multiple copies of some text for tiling. Don't like this option because of the added JS, and the text is actual content, so could cause issues with copy/paste, accessibility.
2. CSS's background-image. Seemingly, one must use a URL to an image file to get "text" to tile (and it's not text, it's an image, of course). So no inline definition of an svg, for example. Either the image file is local (we could build it when this stringparam is used) or some central version stored with the .css files.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.[AAM6LIWEf_y7DhJ-nZiUFSxkJp3iEHa4ks5vSsdcgaJpZM4baNU2.gif]

[Alex-Jordan]

At least a little bit more must be done than CSS, or there is no signal to a screen reader user that it is a draft.

And yes, what David says would work for the styling part. But it is messier XSL to go casewise on what class to use for the main content.

[rbeezer]

I'd like more than just "DRAFT", to parallel LaTeX conversion's watermark.

Signal to screen reader is "(DRAFT)" in the masthead.

See recent work due to the fact that someone asked for variable colors on an SVG play button.

SVG image is manufactured variably for different heights and widths. Slightly different SVG image is manufactured as a "data-uri". I think I have seen this used to inline a background image.

• stringparam gives watermark text (simple ASCCI).
• template has encoded SVG for background image, and inserts text in the right place.
• hard-code background image on correct top-level element.

All done with XSL at build-time, no CSS coordination, no external file.

What am I missing?

[Alex-Jordan]

stringparam gives watermark text (simple ASCCI).

You mean someone would do like --stringparam draft 'Hello World!' and that is the text that would repeat in the background, watermark style? We would not restrict to "draft copy" or something like that?

stringparam gives watermark text (simple ASCCI).

OK, I did not know about using things like url(data:image....). Sounds good.

I like that everything here would be hard coded and not rely on Davids CSS. This way if the content is copied, it is a bit harder to pass it off as not a draft.

Could I wrap this up for HTML, and work on the LaTeX side later? I was thinking that way when I put the draft stringparam in common.

What am I missing?

1. I'm wondering if more signals to the screen-reader user would be good. Maybe the h2 element should also get "(Draft)", since someone might use skip to main content to go there fast and bypass the h1. Sound good? Anywhere else?

2. Should "(Draft)" come before the title or after?

3. Is the watermark text (where my understanding is that this comes from the publisher as they use the stringparam) supposed to match the text used in the h1, or always be "(Draft)"?

[Alex-Jordan]

In my last question, I hope you know what I mean, even though I misworded it. Always "(Draft)" in titles (h1, h2,...) or use whatever the publisher provides for the watermark?

[Alex-Jordan]

Fun fact. To inline style the background svg, you need to go three levels deep with quotations.

style="..."

url('...')

<svg xmlns="...">

So you run out of quotes. But you can escape the innermost with " and all is well.

[rbeezer]

There is nothing to code for LaTeX, but the LaTeX-specific parameters need to be deprecated in favor of the "common" ones, but still work just as they do now. Look to see how the LaTeX parameters behave to see how the new ones should behave for HTML.

In other words, we don't want two different ways to accomplish the same thing. LaTeX got there first, so HTML has to follow.

I'm fine with more signals for a screen reader. But you may have trouble figuring out when an h2 happens, or maybe not? I recently put in place an elaborate mechanism, but perhaps it will be trivial. I'd say the h2 at the top of the content is plenty far enough.

On 3/2/19 5:41 PM, Alex Jordan wrote:

stringparam gives watermark text (simple ASCCI).

You mean someone would do like |--stringparam draft 'Hello World!'| and that is the text that would repeat in the background, watermark style? We would not restrict to "draft copy" or something like that?

stringparam gives watermark text (simple ASCCI).

OK, I did not know about using things like |url(data:image....)|. Sounds good.

I like that everything here would be hard coded and not rely on Davids CSS. This way if the content is copied, it is a bit harder to pass it off as not a draft.

Could I wrap this up for HTML, and work on the LaTeX side later? I was thinking that way when I put the |draft| stringparam in common.

What am I missing?

1.

I'm wondering if more signals to the screen-reader user would be good. Maybe
the |h2| element should also get "(Draft)", since someone might use skip to
main content to go there fast and bypass the |h1|. Sound good? Anywhere else?

2.

Should "(Draft)" come before the title or after?

3.

Is the watermark text (where my understanding is that this comes from the
publisher as they use the stringparam) supposed to match the text used in
the |h1|, or always be "(Draft)"?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/rbeezer/mathbook/pull/1018#issuecomment-468977824, or mute the thread https://github.com/notifications/unsubscribe-auth/ABy2cnbmtZbxzj4iUoqjAw5pSC0NBAClks5vSyg9gaJpZM4baNU2.

[rbeezer]

I ran the whole SVG through an encoder. Search -html for "....-data-uri" template and read comments.

On 3/2/19 6:39 PM, Alex Jordan wrote:

Fun fact. To inline style the background svg, you need to go three levels deep with quotations.

|style="..."|

|url('...')|

|

So you run out of quotes. But you can escape the innermost with |"| and all is well.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/rbeezer/mathbook/pull/1018#issuecomment-468981512, or mute the thread https://github.com/notifications/unsubscribe-auth/ABy2cjnxGsLXYueq16eIsKdhf1-JDeVfks5vSzXbgaJpZM4baNU2.

[Alex-Jordan]

Looking at the LaTeX more, I'm coming to see that LaTeX draft mode is more for the copy editor to easily see typesetting issues. Showing overfull boxes and such things. It's not about alerting the reader that the copy is draft. For that there is the separate watermark feature (where the text can be set to alert the reader the copy is only a draft).

Do we want to continue this distinction as this grows to include HTML?

If so, I don't immediately see the counterpart for "draft" in HTML (where now I mean that as a device for a copy editor to see possible issues more clearly). The function of alerting the reader that the copy is only a draft is what this branch/PR/conversation has been about. Note that is a bit more than just growing watermark to work in HTML, since it would be important to put something the screen reader can catch.

[rbeezer]

When I want to indicate to the reader that a LaTeX version is a draft, I use the watermark, and edit some titlepage piece of information, typically the date.

We would want to alert an AT user to the existence of any watermark, no?

How about the following?

• Implement watermark for HTML.
• Drop a hidden-content div/span (class="watermark"?) with text for the AT user. "Watermark: PREVIEW VERSION"
• Suggest, via accessibility documentation, that authors mark the overall title as a draft so it is in the masthead (yes, I know that can be skipped).
• Move watermark into -common.
• Leave latex.draft alone.

[Alex-Jordan]

OK, ready for looking at. This makes watermark and watermark.scale stringparams from -common.

1. LaTeX behavior is left untouched except as noted below.
2. LaTeX changes the stringparam names. See deprecation note below.
3. The default scaling was 2.0, and a note said this was good for "CONFIDENTIAL", but I found it to be much too large with most of the word "CONFIDENTIAL" off the page. I set default scaling to 0.5.
4. The HTML mimics the LaTeX in the obvious ways. Angle, color, and size.

Things to think about:

1. I am unsure of the right way to deprecate stringparams latex.watermark and 'latex.watermark.scale`. I don't even know where to get started. But I also don't know what behavior it should have. Since this is just a stringparam and doesn't affect source, maybe instead of honoring their values, it should just halt and tell the user to use new stringparams.
2. Should the new stringparam watermark actually be watermark.text?
3. I couldn't directly emulate what you did with the YouTube preview SVG. That is a fixes SVG. This one depends on the two stringparam values. So you can see where I have used a lot of xsl-text to build it. It feels like there could be a way to use inline <svg> tag to get the job done, but since it ends up as a value for a style attribute of a div, things I tried along those lines failed. Maybe you would have more success.

[Alex-Jordan]

And realizing now that I didn't yet do anything for accessibility of the HTML watermark.

[rbeezer]

Visual review:

• Names: this is a good time to change to watermark.text, since we are dropping latex. already.
• Scale: is the default 2.0 scale too big for LaTeX? Or HTML? Or both? Your (3) is not clear, and code comment could go either way.
• Deprecations:
  • Set old parameter to default to empty string.
  • In -common test on the string being empty to see if there is an attempt to use it.
  • Write deprecation warning with others, in same style. Explain that old values still "work."
  • Build new variable in -common that is dashed internal form.
  • Define it with a big xsl:choose
  • first: new dotted form used
  • second: old dotted form used
  • third: default
  • swap in new dashed form in LaTeX (straight replacement) Maybe find an old deprecation commit to crib from.
• Search -common for "Serialization" - this might be the reverse, build SVG as a nodeset and then convert to a text string. See use in Jupyter conversion where some subtleties might be dealt with. Experiment small, this may not be a better solution.

[Alex-Jordan]

Force pushed. And am just now seeing your most recent comment here.

I won't object to coding the backwards compatibility so latex.watermark still "works", but I'll ask: why bother? Isn't it easy enough for a user to change their stringparams? Doesn't it add clutter to the XSL for the smallest of benefits?

Try processing the something into LaTeX with --stringparam latex.watermark CONFIDENTIAL and leave the default scaling at the default of 2. For me, the only visible letters are "FIDENT" and parts of the F, N, and T are clipped. If the scale is 0.5, the whole word is visible, with part of the C and part of the L extending past the textwidth area. More importantly, if the scale is much more than 0.5, then "CONFIDENTIAL" doesn't fit within the 600px-wide #content div in the HTML.

I'll try the svg thing.

[rbeezer]

On fone, so brief. Thanks for scale check, I was not sure about status quo.

I am very sensitive to backwards compatibility, deprecations, upgrades, etc. Author will not see our better variable names the way we do. An urgent need to change will be an irritant. So we absolutely must bother, unless we want to start holding features for new releases.

The extra code is like three lines beyond the actual deprecation warning.

Can't easily run code the next 18 hours. Push by midday with anything new and Wednesday afternoon may be good for me.

On March 4, 2019 10:10:09 PM PST, Alex Jordan notifications@github.com wrote:

Force pushed. And am just now seeing your most recent comment here.

I won't object to coding the backwards compatibility so latex.watermark still "works", but I'll ask: why bother? Isn't it easy enough for a user to change their stringparams? Doesn't it add clutter to the XSL for the smallest of benefits?

Try processing the something into LaTeX with --stringparam latex.watermark CONFIDENTIAL and leave the default scaling at the default of 2. For me, the only visible letters are "FIDENT" and parts of the F, N, and T are clipped. If the scale is 0.5, the whole word is visible, with part of the C and part of the L extending past the textwidth area. More importantly, if the scale is much more than 0.5, then "CONFIDENTIAL" doesn't fit within the 600px-wide #content div in the HTML.

I'll try the svg thing.

[Alex-Jordan]

Looking at your deprecation outline, with the construction happening in -common, it sounds like latex.watermark would end up having an effect on HTML output. Did I read that right?

I was thinking to:

1. Add the deprecation warning to -common.
2. Use common to set the default for the new watermark.text.
3. Respect the old latex.watermark purely within -latex, so you don't get an HTML watermark unless you use the new param.

[rbeezer]

Yes, to respect old use, without new abilities would be best.

On March 6, 2019 2:58:13 PM PST, Alex Jordan notifications@github.com wrote:

Looking at your deprecation outline, with the construction happening in -common, it sounds like latex.watermark would end up having an effect on HTML output. Did I read that right?

I was thinking to:

1. Add the deprecation warning to -common.
2. Use common to set the default for the new watermark.text.
3. Respect the old latex.watermark purely within -latex, so you don't get an HTML watermark unless you use the new param.

[Alex-Jordan]

Ready for review, but no rush.

The serialization of <svg> was not capturing the svg namespace. xmlns looks like an attribute, but it's not. I have something there that works, but you will definitely want to take a close look, and see if it has side effects on Jupyter.

Testing suggestions as follows.

Deprecated stringparams:

xsltproc --stringparam latex.watermark 'CONFIDENTIAL' ../../xsl/mathbook-latex.xsl sample-article.xml
xsltproc --stringparam latex.watermark 'CONFIDENTIAL' --stringparam latex.watermark.scale 1 ../../xsl/mathbook-latex.xsl sample-article.xml

New stringparams with LaTeX:

xsltproc --stringparam watermark.text 'CONFIDENTIAL' ../../xsl/mathbook-latex.xsl sample-article.xml
xsltproc --stringparam watermark.text 'CONFIDENTIAL' --stringparam watermark.scale 1 ../../xsl/mathbook-latex.xsl sample-article.xml

New stringparams with HTML:

xsltproc --stringparam watermark.text 'CONFIDENTIAL' ../../xsl/mathbook-html.xsl sample-article.xml
xsltproc --stringparam watermark.text 'CONFIDENTIAL' --stringparam watermark.scale 1 ../../xsl/mathbook-html.xsl sample-article.xml

For HTML and accessibility, when there is a watermark, there will be a p following the page's h2 with text like Watermark text: CONFIDENTIAL. This p has class watermark. @davidfarmer could make that hidden.

Or maybe there are better ways to address the accessibility issue, but this is the best I could come up with. A screen-reader user who is actually reading anything on the page is highly likely to hit that p. An exception would be if they know the page and want to jump to something beyond the h2.

Even if this p is a good thing, I am unsure that hiding it is necessary. It seems harmless to leave it visible. But I defer to the stylist.

[Alex-Jordan]

Here is a page of HTML with a watermark and the assistive p visible: http://spot.pcc.edu/~ajordan/temp/watermark/interesting-corollary.html

[rbeezer]

Thanks, I'll try to review soon.

Even if this p is a good thing, I am unsure that hiding it is necessary. It seems harmless to leave it visible. But I defer to the stylist.

My vote would be to hide it, since it seems unnecessary for the sighted. And would AT read a class like "hidden-content" if it was there?

But I will defer to you and David. (And any eventual feedback from the groups.)

[rbeezer]

Thanks for this - it'll be very useful.

1. Tested the namespace template against the Jupyter output for AATA. No differences.

2. I added a couple edits on an additional commit. Made it separate so I can take the blame.

Announcement coming, etc.