pretext
pretext copied to clipboard
PreTeXtBook
Adds support for diagcess diagrams.
This PR introduces the possibility of integrating interactive SVG diagrams into Pretext's HTML output. The basic idea is specify diagrams via their SVG image and XML annotation files
<image data-src="figures/tangent.svg" data-cml="figures/tangent.xml"/>
They are then translated into elements that can be picked up by the diagcess library of the form:
<div class="ChemAccess-element" data-src="figures/tangent.svg" data-cml="figures/tangent.xml"></div>
In addition, if images of this nature exist in a page (or knowl), the diagcess.js library is loaded and initialised, which replaces the above tag with interactive diagrams.
Note, that at the moment it is expected that the diagcess.js file is in the same directory. This is due to the fact that I had to make some changes to the library, mainly to get the knowls working
from the npm CDN.
There are still some other issues we might need to discuss:
- Technically, mainly knowl related.
- Better dealing with loading, e.g., can I know in advance if a knowl in the page might have a diagram?
- Multiple generation of data, for every knowl
- ...
- Aesthetics
- Side-by-side is not yet very pretty.
- MathJax formulas in diagrams are not properly highlighted, as every element is a mini-SVG.
- UI/X * We need to link to a page with the table for keyboard navigation * Shall we always switch on voicing (currently yes) and sonification (currently no).
- ...
I might also have misunderstood some of the xsl code.
Anyway, for the time being, I've put a temporary version of our W4A paper here: https://githubraw.com/zorkow/pretext/w4a2023/w4a2023/ In particular, interactive diagrams are on this page: https://githubraw.com/zorkow/pretext/w4a2023/w4a2023/sec_intro.html
I note that I can't choose reviewers. So here's an explicit ping: @rbeezer @davidfarmer @davidaustinm
Very nice, @zorkow! We need some PreTeXt markup for this. Without HTML-centric data-* etc.
I see an SVG image. Good, we already do that. In fact, we prefer that.
We need a PDF for LaTeX. I'll try a manual conversion in Inkscape, that would be a good start.
Annotations. Silly question - can they be embedded in the SVG somehow? A super-SVG? If not, what is cml short for? We could have an attribute for that, and it could be a signal that the image should be handled differently. Could we assume that foo.svg would always be paired with foo.xml?
In any event, I should be able to make quick progress with what is here, and we can streamline workflow as you and @davidaustinm get further along.
Knowls: this is @davidfarmer's baby. Also, @bnmnetp has a lot of hard-won experience, especially with MathJax. Tuesday drop-in is at Noon Pacific if you want to pop in.
PS: paper looks great!
From Drop-In discussion:
- Long-term these files will come from author's source and like
latex-imagewe will know that it is different from other images. - Short-term we can experiment with some variant of an
imageelement with some extra attribute indicating it is different.
@rbeezer you mentioned a way to add a link to the keyboard commands for the diagrams. Can you point me to the relevant code, so I can add them?
That will be a one-off deal, and a first! So I'm not sure.
Put commands here, and I may work on this in the AM.
Put commands here, and I may work on this in the AM.
Found commands at CDN, will work on integrating.
OK, getting close on doing this PreTeXt-style. Have "experimental" markup, and have hooked this into the usual processing.
-
Knowls are a bigger problem, and am not dancing around that right now.
-
We have to get JS from a CDN. We don't expect authors to put certain files in certain places. ;-)
Using network.* as experiment. So, I put the following into the HEAD:
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/dist/diagcess.js" defer=""></script>
<script type="text/javascript" defer="">
document.addEventListener("DOMContentLoaded", function() {
diagcess.Base.init();
});
</script>
Console shows:
Molecule Structure initialisation failed with: Loading of components failed. diagcess.js:1:38592
d https://cdn.jsdelivr.net/npm/[email protected]/dist/diagcess.js:1
Failed to initialize element ChemAccess-element0 diagcess.js:1:37305
d https://cdn.jsdelivr.net/npm/[email protected]/dist/diagcess.js:1
Beta here, Subsection 9.1: https://pretextbook.org/beta/diagcess/graphics.html
Holler if it goes missing, I am experimenting with rsync at that site. I'll be at Drop-In this afternoon.
An Inkscape conversion of network.svg to PDF lost all the labels. I didn't try very hard. But maybe labels are non-standard in some way?
In the plus column, the rsvg-convert did just fine, which @alexeikolesnikov will find comforting. ;-)
We've had good luck embedding braille fonts in SVG, converting to PDF with rsvg-convert, and embossing. Automating that process is the next thing on my to-do list.
On Fri, Mar 10, 2023 at 10:14 PM Rob Beezer @.***> wrote:
An Inkscape conversion of network.svg to PDF lost all the labels. I didn't try very hard. But maybe labels are non-standard in some way?
In the plus column, the rsvg-convert did just fine, which @alexeikolesnikov https://github.com/alexeikolesnikov will find comforting. ;-)
— Reply to this email directly, view it on GitHub https://github.com/PreTeXtBook/pretext/pull/1944#issuecomment-1464808273, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABTLXTGYJLULFGGEURCQQX3W3PUZDANCNFSM6AAAAAAVRW2MCE . You are receiving this because you were mentioned.Message ID: @.***>
Here's a page with the instructions https://progressiveaccess.com/physics/instructions/
I can also send you the markdown for the page.
Instructions for working with Accessible Diagrams
You can navigate through the diagrams with various keys. Reading the diagram is possible on every platform and browser. Below is a list of keys that you can use for navigation, some more detailed instructions on how to navigate inside a diagram, and some tips on working with some selected screen readers.
Keys to Navigate {#keys-to-navigate}
Initialisation
| Key | Effect |
|---|---|
| Enter, Left-Click, or A | Activate keyboard driven exploration |
| B | Activate menu driven exploration |
| Escape | Leave exploration mode |
Righthanded Navigation
| Key | Result |
|---|---|
| Cursor down | Explore next lower level |
| Cursor up | Explore next upper level |
| Cursor right | Explore next element on level |
| Cursor left | Explore previous element on level |
Lefthanded Navigation
| Key | Result |
|---|---|
| D | Explore next lower level |
| E | Explore next upper level |
| F | Explore next element on level |
| S | Explore previous element on level |
Other Interaction Control
Magnification
| Key | Result |
|---|---|
| N | No magnification |
| M | Step magnification |
| Comma | Direct magnification |
Speech Output and Display
| Key | Result |
|---|---|
| X | Toggle expert mode |
| L | Next language (if available) |
| Z | Toggle subtitles |
| V | Toggle screenread style subtitle |
| C | Next high contrast color |
| T | Toggle monochrome display |
Sound Output
| Key | Result |
|---|---|
| K | Kill sound |
| O | Start sonification (if available) |
| P | Repeat sonification |
| Y | Stop self-voicing (if available) |
| U | Repeat last utterance |
| Space | Repeat last sound |
Navigating in a Diagram {#navigating-in-a-diagram}
If you focusing a diagram you screen reader should announce ‘Navigatable Diagram’ or ‘Navigatable Molecule’. Press ‘Return’ or ‘A’ to start navigation. This will present the name or caption of the diagram or a simple top-level description.
- With the down arrow you go one level deeper. We call this level 1. You are on a (main) component of the diagram. To find out how many main parts there are, press the right arrow key. You step back with the left arrow key.
- To find out what one of the main components consists of, go to that component and press the down arrow key again. Now you have entered level 2, which is a level deeper.
- To know if you are at the deepest possible level, try your down arrow. If another explanation is presented you have entered another, deeper level with additional details. Otherwise you are already on the deepest possible level.
- To move back up one level higher, use the up arrow key.
- In this way you can walk through the diagram and can form a mental picture of where you are in the diagram and how its components relate to each other.
Getting started with your Screen Reader {#working-with-screen-readers}
Here are some tips on what you might need to do to make it easier to work with the accessible diagrams with your particular screen reader or platform.
-
Voice-over on Mac OS
Do you work with voice-over on the Mac? Before you start using the website, you must do a number of things:
- In the VoiceOver utility under the Web tab, check the last option (Always allow keyboard commands to navigate websites).
- Turn off your quick navigation when viewing the diagrams.
- As soon as you hear the announcement of “navigable diagram/molecule”, press A. You can then navigate the diagram. To leave navigation, use quick navigation or press CTRL + Option + arrows.
-
Windows with Jaws
If you work with Jaws, navigate to the diagram with Jaws and press space and then A to enter navigation mode. To exit navigation mode, press the plus on the numeric keypad twice.
-
Windows with NVDA
With NVDA you can enter the diagram by focusing on it pressing Tab. Then press A to enter navigation mode. To exit navigation mode, press ctrl + NVDA + space.
Oops, I seem to be late to the party. I did not see the whole thread. I am sitting in the Santa Cruz with power and Internet outages...
Keyboard Control Knowl constructed. We can adjust styling (it needs it!).
That looks great!
OK, getting close on doing this PreTeXt-style. Have "experimental" markup, and have hooked this into the usual processing.
- Knowls are a bigger problem, and am not dancing around that right now.
- We have to get JS from a CDN. We don't expect authors to put certain files in certain places. ;-)
Using
network.*as experiment. So, I put the following into the HEAD:<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/dist/diagcess.js" defer=""></script> <script type="text/javascript" defer=""> document.addEventListener("DOMContentLoaded", function() { diagcess.Base.init(); }); </script>
The latest released version of diagcess is 1.1.4. That should get around most of the errors you see.
But it won't work with the knowls.
We need to make a release from the latest version. But since this is part of our production environment we first need to test it thoroughly. I can spend some time on this Monday, when the hopefully the storm here is over.
Thanks, @zorkow, for the updates. Thanks for working through this during the power cuts. And your battery charger dilemma.
The latest released version of diagcess is 1.1.4. That should get around most of the errors you see.
Ok, good. I'll wait on that.
But it won't work with the knowls.
This is a bigger problem that we should stop trying to fix with Band-Aids. So it can wait, I'd say.
The latest released version of diagcess is 1.1.4. That should get around most of the errors you see.
Ok, good. I'll wait on that.
Just to clarify: The 1.1.4 version is already out there and works with diagrams not in knowls.
The upcoming 1.2.0 version will work with knowls as well.
We now ship JS with builds, so the CDN requirement above is now moot.
@alexeikolesnikov and @davidaustinm are working on prefigure and tactile diagrams, so I think this PR is no longer the path forward, though they might find things to like. So I'm going to close, but it can always be re-opened or mined for good ideas.