branch: externals/org
commit 8824b3ce4df7201be081f64aa90d157e5cc805f2
Author: Ihor Radchenko <yanta...@posteo.net>
Commit: Ihor Radchenko <yanta...@posteo.net>
org-export-options-alist: Add suggestion on when to use KEYWORD/OPTION
* lisp/ox.el (org-export-options-alist):
---
lisp/ox.el | 14 ++++++++++++++
1 file changed, 14 insertions(+)
diff --git a/lisp/ox.el b/lisp/ox.el
index 8ec1b608f8..c5e3bab985 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -185,6 +185,20 @@ BEHAVIOR determines how Org should handle multiple
keywords for
Values set through KEYWORD and OPTION have precedence over
DEFAULT.
+When adding new export options to the alist, it is recommended to
+provide OPTION and/or KEYWORD depending on the allowed values for a
+given export option. For example,
+ (:with-tags nil \"tags\" org-export-with-tags)
+takes short boolean values t/nil and can be succintly set as
+ #+OPTIONS: tags:t
+So, using OPTION makes more sense than forcing something like
+ #+WITH_TAGS: t
+
+On the other hand,
+ (:title \"TITLE\" nil nil parse)
+may have very long string value and may better be set on a separate line
+ #+TITLE: Some very long title that would not fit well into #+OPTIONS
+
All these properties should be backend agnostic. Backend
specific properties are set through `org-export-define-backend'.
Properties redefined there have precedence over these.")
