Export Documentation Confusions

[Matt]

In the Emacs Berlin meeting today, we noticed several items that might be 
improved in the manual.

- Section 13.18. 1: Bare HTML may be better placed under Section 13.9 HTML 
Export.  The information in this section appears unrelated to Exporting in 
non-Org buffers.  In fact,  the settings given for a minimal HTML export do not 
apply when converting a region.  For example, when converting a region 
containing an Org table to HTML, a preamble is not inserted even when the 
variable `org-html-preamble` is t.

https://orgmode.org/manual/Bare-HTML.html

Proposed solution: Move Section 13.18.1 nearer the sections on HTML export.

- Section 13.18: Export in Foreign Buffers

The section uses the term "foreign buffer" without providing a definition.  It 
appears to mean a buffer without "org-mode" enabled.  The section describes 
functions which allow users to write Org mode syntax in non-Org buffers and use 
various functions to convert the Org syntax to other syntaxes, like HTML, 
Markdown, etc.

https://orgmode.org/manual/Export-in-Foreign-Buffers.html

Proposed solution: Change wording from "foreign buffers" to "Convert Region" 
and "non-Org" buffer.   The functionality is really about conversion rather 
than anything to do with non-Org buffers.  If fact, Org respects users' freedom 
to run the program as they wish–it does not prevent them from converting Org 
formatted text within an Org buffer to a non-Org format, no matter how absurd 
it may appear :)

- Section 13.18: Export in Foreign Buffers

There was confusion caused by the function names.  Specifically, the 
"namespace" (such as "org-ascii-" or "org-texinfo-") is confusing to users who 
are not familiar with Org function naming conventions. For example, one 
participant thought `org-ascii-convert-region-to-utf8` might convert non-utf8 
ascii to utf8 and was confused why `org-texinfo-convert-region-to-texinfo` 
would convert texinfo to texinfo.  Of course, this is not a correct 
understanding of the function behavior.

https://orgmode.org/manual/Export-in-Foreign-Buffers.html

Proposed solution: Clarify the overall purpose of the functions.  Another 
solution could be to make an aside and clarify what is meant by "Org export 
back end".  For example, change

"The export back-ends in Org often include..."

to 

"The export back-ends in Org (for example, Org ASCII or Org HTML) often 
include..."

However, my hope is that the changes I made with regard to "foreign buffers" 
also clarifies the purpose and use of functions listed in this section.

These changes are given in the attached patches.   If there are no suggested 
improvements, I could merge them in.  Please let me know your thoughts.

move-bare-html-section-to-html-export-section.patch
Description: Binary data

change-foreign-to-non-org.patch
Description: Binary data