emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Export Documentation Confusions
@ 2023-06-28 19:45 Matt
  2023-06-29 10:24 ` Ihor Radchenko
  0 siblings, 1 reply; 6+ messages in thread
From: Matt @ 2023-06-28 19:45 UTC (permalink / raw)
  To: emacs-orgmode

[-- 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)}}}.
 

^ permalink raw reply related	[flat|nested] 6+ messages in thread

* Re: Export Documentation Confusions
  2023-06-28 19:45 Export Documentation Confusions Matt
@ 2023-06-29 10:24 ` Ihor Radchenko
  2023-06-29 17:42   ` Matt
  0 siblings, 1 reply; 6+ messages in thread
From: Ihor Radchenko @ 2023-06-29 10:24 UTC (permalink / raw)
  To: Matt; +Cc: emacs-orgmode

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>


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Export Documentation Confusions
  2023-06-29 10:24 ` Ihor Radchenko
@ 2023-06-29 17:42   ` Matt
  2023-06-29 18:04     ` Ihor Radchenko
  0 siblings, 1 reply; 6+ messages in thread
From: Matt @ 2023-06-29 17:42 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode


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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Export Documentation Confusions
  2023-06-29 17:42   ` Matt
@ 2023-06-29 18:04     ` Ihor Radchenko
  2023-06-29 19:26       ` Matt
  0 siblings, 1 reply; 6+ messages in thread
From: Ihor Radchenko @ 2023-06-29 18:04 UTC (permalink / raw)
  To: Matt; +Cc: emacs-orgmode

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>


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Export Documentation Confusions
  2023-06-29 18:04     ` Ihor Radchenko
@ 2023-06-29 19:26       ` Matt
  2023-06-29 19:30         ` Ihor Radchenko
  0 siblings, 1 reply; 6+ messages in thread
From: Matt @ 2023-06-29 19:26 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

Changes have been pushed


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Export Documentation Confusions
  2023-06-29 19:26       ` Matt
@ 2023-06-29 19:30         ` Ihor Radchenko
  0 siblings, 0 replies; 6+ messages in thread
From: Ihor Radchenko @ 2023-06-29 19:30 UTC (permalink / raw)
  To: Matt; +Cc: emacs-orgmode

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.


^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2023-06-29 19:31 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-06-28 19:45 Export Documentation Confusions Matt
2023-06-29 10:24 ` Ihor Radchenko
2023-06-29 17:42   ` Matt
2023-06-29 18:04     ` Ihor Radchenko
2023-06-29 19:26       ` Matt
2023-06-29 19:30         ` Ihor Radchenko

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).