Towards Braille output

[Michael Doob]

I have a standard mathbook setup under Linux, and a ptx file with mathematics.

I would like to use this to make a brf (Braille) file. Obviously pretext-braille.xsl

is needed and perhaps sre. The documentation within the pretext guide is a

bit scattered, and I'm afraid I don't see the full picture. A list of things to do

to allow ptx -> brf would be a big help. 

[Rob Beezer]

See if you can use the pretext/pretext script to make an EPUB with math as SVG images from the supplied "epub-sampler". That should be fully documented (holler where it is not), and will get you 90% of the way to braille.

Calibre is a good desktop viewer. You will likely need a cover image for your own project, just use any old thing to get past errors.

Then report back for help with the remaining 10%.

Rob

[John Hammond]

I wanted to explore this and have gotten the 90%  (maybe 91%?) of the way there.

- I've successfully built an epub-svg of my book

- opened it in Apple Books and also Calibre.  Looks good with a quick click through of pages.

I can't get `file2brl` to install. I'm on MacOS 12 (arm) and no matter how hard I try, I'm getting the same errors as someone did in 2016.   That said, when I modified the pretext.py script line 1490 to instead of running file2brl, it copies the temporary liblouis_xml to my home directory. 

That xml/html is great and all my math is rendered in <span data-braille> tags!  Hooray!

So I've got:

  1. The ability to make the epub

  2. The partial ability to make the html with the math in Nemeth Braille via `lou_translate`

but I can't finish the job with `file2brl`.

Has anybody gotten liblouisutdml to compile on macos?  Or alternatively anyone gotten the liblouis docker image to run pretext? 

Thanks!

[Rob Beezer]

Dear John,

EPUB looks fabulous on my crappy e-reader on Android! Nice work.

Is a Linux virtual machine an option? I have notes from the two times I compiled on Ubuntu (but it'd be a few days before I could get them to you).

Rob

On February 15, 2022 1:46:27 PM PST, John Hammond <jmha...@gmail.com> wrote:
>I wanted to explore this and have gotten the 90% (maybe 91%?) of the way
>there.
>
>- I've successfully built an epub-svg of my book

><http://hammond.math.wichita.edu/classnotes-svg.epub>

>- opened it in Apple Books and also Calibre. Looks good with a quick click
>through of pages.
>
>I can't get `file2brl` to install. I'm on MacOS 12 (arm) and no matter how
>hard I try, I'm getting the same errors as someone did in 2016

><https://www.freelists.org/post/liblouis-liblouisxml/liblouisutdml-build-issue-on-latest-MacOS,8>.

>That said, when I modified the pretext.py script line 1490

><https://github.com/rbeezer/mathbook/blob/d73b4ccb4dac3a0c3c135070ab3b7a6530eca53b/pretext/pretext.py#L1490>

>to instead of running file2brl, it copies the temporary liblouis_xml to my
>home directory.

>That xml/html is great <https://hammond.math.wichita.edu/temporaryxml.html>

[John Hammond]

Brilliant idea! 

I spun up an ubuntu vm, played dependency whack-a-mole until everything is installed and happy. I install liblouisutdml-bin and its dependencies via apt and that got me file2brl without compiling.  I'm getting really close now.

Running (in debug mode to get you the full error context):

```bash

mathbook/pretext/pretext -c all -f braille-electronic -p class-notes/publication/publication.ptx -d class-notes/output/epub -vv class-notes/source/class-notes.ptx

```

results in this error along with the rest of the build messages:

--- output ---

PTX:DEBUG: Parsed CLI args {'verbose': 2, 'config_file': None, 'component': 'all', 'format': 'braille-emboss', 'publication_file': 'class-notes/publication/publication.ptx', 'stringparams': [], 'extra_stylesheet': None, 'method': '', 'xmlid': '', 'server': None, 'data_dir': None, 'out': None, 'dir': 'class-notes/output/epub', 'abort': False, 'xml_file': 'class-notes/source/class-notes.ptx'}
PTX:DEBUG: Python version: 3.8 (expecting 3.6 or newer)
PTX:DEBUG: discovered distribution and xsl directories: /src/mathbook, /src/mathbook/xsl
PTX: parsing possible configuration files: ['/src/mathbook/pretext/pretext.cfg', '/src/mathbook/user/mbx.cfg', '/src/mathbook/user/pretext.cfg']
PTX:DEBUG: configuration files actually used/read: ['/src/mathbook/pretext/pretext.cfg']
PTX: using default configuration only
PTX: custom configuration file not used at /src/mathbook/user/pretext.cfg
PTX:DEBUG: dictionary of executables/commands: {'latex': 'latex', 'pdflatex': 'pdflatex', 'xelatex': 'xelatex', 'pdfsvg': 'pdf2svg', 'asy': 'asy', 'sage': 'sage', 'pdfpng': 'convert', 'pdfeps': 'pdftops', 'pdfcrop': 'pdf-crop-margins', 'pageres': 'pageres', 'node': 'node', 'liblouis': 'file2brl'}
PTX: verifying and expanding XML source file: class-notes/source/class-notes.ptx
PTX: input XML source file expanded to absolute path: /src/class-notes/source/class-notes.ptx
PTX: verifying and expanding publisher file: class-notes/publication/publication.ptx
PTX: input publisher file expanded to absolute path: /src/class-notes/publication/publication.ptx
PTX: verifying and expanding input directory: class-notes/output/epub
PTX: input directory expanded to absolute path: /src/class-notes/output/epub
PTX: Done examining environment and initializing setup info
PTX: converting /src/class-notes/source/class-notes.ptx into BRF in /src/class-notes/output/epub combining UEB2 and Nemeth
PTX:DEBUG: Braille manufacture in temporary directory: /tmp/tmpc9iuzx_z
PTX:DEBUG: converting raw LaTeX from /src/class-notes/source/class-notes.ptx into clean nemeth format placed into /tmp/tmpc9iuzx_z/math-representations-nemeth.xml
PTX: converting LaTeX from /src/class-notes/source/class-notes.ptx into nemeth format
PTX:DEBUG: converting LaTeX from /src/class-notes/source/class-notes.ptx into nemeth format
PTX:DEBUG: temporary directory for MathJax work: /tmp/tmp2a_ls7y4
PTX:DEBUG: extracting LaTeX from /src/class-notes/source/class-notes.ptx and collected in /tmp/tmp2a_ls7y4/mj-input-latex.html
PTX: XSL conversion of /src/class-notes/source/class-notes.ptx by /src/mathbook/xsl/support/extract-math.xsl
PTX:DEBUG: XSL conversion via /src/mathbook/xsl/support/extract-math.xsl of /src/class-notes/source/class-notes.ptx to /tmp/tmp2a_ls7y4/mj-input-latex.html and/or into directory None with parameters {'math.punctuation': 'none', 'publisher': '/src/class-notes/publication/publication.ptx'}
PTX:DEBUG: calling MathJax to convert LaTeX from /tmp/tmp2a_ls7y4/mj-input-latex.html into raw representations as nemeth in /tmp/tmp2a_ls7y4/mj-output-nemeth.html
PTX:DEBUG: locating "node" in [executables] section of configuration file
PTX:DEBUG: node executable: node, options:
PTX:DEBUG: packaging math as nemeth from /tmp/tmp2a_ls7y4/mj-output-nemeth.html into XML file /tmp/tmpc9iuzx_z/math-representations-nemeth.xml
PTX: XSL conversion of /tmp/tmp2a_ls7y4/mj-output-nemeth.html by /src/mathbook/xsl/support/package-math.xsl
PTX:DEBUG: XSL conversion via /src/mathbook/xsl/support/package-math.xsl of /tmp/tmp2a_ls7y4/mj-output-nemeth.html to /tmp/tmpc9iuzx_z/math-representations-nemeth.xml and/or into directory None with parameters {}
PTX: XML file of math representations deposited as /tmp/tmpc9iuzx_z/math-representations-nemeth.xml
PTX:DEBUG: converting source (/src/class-notes/source/class-notes.ptx) and clean representations (/tmp/tmpc9iuzx_z/math-representations-nemeth.xml) into liblouis precursor XML file (/tmp/tmpc9iuzx_z/liblouis-precursor.xml)
PTX: XSL conversion of /src/class-notes/source/class-notes.ptx by /src/mathbook/xsl/pretext-braille.xsl
PTX:DEBUG: XSL conversion via /src/mathbook/xsl/pretext-braille.xsl of /src/class-notes/source/class-notes.ptx to None and/or into directory /tmp/tmpc9iuzx_z with parameters {'mathfile': '/tmp/tmpc9iuzx_z/math-representations-nemeth.xml', 'page-format': 'emboss', 'publisher': '/src/class-notes/publication/publication.ptx'}
PTX:DEBUG: locating "liblouis" in [executables] section of configuration file
PTX:DEBUG: liblouis executable: file2brl, options:
PTX:DEBUG: applying liblouis to /tmp/tmpc9iuzx_z/liblouis-precursor.xml with configurations /src/mathbook/script/braille/pretext-liblouis.cfg,/src/mathbook/script/braille/pretext-liblouis-emboss.cfg, creating BRF /src/class-notes/output/epub/class-notes.brf
Cannot resolve table 'nemeth.ctb'
1 errors found.
nemeth.ctb could not be compiled
liblouisutdml.ini:38: Table 'nemeth.ctb' cannot be found.
liblouisutdml.ini:38: invalid mathexprTableName
Cannot resolve table 'nemeth.ctb'
1 errors found.
nemeth.ctb could not be compiled
liblouisutdml.ini:38: Table 'nemeth.ctb' cannot be found.
liblouisutdml.ini:38: invalid mathexprTableName
PTX: BRF file deposited as /src/class-notes/output/epub/class-notes.brf
PTX:DEBUG: Temporary directories left behind for inspection: ['/tmp/tmpc9iuzx_z', '/tmp/tmp2a_ls7y4']

--------

 The last error is happening during the `file2brl` phase.   It does create a brf file, but I'm suspicious it's invalid since we're seeing this error.   Also, note I get the same error whether I use -f braille-emboss or braille-electronic

We're so close! 

[John Hammond]

Sorry for flooding this channel :-(

I learned that liblouis stopped including nemeth.ctb in version 3.7.0 and moved it to liblouisutdml.  So installing liblouisutdml-data  (I don't know why that was missing previously) I can now run the command. Hooray!

Now I'm getting tons of errors such as "pretext-liblouis.cfg:11767: word ',ex}cises' in column 1 not recognized" which tells me that we're at least working on the translation, so I'll start digging in there first with a sample book from `pretext new book` and see if I have any success.

[Rob Beezer]

Dear John,

Excellent!

That final error is a red herring, I think. I get it *always* and also get output semi-legible for blind readers. So I'd say you are up to speed. DONE! Thanks for the careful report.

Learn to decipher ASCII braille (a markup language with a 6-bit alphabet and heavy use of "contractions") and you can proof your output.

Here's the warning. We test on Judson's AATA, since it has "traditional" devices and does not stress PTX features. (If I include the index, I get zero output.) See the sample book in examples/braille, which is the other test document. If some PTX construction from your notes fails, try an instance here, and make an issue. Some will be easy to implement, some will need adaptation to the constraints (eg side-by-side), some are open questions (graphics).

Do you possibly have a blind reader? We need real-world testers.

Homework: check your APT-version version-number versus latest source on web. I have notes for compiling from scratch. Moderate whack-a-mole, iirc.

We are in contact with liblouis developers (just recently) and I should be more active in their community.

Rob

[Rob Beezer]

Thanks, John. Not a flood, but an important tributary.

It'll be good to see that error go away. I have no great ideas about the new errors, and don't have all my tools with me.

I think you know this: we are letting MathJax/SRE implement the Nemeth.

I, myself, should build a new version from source, since it has been months since I did.

On February 16, 2022 11:09:51 AM PST, John Hammond <jmha...@gmail.com> wrote:
>Sorry for flooding this channel :-(
>
>I learned that liblouis stopped including nemeth.ctb in version 3.7.0

><http://liblouis.org/liblouis/2018/09/03/release-3.7.0.html> and moved it

[David Farmer]

Earlier in this thread:

> errors such as "pretext-liblouis.cfg:11767: word ',ex}cises' not recognized

I think the error is that "}" should be "]".

According to Wikipedia
https://en.wikipedia.org/wiki/Braille_ASCII
the ASCII contraction for "er" is "]". And curly brackets {, },
and the pipe | and left tic ` are not used in ASCII Braille (nor
apparently is ~).

Maybe errors like that could be intercepted and fixed with another
step immediately before liblouis? If the files are still sitting
around, maybe it is possible to hand-edit and see if that fixes
the error?

Are there liblouis errors that do not involve {, }, `, ~, or | ?

[David Farmer]

Maybe a clue:

The braille for "}" takes two cells, which suitably interpreted
can be read as

(capital) ]

The comma at the beginning of ',ex}cises' is ASCII braille for "capital"
(which I take to only apply to the letter "e", but I am speculating
beyond my comfort zone). But if the "capital" was mistakenly applied
to ], then you get }.

Also, the Wikipedia page says that only capital letters are used in
ASCII braille (but they represent lower case braille letters unless
prefixed), so that is inconsistent with what liblouis sees.
Unless everything in ',ex}cises' is wrong (except for the comma
at the beginning).

If that is right, then the handling of words starting with
a capital letter has gone awry.

David

> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt support" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pretext-suppo...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pretext-support/alpine.LRH.2.21.2202170752260.5158%40li375-150.members.linode.com.
>

[Rob Beezer]

One comma is like the shift key, two is like caps-lock for the whole word. I think there are two variants of ASCII braille. Alexei K knows the difference.

Anyway, } -> "er" shows up all the time. Early on in ,chapt}.

Rob

[John Hammond]

To further share the ASCII Braille code, the outputted brf file does have the incorrect entries as David noted:

Here's a sample:

```

  ,= modul> >i?metic1 we h addi;n &
multiplica;n4 ,subtrac;n is d"o via
additive 9v}ses1 b divi.n is n a ?+6
,we'll 4cuss multiplicative 9v}ses 9
sec;n #c4d4
,ex}cises #c4a4c ,ex}cises #a 4

```

so we have ; for "tio" and } for "er" which isn't the correct in the generated brf file.  The } should be ], but I'm not sure about ; since it's supposed to be (letter prefix).  This is all new to me, so if there's anything I can do to help let me know!

[David Farmer]

It is true that the Wikipedia page I linked says that ";", which is
dots 5-6, are "letter prefix", whatever that means.

But this page:
http://www.dotlessbraille.org/braillecontractions.htm
(see next-to last paragraph) says that dots 5-6 are the contraction
for "tio". So, whatever contraction encoding liblouis is using,
probably the semicolon is correct?

Does "addi;n" give an error? I suspect not.

Is the "}" the only one that gives an error? If so, that seems
like something we can fix.

> To view this discussion on the web visithttps://groups.google.com/d/msgid/pretext-support/a8a07b8f-9f24-4220-9f7a-2c0fe48a072fn%40goog
> legroups.com.
>
>

[John Hammond]

I can't reproduce the errors now, which is frustrating.  Every time I run it, I just get the "red herring" error of "nemeth.ctb could not be compiled." I'm getting the same brf file output each time with no errors.

I have sent this brf file over to our media people and they've reported they'll be looking at it when they get time -- which means April or May since they're swamped with building stuff on the fly for the semester.  So I'm on hold for now

[Rob Beezer]

We feed (customized) PreTeXt HTML to liblouis, and out come the braille cells, contractions and all. Our tester, Al Maneki, has never complained about the sorts of details about which cells are where. And they are out of our control at a low level.

So I'm really uncertain about error messages that are being discussed here.

I'll rebuild liblouis here in a few days and see if I can clear the red herring without introducing new errors.

[Rob Beezer]

Dear John,

I installed the latest liblouis, from source files: liblouis-3.20.0,
liblouisutdml-2.10.0

On Ubuntu 20.04, my (minimally used) laptop just needed packages: libxml2-dev
openjdk-17-jdk

And "configure" did an OK job telling me what was missing. On my desktop, I
just installed over the old version (I think - no attempt to remove anything first).

One deprecation with one of the PreTeXt configuration files, which I will sort
out here tonight and push. Comment out line 58 of "pretext-symbol.dis" if it
raises errors. Not really sure why we have it anyway.

I still get:

Cannot resolve table 'nemeth.ctb'
1 errors found.
nemeth.ctb could not be compiled
liblouisutdml.ini:38: Table 'nemeth.ctb' cannot be found.
liblouisutdml.ini:38: invalid mathexprTableName

I have:

/usr/share/liblouisutdml/lbu_files/liblouisutdml.ini
/usr/share/liblouisutdml/lbu_files/nemeth.ctb

Any thoughts on stopping those errors? These both seem to be on the
liblouisutdml side. And I don't see a file/package like "liblouisutdml-data"
anywhere at the liblouis downloads area.

Still failing on the index for AATA, so an upgrade did not fix that. Otherwise
just one minor (consistent) change in output that I'll take up with our experts.

Rob

[John Hammond]

I'm still getting the error

> Cannot resolve table 'nemeth.ctb'
> 1 errors found.
> nemeth.ctb could not be compiled
> liblouisutdml.ini:38: Table 'nemeth.ctb' cannot be found.
> liblouisutdml.ini:38: invalid mathexprTableName

as well and also have liblouisutdml.ini and nemeth.ctb in the same folder as each other, so I have no idea what it's issue is. I fought with it a while longer today and couldn't make headway on it.

I won't hear back from the brailling team at our university for a couple months, so I won't know how correct my output is for a while. I'll just have to wait and see.