Tidy up grammar, promote Unicode characters
improves grammar and narrative for clarity and brevity
moves a link closer to its paragraph
explicitly cites Unicode characters as a potential build failure
@@ -5,34 +5,37 @@ Build PDF format for non-ASCII languages
.. warning::
To be able to follow this guide and build PDF with this method,
- you need to ask to enable ``USE_PDF_LATEXMK`` :doc:`feature flag </guides/feature-flags>` in your project.
- Please, `open an issue`_ in our repository asking for this and wait for one of the core team to enable it.
+ you need to ask the Read the Docs core team to enable ``USE_PDF_LATEXMK`` :doc:`feature flag </guides/feature-flags>` in your project.
+ Please, `open an issue`_ in our repository asking for this, and wait for one of the core team to enable it.
.. _open an issue: https://github.com/rtfd/readthedocs.org/issues/new
-
-Sphinx comes with support for different `LaTeX engines`_ that support non-ASCII languages,
-like Japanese or Chinese, for example.
+Sphinx offers different `LaTeX engines`_ that support Unicode characters and non-ASCII languages,
+like Japanese or Chinese.
By default Sphinx uses ``pdflatex``,
-which does not have good support for Unicode characters and may make the PDF builder to fail on these languages.
+which does not have good support for Unicode characters and may make the PDF builder fail.
.. _LaTeX engines: http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_engine
-In case you want to build your documentation in PDF format you need to configure Sphinx properly,
-so Read the Docs can execute the proper commands depending on these settings.
+To build your documentation in PDF format, you need to configure Sphinx properly in your project's ``conf.py``.
+Read the Docs will execute the proper commands depending on these settings.
There are `several settings that can be defined`_ (all the ones starting with ``latex_``),
to modify Sphinx and Read the Docs behavior to make your documentation to build properly.
-A good first try would be to use only ``latex_engine = 'xelatex'`` in your ``conf.py``,
-if your docs are not written in Chinese or Japanese.
-This is because your build could be failing just because of an Unicode error
-(which ``xelatex`` has better support for them than the default ``pdflatex``)
-
.. _several settings that can be defined: http://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output
-When Read the Docs detects that your documentation is in Chinese or Japanese it automatically adds some defaults for you.
+For docs that are not written in Chinese or Japanese,
+and if your build fails from a Unicode error,
+then try ``xelatex`` as the ``latex_engine`` instead of the default ``pdflatex`` in your ``conf.py``:
+
+.. code-block:: python
+
+ latex_engine = 'xelatex'
+
+When Read the Docs detects that your documentation is in Chinese or Japanese,
+it automatically adds some defaults for you.
-For *Chinese* projects, it appends to your ``conf.py`` these configurations:
+For *Chinese* projects, it appends to your ``conf.py`` these settings:
.. code-block:: python
@@ -51,7 +54,7 @@ And for *Japanese* projects:
.. tip::
- You can always override these configurations if you define them by yourself in your ``conf.py`` file.
+ You can always override these settings if you define them by yourself in your ``conf.py`` file.
.. note::
