Export Documentation Confusions

Export Documentation Confusions

[Matt]

[-- Attachment #1: Type: text/plain, Size: 2702 bytes --]

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.

[-- Attachment #2: move-bare-html-section-to-html-export-section.patch --]
[-- Type: application/octet-stream, Size: 2205 bytes --]

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 76131f110..c47971914 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -13213,6 +13213,32 @@ a postamble from looking up author's name, email address, creator's
 name, and date.
 
 
+*** Exporting to minimal HTML
+:PROPERTIES:
+:DESCRIPTION: Exporting HTML without CSS, Javascript, etc.
+:ALT_TITLE: Bare HTML
+:END:
+
+If you want to output a minimal HTML file, with no CSS, no Javascript,
+no preamble or postamble, here are the variable you would need to set:
+
+#+vindex: org-html-head
+#+vindex: org-html-head-extra
+#+vindex: org-html-head-include-default-style
+#+vindex: org-html-head-include-scripts
+#+vindex: org-html-preamble
+#+vindex: org-html-postamble
+#+vindex: org-html-use-infojs
+#+begin_src emacs-lisp
+(setq org-html-head ""
+      org-html-head-extra ""
+      org-html-head-include-default-style nil
+      org-html-head-include-scripts nil
+      org-html-preamble nil
+      org-html-postamble nil
+      org-html-use-infojs nil)
+#+end_src
+
 *** Quoting HTML tags
 :PROPERTIES:
 :DESCRIPTION: Using direct HTML in Org files.
@@ -16410,32 +16436,6 @@ tables and lists in foreign buffers.  For example, in an HTML buffer,
 write a list in Org syntax, select it, and convert it to HTML with
 {{{kbd(M-x org-html-convert-region-to-html)}}}.
 
-*** Exporting to minimal HTML
-:PROPERTIES:
-:DESCRIPTION: Exporting HTML without CSS, Javascript, etc.
-:ALT_TITLE: Bare HTML
-:END:
-
-If you want to output a minimal HTML file, with no CSS, no Javascript,
-no preamble or postamble, here are the variable you would need to set:
-
-#+vindex: org-html-head
-#+vindex: org-html-head-extra
-#+vindex: org-html-head-include-default-style
-#+vindex: org-html-head-include-scripts
-#+vindex: org-html-preamble
-#+vindex: org-html-postamble
-#+vindex: org-html-use-infojs
-#+begin_src emacs-lisp
-(setq org-html-head ""
-      org-html-head-extra ""
-      org-html-head-include-default-style nil
-      org-html-head-include-scripts nil
-      org-html-preamble nil
-      org-html-postamble nil
-      org-html-use-infojs nil)
-#+end_src
-
 * Publishing
 :PROPERTIES:
 :DESCRIPTION: Create a web site of linked Org files.

[-- Attachment #3: change-foreign-to-non-org.patch --]
[-- Type: application/octet-stream, Size: 1431 bytes --]

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 76131f110..b0dbe4ec6 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16365,15 +16365,14 @@ Further steps to consider would be an interactive function,
 self-installing an item in the export dispatcher menu, and other
 user-friendly improvements.
 
-** Export in Foreign Buffers
+** Convert Region
 :PROPERTIES:
 :DESCRIPTION: Author tables and lists in Org syntax.
 :END:
 
-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:
 
 - ~org-ascii-convert-region-to-ascii~ ::
 
@@ -16405,8 +16404,8 @@ functions:
   #+findex: org-md-convert-region-to-md
   Convert the selected region into Markdown.
 
-In-place conversions are particularly handy for quick conversion of
-tables and lists in foreign buffers.  For example, in an HTML buffer,
+The in-place conversion is particularly handy for quick conversion of
+tables and lists in non-Org buffers.  For example, in an HTML buffer,
 write a list in Org syntax, select it, and convert it to HTML with
 {{{kbd(M-x org-html-convert-region-to-html)}}}.
 

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>

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 <matt@excalamus.com> 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 <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Export Documentation Confusions

[Matt]

Changes have been pushed

Re: Export Documentation Confusions

[Ihor Radchenko]

Matt <matt@excalamus.com> 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 <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Applied.