txt2tags exporter: patch & questions

txt2tags exporter: patch & questions

[Matteo Cypriani]

[-- Attachment #1.1: Type: Text/Plain, Size: 3692 bytes --]

Hi there,


I worked on an exporter to the txt2tags format (http://txt2tags.org/) via org-
export-generic, and I have got a few questions (that are also included as 
comments in the attached patch).


My first question is about numbered lists: they don't seem to be detected, 
i.e. numbers are kept (despite :body-number-list-leave-number is set to nil), 
and the prefix is not applied. It seems to be the case also for other formats 
handled by the generic exporter, so maybe it is a known issue.


In the same kind of issue, the #+BEGIN_QUOTE blocks does not seem to be 
detected, setting :blockquote-start and :blockquote-end doesn't have any 
effect and the text inside the block is outputted as normal paragraph text.

#+BEGIN_VERSE blocks are the same except they start with “ORG-VERSE-START” and 
end with “ORG-VERSE-END”, but I guess this is more normal since I don't find 
any mention of verse blocks in the org-export-generic code.

That said the txt2tags format doen't handle quote blocks, each line of a quote 
must be indented by a tab. Would it be possible to add something like :body-
line-quote-format and :body-line-verse-format (as :body-line-fixed-format 
exists)?


I also have a problem with tables, as txt2tags doesn't handle horizontal lines 
in the tables; would it be possible to add an option like :body-line-export-
hline?


My last question is about paragraph spacing. To get a blank line between two 
paragraphs (which is the way to separate paragraphs in txt2tags as well as in 
org-mode), I set :body-newline-paragraph to "\n" (by the way that should also 
be the case at least in the MediaWiki exporter). It works as expected for 
normal paragraphs, but it becomes a mess with item lists.

I set the following variables for more visibility:
     :body-line-format              "%s!EOL!\n"
     :body-newline-paragraph        "!NP!\n"
     :body-list-format              "- %s!EOI!"
     :body-list-suffix              "!BLS!\n\n!ELS!"
So we have !EOL! before an end of line, !NP! before a new paragraph, !EOI! at 
the end of a list item (without a trailing new line), !BLS! to begin the list 
suffix and !ELS! to end it. Note that the txt2tags format requires two blank 
lines to close a list.

Now we have the following text in our org-mode buffer:

- First item.
- This is
  an item
  on three lines.
- Bar foo
  blah.

Which gets exported as:

- First item.!EOI!!NP!
- This is!EOI!!BLS!

!ELS!  an item!EOL!
  on three lines.!EOL!
!NP!
- Bar foo!EOI!!BLS!

!ELS!  blah.!EOL!
!NP!

So, it sounds like multi-line items are not handled properly by org-generic-
exporter. In my opinion:
- :body-newline-paragraph should not be added inside a list, we can handle the 
format of an item list with :body-list-format.
- The second and subsequent lines of an item should be handled as special 
elements instead of as normal lines, i.e. :body-line-format should not be 
used, but maybe a :body-list-line-format should be added.
- The end of a list should be detected so that :body-list-suffix is added only 
there.

I am by no mean a Lisp developper, so that is what I *think* should be done to 
get a proper handling of lists, but (1) I may be wrong, and (2) I don't think 
I can do that myself. Comments and advices appreciated.


Also, at the end of my patch is a small list of things missing in org-generic-
exporter to get a complete txt2tags support, in case someone's got some spare 
time and doesn't know where to start :-)


Thanks for reading so far,

  Matteo

P.S.: please keep me CC'ed if you answer this email, as I am not subscribed to 
the list.

[-- Attachment #1.2: org-export-generic_txt2tags.diff --]
[-- Type: text/x-patch, Size: 3996 bytes --]

--- org-export-generic.el.orig	2012-11-13 17:59:22.795585712 +0100
+++ org-export-generic.el	2012-11-13 19:33:15.458769199 +0100
@@ -371,6 +371,103 @@
 
      )
     ;;
+    ;; txt2tags
+    ;;
+    ("txt2tags"
+     :file-suffix                   ".t2t"
+     :key-binding                   ?2
+
+     ; Header
+     :title-format                  "%s\n"
+     :author-export                 t
+     :date-export                   t
+     :date-suffix                   "\n"
+     :toc-export                    nil
+
+     ; Titles & sections
+     :body-section-prefix           ""
+     :body-header-section-numbers   nil
+     :body-section-header-prefix   ("\n\n\n= " "\n== " "=== "
+                                    "==== " "===== " "====== ")
+     :body-section-header-format    "%s"
+     :body-section-header-suffix   (" =\n" " ==\n" " ===\n"
+                                    " ====\n" " =====\n" " ======\n")
+
+     ; General line format
+     :body-line-format              "%s\n"
+     :body-line-wrap                72
+     ; To have a new line after each paragraph:
+     :body-newline-paragraph        "\n"
+     :body-text-prefix              ""
+     :body-text-suffix              ""
+
+     ; Lists
+     ; Note: nested lists are not handled by org-export-generic yet.
+     ; /!\ Multi-line items get a new line after their first line
+     ;     (because of :body-newline-paragraph)
+     :body-list-format              "- %s"
+     :body-list-suffix              "\n\n"
+
+     ; Numbered lists
+     ; /!\ Numbered lists does not seem to be detected in the Org source
+     ;     file!
+     :body-number-list-format       "+ %s\n"
+     :body-number-list-suffix       "\n\n"
+     :body-number-list-leave-number nil
+
+     ; Checkboxes
+     :body-list-checkbox-todo       "\\1 "
+     :body-list-checkbox-done       "\\1 "
+     :body-list-checkbox-half       "\\1 "
+     :body-list-checkbox-todo-end   ""
+     :body-list-checkbox-done-end   ""
+     :body-list-checkbox-half-end   "\n"
+
+     ; Text style formats
+     :bold-format                   "**%s**"
+     :italic-format                 "//%s//"
+     :underline-format              "__%s__"
+     :strikethrough-format          "--%s--"
+     :code-format                   "``%s``"
+     :verbatim-format               "``%s``"
+
+     ; Block formats
+     :body-line-export-preformated  t
+     :body-line-fixed-format        "``` %s\n"
+     ; /!\ #+BEGIN_QUOTE does not seem to work (neither do #+BEGIN_VERSE)
+;     :blockquote-start              "!BLOCKQUOTE-START!"
+;     :blockquote-end                "!BLOCKQUOTE-END!"
+
+     ; Tables
+     :body-table-start              ""
+     :body-table-end                ""
+     :body-table-row-start          "|"
+     :body-table-row-end            "|"
+     :body-table-cell-start         ""
+     :body-table-cell-end           ""
+     :body-table-first-cell-start   ""
+     :body-table-interior-cell-start "| "
+     :body-table-interior-cell-end  " "
+     :body-table-last-cell-end      ""
+     ; /!\ Horizontal lines are not handled by txt2tags, but there is
+     ;     apparently no way to avoid them
+     :body-table-hline-start        ""
+     :body-table-hline-end          ""
+
+     ; Other stuff handled by txt2tags and org-mode but not yet by
+     ; org-export-generic:
+     ; - definition/description lists
+     ; - comments (# lines and #+BEGIN_COMMENT blocks)
+     ; - verbatim/literal blocks (#+BEGIN_EXAMPLE and #+BEGIN_SRC)
+     ; - horizontal rule (currently detected as a list item)
+     ; - links
+     ; - images
+     ; - included files (#+INCLUDE) (what would be nice is an option to
+     ;   allow choosing between inclusion of sub-files as #+INCLUDEs or
+     ;   directly in the text)
+     ; - macros
+     )
+    ;;
     ;; internet-draft .xml for xml2rfc exporter
     ;;
     ("ietfid"

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: txt2tags exporter: patch & questions

[Nicolas Goaziou]

Hello,

Matteo Cypriani <mcy@lm7.fr> writes:

> I worked on an exporter to the txt2tags format (http://txt2tags.org/) via org-
> export-generic, and I have got a few questions (that are also included as 
> comments in the attached patch).

There's a more powerful generic exporter being tested right now:
org-export.el. Assuming you use a very recent Org , it lives in contrib/
directory and should be moved into core soon. You may want to try it in
order to implement the text2tags backend.

There is documentation for backend developers using this framework at:

  http://orgmode.org/worg/dev/org-export-reference.html

Thanks for your interest in Org.


Regards,

-- 
Nicolas Goaziou