Re: Export Documentation Confusions

[Ihor Radchenko]

Matt <matt@excalamus.com> writes:

> - 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.

Approved.

> - 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 :)

"Convert region" may be still confusing. Maybe something like
"Convert Org region to other markup syntax"?

> - 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:  ...

We can also create more intuitive function aliases.

> -The export backends in Org often include commands to convert selected
> -regions.  A convenient feature of this in-place conversion is that the
> -exported output replaces the original source.  Here are such
> -functions:
> +Some export backends include commands to convert a region of Org
> +formatted text to another format, such as HTML or LaTeX.  The
> +conversion replaces the original source.  Here are such functions:

While we are at it, "Here are such *commands*:"

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>