Re: Export Documentation Confusions

[Ihor Radchenko]

Matt  writes:

> Changes have been pushed

Thanks!

For future reference:
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=1b5451a10504ad5d17453e15bba5ea1cb0394399
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=9da248ccd2e2fb86a37009bb0e672cb8419dc30c
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=88c572de25894a7a012eee9c7316998135cf8f13

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Applied.

Re: Export Documentation Confusions

[Matt]

Changes have been pushed

Re: Export Documentation Confusions

[Ihor Radchenko]

Matt  writes:

>  > "Convert region" may be still confusing. Maybe something like
>  > "Convert Org region to other markup syntax"?
>
> How about renaming the section to "Export Region"?

Reasonable.

>  > We can also create more intuitive function aliases.
>
> How about `org-export-region-to-...`?  This would correspond nicely with 
> options given by `org-export-dispatch`.

+1.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Export Documentation Confusions

[Matt]

  On Thu, 29 Jun 2023 12:24:12 +0200  Ihor Radchenko  wrote --- 

 > > - Section 13.18: Export in Foreign Buffers
 > >
 > > The section uses the term "foreign buffer" without providing a definition. 
 > >
 > > Proposed solution: Change wording from "foreign buffers" to "Convert 
 > > Region" and "non-Org" buffer. 
 > 
 > "Convert region" may be still confusing. Maybe something like
 > "Convert Org region to other markup syntax"?

How about renaming the section to "Export Region"?  I was getting ahead of 
myself.  The confusion was about "foreign buffers" and not the meaning of 
"export".

 > > - Section 13.18: Export in Foreign Buffers
 > >
 > > There was confusion caused by the function names.
 > 
 > We can also create more intuitive function aliases.

How about `org-export-region-to-...`?  This would correspond nicely with 
options given by `org-export-dispatch`.

Re: Export Documentation Confusions

[Ihor Radchenko]

Matt  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 .
Support Org development at ,
or support my work at