[RFC] About `org-export-with-\(fixed-width\|tables\)'

[RFC] About `org-export-with-\(fixed-width\|tables\)'

[Nicolas Goaziou]

Hello,

At the moment, `org-export-with-fixed-width' and
`org-export-with-tables' (or their OPTIONS equivalent ::t and |:t) are
broken when not set to their default value. Also, "fixing" them is not
trivial. I think this is a good time to ponder about their usefulness.

Indeed, I don't think anyone would want to remove tables (or fixed-width
areas) from Org syntax. These variables were probably written because
tables and fixed-width can occasionally get in the way, on very specific
lines.

However, Org already provides ways to work around such problems. For
example, a table can be wrapped within an example block, or an offending
line can start with \vert instead of "|".

Therefore, in today's Org, they don't make much sense anymore. As
a consequence, I'd like to either:

  1. Remove them completely from code base;

  2. Change their meaning so they behave like `org-export-with-toc' or
     `org-export-with-tags', that is: when `org-export-with-tables' is
     set to nil, all tables are ignored during export.

I don't think option 2 is really useful, but I don't mind either way.


WDYT?


Regards,

-- 
Nicolas Goaziou

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Nick Dokos]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Hello,
>
> At the moment, `org-export-with-fixed-width' and
> `org-export-with-tables' (or their OPTIONS equivalent ::t and |:t) are
> broken when not set to their default value. Also, "fixing" them is not
> trivial. I think this is a good time to ponder about their usefulness.
>
> Indeed, I don't think anyone would want to remove tables (or fixed-width
> areas) from Org syntax. These variables were probably written because
> tables and fixed-width can occasionally get in the way, on very specific
> lines.
>
> However, Org already provides ways to work around such problems. For
> example, a table can be wrapped within an example block, or an offending
> line can start with \vert instead of "|".
>
> Therefore, in today's Org, they don't make much sense anymore. As
> a consequence, I'd like to either:
>
>   1. Remove them completely from code base;
>

AFAIAC, they can go.

>   2. Change their meaning so they behave like `org-export-with-toc' or
>      `org-export-with-tags', that is: when `org-export-with-tables' is
>      set to nil, all tables are ignored during export.
>
> I don't think option 2 is really useful, but I don't mind either way.
>
>
> WDYT?
>

Nick

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Rasmus]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

>   1. Remove them completely from code base;

Fine with me.  If needing to treat a region in a special way it's more
clear to explicitly state it IMO.

–Rasmus

-- 
A clever person solves a problem. A wise person avoids it

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Thomas S. Dye]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Hello,
>
> At the moment, `org-export-with-fixed-width' and
> `org-export-with-tables' (or their OPTIONS equivalent ::t and |:t) are
> broken when not set to their default value. Also, "fixing" them is not
> trivial. I think this is a good time to ponder about their usefulness.
>
> Indeed, I don't think anyone would want to remove tables (or fixed-width
> areas) from Org syntax. These variables were probably written because
> tables and fixed-width can occasionally get in the way, on very specific
> lines.
>
> However, Org already provides ways to work around such problems. For
> example, a table can be wrapped within an example block, or an offending
> line can start with \vert instead of "|".
>
> Therefore, in today's Org, they don't make much sense anymore. As
> a consequence, I'd like to either:
>
>   1. Remove them completely from code base;

Removal is fine with me. For years now, I've inserted the automatic
boilerplate at the top of my Org mode documents, which has ::t and |:t.
If the functions are removed, then it would be great if it wasn't necessary
to go back and get rid of the obsolete OPTIONS in all those old, but
still active, files.

All the best,
Tom
-- 
Thomas S. Dye
http://www.tsdye.com

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Nicolas Goaziou]

Hello,

tsd@tsdye.com (Thomas S. Dye) writes:

> Nicolas Goaziou <n.goaziou@gmail.com> writes:
> Removal is fine with me. For years now, I've inserted the automatic
> boilerplate at the top of my Org mode documents, which has ::t and |:t.
> If the functions are removed, then it would be great if it wasn't necessary
> to go back and get rid of the obsolete OPTIONS in all those old, but
> still active, files.

For clarification, you needn't change old OPTIONS lines. It is the same
as @:t in Org files written before 8.0: it doesn't mean anything
anymore, but doesn't hurt either.


Regards,

-- 
Nicolas Goaziou

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Thomas S. Dye]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Hello,
>
> tsd@tsdye.com (Thomas S. Dye) writes:
>
>> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>> Removal is fine with me. For years now, I've inserted the automatic
>> boilerplate at the top of my Org mode documents, which has ::t and |:t.
>> If the functions are removed, then it would be great if it wasn't necessary
>> to go back and get rid of the obsolete OPTIONS in all those old, but
>> still active, files.
>
> For clarification, you needn't change old OPTIONS lines. It is the same
> as @:t in Org files written before 8.0: it doesn't mean anything
> anymore, but doesn't hurt either.

Perfect (as usual).  Thanks!

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Florian Beck]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> I don't think option 2 is really useful, but I don't mind either way.

Actually, I would find it useful (because I sometimes export my notes as
an ebook and tables get garbled on the way).

Tables are kind of tricky to get exported correctly and it seems quite
reasonble to optimise them for a certain export backend and ignore them
otherwise. One might also have lots of tables that don't export
correctly (typically, because they are too wide). 

-- 
Florian Beck

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Bastien]

Florian Beck <fb@miszellen.de> writes:

>> I don't think option 2 is really useful, but I don't mind either way.
>
> Actually, I would find it useful (because I sometimes export my notes as
> an ebook and tables get garbled on the way).

+1.

-- 
 Bastien

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Nicolas Goaziou]

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

Hello,

Bastien <bzg@gnu.org> writes:

> Florian Beck <fb@miszellen.de> writes:
>
>>> I don't think option 2 is really useful, but I don't mind either way.
>>
>> Actually, I would find it useful (because I sometimes export my notes as
>> an ebook and tables get garbled on the way).
>
> +1.

Patch attached. WDYT?


Regards,

-- 
Nicolas Goaziou

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-Change-meaning-of-org-export-with-table-fixed-wid.patch --]
[-- Type: text/x-diff, Size: 5133 bytes --]

From ddc02dddeff02b9e339a1a78e66ab706697032c2 Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <n.goaziou@gmail.com>
Date: Sun, 5 Jan 2014 01:13:54 +0100
Subject: [PATCH] ox: Change meaning of `org-export-with-\(table\|fixed-width\)

* lisp/ox.el (org-export-with-fixed-width, org-export-with-tables):
  Change docstring to reflect new meaning.
(org-export--skip-p): Completely ignore tables and fixed-width areas
if appropriate option is nil.
* testing/lisp/test-ox.el (test-org-export/handle-options): Add tests.
---
 lisp/ox.el              | 30 ++++++++++--------------------
 testing/lisp/test-ox.el | 24 +++++++++++++++++++++++-
 2 files changed, 33 insertions(+), 21 deletions(-)

diff --git a/lisp/ox.el b/lisp/ox.el
index d26d0c1..c2ff063 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -457,19 +457,12 @@ This option can also be set with the EXCLUDE_TAGS keyword."
   :type '(repeat (string :tag "Tag")))
 
 (defcustom org-export-with-fixed-width t
-  "Non-nil means lines starting with \":\" will be in fixed width font.
-
-This can be used to have pre-formatted text, fragments of code
-etc.  For example:
-  : ;; Some Lisp examples
-  : (while (defc cnt)
-  :   (ding))
-will be looking just like this in also HTML.  See also the QUOTE
-keyword.  Not all export backends support this.
-
+  "Non-nil means export lines starting with \":\".
 This option can also be set with the OPTIONS keyword,
 e.g. \"::nil\"."
   :group 'org-export-general
+  :version "24.4"
+  :package-version '(Org . "8.0")
   :type 'boolean)
 
 (defcustom org-export-with-footnotes t
@@ -703,16 +696,12 @@ e.g. \"toc:nil\" or \"toc:3\"."
 	  (integer :tag "TOC to level")))
 
 (defcustom org-export-with-tables t
-  "If non-nil, lines starting with \"|\" define a table.
-For example:
-
-  | Name        | Address  | Birthday  |
-  |-------------+----------+-----------|
-  | Arthur Dent | England  | 29.2.2100 |
-
+  "Non-nil means export tables.
 This option can also be set with the OPTIONS keyword,
 e.g. \"|:nil\"."
   :group 'org-export-general
+  :version "24.4"
+  :package-version '(Org . "8.0")
   :type 'boolean)
 
 (defcustom org-export-with-tags t
@@ -1440,7 +1429,7 @@ The back-end could then be called with, for example:
 ;;   - category :: option
 ;;   - type :: symbol (nil, t)
 ;;
-;; + `:with-fixed-width' :: Non-nil if transcoder should interpret
+;; + `:with-fixed-width' :: Non-nil if transcoder should export
 ;;      strings starting with a colon as a fixed-with (verbatim) area.
 ;;   - category :: option
 ;;   - type :: symbol (nil, t)
@@ -1482,8 +1471,7 @@ The back-end could then be called with, for example:
 ;;   - category :: option
 ;;   - type :: symbol (nil, {}, t)
 ;;
-;; + `:with-tables' :: Non-nil means transcoding should interpret
-;;      tables.
+;; + `:with-tables' :: Non-nil means transcoding should export tables.
 ;;   - category :: option
 ;;   - type :: symbol (nil, t)
 ;;
@@ -2091,6 +2079,7 @@ a tree with a select tag."
 		  (if (eq (car with-drawers-p) 'not)
 		      (member-ignore-case name (cdr with-drawers-p))
 		    (not (member-ignore-case name with-drawers-p))))))))
+    (fixed-width (not (plist-get options :with-fixed-width)))
     ((footnote-definition footnote-reference)
      (not (plist-get options :with-footnotes)))
     ((headline inlinetask)
@@ -2128,6 +2117,7 @@ a tree with a select tag."
     (planning (not (plist-get options :with-planning)))
     (property-drawer (not (plist-get options :with-properties)))
     (statistics-cookie (not (plist-get options :with-statistics-cookies)))
+    (table (not (plist-get options :with-tables)))
     (table-cell
      (and (org-export-table-has-special-column-p
 	   (org-export-get-parent-table blob))
diff --git a/testing/lisp/test-ox.el b/testing/lisp/test-ox.el
index 0b148e0..78347af 100644
--- a/testing/lisp/test-ox.el
+++ b/testing/lisp/test-ox.el
@@ -430,6 +430,17 @@ Paragraph"
 	  (org-test-with-temp-text ":FOO:\nkeep\n:END:\n:BAR:\nremove\n:END:"
 	    (org-export-as (org-test-default-backend)
 			   nil nil nil '(:with-drawers (not "BAR"))))))
+  ;; Fixed-width.
+  (should
+   (equal ": A\n"
+	  (org-test-with-temp-text ": A"
+	    (org-export-as (org-test-default-backend) nil nil nil
+			   '(:with-fixed-width t)))))
+  (should
+   (equal ""
+	  (org-test-with-temp-text ": A"
+	    (org-export-as (org-test-default-backend) nil nil nil
+			   '(:with-fixed-width nil)))))
   ;; Footnotes.
   (should
    (equal "Footnote?"
@@ -498,7 +509,18 @@ Paragraph"
    (equal ""
 	  (org-test-with-temp-text "[0/0]"
 	    (org-export-as (org-test-default-backend)
-			   nil nil nil '(:with-statistics-cookies nil))))))
+			   nil nil nil '(:with-statistics-cookies nil)))))
+  ;; Tables.
+  (should
+   (equal "| A |\n"
+	  (org-test-with-temp-text "| A |"
+	    (org-export-as (org-test-default-backend) nil nil nil
+			   '(:with-tables t)))))
+  (should
+   (equal ""
+	  (org-test-with-temp-text "| A |"
+	    (org-export-as (org-test-default-backend) nil nil nil
+			   '(:with-tables nil))))))
 
 (ert-deftest test-org-export/with-timestamps ()
   "Test `org-export-with-timestamps' specifications."
-- 
1.8.5.2

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Bastien]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Patch attached. WDYT?

'looks good!

-- 
 Bastien

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Florian Beck]

> Patch attached. WDYT?

Works nicely. Thanks.

>
> Regards,
>

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Nicolas Goaziou]

Hello,

Florian Beck <fb@miszellen.de> writes:

> Works nicely. Thanks.

Applied then.


Regards,

-- 
Nicolas Goaziou

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Eric Abrahamsen]

Florian Beck <fb@miszellen.de> writes:

> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>
>> I don't think option 2 is really useful, but I don't mind either way.
>
> Actually, I would find it useful (because I sometimes export my notes as
> an ebook and tables get garbled on the way).

Hey, are you actually exporting to an epub? How are you doing that?

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Eric S Fraga]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Florian Beck <fb@miszellen.de> writes:
>> [...]
>> Actually, I would find it useful (because I sometimes export my notes as
>> an ebook and tables get garbled on the way).
>
> Hey, are you actually exporting to an epub? How are you doing that?

I'd be curious to know as well.  I export to epub in two ways, both by
first exporting to HTML.  Then either use calibre to convert the HTML
document or load the HTML document in firefox and use the "dotepub"
addon.  I haven't done this enough to say which is better.

I would guess that defining an epub exporter, derived from the HTML
exporter, may not be that difficult.  If only I had the time :-(

-- 
: Eric S Fraga (0xFFFCF67D), Emacs 24.3.1, Org release_8.2.4-322-gece429

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Florian Beck]

On 07.01.2014 19:17, Eric S Fraga wrote:
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:

>> Hey, are you actually exporting to an epub? How are you doing that?
>
> I'd be curious to know as well.  I export to epub in two ways, both by
> first exporting to HTML.  Then either use calibre to convert the HTML
> document or load the HTML document in firefox and use the "dotepub"
> addon.  I haven't done this enough to say which is better.

If you are copying your file to a device, conversion with calibre is the 
simplest option.

> I would guess that defining an epub exporter, derived from the HTML
> exporter, may not be that difficult.  If only I had the time :-(


(org-export-define-derived-backend 'fb/org-export-epub 'html
   :menu-entry '(?h 99 ((?p "As epub file" fb/org-export-epub))))

(defun fb/convert-html-to-epub (infile)
   (let ((outfile (concat (file-name-sans-extension infile)
			 ".epub"))
	(max-toc-links "0")
	(level1 "//h:h2")
	(level2 "//h:h3")
	(chapter "\"//*[name()='h1' or name()='h2']\"")
	(chapter-mark "pagebreak"))
     (shell-command
      (format "ebook-convert %s %s --max-toc-links=%s --use-auto-toc 
--level1-toc=%s --level2-toc=%s --chapter=%s --chapter-mark=%s 
--input-encoding=utf8 -v -v -v --authors=\"%s\" --title=\"%s\""
	     infile outfile
	     max-toc-links level1 level2 chapter chapter-mark
	     (user-full-name)
	     (file-name-base outfile)))
     outfile))

(defun fb/org-export-epub (&optional async subtreep visible-only
				     body-only ext-plist)
   (interactive)
   (let* ((extension (concat "." org-html-extension))
	 (file (org-export-output-file-name extension subtreep))
	 (org-export-coding-system org-html-coding-system))
     (org-export-to-file 'fb/org-export-epub file
       async subtreep visible-only body-only ext-plist
       (lambda (file) (fb/convert-html-to-epub file)))))

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Eric Abrahamsen]

Florian Beck <fb@miszellen.de> writes:

> On 07.01.2014 19:17, Eric S Fraga wrote:
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>>> Hey, are you actually exporting to an epub? How are you doing that?
>>
>> I'd be curious to know as well.  I export to epub in two ways, both by
>> first exporting to HTML.  Then either use calibre to convert the HTML
>> document or load the HTML document in firefox and use the "dotepub"
>> addon.  I haven't done this enough to say which is better.
>
> If you are copying your file to a device, conversion with calibre is
> the simplest option.
>
>> I would guess that defining an epub exporter, derived from the HTML
>> exporter, may not be that difficult.  If only I had the time :-(
>
>
> (org-export-define-derived-backend 'fb/org-export-epub 'html
>   :menu-entry '(?h 99 ((?p "As epub file" fb/org-export-epub))))

Definitely looks like the simplest option! Would there be any real
advantage to having a native Org exporter? Setting metadata directly is
the only thing I can think of...

E

Re: [RFC] About `org-export-with-\(fixed-width\|tables\)'

[Eric S Fraga]

Florian Beck <fb@miszellen.de> writes:

> On 07.01.2014 19:17, Eric S Fraga wrote:

[...]

>> I would guess that defining an epub exporter, derived from the HTML
>> exporter, may not be that difficult.  If only I had the time :-(
>
>
> (org-export-define-derived-backend 'fb/org-export-epub 'html
>   :menu-entry '(?h 99 ((?p "As epub file" fb/org-export-epub))))

[...]

Cute!  And obvious in hindsight.  Using calibre to do the conversion is
definitely a case of not re-inventing the wheel.  And it works
well.  Thanks.

-- 
: Eric S Fraga (0xFFFCF67D), Emacs 24.3.50.1, Org release_8.2.5c-436-ga24e64