org.texi: Improve special symbols section

* doc/org.texi (Special symbols): Add details about `org-entities-help'
  and entities as a way to escape characters in Org.  Also move the
  section outside of LaTeX markup.

1 files changed, 58 insertions, 45 deletions

diff --git a/doc/org.texi b/doc/org.texi
index 5e1faf0..cb88b20 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -9718,6 +9718,7 @@ markup rules used in an Org mode buffer.
 * Horizontal rules::            Make a line
 * Images and tables::           Images, tables and caption mechanism
 * Literal examples::            Source code examples with special formatting
+* Special symbols::             Greek letters and other symbols
 * Embedded @LaTeX{}::           LaTeX can be freely used inside Org documents
 @end menu
 
@@ -9986,63 +9987,44 @@ formatting like @samp{(ref:label)} at the end of the current line.  Then the
 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
 @end table
 
-@node Embedded @LaTeX{}
-@section Embedded @LaTeX{}
-@cindex @TeX{} interpretation
-@cindex @LaTeX{} interpretation
-
-Plain ASCII is normally sufficient for almost all note taking.  Exceptions
-include scientific notes, which often require mathematical symbols and the
-occasional formula.  @LaTeX{}@footnote{@LaTeX{} is a macro system based on
-Donald E. Knuth's @TeX{} system.  Many of the features described here as
-``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
-distinction.}  is widely used to typeset scientific documents.  Org mode
-supports embedding @LaTeX{} code into its files, because many academics are
-used to writing and reading @LaTeX{} source code, and because it can be
-readily processed to produce pretty output for a number of export back-ends.
-
-@menu
-* Special symbols::             Greek letters and other symbols
-* Subscripts and superscripts::  Simple syntax for raising/lowering text
-* @LaTeX{} fragments::          Complex formulas made easy
-* Previewing @LaTeX{} fragments::  What will this snippet look like?
-* CDLaTeX mode::                Speed up entering of formulas
-@end menu
-
 @node Special symbols
-@subsection Special symbols
+@section Special symbols
+@cindex Org entities
 @cindex math symbols
 @cindex special symbols
-@cindex @TeX{} macros
-@cindex @LaTeX{} fragments, markup rules
 @cindex HTML entities
 @cindex @LaTeX{} entities
 
-You can use @LaTeX{}-like syntax to insert special symbols like @samp{\alpha}
-to indicate the Greek letter, or @samp{\to} to indicate an arrow.  Completion
-for these symbols is available, just type @samp{\} and maybe a few letters,
-and press @kbd{M-@key{TAB}} to see possible completions.  Unlike @LaTeX{}
-code, Org mode allows these symbols to be present without surrounding math
-delimiters, for example:
+You can use @LaTeX{}-like syntax to insert special symbols---named
+entities---like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to
+indicate an arrow.  Completion for these symbols is available, just type
+@samp{\} and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible
+completions.  If you need such a symbol inside a word, terminate it with
+a pair of curly brackets.  For example
 
 @example
-Angles are written as Greek letters \alpha, \beta and \gamma.
+Protip: Given a circle \Gamma of diameter d, the length of its circumference
+is \pi{}d.
 @end example
 
-@vindex org-entities
-During export, these symbols will be transformed into the native format of
-the exporter back-end.  Strings like @code{\alpha} will be exported as
-@code{α} in the HTML output, and as @code{\(\alpha\)} in the @LaTeX{}
-output.  Similarly, @code{\nbsp} will become @code{ } in HTML and
-@code{~} in @LaTeX{}.  If you need such a symbol inside a word, terminate it
-like this: @samp{\Aacute@{@}stor}.
-
+@findex org-entities-help
+@vindex org-entities-user
 A large number of entities is provided, with names taken from both HTML and
-@LaTeX{}; see the variable @code{org-entities} for the complete list.
-@samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and
-@samp{...} are all converted into special commands creating hyphens of
-different lengths or a compact set of dots.
+@LaTeX{}; you can comfortably browse the complete list from a dedicated
+buffer using the command @code{org-entities-help}.  It is also possible to
+provide your own special symbols in the variable @code{org-entities-user}.
 
+During export, these symbols are transformed into the native format of the
+exporter back-end.  Strings like @code{\alpha} are exported as @code{α}
+in the HTML output, and as @code{\(\alpha\)} in the @LaTeX{} output.
+Similarly, @code{\nbsp} becomes @code{ } in HTML and @code{~} in
+@LaTeX{}.
+
+@cindex escaping characters
+Entities may also be used as a may to escape markup in an Org document, e.g.,
+@samp{\under@{@}not underlined\under} exports as @samp{_not underlined_}.
+
+@cindex special symbols, in-buffer display
 If you would like to see entities displayed as UTF-8 characters, use the
 following command@footnote{You can turn this on by default by setting the
 variable @code{org-pretty-entities}, or on a per-file base with the
@@ -10057,6 +10039,37 @@ buffer content which remains plain ASCII, but it overlays the UTF-8 character
 for display purposes only.
 @end table
 
+@cindex shy hyphen, special symbol
+@cindex dash, special symbol
+@cindex ellipsis, special symbol
+In addition to regular entities defined above, Org exports in a special
+way@footnote{This behaviour can be disabled with @code{-} export setting
+(@pxref{Export settings}).} the following commonly used character
+combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---}
+are converted into dashes, and @samp{...} becomes a compact set of dots.
+
+@node Embedded @LaTeX{}
+@section Embedded @LaTeX{}
+@cindex @TeX{} interpretation
+@cindex @LaTeX{} interpretation
+
+Plain ASCII is normally sufficient for almost all note taking.  Exceptions
+include scientific notes, which often require mathematical symbols and the
+occasional formula.  @LaTeX{}@footnote{@LaTeX{} is a macro system based on
+Donald E. Knuth's @TeX{} system.  Many of the features described here as
+``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
+distinction.}  is widely used to typeset scientific documents.  Org mode
+supports embedding @LaTeX{} code into its files, because many academics are
+used to writing and reading @LaTeX{} source code, and because it can be
+readily processed to produce pretty output for a number of export back-ends.
+
+@menu
+* Subscripts and superscripts::  Simple syntax for raising/lowering text
+* @LaTeX{} fragments::          Complex formulas made easy
+* Previewing @LaTeX{} fragments::  What will this snippet look like?
+* CDLaTeX mode::                Speed up entering of formulas
+@end menu
+
 @node Subscripts and superscripts
 @subsection Subscripts and superscripts
 @cindex subscript