[patch][ox-html] Support for level based containers

[patch][ox-html] Support for level based containers

[Rasmus]

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

Hi,

This patch allows different containers in ox-html.el depending on the
level of the heading.  For example, it is possible to get a container
structure like this (level . container):

*   . section
**  . article
*** . div

This is good for HTML5 at least, and I suspect also for ox-publish
projects.  I don't know if this additional semantics is useful for
"HTML4".

Let me know if you find you'd be willing to merge something like this
and what changes are necessary, if any.

Thanks,
Rasmus

-- 
When in doubt, do it!

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Support-for-level-based-containers-in-ox-html.patch --]
[-- Type: text/x-diff, Size: 2231 bytes --]

From b24e403030ea76febc3fecb0ba9db56b3c39d5aa Mon Sep 17 00:00:00 2001
From: Rasmus <w530@pank.eu>
Date: Sun, 16 Mar 2014 00:01:35 +0100
Subject: [PATCH] Support for level-based containers in ox-html

* ox-html.el (org-html-container-element): List of
cons of section-level containers.
(org-html--container): Redefine to consider
org-html-container-element.
---
 lisp/ox-html.el | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index a8c924f..f1a4cb1 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -940,17 +940,23 @@ versions 8 and below."
   :package-version '(Org . "8.0")
   :type 'boolean)
 
-(defcustom org-html-container-element "div"
-  "HTML element to use for wrapping top level sections.
+(defcustom org-html-container-element '(("div" . "section")
+					("div" . "article")
+					("div" . "div"))
+  "HTML elements to use for wrapping sections.
 Can be set with the in-buffer HTML_CONTAINER property or for
 publishing, with :html-container.
 
-Note that changing the default will prevent you from using
-org-info.js for your website."
+Should be a list of cons cells with positions corresponding to a
+section.  If `org-html-html5-fancy' is t the cdr is used
+otherwise the car.
+
+Note that changing the default will prevent you from
+using org-info.js for your website."
   :group 'org-export-html
   :version "24.4"
   :package-version '(Org . "8.0")
-  :type 'string)
+  :type '(repeat (cons string string)))
 
 (defcustom org-html-divs
   '((preamble  "div" "preamble")
@@ -2412,9 +2418,14 @@ holding contextual information."
 
 (defun org-html--container (headline info)
   (or (org-element-property :HTML_CONTAINER headline)
-      (if (= 1 (org-export-get-relative-level headline info))
-	  (plist-get info :html-container)
-	"div")))
+      (let* ((hc (plist-get info :html-container))
+	     (n (org-export-get-relative-level headline info)))
+	(cond ((listp hc)
+	       (or (funcall (if org-html-html5-fancy 'cdr-safe 'car-safe)
+			    (nth (1- (min n (length hc))) hc)) "div"))
+	      ((and (stringp hc) (= 1 n))
+	       (plist-get info :html-container))
+	      (t "div")))))
 
 ;;;; Horizontal Rule
 
-- 
1.9.0

Re: [patch][ox-html] Support for level based containers

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> This patch allows different containers in ox-html.el depending on the
> level of the heading.  For example, it is possible to get a container
> structure like this (level . container):
>
> *   . section
> **  . article
> *** . div
>
> This is good for HTML5 at least, and I suspect also for ox-publish
> projects.  I don't know if this additional semantics is useful for
> "HTML4".

Thank you for the patch.

> Let me know if you find you'd be willing to merge something like this

I don't know enough HTML to have an opinion here.

> and what changes are necessary, if any.

Some comments follow.

> +(defcustom org-html-container-element '(("div" . "section")
> +					("div" . "article")
> +					("div" . "div"))
> +  "HTML elements to use for wrapping sections.
>  Can be set with the in-buffer HTML_CONTAINER property or for
>  publishing, with :html-container.
>  
> -Note that changing the default will prevent you from using
> -org-info.js for your website."
> +Should be a list of cons cells with positions corresponding to a

A "list of cons cells" is an "alist".

> +section.  If `org-html-html5-fancy' is t the cdr is used
> +otherwise the car.

"is non-nil" is better than "is t". Also, you shouldn't use
`org-html-html5-fancy': see below.

> +Note that changing the default will prevent you from
> +using org-info.js for your website."
>    :group 'org-export-html
>    :version "24.4"
>    :package-version '(Org . "8.0")
> -  :type 'string)
> +  :type '(repeat (cons string string)))

There is an `alist' type. See (info "(elisp) Composite Types")

> +      (let* ((hc (plist-get info :html-container))
> +	     (n (org-export-get-relative-level headline info)))

You don't need a starred `let' here. Also, I suggest to not use short
variable names. IMO "container-alist" is better than "hc" and "level"
better than "n".

> +	(cond ((listp hc)
> +	       (or (funcall (if org-html-html5-fancy 'cdr-safe 'car-safe)
> +			    (nth (1- (min n (length hc))) hc)) "div"))

You shouldn't use directly the variable `org-html-html5-fancy' since its
value can be overridden with external properties (e.g., during
a publishing process, with a specific setup). Instead, it should be:

  (plist-get info :html-html5-fancy)

As a rule of thumb, don't use variables when there's a property in INFO
for them.

Also, I don't think you need to use `car-safe' instead of `car' and
`cdr-safe' instead of `cdr'.

Eventually, due to the (min n (length hc)) (which should be documented
in the docstring) and the fact that the alist cannot be empty, the
`funcall' never evaluates to nil. Therefore, the `or' is not necessary.

> +	      ((and (stringp hc) (= 1 n))
> +	       (plist-get info :html-container))

Note that this branch is always false since HC shouldn't be a string,
per the defcustom type, but an alist.

> +	      (t "div")))))

Given the recommendations above, the whole `cond' could be rewritten:

  (funcall (if (plist-get info :html-html5-fancy) #'cdr #'car)
           (nth (1- (min level (length container-alist))) container-alist))


Regards,

-- 
Nicolas Goaziou

Re: [patch][ox-html] Support for level based containers

[Rasmus]

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

Hi,

Thanks for the—as always—useful comments.  I have attached a new
version of the patch with better doc and a bit better functionality, I
think.

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

> I don't know enough HTML to have an opinion here.

Then we are two. . .

>> and what changes are necessary, if any.
>
> Some comments follow.
>
>> +(defcustom org-html-container-element '(("div" . "section")
>> +					("div" . "article")
>> +					("div" . "div"))
>> +  "HTML elements to use for wrapping sections.
>>  Can be set with the in-buffer HTML_CONTAINER property or for
>>  publishing, with :html-container.
>>
>> -Note that changing the default will prevent you from using
>> -org-info.js for your website."
>> +Should be a list of cons cells with positions corresponding to a
>
> A "list of cons cells" is an "alist".

I think I knew that at some point, but forgot along the way.  At least
"list of cons" is better than "list of tuples". . .

>> +section.  If `org-html-html5-fancy' is t the cdr is used
>> +otherwise the car.
>
> "is non-nil" is better than "is t". Also, you shouldn't use
> `org-html-html5-fancy': see below.

>> +Note that changing the default will prevent you from
>> +using org-info.js for your website."
>>    :group 'org-export-html
>>    :version "24.4"
>>    :package-version '(Org . "8.0")
>> -  :type 'string)
>> +  :type '(repeat (cons string string)))
>
> There is an `alist' type. See (info "(elisp) Composite Types")

I went for another solution as I would prefer not to break backward
comparability.

>> +      (let* ((hc (plist-get info :html-container))
>> +	     (n (org-export-get-relative-level headline info)))
>
> You don't need a starred `let' here. Also, I suggest to not use short
> variable names. IMO "container-alist" is better than "hc" and "level"
> better than "n".

Good rule of thumb.

>> +	(cond ((listp hc)
>> +	       (or (funcall (if org-html-html5-fancy 'cdr-safe 'car-safe)
>> +			    (nth (1- (min n (length hc))) hc)) "div"))
>
> You shouldn't use directly the variable `org-html-html5-fancy' since its
> value can be overridden with external properties (e.g., during
> a publishing process, with a specific setup). Instead, it should be:
>
>   (plist-get info :html-html5-fancy)
>
> As a rule of thumb, don't use variables when there's a property in INFO
> for them.

You are right.  Thanks for spotting it.

> Also, I don't think you need to use `car-safe' instead of `car' and
> `cdr-safe' instead of `cdr'.

My "defense" is, people could make mistakes, e.g. provide the list
'("div" "div" "div").  But you are right.

> Eventually, due to the (min n (length hc)) (which should be documented
> in the docstring) and the fact that the alist cannot be empty, the
> `funcall' never evaluates to nil. Therefore, the `or' is not necessary.

See below.

>> +	      ((and (stringp hc) (= 1 n))
>> +	       (plist-get info :html-container))
>
> Note that this branch is always false since HC shouldn't be a string,
> per the defcustom type, but an alist.

Yeah, but since ATM it's a string, there may be people who've
customized it in there init.el or in project definition.  I wouldn't
want to break it for them. . .  I have adjusted the docstring to
consider this.


>> +	      (t "div")))))
>
> Given the recommendations above, the whole `cond' could be rewritten:
>
>   (funcall (if (plist-get info :html-html5-fancy) #'cdr #'car)
>            (nth (1- (min level (length container-alist))) container-alist))

More elegant. 

Thanks,
Rasmus

--
Hooray!

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Support-for-level-based-containers-in-ox-html.patch --]
[-- Type: text/x-diff, Size: 3313 bytes --]

From 3514d5bc9311f7e38fc9518c6a8f450c9fa3a37a Mon Sep 17 00:00:00 2001
From: Rasmus <w530@pank.eu>
Date: Sun, 16 Mar 2014 00:01:35 +0100
Subject: [PATCH] Support for level-based containers in ox-html

* ox-html.el (org-html-container-element): List of
cons of section-level containers.
(org-html--container): Redefine to consider
org-html-container-element.
---
 lisp/ox-html.el | 48 +++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 39 insertions(+), 9 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index a8c924f..f34b3a0 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -940,17 +940,36 @@ versions 8 and below."
   :package-version '(Org . "8.0")
   :type 'boolean)
 
-(defcustom org-html-container-element "div"
-  "HTML element to use for wrapping top level sections.
+(defcustom org-html-container-element '(("div" . "section")
+					("div" . "article")
+					("div" . "div"))
+  "HTML elements to use for wrapping sections.
 Can be set with the in-buffer HTML_CONTAINER property or for
 publishing, with :html-container.
 
-Note that changing the default will prevent you from using
-org-info.js for your website."
+Should be an alist where each cons-cell corresponds to a section
+levels.  The first cons-cell is used for top-level headlines, the
+second cons-cell is used for second level headlines and so forth.
+Headlines with levels higher than the length of the alist use the
+last cons-cell.
+
+If the output is \"html5\" (see `org-html-doctype') and
+html5-fancy is non-nil (see `org-html-html5-fancy') then the cdr
+of cons-cell is used.  Otherwise the car is used.
+
+May also be a single string corresponding to the top-level
+container for backward comparability.
+
+Note that changing the default will prevent you from
+using org-info.js for your website."
   :group 'org-export-html
   :version "24.4"
   :package-version '(Org . "8.0")
-  :type 'string)
+  :type '(choice (repeat :tag "Fine control"
+                         (choice (cons :tag "level"
+                                       (string :tag "Default")
+                                       (string :tag "Fancy HTML5"))))
+                 (string :tag "Control top level only" :value "div")))
 
 (defcustom org-html-divs
   '((preamble  "div" "preamble")
@@ -2411,10 +2430,21 @@ holding contextual information."
 		(org-html--container headline info)))))))
 
 (defun org-html--container (headline info)
-  (or (org-element-property :HTML_CONTAINER headline)
-      (if (= 1 (org-export-get-relative-level headline info))
-	  (plist-get info :html-container)
-	"div")))
+  "Select an appropriate HTML container for a headline.
+
+The container is selected based on level and depend on
+:html-container corresponding to org-html-container-element."
+  (let ((container-alist (plist-get info :html-container))
+	(level (org-export-get-relative-level headline info)))
+    (cond ((listp container-alist)
+	   (funcall (if (and (org-html-html5-p info)
+			     (plist-get info :html-html5-fancy)) #'cdr #'car)
+		    (nth (1- (min level (length container-alist)))
+			 container-alist)))
+	  ;; Previously :html-container took a string as an argument.
+	  ((and (stringp container-alist) (= 1 level))
+	   (plist-get info :html-container))
+	  (t "div"))))
 
 ;;;; Horizontal Rule
 
-- 
1.9.0

Re: [patch][ox-html] Support for level based containers

[Bastien]

Hi Rasmus and Nicolas,

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

>> Let me know if you find you'd be willing to merge something like this
>
> I don't know enough HTML to have an opinion here.

Well, Rick is our HTML expert, let's ping him for such decisions.

-- 
 Bastien

Re: [patch][ox-html] Support for level based containers

[Rick Frankel]

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

On Mon, Mar 17, 2014 at 03:15:50AM +0100, Bastien wrote:
> Hi Rasmus and Nicolas,
>
> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>
> >> Let me know if you find you'd be willing to merge something like this
> >
> > I don't know enough HTML to have an opinion here.
>

I don't think it's a bad change, but i have a couple of concerns:

    1. It's a breaking change.
    2. The default should mimic the current functionality:
       ='((div . div))=
    3. The customization should be more structured, not just a
       string (see e.g., =org-html-text-markup-alist=.)

Attached is a modification of the patch which fixes 2 & 3. #1 is a
question more for Nicolas & Bastien...

rick

[-- Attachment #2: 0001-Support-for-heading-level-based-containers-in-ox-htm.patch --]
[-- Type: text/plain, Size: 2299 bytes --]

From 21aed5d34613f9f922c2d1c8f5f67caac918c9cf Mon Sep 17 00:00:00 2001
From: Rick Frankel <github@rickster.com>
Date: Mon, 17 Mar 2014 13:27:12 -0400
Subject: [PATCH] Support for heading level based containers in ox-html.

* ox-html.el (org-html-container-element): Change to list of cons
cells for heading level containers.
(org-html--container): Use heading level entries from
org-html-container-element.
---
 lisp/ox-html.el | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index cb95161..b51a746 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -938,17 +938,23 @@ versions 8 and below."
   :package-version '(Org . "8.0")
   :type 'boolean)
 
-(defcustom org-html-container-element "div"
-  "HTML element to use for wrapping top level sections.
+(defcustom org-html-container-element '(("div" . "div"))
+
+  "HTML elements to use for wrapping sections.
 Can be set with the in-buffer HTML_CONTAINER property or for
 publishing, with :html-container.
 
-Note that changing the default will prevent you from using
-org-info.js for your website."
+Should be a list of cons cells with positions corresponding to
+heading levels.  If `org-html-html5-fancy' is t the cdr is used
+otherwise the car.
+
+Note that changing the default will prevent you from
+using org-info.js for your website."
   :group 'org-export-html
   :version "24.4"
   :package-version '(Org . "8.0")
-  :type 'string)
+  :type '(alist :key-type (string :tag "HTML4")
+		:value-type (string :tag "HTML5")))
 
 (defcustom org-html-divs
   '((preamble  "div" "preamble")
@@ -2410,9 +2416,14 @@ holding contextual information."
 
 (defun org-html--container (headline info)
   (or (org-element-property :HTML_CONTAINER headline)
-      (if (= 1 (org-export-get-relative-level headline info))
-	  (plist-get info :html-container)
-	"div")))
+      (let* ((hc (plist-get info :html-container))
+	     (n (org-export-get-relative-level headline info)))
+	(cond ((listp hc)
+	       (or (funcall (if org-html-html5-fancy 'cdr-safe 'car-safe)
+			    (nth (1- (min n (length hc))) hc)) "div"))
+	      ((and (stringp hc) (= 1 n))
+	       (plist-get info :html-container))
+	      (t "div")))))
 
 ;;;; Horizontal Rule
 
-- 
1.8.5.2 (Apple Git-48)

Re: [patch][ox-html] Support for level based containers

[Rasmus]

Rick Frankel <rick@rickster.com> writes:

> On Mon, Mar 17, 2014 at 03:15:50AM +0100, Bastien wrote:
>> Hi Rasmus and Nicolas,
>>
>
>> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>>
>> >> Let me know if you find you'd be willing to merge something like this
>> >
>> > I don't know enough HTML to have an opinion here.
>>
>
> I don't think it's a bad change, but i have a couple of concerns:
>
>     1. It's a breaking change.
>     2. The default should mimic the current functionality:
>        ='((div . div))=
>     3. The customization should be more structured, not just a
>        string (see e.g., =org-html-text-markup-alist=.)
>
> Attached is a modification of the patch which fixes 2 & 3. #1 is a
> question more for Nicolas & Bastien...

It seems you modified v1 rather than v2 that I send last night¹?  I'm
not sure if point 1 holds in the second revision as it explicitly
allows for a string as now. I think I disagree with your point 2 as it
only shows up when you use HTML5-fancy.  On point 3,
org-html-text-markup-alist is nice.  What do you want to see in
addition to the current structure (in patch v2)?

—Rasmus

Footnotes: 
¹   http://permalink.gmane.org/gmane.emacs.orgmode/83635

-- 
Sådan en god dansk lagereddike kan man slet ikke bruge mere

Re: [patch][ox-html] Support for level based containers

[Rick Frankel]

On Mon, Mar 17, 2014 at 11:26:28PM +0100, Rasmus wrote:
> Rick Frankel <rick@rickster.com> writes:
>
> > On Mon, Mar 17, 2014 at 03:15:50AM +0100, Bastien wrote:
> >> Hi Rasmus and Nicolas,
> >>
> >
> >> Nicolas Goaziou <n.goaziou@gmail.com> writes:
> >>
> >> >> Let me know if you find you'd be willing to merge something like this
> >> >
> >> > I don't know enough HTML to have an opinion here.
> >>
> >
> > I don't think it's a bad change, but i have a couple of concerns:
> >
> >     1. It's a breaking change.
> >     2. The default should mimic the current functionality:
> >        ='((div . div))=
> >     3. The customization should be more structured, not just a
> >        string (see e.g., =org-html-text-markup-alist=.)
> >
> > Attached is a modification of the patch which fixes 2 & 3. #1 is a
> > question more for Nicolas & Bastien...
>
> It seems you modified v1 rather than v2 that I send last night¹?  I'm
> not sure if point 1 holds in the second revision as it explicitly
> allows for a string as now. I think I disagree with your point 2 as it
> only shows up when you use HTML5-fancy.  On point 3,

But not everyone using html5-fancy would agree with your choice of
hierarchy, and it should be up to indvidual users to add additional
semantic structure to the output.

> org-html-text-markup-alist is nice.  What do you want to see in
> addition to the current structure (in patch v2)?

Somehow I never saw the original thread, only the email cc'ing me
directly. I went to gmane to find the patch, and obviously grabbed the
wrong one.

Could you please send me the (new) patch so that i can review it?

thanx,
rick

Re: [patch][ox-html] Support for level based containers

[Rasmus]

Rick Frankel <rick@rickster.com> writes:

> On Mon, Mar 17, 2014 at 11:26:28PM +0100, Rasmus wrote:
>> Rick Frankel <rick@rickster.com> writes:
>>
>
>> > On Mon, Mar 17, 2014 at 03:15:50AM +0100, Bastien wrote:
>> >> Hi Rasmus and Nicolas,
>> >>
>> >
>> >> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>> >>
>> >> >> Let me know if you find you'd be willing to merge something like this
>> >> >
>> >> > I don't know enough HTML to have an opinion here.
>> >>
>> >
>> > I don't think it's a bad change, but i have a couple of concerns:
>> >
>> >     1. It's a breaking change.
>> >     2. The default should mimic the current functionality:
>> >        ='((div . div))=
>> >     3. The customization should be more structured, not just a
>> >        string (see e.g., =org-html-text-markup-alist=.)
>> >
>> > Attached is a modification of the patch which fixes 2 & 3. #1 is a
>> > question more for Nicolas & Bastien...
>>
>> It seems you modified v1 rather than v2 that I send last night¹?  I'm
>> not sure if point 1 holds in the second revision as it explicitly
>> allows for a string as now. I think I disagree with your point 2 as it
>> only shows up when you use HTML5-fancy.  On point 3,
>
> But not everyone using html5-fancy would agree with your choice of
> hierarchy, and it should be up to indvidual users to add additional
> semantic structure to the output.

It's a variable that you can set in your project or in your Org file
or in your init file.  I don't see why div × 3 is better than section
article div or something else conditional on two variables being
explicitly set to get fancy HTML5. . .  In any case, I don't have
strong—if any—preferences on this.

>> org-html-text-markup-alist is nice.  What do you want to see in
>> addition to the current structure (in patch v2)?
>
> Somehow I never saw the original thread, only the email cc'ing me
> directly. I went to gmane to find the patch, and obviously grabbed the
> wrong one.
>
> Could you please send me the (new) patch so that i can review it?

Here's the Gmane link.  I believe it's different than what you
reviewed before, but perhaps I'm wrong. . .

>> Footnotes: 
>> ¹   http://permalink.gmane.org/gmane.emacs.orgmode/83635

—Rasmus

-- 
ツ

Re: [patch][ox-html] Support for level based containers

[Rick Frankel]

On 2014-03-17 23:31, Rasmus wrote:
> It's a variable that you can set in your project or in your Org file
> or in your init file.  I don't see why div × 3 is better than section
> article div or something else conditional on two variables being
> explicitly set to get fancy HTML5. . .  In any case, I don't have
> strong—if any—preferences on this.

Because using these tags is assigning semantic meaning which may or
may not be valid for the current document. Based on the spec, your use
of =section= seems ok (but could also be used for the other levels),
but your use of =article= is probably wrong in most cases. From
http://www.w3.org/html/wg/drafts/html/master/sections.html#the-article-element:

The article element represents a complete, or self-contained,
composition in a document, page, application, or site and that is,
in principle, independently distributable or reusable, e.g. in
syndication. This could be a forum post, a magazine or newspaper
article, a blog entry, a user-submitted comment, an interactive
widget or gadget, or any other independent item of content.

As to the =section= element, the from the above doc:

The section element represents a generic section of a document or
application. A section, in this context, is a thematic grouping of
content. The theme of each section should be identified, typically
by including a heading (h1-h6 element) as a child of the section
element.

and

A general rule is that the section element is appropriate only if
the element's contents would be listed explicitly in the
document's outline.

So, using this definition, in html5, the wrappers should be =sections=
to the same level as the toc heading level specified for the document,
and =divs= after.[1]

> org-html-text-markup-alist is nice.  What do you want to see in
> addition to the current structure (in patch v2)?
> 
> Somehow I never saw the original thread, only the email cc'ing me
> directly. I went to gmane to find the patch, and obviously grabbed the
> wrong one.
> 
> Could you please send me the (new) patch so that i can review it?
> 
> Here's the Gmane link.  I believe it's different than what you
> reviewed before, but perhaps I'm wrong. . .

No, i got the wrong patch from gmane. This one looks better modulo:

1. The default should stay the same as it is now -- the string "div"
2. Minor typo, but "backward comparability" should be "backwards
compatibility".

But, after reviewing the spec (see above vis. =section= and
=article=), i would submit that a better patch would be to
implement [1] above -- remove the defcustom (i only added to support
using a different default wrapper element in html5), and use =section=
and =div= based on toc level when html5-fancy is true. As far as i can
tell from the spec, =article= would almost never be correct for the
average org doc. Here's a relevant quote from the spec:

Authors are encouraged to use the article element instead of the
section element when it would make sense to syndicate the contents
of the element.

I think the best way to implement this would be letting the user
specify it with the =HTML_CONTAINER= property already implemented. As
this seems very much in keeping with the spec, i will implement this
change when i have some time in the next couple of weeks if i don't
hear any strong arguments against.

As an aside, the complex semantics of the new html5 tags is why we
have been slow in implementing them in ox-html. =div= is by
definition a non-semantic tag meant to be used for grouping and
styling, but the new tags have very specific meanings associated with
them and their mis-use is worse than their non-use.

rick

Re: [patch][ox-html] Support for level based containers

[Rasmus]

Rick,

Rick Frankel <rick@rickster.com> writes:

> On 2014-03-17 23:31, Rasmus wrote:
>> It's a variable that you can set in your project or in your Org file
>> or in your init file.  I don't see why div × 3 is better than section
>> article div or something else conditional on two variables being
>> explicitly set to get fancy HTML5. . .  In any case, I don't have
>> strong—if any—preferences on this.
>
> Because using these tags is assigning semantic meaning which may or
> may not be valid for the current document. Based on the spec, your use
> of =section= seems ok (but could also be used for the other levels),
> but your use of =article= is probably wrong in most cases. From
> http://www.w3.org/html/wg/drafts/html/master/sections.html#the-article-element:
>
> The article element represents a complete, or self-contained,
> composition in a document, page, application, or site and that is,
> in principle, independently distributable or reusable, e.g. in
> syndication. This could be a forum post, a magazine or newspaper
> article, a blog entry, a user-submitted comment, an interactive
> widget or gadget, or any other independent item of content.

OK.  Thanks for your through clarification.  

> As to the =section= element, the from the above doc:
>
> The section element represents a generic section of a document or
> application. A section, in this context, is a thematic grouping of
> content. The theme of each section should be identified, typically
> by including a heading (h1-h6 element) as a child of the section
> element.

This happens with the patch (as is does with divs ATM).

> and
>
> A general rule is that the section element is appropriate only if
> the element's contents would be listed explicitly in the
> document's outline.
>
> So, using this definition, in html5, the wrappers should be =sections=
> to the same level as the toc heading level specified for the document,
> and =divs= after.[1]

So you want it to be section until h:N?  That should be easy.

>> org-html-text-markup-alist is nice.  What do you want to see in
>> addition to the current structure (in patch v2)?
>>
>> Somehow I never saw the original thread, only the email cc'ing me
>> directly. I went to gmane to find the patch, and obviously grabbed the
>> wrong one.
>>
>> Could you please send me the (new) patch so that i can review it?
>>
>> Here's the Gmane link.  I believe it's different than what you
>> reviewed before, but perhaps I'm wrong. . .
>
> No, i got the wrong patch from gmane. This one looks better modulo:
>
> 1. The default should stay the same as it is now -- the string "div"

As you prefer.

> 2. Minor typo, but "backward comparability" should be "backwards
> compatibility".

Thanks.

> But, after reviewing the spec (see above vis. =section= and
> =article=), i would submit that a better patch would be to
> implement [1] above -- remove the defcustom (i only added to support
> using a different default wrapper element in html5), and use =section=
> and =div= based on toc level when html5-fancy is true. As far as i can
> tell from the spec, =article= would almost never be correct for the
> average org doc. Here's a relevant quote from the spec:

OK.  That certainly makes it easier.  But should it not then be a cons
or an alist specifying which container to use when the headline level
is above or below h:N and deepening on whether html5-fancy is used?


> Authors are encouraged to use the article element instead of the
> section element when it would make sense to syndicate the contents
> of the element.

So blogs, technical docs and similar?  I can see people using Org such
things?  Or do W3-people thinkg of something different when they say
it is "syndicatable"

> I think the best way to implement this would be letting the user
> specify it with the =HTML_CONTAINER= property already implemented. As
> this seems very much in keeping with the spec, i will implement this
> change when i have some time in the next couple of weeks if i don't
> hear any strong arguments against.

I can change my patch to this behavior if you want.  Though I think
it's pretty strong to hardcode values, as one would might have reasons
to change it in say an ox-publish project.

> As an aside, the complex semantics of the new html5 tags is why we
> have been slow in implementing them in ox-html. =div= is by
> definition a non-semantic tag meant to be used for grouping and
> styling, but the new tags have very specific meanings associated with
> them and their mis-use is worse than their non-use.

Good point.

Thanks again Rick.

—Rasmus

-- 
Governments should be afraid of their people

Re: [patch][ox-html] Support for level based containers

[Rick Frankel]

On 2014-03-18 15:41, Rasmus wrote:
> Rick Frankel <rick@rickster.com> writes:
> On 2014-03-17 23:31, Rasmus wrote:

> A general rule is that the section element is appropriate only if
> the element's contents would be listed explicitly in the
> document's outline.

> So, using this definition, in html5, the wrappers should be =sections=
> to the same level as the toc heading level specified for the document,
> and =divs= after.[1]
> 
> So you want it to be section until h:N?  That should be easy.
> 
> 1. The default should stay the same as it is now -- the string "div"
> 
> As you prefer.
> 
> But, after reviewing the spec (see above vis. =section= and
> =article=), i would submit that a better patch would be to
> implement [1] above -- remove the defcustom (i only added to support
> using a different default wrapper element in html5), and use =section=
> and =div= based on toc level when html5-fancy is true. As far as i can
> tell from the spec, =article= would almost never be correct for the
> average org doc. Here's a relevant quote from the spec:
> 
> OK.  That certainly makes it easier.  But should it not then be a cons
> or an alist specifying which container to use when the headline level
> is above or below h:N and deepening on whether html5-fancy is used?

Not really necessary. It's overly complex with no obvious advantage. I
guess the right question to ask is (it may have been mentioned much
earlier in the thread) -- what problem does the patch solve?
> 
> Authors are encouraged to use the article element instead of the
> section element when it would make sense to syndicate the contents
> of the element.
> 
> So blogs, technical docs and similar?  I can see people using Org such
> things?  Or do W3-people thinkg of something different when they say
> it is "syndicatable"

Yes, a a blog is the prototypical example -- but only the index page,
where multiple articles are concatenated into a single page.

Most likely, an org document implementing this would have the
=article=s (indvidual blog posts) at level 1, and sections below.

In the most common use, the  =article= would probably be the outer
wrapper around the entire body section of the output, and would be set
as the "content" wrapper in =org-html-divs=. BTW, the html5 version of
=org-html-divs= would be:

#+BEGIN_SRC emacs-lisp
'((preamble  "header" "preamble")
(content   "article" "content")
(postamble "footer" "postamble"))
#+END_SRC

> I think the best way to implement this would be letting the user
> specify it with the =HTML_CONTAINER= property already implemented. As
> this seems very much in keeping with the spec, i will implement this
> change when i have some time in the next couple of weeks if i don't
> hear any strong arguments against.
> 
> I can change my patch to this behavior if you want.  Though I think
> it's pretty strong to hardcode values, as one would might have reasons
> to change it in say an ox-publish project.

Using =PROPERTIES= on org heading is not really hardcoding. It's the
"org-way" of associating things with document sections/headings.

To recap, I don't really see a compelling reason to specify a
hierarchy of wrappers specific to html5-fancy output. After reviewing
the spec, i do see the value in wrapping org document sections in
=section= tags per the rules in [1] above (from previous email).

rick