Re: [PATCH] Documentation and NEWS for ` org-latex-language-alist'

["Juan Manuel Macías" <maciaschain@posteo.net>]

[-- Attachment #1: Type: text/plain, Size: 1850 bytes --]

Hi, Ihor. Sorry for my late reply. These last few days have been a bit
complicated for me due to work issues.

Ihor Radchenko writes:

> I feel like we should first describe what #+LANGUAGE keyword does and
> go into the gory details of LaTeX language support a bit later.
>
> Basically, I am asking you to reshuffle paragraphs a bit possibly moving
> some parts to more relevant 13.10.3 LaTeX header and sectioning
> structure. People have no idea about #+LATEX_HEADER when reading 13.10.2
> LaTeX specific export settings (coming before the 13.10.3).

I am attaching a new version of the patch.

Addendum: Just as I was going to send this email, I saw the other email
from Maxim in this thread, who says:

> Firefox may block downloading of a file through unencrypted http:
> protocol if a link is opened from a https: page (HTML version of the
> Org manual served from orgmode.org this case). The problem with CTAN
> mirrors is that not all hosts have TLS certificates including their
> CTAN names.

I can't figure out how to link to the babel documentation in a way other
than a link to CTAN. If this might be an inconvenience (due to https
issues), perhaps we could simply put in the documentation something like
'see the Babel docs', or referencing the command 'texdoc -M
babel', which opens the locally installed babel documentation. The
problem is that not all GNU/Linux distributions include the
documentation in their versions of TeX live. For example, Arch Linux
does not include documentation in the official repos and must be
installed separately via an AUR package.

Best regards,

Juan Manuel 

-- 
--
------------------------------------------------------
Juan Manuel Macías 

https://juanmanuelmacias.com

https://lunotipia.juanmanuelmacias.com

https://gnutas.juanmanuelmacias.com


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-documentation-for-org-latex-langu.patch --]
[-- Type: text/x-patch, Size: 4628 bytes --]

From 46192df70cd00e2eca2e8e059e9d39723b9d32d8 Mon Sep 17 00:00:00 2001
From: Juan Manuel Macias <maciaschain@posteo.net>
Date: Tue, 16 Aug 2022 15:41:22 +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 | 58 ++++++++++++++++++++++++++++++++++++++++++++--
 etc/ORG-NEWS       | 13 +++++++++++
 2 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 466718e6e..8973f08ce 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -13370,15 +13370,21 @@ general options (see [[*Export Settings]]).
 - =LANGUAGE= ::
   #+cindex: @samp{LANGUAGE}, keyword
   #+vindex: org-latex-packages-alist
+  #+vindex: org-latex-language-alist
+  
+  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
@@ -13508,6 +13514,54 @@ A sample Org file with the above headers:
   some more text
 #+end_example
 
+#+cindex: @samp{LANGUAGE}, keyword
+#+vindex: org-export-default-language
+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
+
 *** Quoting LaTeX code
 :PROPERTIES:
 :DESCRIPTION: Incorporating literal @LaTeX{} code.
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.2