louis module for Braille output in WSL

[Michael Duffy]

I've been trying to use WSL to get Braille output from the CLI. 

I have added <target name="braille" format="braille" braille-mode="emboss"/> to the project.ptx manifest. Then, running pretext build braille gives the error 
critical: The "louis" module, providing Python bindings for LibLouis, is required for Braille output.  See the PreTeXt Guide for instructions.

I have liblouis-3.36.0, liblouisutdml, libxml2 unzipped from their tarballs into my ~/, and am able to use lou_translate as a command, for example. So I know I have the louis module somewhere.

$ pip install louis tells me

This environment is externally managed

with the recommendation to run $ apt install python3-louis (altho I need to run this as sudo apt), $ python3 -m venv myenv, or $ pip install louis --break-system-packages. 

$ sudo apt install python3-louis tells me

python3-louis is already the newest version (3.29.0-1build1)

I run $ python3 -m venv myenv and then $ source myenv/bin/activate and then $ pip install louis, and since I've already done it in this venv, it tells me

Requirement already satisfied: louis in ./myenv/lib/python3.12/site-packages (1.3)

Still I get the same error when I run (myenv) $ pretext build braille (i.e. the same build command but inside the venv).

$ pip install louis --break-system-packages tells me

Requirement already satisfied: louis in /usr/lib/python3/dist-packages (3.29.0)

and when I run $ cd /usr/lib/python3/dist-packages, I find the directories louis and louis-3.29.0.egg-info. 

So I do in fact have louis installed in my WSL machine. My question: how can I get PreTeXt to recognize this when I'm building Braille?

Best,

Michael

[David Austin]

I'm pretty sure the braille conversion is not available through the CLI.  You'll need to use the pretext/pretext script.  Write back if you need help with that.

David

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/8728d85b-8ac6-4581-8c06-ff06e4452641n%40googlegroups.com.

[Rob Beezer]

I think it may be in the CLI.

But you need to install liblouis, and setup the Python bindings. The README for liblouis explains the binding setup, and I recently contributed updates to that.

Rob

On December 15, 2025 8:00:00 PM MST, David Austin <david.a...@gmail.com> wrote:
>I'm pretty sure the braille conversion is not available through the CLI.
>You'll need to use the pretext/pretext script. Write back if you need help
>with that.
>
>David
>
>On Mon, Dec 15, 2025 at 9:30 PM Michael Duffy <mjbmicha...@gmail.com>
>wrote:
>
>> I've been trying to use WSL to get Braille output from the CLI.
>>

>> I have added *<target name="braille" format="braille"
>> braille-mode="emboss"/>* to the project.ptx manifest. Then, running *pretext
>> build braille* gives the error

>> critical: The "louis" module, providing Python bindings for LibLouis, is
>> required for Braille output. See the PreTeXt Guide for instructions.
>>

>> I have *liblouis-3.36.0*,* liblouisutdml*, *libxml2* unzipped from their
>> tarballs into my *~/*, and am able to use *lou_translate* as a command,

>> for example. So I know I have the louis module somewhere.
>>

>> *$ pip install louis *tells me

>> This environment is externally managed

>> with the recommendation to run *$ apt install python3-louis* (altho I
>> need to run this as sudo apt),* $ python3 -m venv myenv*, or *$* *pip
>> install louis* *--break-system-packages*.
>>
>> *$ sudo apt install python3-louis* tells me

>> python3-louis is already the newest version (3.29.0-1build1)
>>

>> I run *$* *python3 -m venv myenv *and then *$ source myenv/bin/activate *and
>> then *$* *pip install louis*, and since I've already done it in this

>> venv, it tells me
>> Requirement already satisfied: louis in
>> ./myenv/lib/python3.12/site-packages (1.3)

>> Still I get the same error when I run *(myenv) $ pretext build braille *(i.e.

>> the same build command but inside the venv).
>>

>> *$ pip install louis* *--break-system-packages *tells me

>> Requirement already satisfied: louis in /usr/lib/python3/dist-packages
>> (3.29.0)

>> and when I run *$ cd /usr/lib/python3/dist-packages*, I find the
>> directories *louis* and *louis-3.29.0.egg-info*.
>>
>> So I do in fact have *louis* installed in my WSL machine. My question:

>> how can I get PreTeXt to recognize this when I'm building Braille?
>>
>> Best,
>> Michael
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "PreTeXt development" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to pretext-dev...@googlegroups.com.
>> To view this discussion visit
>> https://groups.google.com/d/msgid/pretext-dev/8728d85b-8ac6-4581-8c06-ff06e4452641n%40googlegroups.com

>> <https://groups.google.com/d/msgid/pretext-dev/8728d85b-8ac6-4581-8c06-ff06e4452641n%40googlegroups.com?utm_medium=email&utm_source=footer>
>> .
>>
>

[Michael Duffy]

David, are you referring to this? Do you know how to find the filepath in WSL to the pretext folder where the pretext/pretext script lives? 

Rob, I had tried to follow the liblouis README as much as possible. I downloaded the .tar.gz file from the liblouis websiteI, ran $ tar on it, $ cded to the directory it created, and ran the $ ./configure $ make $ sudo make install $ sudo ld config. Then, once I'm installed, do I simply go to the directory containing my PreTeXt and run $ pretext make braille? I still get the same error if I try that.

[David Austin]

Yes, that's the script that I'm referring to.  I can't find that script in my CLI installation, but I have a local fork of the pretext repository, and the script is at pretext/pretext.

On my ubuntu machine, all I needed to do was install the python3-louis package.  Then I could open a session in the python interpreter and "import louis".  Are you able to do that?  If you're in a virtual environment, you will need to set the --system-site-packages flag.

David

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/fb20cdf8-d814-45f6-bbf3-60bf8460345bn%40googlegroups.com.

[David Austin]

I'll also add that I successfully compiled a project to braille using the CLI this morning.

[Michael Duffy]

In a python3 interpreter (i.e. I run $ python3), I can run >>> import louis with no errors. (Playing around here, I can also >>> import pretext successfully, but I'm not sure how to work with that). So I can access louis in the interpreter, but not in the normal WSL command line. Does the PreTeXt compiling into Braille need to happen within this Python instance somehow?

[Michael Duffy]

OK, I think I'm making progress. I was having a problem where I was trying to run $ pretext -c all -f braille but it was getting confused with the pretext of $ pretext new article versus the pretext/pretext script. So right now, I am able to call $ pretext/pretext/pretext -c all -f braille-emboss test/source/frontmatter.ptx (my fork of PreTeXt is in a root directory called pretext, and the pretext/pretext script is located at pretext/pretext/pretext haha; and my PreTeXt document lives in a directory called test, and I'm just trying to pick out one of the xml files, although I admit this may not be the right approach). I'm getting the error

lxml.etree.XMLSyntaxError: Document is empty, line 1, column 1

Is this at least the right command to be running? How can I debug this? Thank you.

[David Austin]

Point the script to the root of your XML tree, which is likely in main.ptx, if you started the project with the CLI.  You want the file that has the root #pretext element.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/9cec1f83-7b3a-4a97-9e95-7bc8b9f432aen%40googlegroups.com.

[Michael Duffy]

I'm just working on the default PreTeXt article as a proof of concept, so yeah my project is just the default XML tree structure. By root #pretext element, do you mean the line <pretext xml:lang="en-US" xmlns:xi="http://www.w3.org/2001/XInclude"> in the main.ptx file? 

If I run $ pretext/pretext/pretext -c all -f braille-emboss test/source/main.ptx instead, I get the same error message. I'll include the whole readout, because maybe it has something to do with node as well?

node:internal/modules/cjs/loader:1137
  throw err;
  ^

Error: Cannot find module 'mathjax-full/js/util/asyncLoad/node.js'
Require stack:
- /home/unix/pretext/script/mjsre/mj-sre-page.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1134:15)
    at Module._load (node:internal/modules/cjs/loader:975:27)
    at Module.require (node:internal/modules/cjs/loader:1225:19)
    at require (node:internal/modules/helpers:177:18)
    at Object.<anonymous> (/home/unix/pretext/script/mjsre/mj-sre-page.js:34:1)
    at Module._compile (node:internal/modules/cjs/loader:1356:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1414:10)
    at Module.load (node:internal/modules/cjs/loader:1197:32)
    at Module._load (node:internal/modules/cjs/loader:1013:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:128:12) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/home/unix/pretext/script/mjsre/mj-sre-page.js' ]
}

Node.js v18.19.1
Traceback (most recent call last):
  File "/home/unix/pretext/pretext/pretext", line 936, in <module>
    main()
  File "/home/unix/pretext/pretext/pretext", line 865, in main
    ptx.braille(xml_source, publication_file, stringparams, out_file, dest_dir, "emboss")
  File "/home/unix/pretext/pretext/lib/pretext.py", line 3436, in braille
    mathjax_latex(xml_source, pub_file, math_representations, None, math_format)
  File "/home/unix/pretext/pretext/lib/pretext.py", line 240, in mathjax_latex
    xsltproc(cleaner_xslt, mjoutput, derivedname)
  File "/home/unix/pretext/pretext/lib/pretext.py", line 5138, in xsltproc
    src_tree = guarded_xml_include_parser(xml)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/unix/pretext/pretext/lib/pretext.py", line 5348, in guarded_xml_include_parser
    src_tree = ET.parse(xml, parser=huge_parser)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "src/lxml/etree.pyx", line 3711, in lxml.etree.parse
  File "src/lxml/parser.pxi", line 2031, in lxml.etree._parseDocument
  File "src/lxml/parser.pxi", line 2057, in lxml.etree._parseDocumentFromURL
  File "src/lxml/parser.pxi", line 1958, in lxml.etree._parseDocFromFile
  File "src/lxml/parser.pxi", line 1230, in lxml.etree._BaseParser._parseDocFromFile
  File "src/lxml/parser.pxi", line 647, in lxml.etree._ParserContext._handleParseResultDoc
  File "src/lxml/parser.pxi", line 765, in lxml.etree._handleParseResult
  File "src/lxml/parser.pxi", line 689, in lxml.etree._raiseParseError
  File "/tmp/ptx-kxu6yywv/mj-output-nemeth.html", line 1

lxml.etree.XMLSyntaxError: Document is empty, line 1, column 1

[David Austin]

OK, we're making progress!  Hopefully you have node installed (I'm not too familiar with WSL).  You need to go into your pretext installation to pretext/script/mjsre and execute the script called update-sre.  Alternatively, you can just say "npm install".  This will install MathJax locally, which is needed to convert your math expressions into Nemeth braille.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/352a1460-2665-4c3e-aa53-6c499ff6aa95n%40googlegroups.com.

[Rob Beezer]

Did not read this carefully the first time, and was in a rush. :-(

I build liblouis from source. I suspect system packages are likely old versions and it might be a mess to get the Python bindings configured.

As it is you need to be careful about setting up the bindings in a Python virtual environment. I forget where that is documented, maybe the related README.

Rob

[Michael Duffy]

Mission accomplished! That MathJax installation was what I needed for WSL :)

So summing this up for myself later:

I needed a local fork of pretext on my WSL.

From that, I could get an installation of MathJax using the mjsre update-sre script

Then I can use the pretext/pretext script to format my ptx file in Braille

Thank you so much! I've been trying to teach myself Linux and whatnot for this purpose, so I'm getting adjusted to the "building everything from source myself" mindset haha. 

Rob, are those Python bindings more for if you want to use liblouis within another Python script? I feel in a good place with using this in a command line, though.

Thank you for your help! 

Michael

[David Austin]

Congratulations on getting the embossed braille!  

You get python bindings for liblouis with the python3-louis package.  I believe Rob is saying that the package likely provides an older version of liblouis than you would get by building them yourself.  For instance, my version installed with the python3-louis package about a year ago is liblouis 3.29.0 while 3.36.0 is current.  My reading is that the latest debian package is built with 3.36.0 so I'm now planning to update that package.  You could check with "dpkg -l python3-louis".

I once tried setting up the bindings in a virtual environment and ran into some problems.  I didn't spend much time on it though once I found the debian package.

David

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/c9f46fbd-3d46-4b1a-adaa-b70ddbc6d919n%40googlegroups.com.