Xelatex for PDF generation

[NoralK]

I was wondering if xelatex is supported for PDF generation? If so is the font Symobla.ttf installed as well? If not do you know when it will be supported.

Thank you

[gregmuellegger]

That's a question for @agjohnson or @ericholscher. Let's see what they say :)

[agjohnson]

Ubuntu offers the texlive-xetex package, which is installed. Past that, I don't know anything about xelatex, so I don't know if your case would be supported. You can certainly try though.

Symbola.ttf is installed via ttf-ancient-fonts-symbola, which is not installed, and isn't on or backported to the ubuntu 14.04 release. We would install this if there was a supported package, but won't install and support third party packages like this manually.

[NoralK]

Locally, I had to modify the Make.bat to give an option for xelatex and then script changes to the makefile using SED. RFTD is calling the pdflatex option and a new option would need to be created for xelatex.

For this to work I am guessing an advanced option preference would need to be added to select pdflatex (recommended) and xelatex. Based on that option there would be scripting to correct the makefile then build using xelatex.

BTW - It would also be nice to add in some "preprocessing" capabilities. I currently use SED to make changes to the "whateverthefilenameis.tex". Some changes I do before calling the makefile is sed -i s/\\RequirePackage{color}/\\RequirePackage{xcolor}/ sphinx.sty and sed -i s/]{hyperref}/,unicode]{hyperref}/ sphinx.sty - these are some changes that may be needed, not all the time required, when using xelatex.

Thank you for the help.

[NoralK]

BTW - here is my xelatex section of make.bat:

if "%1" == "xelatex" (
    %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
    cd %BUILDDIR%/latex
    echo "Running XeLaTeX files through xelatex..."
    sed -i s/pdflatex/xelatex/ Makefile
    sed -i s/\\RequirePackage{color}/\\RequirePackage{xcolor}/ sphinx.sty
    sed -i s/]{hyperref}/,unicode]{hyperref}/ sphinx.sty

    rem WINDOWS batch files require an escape for & using ^!
    sed -i s#\\{\\textbackslash{}faWrench\s\\}\s\\^&\\\#x1F527#{\\faWrench}#g whateverthefilenameis.tex

    del sed*
    make all-pdf
    cd %~dp0
    echo.
    echo ****
    echo %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
    echo ****
    echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex."
    goto end
    )

[agjohnson]

Running xelatex would require special processing in our build environments. Our build environments disregard makefiles completely, you would probably want to implement your special processing as a sphinx extension. The changes you are describing are slightly outside the realm of RTD though.

Marking this community support if anyone wants to take this on, it's off our roadmap for now.

[skirpichev]

Running xelatex would require special processing in our build environments.

I think that no severe changes would be needed. Just a replacement pdflatex -> xelatex - will work for most cases.

@agjohnson, what about extending yml config with options to allow this?

I see following variants:

• boolean option (e.g. use_xelatex)
• string option, i.e. "command name" for pdflatex-replacement

[asr]

Blocking agda/agda#2153.

[skirpichev]

@agjohnson, there is a patch that sits in queue for month. Apparently, this is an important issue for several projects and require minimal changes. How else I can help to get it fixed?

BTW, another possible option (other than those mentioned above) is to query conf.py for 'latex_engine' value. Let me know if you prefer this.

[ricpelo]

It seems that the latex_engine option doesn't work because readthedocs uses sphinx-build -b latex and then pdflatex over the .tex files that sphinx-build generates.

[skirpichev]

It seems that the latex_engine option

Yes, because readthedocs doesn't use it now, which I suggest.

and then pdflatex

To select correct binary, we can query 'latex_engine' option.

[agjohnson]

@skirpichev it seems the purposed fix would be to simply just replace the binary executed with the binary name from the readthedocs-build config module? If there is feature parity there, this sounds fine, however I'd want to note that we only officially support pdflatex in the docs. A PR should update our docs to describe this change.

[skirpichev]

@skirpichev it seems the purposed fix would be to simply just replace the binary executed with the binary name from

Yes. But after "from" - a number of options.

1. We can configure binary name in readthedocs-build
   a. string option
   b. boolean option (like "use_xelatex")
2. We can configure binary name from the projects conf.py option "latex_engine".

I'd want to note that we only officially support pdflatex in the docs.

But can we be sure that xelatex doesn't disappear from the environment in future?

[cyberorg]

#2620

Sphinx allows the use of following:

make PDFLATEX=xelatex -e SPHINXOPTS="-D language='gu'" latexpdf

All we need on readthedocs is the way to set PDFLATEX=xelatex

[humitos]

To add more info to this issue, I did this stupid change in my local instance and it built the PDF from #2620 (https://readthedocs.org/projects/mss-doc-gu)

diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py
index c6bd529e..45ad7e32 100644
--- a/readthedocs/doc_builder/backends/sphinx.py
+++ b/readthedocs/doc_builder/backends/sphinx.py
@@ -292,7 +292,7 @@ class PdfBuilder(BaseSphinx):
 
         # Run LaTeX -> PDF conversions
         pdflatex_cmds = [
-            ['pdflatex',
+            ['xelatex',  # 'pdflatex',
                 '-interaction=nonstopmode',
                 tex_file]
             for tex_file in tex_files]

Besides, I uncommented the lines from conf.py regarding latex_elements. So, giving an experimental way of changing the pdflatex command to xelatex to the user could be a way to build, at least, a couple of builds.

The result, that wasn't linked in the Downloads section of the project for some reason, but I opened it from user_builds/h-gu/artifacts/xelatex/sphinx_pdf/h-gu.pdf

[skirpichev]

@humitos, please see readthedocs/readthedocs-build#18

The result, that wasn't linked in the Downloads section of the project for some reason

I don't know you local settings, but perhaps that could be #2582 (which also has patch, awaiting for review).

[agjohnson]

@humitos good point. Seems we'll need more logic on the RTD side than just swapping out the binary used. The download path is probably because of some difference in the output, and may take a patch to fix the sphinx builder in RTD.

[skirpichev]

@agjohnson, what about conf.py option? Should we add something to yml config or just utilize 'latex_engine'?

Correct me, but rtd now don't parse & query for any conf.py settings, right?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[skirpichev]

Wow, an original method of fixing issues.

[asr]

Indeed!

[stsewd]

This is still valid, but we haven't had the time to check in to this yet.

[skirpichev]

we haven't had the time to check in

(You had a working PR (or PRs) year ago (or more?), but prefer the Code of Conduct, instead of code...)

[humitos]

We can use sphinx-doc/sphinx:sphinx/config.py@bc02abc#L183 to read the file from the rtd application.

This will be a problem.

If the user is executing code that writes a file, calculate something or whatever this will be executed twice and, besides it's a waste of resources, it could bring other issues.

[agjohnson]

Feature flag is a good direction temporarily. How we arrive at a binary to use will probably end up being a config file change, as it seems we can't automate this before we execute the conf.py. We can't rely on the makefile, but there might be a third option such as using a custom RTD builder that is a wrapper for pdflatex/xelatex depending on the conf. Keeping this out of our config would be helpful.

Either way PRs welcome here. Our code of conduct is not going to be removed, please stop implying we should remove it.

[skirpichev]

please stop implying we should remove it.

Sorry, unsubscribed.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stevepiercy]

Please remove the status: stale label.

There is some relevant discussion taking place in #4454 about how to avoid a makefile.

[skirpichev]

@ericholscher, you closed this issue.

Unless I misunderstood something, new feature (from #5437) is not working on the https://readthedocs.org/, it may be enabled only for custom installations.

If so, I don't think the original issue was solved. Or this is closed as "will not fix" and the https://readthedocs.org/ will never support xelatex?

[stevepiercy]

I followed this issue in hopes that it would resolve Pylons/pyramid#3290. Although #5437 was merged, this issue was not resolved, unless I have missed some configuration or other user-configurable option. Should I open a new issue or is there another that I should follow?

[stsewd]

Please see #5453

[skirpichev]

@stsewd, it seems - it's impossible to use xelatex on the readthedocs.org, I don't think your reference to #5453 could help. For example, I set latex_engine="xelatex" in conf.py, but rtfd still uses pdflatex: see failed build.

[humitos]

The issue was closed automatically because the PR was merged.

If you want to test/try this new feature in your project, please open a new issue asking to enable USE_PDF_LATEXMK (https://docs.readthedocs.io/en/latest/guides/feature-flags.html)

Thanks!

[skirpichev]

If you want to test/try this new feature in your project, please open a new issue asking to enable

Ok, thank you for the explanation, see #5494.