Pedro Andres Aranda Gutierrez <[email protected]> writes: > it's taken a bit of time to consolidate. All points taken into > account. Let me know...
Thanks! I have made a number of changes, trying to make the whole section coherent and more dedicated to language (not font) configuration. See the attached patch.
>From 93a4e58db42fe9b09f20a2b598a5e1552a7a0d91 Mon Sep 17 00:00:00 2001 Message-ID: <93a4e58db42fe9b09f20a2b598a5e1552a7a0d91.1760183241.git.yanta...@posteo.net> From: Ihor Radchenko <[email protected]> Date: Sat, 11 Oct 2025 13:47:08 +0200 Subject: [PATCH] doc/org-manual.org: More suggestions --- doc/org-manual.org | 162 ++++++++++++++++++++++++--------------------- 1 file changed, 88 insertions(+), 74 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index cb23088d4..acd69c7b8 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -14280,6 +14280,7 @@ *** LaTeX specific export settings *** LaTeX header and sectioning structure :PROPERTIES: +:CUSTOM_ID: latex-headers :DESCRIPTION: Setting up the export file structure. :ALT_TITLE: LaTeX header and sectioning :END: @@ -14343,57 +14344,49 @@ *** LaTeX header and sectioning structure some more text #+end_example -*** Handling different languages in LaTeX exports +*** Non-English languages and non-Latin characters in LaTeX exports #+cindex: @samp{LANGUAGE} keyword, @samp{LATEX_MULTI_LANG} keyword #+vindex: org-export-multi-lang #+vindex: org-export-default-language LaTeX was initially developed to handle documents written primally - in English. As long as you don't need localisation, you can use it - as-is with any language that uses the Latin character set. As a - general rule, most LaTeX classes include standard font settings that - work well in this situation. Languages using non-Latin character - sets will need font configuration, which will vary depending on the - LaTeX compiler and multi-language support package you use. - - Non-English and multi-language documents use the LaTeX packages - =babel= or =polyglossia= to localise document features like the - table of contents, dates, hyphenation, etc. - - By default, LaTeX only loads the fonts appropriate for Latin - characters. Non-Latin characters in the document are often not - rendered correctly without loading a custom font. =pdflatex= relies - on LaTeX packages you need to include using the =#+LATEX_HEADER:= - keyword. =lualatex= and =xelatex= handle custom fonts using either - =fontspec=, =polyglossia= or =babel= as described below. We - recommend selecting Unicode fonts that cover the character sets of - in the languages used in your document. - - The languages used in a document are specified using =LANGUAGE= - keyword. Use the =LATEX_MULTI_LANG= keyword to set the way - to handle localisation and font configuration. - - =LATEX_MULTI_LANG= is ~nil~ by default to handle localisation - manually as described at the end of this section. - - When =#+LATEX_MULTI_LANG= is set to ~fontspec~, Org mode will - configure the document's fonts using LaTeX's ~fontspec~ package. - Note that ~fontspec~ does not support document localisation. It - configures the fonts used in the document. It distinguishes between - the main, sans and monotype fonts, and can provide fallbacks for - character sets (for example, ~emoji~, ~han~, ~kana~, etc.) not - supported by the default fonts. See [[#lualatex-fontspec]] for more - details. Beware that ~fontspec~ does not work with =pdflatex= - compiler. We recommend using =lualatex= or =xelatex= for reliable - non-Latin language support. - - When =#+LATEX_MULTI_LANG= is either ~babel~ or ~polyglossia~, Org - mode will use the indicated LaTeX package to handle multi-language - support. Either should be used for non-English documents. Both - provide setting up your font configuration globally for your - document and on a per-language basis. The =LANGUAGE= option will be - used to determine the main and secondary languages. For example: + in Americal English. As a result, the default LaTeX configuration + arranges the fonts that are only guaranteed to support Latin + characters. The localisation and puncuation rules are also + conforming to American English. + + For other languages, and in multi-language documents, you need to + use the LaTeX packages =babel= or =polyglossia= to use appropriate + puntuation and localise document features like the table of + contents, dates, hyphenation, etc. You can either load the packages + manually, by providing appropriate LaTeX header configuration, or + use =LANGUAGE= and =LATEX_MULTI_LANG= keywords (see below). + + For languages using non-Latin characters, you also need to load + appropriate fonts. This is because, by default, LaTeX only loads the + fonts appropriate for Latin characters. Non-Latin characters in the + document are often not rendered correctly with the default settings. + Please refer to [[#pdflatex-fonts]] and [[#nonpdflatex-fonts]] for + instructions how to configure fonts used in the exported LaTeX. We + recommend using =xelatex= or =lualatex= and a Unicode font set that + covers all the scripts you use in your document. This will simplify + the font configuration. + + By default, for historical reasons, Org mode uses LaTeX defaults - + American English + Latin fonts. No special configuration is + performed for non-English languages, even when a different language + is specified via =LANGUAGE= export setting. You should either set + =LATEX_MULTI_LANG= setting to non-nil (by default, it is nil) or + configure LaTeX headers manually. + + The easiest way to configure non-English document export is setting + =LATEX_MULTI_LANG= to either ~polyglossia~ (works only for =xelatex= + and =lualatex= compilers) or ~babel~ (works for all LaTeX + compilers). Then, Org mode will automatically load the selected + LaTeX package. You will also need to specify main and secondary + languages in the document using =LANGUAGE= export setting. For + example: #+BEGIN_SRC org :results none :exports code ,#+LANGUAGE: fr de es @@ -14403,35 +14396,53 @@ *** Handling different languages in LaTeX exports sets multi-language handling to use =polyglossia= in a document, where the main language (used for header, figure, table names and typesetting options) is French and there are passages in German and - Spanish. - - # If you use =polyglossia=, you can control the fonts used for - # different languages in the PDF output with the variable - # ~org-latex-polyglossia-font-config~. - # #+vindex: org-latex-polyglossia-font-config - - # If you use =babel=, you can control the fonts used for different - # languages in the PDF output with the variable - # ~org-latex-babel-font-config~. - - In general, when exporting to LaTeX or PDF, we recommend - using a Unicode font set that covers the scripts you use in your - document. This will simplify the font configuration. - - See [[#lualatex-polyglossia]] and [[#babel-fontconfig]] for more - details about how to configure fonts using ~babel~ and - ~polyglossia~. Note that ~polyglossia~ does not work with - =pdflatex= compiler. We recommend using =lualatex= or =xelatex= for - reliable non-Latin language support. - - When =LATEX_MULTI_LANG= is ~nil~, you need to configure LaTeX - language features manually in LaTeX headers (see ~#+LATEX_HEADER~ - keyword). For convenience, if the LaTeX headers load =babel= or - =polyglossia=, you may use =AUTO= in the package options to refer to - the document's main language. Org's will translate it according to - the value of the =#+LANGUAGE= keyword. Use this setting when you - must use =pdflatex= and follow the instructions in - [[#pdflatex-fonts]] to set up fonts in your document. + Spanish. The list of all the supported language abbreviations + can be found in ~org-latex-language-alist~. + + When using multiple languages, you can include passages in non-main + language as the following: + #+begin_src org :results none :exports code + For =polyglossia=: + + @@latex:\textgerman{@@Dies ist ein Abschnitt auf Deutsch.@@latex:}@@ + + ,#+begin_german + Auch dies ist ein Absatz auf Deutsch. + ,#+end_german + + For =babel=: + + @@latex:\foreignlanguage{french}{@@Ceci est un passage en français.@@latex:}@@ + + ,#+ATTR_LATEX: :options {french} + ,#+begin_otherlanguage + Ce passage est aussi en français. + ,#+end_otherlanguage + #+end_src + + Remember that you will still need to configure appropriate fonts for + languages that use non-Latin characters. See + [[#lualatex-polyglossia]] and [[#babel-fontconfig]] for more details + about how to configure fonts using ~babel~ and ~polyglossia~. + + If your document is mostly written in American English with + occasional non-Latin text, and you do not need accurate non-English + punctuation, you can set =LATEX_MULTI_LANG= to ~fontspec~. Then, Org + mode will only configure document fonts (using ~fontspec~ package) + and use LaTeX's defaults for document punctuation and localization. + ~fontspec~ distinguishes between the main, sans and monotype fonts, + and can provide fallbacks for character sets (for example, ~emoji~, + ~han~, ~kana~, etc.) not supported by the default fonts. See + [[#lualatex-fontspec]] for more details. Beware that ~fontspec~ + does not work with =pdflatex= compiler. We recommend using + =lualatex= or =xelatex= for reliable non-Latin character support. + + By default, =LATEX_MULTI_LANG= is ~nil~, and you need to configure + LaTeX language features manually in LaTeX headers (see + =LATEX_HEADER= keyword). For convenience, if the LaTeX headers load + =babel= or =polyglossia=, you may use =AUTO= in the package options + to refer to the document's main language. Org mode will translate it + according to the value of the =LANGUAGE= keyword. #+BEGIN_EXAMPLE #+LANGUAGE: es @@ -15048,6 +15059,9 @@ *** Controlling the font configuration for PDFLaTeX #+END_SRC *** Controlling the font configuration for LuaLaTeX and XeLaTeX +:PROPERTIES: +:custom_id: nonpdflatex-fonts +:END: #+cindex: latex backend #+vindex: org-latex-multi-lang #+vindex: org-latex-classes -- 2.50.1
-- Ihor Radchenko // yantar92, Org mode maintainer, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92>
