From 2ec740e4b2f691f619878a7b86e4874fa05d3a82 Mon Sep 17 00:00:00 2001
From: Juan Manuel Macias <maciaschain@posteo.net>
Date: Mon, 8 Aug 2022 16:30:01 +0200
Subject: [PATCH] doc/org-manual.org: documentation for
 `org-latex-language-alist'

* etc/ORG-NEWS: update the news with the new variable.
---
 doc/org-manual.org | 57 ++++++++++++++++++++++++++++++++++++++++++++--
 etc/ORG-NEWS       | 13 +++++++++++
 2 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 466718e6e..5d0283bf2 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -13370,19 +13370,72 @@ general options (see [[*Export Settings]]).
 - =LANGUAGE= ::
   #+cindex: @samp{LANGUAGE}, keyword
   #+vindex: org-latex-packages-alist
+  #+vindex: org-latex-language-alist
+  #+vindex: org-export-default-language
+  
+  The list of languages supported by Org is stored in the variable
+  ~org-latex-language-alist~.
+
   In order to be effective, the =babel= or =polyglossia=
   packages---according to the LaTeX compiler used---must be loaded
   with the appropriate language as argument.  This can be accomplished
   by modifying the ~org-latex-packages-alist~ variable, e.g., with the
-  following snippet:
+  following snippet (note that =polyglossia= does not work with
+  pdfLaTeX):
 
   #+begin_src emacs-lisp
   (add-to-list 'org-latex-packages-alist
-               '("AUTO" "babel" t ("pdflatex")))
+               '("AUTO" "babel" t ("pdflatex" "xelatex" "lualatex")))
   (add-to-list 'org-latex-packages-alist
                '("AUTO" "polyglossia" t ("xelatex" "lualatex")))
   #+end_src
 
+  LaTeX packages =babel= or =polyglossia= can also be loaded in a
+  document.  The "AUTO" string will be replaced in both cases by the
+  appropiate value for the =LANGUAGE= keyword, if present in the
+  document, or by the value of ~org-export-default-language~.  Let's
+  see some examples in one or another case.
+
+  =Babel= accepts the classic syntax and (in addition) the new syntax
+  with the =\babelprovide= command to load the languages using the new
+  =INI= files procedure.  Keep in mind that there are a number of
+  languages that are only served in babel using =INI= files, so they
+  cannot be declared using the classic syntax, but only using the
+  =\babelprovide= command (see
+  http://mirrors.ctan.org/macros/latex/required/babel/base/babel.pdf).
+  Valid usage examples could be:
+
+  #+begin_example
+  ,#+LATEX_HEADER: \usepackage[french,italian,AUTO]{babel}
+  #+end_example
+
+  where "AUTO" is the main language.  But it can also be loaded using
+  the =\babelprovide= command:
+
+  #+begin_example
+  ,#+LATEX_HEADER: \usepackage[french,italian]{babel}
+  ,#+LATEX_HEADER: \babelprovide[import, main]{AUTO}
+  #+end_example
+
+  =Polyglossia=, for this procedure to be effective, must be loaded
+  using the same =babel= classic syntax (but note that /this is not/
+  the actual polyglossia syntax).  For example, suppose a document
+  declares Polytonic Greek as the primary language, and French as the
+  secondary language.  In this case, it would be expressed as:
+
+  #+begin_example
+  ,#+LANGUAGE: el-polyton
+  ,#+LATEX_HEADER: \usepackage[french,AUTO]{polyglossia}
+  #+end_example
+
+  This would produce in LaTeX (with the actual =polyglossia= syntax):
+
+  #+begin_example
+  \usepackage{polyglossia}
+  \setmainlanguage[variant=polytonic]{greek}
+  \setotherlanguage{french}
+  #+end_example
+
 - =LATEX_CLASS= ::
 
   #+cindex: @samp{LATEX_CLASS}, keyword
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 00fe101dc..fc9ac688a 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -431,6 +431,19 @@ prompting for a link description.  It can be a string (used as-is) or
 a function (called with the same arguments as
 ~org-make-link-description-function~ to return a string to use).
 
+*** New list of languages for LaTeX export: ~org-latex-language-alist~ 
+
+~org-latex-language-alist~ unifies into a single list the old language
+lists for the =babel= and =polyglossia= LaTeX packages:
+~org-latex-babel-language-alist~ and
+~org-latex-polyglossia-language-alist~, respectively, which are
+declared obsolete.
+
+This new list captures the current state of art regarding language
+support in LaTeX.  The new =babel= syntax for loading languages via
+=ini= files and the new command =\babelprovide= (see:
+http://mirrors.ctan.org/macros/latex/required/babel/base/babel.pdf)
+are also supported.
 * Version 9.5
 
 ** Important announcements and breaking changes
-- 
2.37.1