[PATCH] doc/org-manual.org: Document `org-latex-src-block-backend'

[PATCH] doc/org-manual.org: Document `org-latex-src-block-backend'

[Ihor Radchenko]

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


Attaching tentative manual patch that explains about
`org-latex-src-block-backend'. There was no explanation about different
ways to export colored source blocks in the past.

Please try to read and let me know if anything is confusing.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-Document-org-latex-src-block-back.patch --]
[-- Type: text/x-patch, Size: 2026 bytes --]

From fb77ae66d4d9c01a350140481bcb0f030a45fb69 Mon Sep 17 00:00:00 2001
Message-Id: <fb77ae66d4d9c01a350140481bcb0f030a45fb69.1683897756.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Fri, 12 May 2023 15:21:59 +0200
Subject: [PATCH] doc/org-manual.org: Document `org-latex-src-block-backend'

* doc/org-manual.org (Source blocks in LaTeX export): Explain possible
LaTeX export options for source blocks.
---
 doc/org-manual.org | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index ba9fdaf20..4e56a1e00 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -14181,6 +14181,37 @@ *** Source blocks in LaTeX export
 #+cindex: source blocks, in @LaTeX{} export
 #+cindex: @samp{ATTR_LATEX}, keyword
 
+#+vindex: org-latex-src-block-backend
+LaTeX export backend provides multiple ways to render src blocks in
+LaTeX, according to the value of ~org-latex-src-block-backend~:
+
+- =verbatim= (default) ::
+
+  Use =verbatim= LaTeX environment with no language-specific
+  fontification.
+
+- =listings= ::
+
+  Use =listings= environment provided by the corresponding LaTeX
+  package.  Org will not add the =listings= package to LaTeX preamble,
+  users need to customize ~org-latex-packages-alist~ or LaTeX headers
+  manually.
+
+- =minted= ::
+
+  Use more syntax-aware =minted= package.  Note that in addition to
+  customizing the LaTeX preamble, [[https://pygments.org][pygments]]
+  program should be installed and ~org-latex-pdf-process~ should pass
+  =-shell-escape= option to LaTeX executable.
+
+- =engraved= ::
+
+  Use =fvextra= LaTeX package and Emacs package
+  [[https://elpa.gnu.org/packages/engrave-faces][engrave-faces]]
+  available on GNU Elpa.  =engrave-faces= will use Emacs fontification
+  to colorize the source blocks in LaTeX output.
+
+
 The LaTeX export backend can make source code blocks into floating
 objects through the attributes =:float= and =:options=.  For =:float=:
 
-- 
2.40.0


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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>

Re: [PATCH] doc/org-manual.org: Document `org-latex-src-block-backend'

[Nick Dokos]

Ihor Radchenko <yantar92@posteo.net> writes:

> Attaching tentative manual patch that explains about
> `org-latex-src-block-backend'. There was no explanation about different
> ways to export colored source blocks in the past.
>
> Please try to read and let me know if anything is confusing.

To me, it does not seem necessary to include the various descriptions. Just
the first three lines of the patch, perhaps with a prompt to consult
the doc string of the variable which describes these options in
detail, seems enough IMO.

My $0.02 - feel free to disregard.

-- 
Nick

[PATCH v2] doc/org-manual.org: Document `org-latex-src-block-backend'

[Ihor Radchenko]

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

Nick Dokos <ndokos@gmail.com> writes:

>> Please try to read and let me know if anything is confusing.
>
> To me, it does not seem necessary to include the various descriptions. Just
> the first three lines of the patch, perhaps with a prompt to consult
> the doc string of the variable which describes these options in
> detail, seems enough IMO.

I feel that we at least need to tell people briefly what is possible.
What about the attached, shorter, patch?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2-0001-doc-org-manual.org-Document-org-latex-src-block-b.patch --]
[-- Type: text/x-patch, Size: 1428 bytes --]

From c45b8c6f82bdcbb687c1eb94410fe34d8cee33da Mon Sep 17 00:00:00 2001
Message-Id: <c45b8c6f82bdcbb687c1eb94410fe34d8cee33da.1685460418.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Fri, 12 May 2023 15:21:59 +0200
Subject: [PATCH v2] doc/org-manual.org: Document `org-latex-src-block-backend'

* doc/org-manual.org (Source blocks in LaTeX export): Explain possible
LaTeX export options for source blocks.
---
 doc/org-manual.org | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index ab5c10c1d..a86db2848 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -14203,6 +14203,15 @@ *** Source blocks in LaTeX export
 #+cindex: source blocks, in @LaTeX{} export
 #+cindex: @samp{ATTR_LATEX}, keyword
 
+#+vindex: org-latex-src-block-backend
+LaTeX export backend provides multiple ways to render src blocks in
+LaTeX, according to the value of ~org-latex-src-block-backend~.  The
+default value =verbatim= renders the src code verbatim, without any
+extra styling.  Alternative values allow more colorful styling, but
+require additional LaTeX (=listings=, =minted=), system (=minted=), or
+Emacs (=engraved=) packages.  See the ~org-latex-src-block-backend~
+docstring for more details.
+
 The LaTeX export backend can make source code blocks into floating
 objects through the attributes =:float= and =:options=.  For =:float=:
 
-- 
2.40.0


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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>

Re: [PATCH v2] doc/org-manual.org: Document `org-latex-src-block-backend'

[Nick Dokos]

On 5/30/23 11:27, Ihor Radchenko wrote:
> Nick Dokos <ndokos@gmail.com> writes:
>
>>> Please try to read and let me know if anything is confusing.
>> To me, it does not seem necessary to include the various descriptions. Just
>> the first three lines of the patch, perhaps with a prompt to consult
>> the doc string of the variable which describes these options in
>> detail, seems enough IMO.
> I feel that we at least need to tell people briefly what is possible.
> What about the attached, shorter, patch?
>
>
LGTM.

-- 

Nick

Re: [PATCH v2] doc/org-manual.org: Document `org-latex-src-block-backend'

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

> I feel that we at least need to tell people briefly what is possible.
> What about the attached, shorter, patch?

Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=a144b2355

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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>