* [patch][ox-html] Support for level based containers @ 2014-03-15 23:18 Rasmus 2014-03-16 13:10 ` Nicolas Goaziou 0 siblings, 1 reply; 11+ messages in thread From: Rasmus @ 2014-03-15 23:18 UTC (permalink / raw) To: emacs-orgmode [-- 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 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-15 23:18 [patch][ox-html] Support for level based containers Rasmus @ 2014-03-16 13:10 ` Nicolas Goaziou 2014-03-17 0:30 ` Rasmus 2014-03-17 2:15 ` Bastien 0 siblings, 2 replies; 11+ messages in thread From: Nicolas Goaziou @ 2014-03-16 13:10 UTC (permalink / raw) To: Rasmus; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-16 13:10 ` Nicolas Goaziou @ 2014-03-17 0:30 ` Rasmus 2014-03-17 2:15 ` Bastien 1 sibling, 0 replies; 11+ messages in thread From: Rasmus @ 2014-03-17 0:30 UTC (permalink / raw) To: n.goaziou; +Cc: emacs-orgmode [-- 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 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-16 13:10 ` Nicolas Goaziou 2014-03-17 0:30 ` Rasmus @ 2014-03-17 2:15 ` Bastien 2014-03-17 17:31 ` Rick Frankel 1 sibling, 1 reply; 11+ messages in thread From: Bastien @ 2014-03-17 2:15 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: Rick Frankel, emacs-orgmode, Rasmus 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-17 2:15 ` Bastien @ 2014-03-17 17:31 ` Rick Frankel 2014-03-17 22:26 ` Rasmus 0 siblings, 1 reply; 11+ messages in thread From: Rick Frankel @ 2014-03-17 17:31 UTC (permalink / raw) To: Bastien; +Cc: emacs-orgmode, Nicolas Goaziou, Rasmus [-- 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) ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-17 17:31 ` Rick Frankel @ 2014-03-17 22:26 ` Rasmus 2014-03-18 0:33 ` Rick Frankel 0 siblings, 1 reply; 11+ messages in thread From: Rasmus @ 2014-03-17 22:26 UTC (permalink / raw) To: bzg; +Cc: emacs-orgmode, n.goaziou 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-17 22:26 ` Rasmus @ 2014-03-18 0:33 ` Rick Frankel 2014-03-18 3:31 ` Rasmus 0 siblings, 1 reply; 11+ messages in thread From: Rick Frankel @ 2014-03-18 0:33 UTC (permalink / raw) To: Rasmus; +Cc: bzg, n.goaziou, emacs-orgmode 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-18 0:33 ` Rick Frankel @ 2014-03-18 3:31 ` Rasmus 2014-03-18 15:05 ` Rick Frankel 0 siblings, 1 reply; 11+ messages in thread From: Rasmus @ 2014-03-18 3:31 UTC (permalink / raw) To: emacs-orgmode 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 -- ツ ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-18 3:31 ` Rasmus @ 2014-03-18 15:05 ` Rick Frankel 2014-03-18 19:41 ` Rasmus 0 siblings, 1 reply; 11+ messages in thread From: Rick Frankel @ 2014-03-18 15:05 UTC (permalink / raw) To: Rasmus; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-18 15:05 ` Rick Frankel @ 2014-03-18 19:41 ` Rasmus 2014-03-19 14:24 ` Rick Frankel 0 siblings, 1 reply; 11+ messages in thread From: Rasmus @ 2014-03-18 19:41 UTC (permalink / raw) To: rick; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [patch][ox-html] Support for level based containers 2014-03-18 19:41 ` Rasmus @ 2014-03-19 14:24 ` Rick Frankel 0 siblings, 0 replies; 11+ messages in thread From: Rick Frankel @ 2014-03-19 14:24 UTC (permalink / raw) To: Rasmus; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2014-03-19 14:24 UTC | newest] Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2014-03-15 23:18 [patch][ox-html] Support for level based containers Rasmus 2014-03-16 13:10 ` Nicolas Goaziou 2014-03-17 0:30 ` Rasmus 2014-03-17 2:15 ` Bastien 2014-03-17 17:31 ` Rick Frankel 2014-03-17 22:26 ` Rasmus 2014-03-18 0:33 ` Rick Frankel 2014-03-18 3:31 ` Rasmus 2014-03-18 15:05 ` Rick Frankel 2014-03-18 19:41 ` Rasmus 2014-03-19 14:24 ` Rick Frankel
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).