From 36d0928043473d38ef716854a4dc259ef003188f Mon Sep 17 00:00:00 2001 From: Ihor Radchenko Date: Sun, 21 Apr 2024 12:41:05 +0300 Subject: [PATCH] Clarify `org-use-sub-superscripts' and related options * lisp/org.el (org-use-sub-superscripts): Update the docstring explaining that (...) is understood as sub/superscript, even when there are spaces inside. Add a note that the underlying markup is not altered. * lisp/ox.el (org-export-with-sub-superscripts): Link to the `org-use-sub-superscripts' docstring instead of duplicating the docstring text. * doc/org-manual.org (Subscripts and Superscripts): Clarify the differences between `org-export-with-sub-superscripts' and `org-use-sub-superscripts'. Add a note that underlying markup does not change. Link: https://orgmode.org/list/87plvproor.fsf@localhost --- doc/org-manual.org | 17 +++++++++++------ lisp/org.el | 15 +++++++++++---- lisp/ox.el | 21 ++------------------- 3 files changed, 24 insertions(+), 29 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 6c699ae1e..343841b53 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -11274,15 +11274,20 @@ the radius of Alpha Centauri is R_{Alpha Centauri} = 1.28 x R_{sun}. #+end_example #+vindex: org-use-sub-superscripts +#+vindex: org-export-with-sub-superscripts If you write a text where the underscore is often used in a different context, Org's convention to always interpret these as subscripts can -get in your way. Configure the variable ~org-use-sub-superscripts~ to -change this convention. For example, when setting this variable to -~{}~, =a_b= is not interpreted as a subscript, but =a_{b}= is. +get in your way. Configure the variable ~org-use-sub-superscripts~ +and/or ~org-export-with-sub-superscripts~ to change this convention. +For example, when setting these variables to ~{}~, =a_b= is not +displayed/exported[fn::The underlying markup still remains a +sub/superscript. Only the visual display and export behavior +changes.] as a subscript, but =a_{b}= is. -You can set ~org-use-sub-superscripts~ in a file using the export -option =^:= (see [[*Export Settings][Export Settings]]). For example, =#+OPTIONS: ^:{}= -sets ~org-use-sub-superscripts~ to ~{}~ and limits super- and +You can set both ~org-use-sub-superscripts~ +~org-export-with-sub-superscripts~ in a file using the export option +=^:= (see [[*Export Settings][Export Settings]]). For example, +=#+OPTIONS: ^:{}= sets the two options to ~{}~ and limits super- and subscripts to the curly bracket notation. You can also toggle the visual display of super- and subscripts: diff --git a/lisp/org.el b/lisp/org.el index b6717066c..c24c67f89 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -1107,19 +1107,26 @@ will be parsed as single sub- or superscripts: 10^-12 or 10^-tau a leading sign with digits or a word x^2-y^3 will be read as x^2 - y^3, because items are terminated by almost any nonword/nondigit char. - x_{i^2} or x^(2-i) braces or parenthesis do grouping. + x^(2 - i) expression inside round braces, including the + braces is read as a sub/superscript. + x_{i^2} curly braces do grouping; braces are not + considered a part of the sub/superscript. Still, ambiguity is possible. So when in doubt, use {} to enclose the sub/superscript. If you set this variable to the symbol `{}', -the braces are *required* in order to trigger interpretations as +the curly braces are *required* in order to trigger interpretations as sub/superscript. This can be helpful in documents that need \"_\" -frequently in plain text." +frequently in plain text. + +Setting this variable does not change Org mode markup. Org mode will +still parse the matching text as sub/superscript internally. It is +only the visual appearance that will be changed." :group 'org-startup :version "24.4" :package-version '(Org . "8.0") :type '(choice (const :tag "Always interpret" t) - (const :tag "Only with braces" {}) + (const :tag "Only with curly braces" {}) (const :tag "Never interpret" nil))) (defcustom org-startup-with-beamer-mode nil diff --git a/lisp/ox.el b/lisp/ox.el index ce0d3a1cb..fc746950d 100644 --- a/lisp/ox.el +++ b/lisp/ox.el @@ -684,31 +684,14 @@ e.g. \"stat:nil\"" "Non-nil means interpret \"_\" and \"^\" for export. If you want to control how Org displays those characters, see -`org-use-sub-superscripts'. `org-export-with-sub-superscripts' -used to be an alias for `org-use-sub-superscripts' in Org <8.0, -it is not anymore. +`org-use-sub-superscripts'. When this option is turned on, you can use TeX-like syntax for sub- and superscripts and see them exported correctly. You can also set the option with #+OPTIONS: ^:t -Several characters after \"_\" or \"^\" will be considered as a -single item - so grouping with {} is normally not needed. For -example, the following things will be parsed as single sub- or -superscripts: - - 10^24 or 10^tau several digits will be considered 1 item. - 10^-12 or 10^-tau a leading sign with digits or a word - x^2-y^3 will be read as x^2 - y^3, because items are - terminated by almost any nonword/nondigit char. - x_{i^2} or x^(2-i) braces or parenthesis do grouping. - -Still, ambiguity is possible. So when in doubt, use {} to enclose -the sub/superscript. If you set this variable to the symbol `{}', -the braces are *required* in order to trigger interpretations as -sub/superscript. This can be helpful in documents that need \"_\" -frequently in plain text." +See `org-use-sub-superscripts' docstring for more details." :group 'org-export-general :version "24.4" :package-version '(Org . "8.0")