[PATCH] org-manual: Document `org-babel-default-inline-header-args'

[Ihor Radchenko <yantar92@gmail.com>]

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

Hi,

In https://orgmode.org/list/87ee927emf.fsf@localhost I proposed to
document org-babel-default-inline-header-args in the manual.

Here is the patch.

WDYT?

Also, I noticed that org-babel-default-header-args has :hlines "no"
while org-babel-default-inline-header-args has :hlines "yes"

The "yes" value can cause errors as documented in the manual (16.6
Results of Evaluation). I am not sure if it is a good default. Also, the
commit introducing the change does not provide any details on why it was
there to start with:

c67e3cda1 default to preserving hlines in call lines
* lisp/ob-core.el (org-babel-default-inline-header-args):
  Added (:hlines "yes") to the default value.

Does anyone know any reason why "yes" value should be kept for inline
src blocks in contrast with "no" for normal src blocks?

I'd be better if we can explain this in the manual.

Best,
Ihor


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual-Document-org-babel-default-inline-header-.patch --]
[-- Type: text/x-patch, Size: 1804 bytes --]

From 51b10e5ca5bb368e71655466a4be5267e6e99d0f Mon Sep 17 00:00:00 2001
Message-Id: <51b10e5ca5bb368e71655466a4be5267e6e99d0f.1658319102.git.yantar92@gmail.com>
From: Ihor Radchenko <yantar92@gmail.com>
Date: Wed, 20 Jul 2022 20:03:37 +0800
Subject: [PATCH] org-manual: Document `org-babel-default-inline-header-args'

* doc/org-manual.org (System-wide header arguments): Update the
default value of `org-babel-default-header-args'.  Document that
inline source blocks use a different set of the default arguments.
---
 doc/org-manual.org | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 26d18f533..7823fbd74 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -17015,8 +17015,31 @@ *** System-wide header arguments
 :exports    => "code"
 :cache      => "no"
 :noweb      => "no"
+:hlines     => "no"
+:tangle     => "no"
 #+end_example
 
+#+vindex: org-babel-default-inline-header-args
+Inline source blocks (see [[*Structure of Code Blocks]]) use slightly
+different default header arguments defined in
+~org-babel-default-inline-header-args~:
+
+#+begin_example
+:session    => "none"
+:results    => "replace"
+:exports    => "results"
+:hlines     => "yes"
+#+end_example
+
+The most notable difference between default header arguments for
+inline and normal source blocks is =:exports= argument.  For inline
+source blocks, results of evaluation are exported by default; not the
+code.
+
+Unlike the default values, header arguments set using Org mode
+properties (see [[*Header arguments in Org mode properties]]) do apply to
+both the normal source blocks and inline source blocks.
+
 The example below sets =:noweb= header arguments to =yes=, which makes
 Org expand =:noweb= references by default.
 
-- 
2.35.1