Hi > El 16 oct 2025, a las 19:23, Ihor Radchenko <[email protected]> escribió: > > 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’d leave it like it is now: we start describing the default value at the beginning and then show what other settings there are and what they imply. > >> 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. We do when we describe the default value. > >> :properties: >> #+LABEL: LaTeX languages and character sets >> :end: > > This incorrect syntax is still there. Right. (Adding a suggestion in the patch would be useful next time ;-) ) > >> 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. Isn't that already a part of the LANGUAGE keyword description? > > 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. OK, will check… > I also moved a note that polyglossia does not work with pdflatex to a > footnote. This is important enough to keep it in the main text IMHO. > 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. Will check when I’m back home. > > 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. OK. And then we keep the current ordering. > > @@ -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. What you add here is already in other parts of the text. > > 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]]). Last time I went through the prep exercises for the C2 certification, this was more style than grammar. Maybe it has changed now… > > -- > 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>
