New html exporter and filters

New html exporter and filters

[Rick Frankel]

This may be a question for Nicolas ---

I seem to have reached the limit of my emacs-fu. I am looking at
adding XOXO output to the S5 exporter (S5 has built-in support for
XOXO structured documents) and was trying to use an element (headline)
filter to modify the document structure. I am also trying to change
the div id to make them more friendly to the deck.js goto function
(which accumulates and displays the ids as a menu).

When i look at the `contents' passed to the filter in edebug, i can see
the element properties (level, raw-title, etc) in the output but I
cannot figure out how to access them.

On the other hand, it would be easier if ox-html were modified so that
org-html-headline uses a variable (or callback) for the format of the
wrapper (currently "<div id=\"%s...") and a callback for the div id
generation. This would add flexibility for inherited backends as well
as allow for more "html5ish" structures (e.g., <section> and <article>
instead of generic <divs>).

The structure of the new exporter has made if very easy for me to add
new html based exporters using the derived backends. Minor changes to
ox-html would make this even more flexible.

I am willing make the changes to ox-html if the approach is agreeable.

tia,
rick

Re: New html exporter and filters

[Nicolas Goaziou]

Hello,

Rick Frankel <rick@rickster.com> writes:

> I seem to have reached the limit of my emacs-fu. I am looking at
> adding XOXO output to the S5 exporter (S5 has built-in support for
> XOXO structured documents) and was trying to use an element (headline)
> filter to modify the document structure. I am also trying to change
> the div id to make them more friendly to the deck.js goto function
> (which accumulates and displays the ids as a menu).

I'm not sure about what you mean here.

> When i look at the `contents' passed to the filter in edebug, i can see
> the element properties (level, raw-title, etc) in the output but I
> cannot figure out how to access them.

You cannot access them. You have access to the full parse tree with
(plist-get info :parse-tree), but not to the parsed current headline.
Filters only give you access to strings produced by the back-end.

Anyway, you still can modify headline div attributes from there.

> On the other hand, it would be easier if ox-html were modified so that
> org-html-headline uses a variable (or callback) for the format of the
> wrapper (currently "<div id=\"%s...") and a callback for the div id
> generation. This would add flexibility for inherited backends as well
> as allow for more "html5ish" structures (e.g., <section> and <article>
> instead of generic <divs>).

Wouldn't it be simpler to just fork `org-html-headline' in your back-end
in order to replace the divs with something you need?

On the other hand, there are a couple of variables providing a way to
modify divs ids in ox-html.el. I suppose one more doesn't hurt. It may
be even better to collect them in a single defcustom.

What do you think?


Regards,

-- 
Nicolas Goaziou

Re: New html exporter and filters

[Rick Frankel]

On Tue, Mar 05, 2013 at 09:16:16AM +0100, Nicolas Goaziou wrote:
> Rick Frankel <rick@rickster.com> writes:

> > On the other hand, it would be easier if ox-html were modified so that
> > org-html-headline uses a variable (or callback) for the format of the
> > wrapper (currently "<div id=\"%s...") and a callback for the div id
> > generation. This would add flexibility for inherited backends as well
> > as allow for more "html5ish" structures (e.g., <section> and <article>
> > instead of generic <divs>).
> 
> Wouldn't it be simpler to just fork `org-html-headline' in your back-end
> in order to replace the divs with something you need?

Well, `org-html-headline' does a lot and I'm trying to rewrite as
little as possible. Actually, i already wrap `org-html-headline', so i
could fix the :CUSTOM_ID on the way in. I think i was looking for a
solution to both the wrapper element and id in the same place (a
filter).

> On the other hand, there are a couple of variables providing a way to
> modify divs ids in ox-html.el. I suppose one more doesn't hurt. It may
> be even better to collect them in a single defcustom.
> 
> What do you think?

What I think is missing is a way to customize the element used for the
wrapper, and possiblly the id/class prefixes.  The simple solution
would be to add an `org-headline-wrapper-element' customization
(defaulting to "div"), or if allowing change to the id and class:

       '("div" "outline-container-%s" "outline-%d").

If you were to over-engineer it,something along the lines of the way
the latex exporter specifies the headline hierarchies for one of the 
document classes would work :}

Likewise, it would make sense for the `org-html-divs' to become a list
of '(element . class) instead of a list of just classes. e.e.g

(defcustom org-html-divs '(("header" . "preamble")
                           ("section" . "content")
                           ("footer" . "postamble"))

Rick

Re: New html exporter and filters

[Jambunathan K]

The <div> </div> aren't really content elements but merely structuring
or styling elements.  

I think there should be a clear separation between contents and how it
is wrapped.  The base HTML exporter should just generate content with no
divs at all.  There could be a fancy HTML exporter which does generate
divs.

I can think of "splitting" the current HTML exporter in to a base-html
backend and an fancy-html backend.  Rick can derive from base-html
backend instead of fancy-html.

The current HTML exporter is one in the circle.

              ---------
          ---/         \---
        -/                 \-
       /                     \
      /   Org Factory HTML    \          Deck HTML
     /     (adds factory divs) \              |
    /            |              \             |
    |            |  +-----------+-------------+
    |            |  |           |
    |            V  V           |
    \        Base HTML          /                 
     \        (no divs)        /                  
      \                       /                   
       \                     /
        -\                 /-
          ---\         /---
              ---------


The problem here is much similar to what Torrey was saying in other
thread wrt to TOC "pseudo"-elements [1].  The Id property is not the TOC
itself but enhances (or particularizes) that specific transoding.

Nicolas,
Let me work with Rick Frankel on this.  I will take over this thread.

Jambunathan K.


Rick Frankel <rick@rickster.com> writes:

> On Tue, Mar 05, 2013 at 09:16:16AM +0100, Nicolas Goaziou wrote:
>> Rick Frankel <rick@rickster.com> writes:
>
>> > On the other hand, it would be easier if ox-html were modified so that
>> > org-html-headline uses a variable (or callback) for the format of the
>> > wrapper (currently "<div id=\"%s...") and a callback for the div id
>> > generation. This would add flexibility for inherited backends as well
>> > as allow for more "html5ish" structures (e.g., <section> and <article>
>> > instead of generic <divs>).
>> 
>> Wouldn't it be simpler to just fork `org-html-headline' in your back-end
>> in order to replace the divs with something you need?
>
> Well, `org-html-headline' does a lot and I'm trying to rewrite as
> little as possible. Actually, i already wrap `org-html-headline', so i
> could fix the :CUSTOM_ID on the way in. I think i was looking for a
> solution to both the wrapper element and id in the same place (a
> filter).
>
>> On the other hand, there are a couple of variables providing a way to
>> modify divs ids in ox-html.el. I suppose one more doesn't hurt. It may
>> be even better to collect them in a single defcustom.
>> 
>> What do you think?
>
> What I think is missing is a way to customize the element used for the
> wrapper, and possiblly the id/class prefixes.  The simple solution
> would be to add an `org-headline-wrapper-element' customization
> (defaulting to "div"), or if allowing change to the id and class:
>
>        '("div" "outline-container-%s" "outline-%d").
>
> If you were to over-engineer it,something along the lines of the way
> the latex exporter specifies the headline hierarchies for one of the 
> document classes would work :}
>
> Likewise, it would make sense for the `org-html-divs' to become a list
> of '(element . class) instead of a list of just classes. e.e.g
>
> (defcustom org-html-divs '(("header" . "preamble")
>                            ("section" . "content")
>                            ("footer" . "postamble"))
>
> Rick
>
>

-- 

Re: New html exporter and filters

[Jambunathan K]

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


Here is a quick patch.  Not meant to be applied but meant for testing
purpose only.

So there is a html backend which doesn't add divs and there is a HTML
backend that adds divs. (The difference is between html and HTML, in
capslock).  

The `org-export-dispatch' uses HTML backend, while you can continue to
derive from html backend and add divs of your own.

Try this patch and let me know what you find.  Or you can circulate a
make-shift patch which improves the attached version to suit your needs.

I can formalize this patch once I get a go ahead from you.


[-- Attachment #2: ox-html.el.diff --]
[-- Type: diff, Size: 7408 bytes --]

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 5e55391..a8989f2 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -103,14 +103,6 @@
   :export-block "HTML"
   :filters-alist ((:filter-options . org-html-infojs-install-script)
 		  (:filter-final-output . org-html-final-function))
-  :menu-entry
-  (?h "Export to HTML"
-      ((?H "As HTML buffer" org-html-export-as-html)
-       (?h "As HTML file" org-html-export-to-html)
-       (?o "As HTML file and open"
-	   (lambda (a s v b)
-	     (if a (org-html-export-to-html t s v b)
-	       (org-open-file (org-html-export-to-html nil s v b)))))))
   :options-alist
   ((:html-extension nil nil org-html-extension)
    (:html-link-home "HTML_LINK_HOME" nil org-html-link-home)
@@ -129,6 +121,18 @@
    ;; Leave room for "ox-infojs.el" extension.
    (:infojs-opt "INFOJS_OPT" nil nil)))
 
+(org-export-define-derived-backend HTML html
+  :menu-entry
+  (?h "Export to HTML"
+      ((?H "As HTML buffer" org-html-export-as-html)
+       (?h "As HTML file" org-html-export-to-html)
+       (?o "As HTML file and open"
+	   (lambda (a s v b)
+	     (if a (org-html-export-to-html t s v b)
+	       (org-open-file (org-html-export-to-html nil s v b)))))))
+  :translate-alist ((headline . org-HTML-headline)
+  		    (section . org-HTML-section)))
+
 
 \f
 ;;; Internal Variables
@@ -2153,31 +2157,70 @@ holding contextual information."
 	     (extra-class (org-element-property :HTML_CONTAINER_CLASS headline))
 	     (level1 (+ level (1- org-html-toplevel-hlevel)))
 	     (first-content (car (org-element-contents headline))))
-	(format "<div id=\"%s\" class=\"%s\">%s%s</div>\n"
+	(concat
+	 (format "\n<h%d id=\"%s\">%s%s</h%d>\n"
+		 level1
+		 preferred-id
+		 (mapconcat
+		  (lambda (x)
+		    (let ((id (org-export-solidify-link-text
+			       (if (org-uuidgen-p x) (concat "ID-" x)
+				 x))))
+		      (org-html--anchor id)))
+		  extra-ids "")
+		 full-text
+		 level1)
+	 ;; When there is no section, pretend there is an empty
+	 ;; one to get the correct <div class="outline- ...>
+	 ;; which is needed by `org-info.js'.
+	 (if (not (eq (org-element-type first-content) 'section))
+	     (concat (org-html-section first-content "" info)
+		     contents)
+	   contents)))))))
+
+(defun org-HTML-headline (headline contents info)
+  "Transcode a HEADLINE element from Org to HTML.
+CONTENTS holds the contents of the headline.  INFO is a plist
+holding contextual information."
+  ;; Empty contents?
+  (setq contents (or contents ""))
+  (let* ((level (org-export-get-relative-level headline info))
+	 (section-number (and (org-export-numbered-headline-p headline info)
+			      (mapconcat 'number-to-string
+					 (org-export-get-headline-number
+					  headline info) ".")))
+	 ;; Create the headline text.
+	 (full-text (org-html-format-headline--wrap headline info)))
+    (cond
+     ;; Case 1: This is a footnote section: ignore it.
+     ((org-element-property :footnote-section-p headline)
+      contents)
+     ;; Case 2. This is a deep sub-tree: export it as a list item.
+     ;;         Also export as items headlines for which no section
+     ;;         format has been found.
+     ((org-export-low-level-p headline info)
+      contents)
+     ;; Case 3. Standard headline.  Export it as a section.
+     (t
+      (let* ((section-number (mapconcat 'number-to-string
+					(org-export-get-headline-number
+					 headline info) "-"))
+	     (ids (remove 'nil
+			  (list (org-element-property :CUSTOM_ID headline)
+				(concat "sec-" section-number)
+				(org-element-property :ID headline))))
+	     (preferred-id (car ids))
+	     (extra-ids (cdr ids))
+	     (extra-class (org-element-property :HTML_CONTAINER_CLASS headline))
+	     (level1 (+ level (1- org-html-toplevel-hlevel)))
+	     (first-content (car (org-element-contents headline))))
+	(format "<div id=\"%s\" class=\"%s\">%s</div>\n"
 		(format "outline-container-%s"
 			(or (org-element-property :CUSTOM_ID headline)
 			    section-number))
 		(concat (format "outline-%d" level1) (and extra-class " ")
 			extra-class)
-		(format "\n<h%d id=\"%s\">%s%s</h%d>\n"
-			level1
-			preferred-id
-			(mapconcat
-			 (lambda (x)
-			   (let ((id (org-export-solidify-link-text
-				      (if (org-uuidgen-p x) (concat "ID-" x)
-					x))))
-			     (org-html--anchor id)))
-			 extra-ids "")
-			full-text
-			level1)
-		;; When there is no section, pretend there is an empty
-		;; one to get the correct <div class="outline- ...>
-		;; which is needed by `org-info.js'.
-		(if (not (eq (org-element-type first-content) 'section))
-		    (concat (org-html-section first-content "" info)
-			    contents)
-		  contents)))))))
+		contents))))))
 
 
 ;;;; Horizontal Rule
@@ -2812,6 +2855,23 @@ holding contextual information."
 	       'number-to-string
 	       (org-export-get-headline-number parent info) "-")))
         ;; Build return value.
+	contents))))
+
+(defun org-HTML-section (section contents info)
+  "Transcode a SECTION element from Org to HTML.
+CONTENTS holds the contents of the section.  INFO is a plist
+holding contextual information."
+  (let ((parent (org-export-get-parent-headline section)))
+    ;; Before first headline: no container, just return CONTENTS.
+    (if (not parent) contents
+      ;; Get div's class and id references.
+      (let* ((class-num (+ (org-export-get-relative-level parent info)
+			   (1- org-html-toplevel-hlevel)))
+	     (section-number
+	      (mapconcat
+	       'number-to-string
+	       (org-export-get-headline-number parent info) "-")))
+        ;; Build return value.
 	(format "<div class=\"outline-text-%d\" id=\"text-%s\">\n%s</div>"
 		class-num
 		(or (org-element-property :CUSTOM_ID parent) section-number)
@@ -3174,10 +3234,10 @@ is non-nil."
 	      (insert output)
 	      (goto-char (point-min))
 	      (set-auto-mode t)
-	      (org-export-add-to-stack (current-buffer) 'html)))
-	`(org-export-as 'html ,subtreep ,visible-only ,body-only ',ext-plist))
+	      (org-export-add-to-stack (current-buffer) 'HTML)))
+	`(org-export-as 'HTML ,subtreep ,visible-only ,body-only ',ext-plist))
     (let ((outbuf (org-export-to-buffer
-		   'html "*Org HTML Export*"
+		   'HTML "*Org HTML Export*"
 		   subtreep visible-only body-only ext-plist)))
       ;; Set major mode.
       (with-current-buffer outbuf (set-auto-mode t))
@@ -3219,14 +3279,14 @@ Return output file's name."
 	 (org-export-coding-system org-html-coding-system))
     (if async
 	(org-export-async-start
-	    (lambda (f) (org-export-add-to-stack f 'html))
+	    (lambda (f) (org-export-add-to-stack f 'HTML))
 	  (let ((org-export-coding-system org-html-coding-system))
 	    `(expand-file-name
 	      (org-export-to-file
-	       'html ,file ,subtreep ,visible-only ,body-only ',ext-plist))))
+	       'HTML ,file ,subtreep ,visible-only ,body-only ',ext-plist))))
       (let ((org-export-coding-system org-html-coding-system))
 	(org-export-to-file
-	 'html file subtreep visible-only body-only ext-plist)))))
+	 'HTML file subtreep visible-only body-only ext-plist)))))
 
 ;;;###autoload
 (defun org-html-publish-to-html (plist filename pub-dir)
@@ -3237,7 +3297,7 @@ is the property list for the given project.  PUB-DIR is the
 publishing directory.
 
 Return output file name."
-  (org-publish-org-to 'html filename ".html" plist pub-dir))
+  (org-publish-org-to 'HTML filename ".html" plist pub-dir))
 
 
 \f

[-- Attachment #3: Type: text/plain, Size: 3718 bytes --]




Jambunathan K <kjambunathan@gmail.com> writes:

> The <div> </div> aren't really content elements but merely structuring
> or styling elements.  
>
> I think there should be a clear separation between contents and how it
> is wrapped.  The base HTML exporter should just generate content with no
> divs at all.  There could be a fancy HTML exporter which does generate
> divs.
>
> I can think of "splitting" the current HTML exporter in to a base-html
> backend and an fancy-html backend.  Rick can derive from base-html
> backend instead of fancy-html.
>
> The current HTML exporter is one in the circle.
>
>               ---------
>           ---/         \---
>         -/                 \-
>        /                     \
>       /   Org Factory HTML    \          Deck HTML
>      /     (adds factory divs) \              |
>     /            |              \             |
>     |            |  +-----------+-------------+
>     |            |  |           |
>     |            V  V           |
>     \        Base HTML          /                 
>      \        (no divs)        /                  
>       \                       /                   
>        \                     /
>         -\                 /-
>           ---\         /---
>               ---------
>
>
> The problem here is much similar to what Torrey was saying in other
> thread wrt to TOC "pseudo"-elements [1].  The Id property is not the TOC
> itself but enhances (or particularizes) that specific transoding.
>
> Nicolas,
> Let me work with Rick Frankel on this.  I will take over this thread.
>
> Jambunathan K.
>
>
> Rick Frankel <rick@rickster.com> writes:
>
>> On Tue, Mar 05, 2013 at 09:16:16AM +0100, Nicolas Goaziou wrote:
>>> Rick Frankel <rick@rickster.com> writes:
>>
>>> > On the other hand, it would be easier if ox-html were modified so that
>>> > org-html-headline uses a variable (or callback) for the format of the
>>> > wrapper (currently "<div id=\"%s...") and a callback for the div id
>>> > generation. This would add flexibility for inherited backends as well
>>> > as allow for more "html5ish" structures (e.g., <section> and <article>
>>> > instead of generic <divs>).
>>> 
>>> Wouldn't it be simpler to just fork `org-html-headline' in your back-end
>>> in order to replace the divs with something you need?
>>
>> Well, `org-html-headline' does a lot and I'm trying to rewrite as
>> little as possible. Actually, i already wrap `org-html-headline', so i
>> could fix the :CUSTOM_ID on the way in. I think i was looking for a
>> solution to both the wrapper element and id in the same place (a
>> filter).
>>
>>> On the other hand, there are a couple of variables providing a way to
>>> modify divs ids in ox-html.el. I suppose one more doesn't hurt. It may
>>> be even better to collect them in a single defcustom.
>>> 
>>> What do you think?
>>
>> What I think is missing is a way to customize the element used for the
>> wrapper, and possiblly the id/class prefixes.  The simple solution
>> would be to add an `org-headline-wrapper-element' customization
>> (defaulting to "div"), or if allowing change to the id and class:
>>
>>        '("div" "outline-container-%s" "outline-%d").
>>
>> If you were to over-engineer it,something along the lines of the way
>> the latex exporter specifies the headline hierarchies for one of the 
>> document classes would work :}
>>
>> Likewise, it would make sense for the `org-html-divs' to become a list
>> of '(element . class) instead of a list of just classes. e.e.g
>>
>> (defcustom org-html-divs '(("header" . "preamble")
>>                            ("section" . "content")
>>                            ("footer" . "postamble"))
>>
>> Rick
>>
>>

--