Pedro Andres Aranda Gutierrez <[email protected]> writes: > OK, I have reshuffled the sections contents...
What about also moving LATEX_MULTI_LANG = nil below babel/polyglossia? > I hope the flow is more understandable now. > I have always been reluctant because there are too many things intertwined > here. > I felt using LATEX_MULTI_LANG as a keyword would introduce less confusion... > > Anyhow, I don't want to open Pandora's box until someone asks what > about setting the language in the document class, which is also > possible... What do not have to support this other than by setting LATEX_MULTI_LANG to nil and letting user do whatever they want to. > :properties: > #+LABEL: LaTeX languages and character sets > :end: This incorrect syntax is still there. > Consult the package manuals to get the language name[fn:50] for the > LaTeX markup. Should we also refer to `org-latex-language-alist'? Otherwise, people may not know how to link between Org mode's abbreviations and babel/polyglossia language names. I am attaching another set of suggestions as a patch. Please consider. I fixed a number of grammar issues and typos. I added an example to LANGUAGE keyword description. I made sure to use "option" when talking about export options rather than just mentioning keyword. I also moved a note that polyglossia does not work with pdflatex to a footnote. Finally, I moved the reference to babel/polyglossia font configuration just below their description, and added extra emphasis that the fonts need to be configured.
>From f9616a164055b2f827f58088b24d36ef8ecc0776 Mon Sep 17 00:00:00 2001 Message-ID: <f9616a164055b2f827f58088b24d36ef8ecc0776.1760635005.git.yanta...@posteo.net> From: Ihor Radchenko <[email protected]> Date: Thu, 16 Oct 2025 19:16:34 +0200 Subject: [PATCH] doc/org-manual.org: Suggestions --- doc/org-manual.org | 96 ++++++++++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 46 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 536df647b..1bc6d22c7 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -14232,10 +14232,12 @@ *** LaTeX specific export settings #+vindex: org-latex-language-alist #+vindex: org-export-default-language - List of languages in the document. The first language is the main - language in the document. If this keyword is not specified, use a - one-element list with the value of ~org-export-default-language~ (by - default - =en=, American English) + List of languages in the document, separated by spaces. For example, + : #+LANGUAGE: fr de es + #+texinfo: @noindent + The first language is the main language in the document. If this + keyword is not specified, use a single language specified in + ~org-export-default-language~ (by default - =en=, American English) The language codes supported by Org are stored in the variable ~org-latex-language-alist~. @@ -14247,7 +14249,7 @@ *** LaTeX specific export settings #+vindex: org-export-default-language The strategy to handle multi-lingual features. Possible values - are ~nil~, ~fontspec~, ~polyglossia~ or ~babel~. + are ~nil~ (default), ~fontspec~, ~polyglossia~ or ~babel~. See more details about setting up multi-language documents in the [[*Handling different languages and character sets in LaTeX exports]] section. @@ -14365,26 +14367,26 @@ *** Handling different languages and character sets in LaTeX exports font configuration, which depend on the document class, the LaTeX compiler and multi-language support package you use[fn:49]. - For documents that a written for outside an American English + For documents that are written for outside an American English linguistic context and for multilingual documents, LaTeX provides - the packages =babel= or =polyglossia= to localise document features - like text direction (left-to-right vs. right-to-left), the table of - contents, dates, hyphenation, etc. - - Org provides the =LANGUAGE= keyword to specify the languages used in - a document and the =LATEX_MULTI_LANG= keyword to set the way to - handle localisation and font configuration when exporting to LaTeX. - - =LATEX_MULTI_LANG= is ~nil~ by default. In this case, you need to - handle localisation manually. In this case you need to configure - LaTeX language features manually in LaTeX headers (see + two packages: =babel= and =polyglossia=. These packages localise + document features like text direction (left-to-right + vs. right-to-left), the table of contents, dates, hyphenation, etc. + + Org mode can assist configuring LaTeX when =LANGUAGE= and + =LATEX_MULTI_LANG= options are provided. =LANGUAGE= is used to + specify the languages used in a document and =LATEX_MULTI_LANG= is + used to chose which LaTeX packages should be used to handle + localisation and font configuration when exporting to LaTeX. + + =LATEX_MULTI_LANG= is ~nil~ by default. In this case 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. For example: + options to refer to the document's main language. Org will translate + it according to the value of the =LANGUAGE= option. Use this setting + when you must use =pdflatex= and then follow the instructions in + [[#pdflatex-fonts]] to set up fonts in your document. For example: #+BEGIN_EXAMPLE #+LANGUAGE: es @@ -14399,12 +14401,14 @@ *** Handling different languages and character sets in LaTeX exports #+texinfo:@noindent Multiple languages are also handled. - When =#+LATEX_MULTI_LANG= is set to either ~babel~ or ~polyglossia~, - Org 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: + When =#+LATEX_MULTI_LANG= is set to either ~babel~ or + ~polyglossia~[fn::Note that ~polyglossia~ only works with ~xelatex~ + and ~lualatex~, but not with ~pdflatex~ compiler.], 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= setting will be used to + determine the main and secondary languages. For example: #+BEGIN_SRC org :results none :exports code ,#+LANGUAGE: fr de es @@ -14416,6 +14420,14 @@ *** Handling different languages and character sets in LaTeX exports typesetting options) is French and there are passages in German and Spanish. + Remember that in addition to the above, you will also need to + configure appropriate fonts that can render all the text used in the + document. See [[#lualatex-polyglossia]] and [[#babel-fontconfig]] + for more details about how to configure fonts using ~babel~ and + ~polyglossia~. We recommend using ~lualatex~ or ~xelatex~ for + reliable non-Latin language support, as they support loading system + fonts, unlike ~pdflatex~. + When using multiple languages, you can include passages in non-main language using embedded LaTeX markup, which will depend on the package you use. @@ -14443,26 +14455,18 @@ *** Handling different languages and character sets in LaTeX exports Consult the package manuals to get the language name[fn:50] for the LaTeX markup. - See [[#lualatex-polyglossia]] and [[#babel-fontconfig]] for more - details about how to configure fonts using ~babel~ and - ~polyglossia~. - When =#+LATEX_MULTI_LANG= is set to ~fontspec~, Org mode will configure the document's fonts using LaTeX's ~fontspec~ package. This assumes that the document is intended for an American English - context. ~fontspec~ will help you to configure the fonts used in the - document. It distinguishes between the Roman (=main=), Sans-serif - (=sans=) and monotype (=mono=) 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. Note that ~fontspec~ is not intended for document - localisation and that it does not work with =pdflatex= compiler. We - recommend using =lualatex= or =xelatex= for reliable non-Latin - language support. - - Finally, remember that ~polyglossia~ does not work with =pdflatex= - compiler. We recommend using =lualatex= or =xelatex= for reliable - non-Latin language support. + context (header, figure, table names and typesetting options will be + set for American English). ~fontspec~ will only configure the fonts + used in the document. It distinguishes between the Roman (=main=), + Sans-serif (=sans=) and monotype (=mono=) 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. Note that ~fontspec~ does + not work with =pdflatex= compiler. We recommend using =lualatex= or + =xelatex= for reliable non-Latin language support. To fine-tune the document's appearance provided by the LaTeX document class you use, you may need to change the font @@ -14473,7 +14477,7 @@ *** Handling different languages and character sets in LaTeX exports Modern, UTF-8 enabled LaTeX compilers (i.e. =lualatex= and =xelatex=) handle font configuration using the package - =fontspec=. We recommend to choose Unicode fonts that include the + =fontspec=. We recommend choosing Unicode fonts that include the non-Latin character sets you use to simplify the configuration (cf. [[#nonpdflatex-fonts]]). -- 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>
