From: Eric Abrahamsen <eric@ericabrahamsen.net>
To: emacs-orgmode@gnu.org
Subject: Re: [PATCH] export to various flavors of (X)HTML
Date: Sun, 28 Apr 2013 23:02:22 -0700 [thread overview]
Message-ID: <87bo8xeuxd.fsf@ericabrahamsen.net> (raw)
In-Reply-To: 20130426184949.GB79236@BigDog.local
[-- Attachment #1: Type: text/plain, Size: 2978 bytes --]
Rick Frankel <rick@rickster.com> writes:
> On Fri, Apr 26, 2013 at 10:14:17AM -0700, Eric Abrahamsen wrote:
>> Rick Frankel <rick@rickster.com> writes:
>> >
>> > Therefore, `org-html-close-tag' should check that the doctype is not a
>> > flavor of html4 rather than a flavor of xhtml. An alternative would be
>> > to add ("xhtml5" . "<!DOCTYPE html>") to the doctype alist, and the
>> > appropriate testing for being html5 and xhtml.
>> >
>> > See the discussions of polyglot markup @
>> > http://en.wikipedia.org/wiki/Polyglot_markup
>> > and
>> > http://www.w3.org/TR/2011/WD-html-polyglot-20110405/#dfn-polyglot-markup
>> > for the rationale.
>>
>> Ah, those were interesting links, I hadn't considered those issues.
>> Luckily, your second option was a three-line change to the existing
>> patch: using "xhtml5" now produces the same output as "html5", except
>> that self-closing tags are self-closed, and there's a xmlns declaration
>> in the <html> element. Best of all worlds, I hope.
>
> Brilliant! I will apply the patch and try it later this weekend...
So here's the fun part -- using the new bits of HTML5. The attached
patch builds on the last one (and corrects a couple of documentation
formatting errors), and touches on the following:
1. There's a new export option, org-html-html5-fancy/HTML_HTML5_FANCY,
which defaults to 'nil, making most of the following opt-in only.
2. The meat of the change is in `org-html-special-block'. If it comes
across a special block #+BEGIN_FOO where "foo" is a member of
`org-html-html5-elements', it will format it as "<foo>" rather than
"<div class="foo">". So #+BEGIN_ASIDE will create an "<aside>" element.
Attributes are now parsed (this change applies to all HTML flavors), so
this:
#+ATTR_HTML :controls controls :width 350
#+BEGIN_VIDEO
#+HTML: <source src="movie.mp4" type="video/mp4">
#+END_VIDEO
becomes:
<video controls="controls" width="350">
<source src="movie.mp4" type="video/mp4">
</video>
3. Standalone images are formatted as <figure> with <figcaption>.
4. Things like timestamps could be expressed as <time> elements, but I
haven't done that here. The relevant attributes still seem to be up in
the air, and it would be complicated.
5. It's generally accepted that one should use some variety of the
html5shiv[1] to make IE <9 render new HTML5 elements correctly. I've
dropped a note to this effect in the docstring of
`org-html-html5-fancy', but I suppose it's possible we could take a more
interventionist stance, perhaps including hosting a version of the shiv
on orgmode.org, and linking to it automatically. I guess I'm in favor of
leaving it to the user, though.
Tangential coding question: I've noticed that setting HTML_HTML5_FANCY
to nil at the top of the export file results in `(plist-get info
:html-html5-fancy)' returning the string "nil", ie true. Not right,
obviously, and it makes it impossible to set it to 'nil per-file if the
global value is 't. Am I handling this wrong?
E
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0010-ox-html.el-Give-access-to-new-elements-in-HTML5.patch --]
[-- Type: text/x-patch, Size: 7987 bytes --]
From 636720ca8444a4767a44170b6ed29cf471f1aee7 Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
Date: Sun, 28 Apr 2013 23:00:26 -0700
Subject: [PATCH 10/10] ox-html.el: Give access to new elements in HTML5
* lisp/ox-html.el (org-html-html5-fancy): New variable, determining whether
or not to use new elements.
(org-html-html5-elements): New variable, new HTML5 elements.
(org-html-special-block): Export special blocks to new HTML5 elements.
(org-html-format-inline-image): Use <figure> and <figcaption> for
standalone images.
* doc/org.texi: Document the above.
---
doc/org.texi | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++-----
lisp/ox-html.el | 61 ++++++++++++++++++++++++++++++++++++++++++++++++------
2 files changed, 114 insertions(+), 11 deletions(-)
diff --git a/doc/org.texi b/doc/org.texi
index 40f5216..ad438f4 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -11007,11 +11007,11 @@ Export to a temporary buffer. Do not create a file.
Org can export to various (X)HTML flavors.
-Setting the variable @var{org-html-doctype} allows you to export to different
-(X)HTML variants. The exported HTML will be adjusted according to the sytax
-requirements of that variant. You can either set this variable to a doctype
+Setting the variable @code{org-html-doctype} allows you to export to different
+(X)HTML variants. The exported HTML will be adjusted according to the sytax
+requirements of that variant. You can either set this variable to a doctype
string directly, in which case the exporter will try to adjust the syntax
-automatically, or you can use a ready-made doctype. The ready-made options
+automatically, or you can use a ready-made doctype. The ready-made options
are:
@itemize
@@ -11035,7 +11035,61 @@ are:
``xhtml5''
@end itemize
-See the variable @var{org-html-doctype-alist} for details. The default is ``xhtml-strict''.
+See the variable @code{org-html-doctype-alist} for details. The default is
+``xhtml-strict''.
+
+@subsubheading Fancy HTML5 export
+@vindex org-html-html5-fancy
+@vindex org-html-html5-elements
+
+HTML5 introduces several new element types. By default, Org will not make
+use of these element types, but you can set @code{org-html-html5-fancy} to
+@code{t} (or use the corresponding @code{HTML_HTML5_FANCY} export option), to
+enable a few new block-level elements. These are created using arbitrary
+#+BEGIN and #+END blocks. For instance:
+
+@example
+#+BEGIN_ASIDE
+Lorem ipsum
+#+END_ASIDE
+@end example
+
+Will export to:
+
+@example
+<aside>
+ <p>Lorem ipsum</p>
+</aside>
+@end example
+
+While this:
+
+@example
+#+ATTR_HTML: :controls controls :width 350
+#+BEGIN_VIDEO
+#+HTML: <source src="movie.mp4" type="video/mp4">
+#+HTML: <source src="movie.ogg" type="video/ogg">
+Your browser does not support the video tag.
+#+END_VIDEO
+@end example
+
+Becomes:
+
+@example
+<video controls="controls" width="350">
+ <source src="movie.mp4" type="video/mp4">
+ <source src="movie.ogg" type="video/ogg">
+ <p>Your browser does not support the video tag.</p>
+</video>
+@end example
+
+Special blocks that do not correspond to HTML5 elements (see
+@code{org-html-html5-elements}) will revert to the usual behavior,
+i.e. #+BEGIN_LEDERHOSEN will still export to <div class=''lederhosen''>.
+
+Headlines cannot appear within special blocks. To wrap a headline and its
+contents in e.g. <section> or <article> tags, set the @code{HTML_CONTAINER}
+property on the headline itself.
@node HTML preamble and postamble, Quoting HTML tags, HTML doctypes, HTML export
@subsection HTML preamble and postamble
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 8223a18..e7cae1a 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -116,6 +116,7 @@
(:html-link-org-as-html nil nil org-html-link-org-files-as-html)
(:html-doctype "HTML_DOCTYPE" nil org-html-doctype)
(:html-container "HTML_CONTAINER" nil org-html-container-element)
+ (:html-html5-fancy "HTML_HTML5_FANCY" nil org-html-html5-fancy)
(:html-link-home "HTML_LINK_HOME" nil org-html-link-home)
(:html-link-up "HTML_LINK_UP" nil org-html-link-up)
(:html-mathjax "HTML_MATHJAX" nil "" space)
@@ -164,6 +165,17 @@
("xhtml5" . "<!DOCTYPE html>"))
"An alist mapping (x)html flavors to specific doctypes.")
+(defconst org-html-html5-elements
+ '("article" "aside" "audio" "canvas" "details" "figcaption"
+ "figure" "footer" "header" "menu" "meter" "nav" "output"
+ "progress" "section" "video")
+ "New elements in html5.
+
+<hgroup> is not included because it's currently impossible to
+wrap special blocks around multiple headlines. For other blocks
+that should contain headlines, use the HTML_CONTAINER property on
+the headline itself.")
+
(defconst org-html-special-string-regexps
'(("\\\\-" . "­") ; shy
("---\\([^-]\\)" . "—\\1") ; mdash
@@ -906,6 +918,21 @@ publishing, with :html-doctype."
:package-version '(Org . "8.0")
:type 'string)
+(defcustom org-html-html5-fancy nil
+ "When exporting to HTML5, set this to t to use new HTML5
+ elements. This variable is ignored for anything other than
+ HTML5.
+
+For compatibility with Internet Explorer, it's probably a good
+idea to download some form of the html5shiv (for instance
+https://code.google.com/p/html5shiv/) and add it to your
+HTML_HEAD_EXTRA, so that your pages don't break for users of IE
+versions 8 and below."
+ :group 'org-export-html
+ :version "24.4"
+ :package-version '(Org . "8.0")
+ :type 'boolean)
+
(defcustom org-html-container-element "div"
"HTML element to use for wrapping top level sections.
Can be set with the in-buffer HTML_CONTAINER property or for
@@ -1308,14 +1335,20 @@ When STANDALONE-P is t, wrap the <img.../> into a <div>...</div>."
(org-find-text-property-in-string
'org-latex-src src))))
(t (format " alt=\"%s\""
- (file-name-nondirectory src)))))))
+ (file-name-nondirectory src))))))
+ (html5-fancy (and (org-html-html5-p info)
+ (plist-get info :html-html5-fancy))))
(cond
(standalone-p
(let ((img (org-html-close-tag "img" attr info)))
- (format "\n<div%s class=\"figure\">%s%s\n</div>"
+ (format (if html5-fancy
+ "\n<figure%s>%s%s\n</figure>"
+ "\n<div%s class=\"figure\">%s%s\n</div>")
id (format "\n<p>%s</p>" img)
(if (and caption (not (string= caption "")))
- (format "\n<p>%s</p>" caption) ""))))
+ (format (if html5-fancy
+ "\n<figcaption>%s</figcaption>"
+ "\n<p>%s</p>") caption) ""))))
(t (org-html-close-tag "img" (concat attr id) info)))))
(defun org-html--textarea-block (element)
@@ -2927,9 +2960,25 @@ contextual information."
"Transcode a SPECIAL-BLOCK element from Org to HTML.
CONTENTS holds the contents of the block. INFO is a plist
holding contextual information."
- (format "<div class=\"%s\">\n%s\n</div>"
- (downcase (org-element-property :type special-block))
- contents))
+ (let* ((block-type (downcase
+ (org-element-property :type special-block)))
+ (contents (or contents ""))
+ (html5-fancy (and (org-html-html5-p info)
+ (plist-get info :html-html5-fancy)
+ (member block-type org-html-html5-elements)))
+ (attributes (org-export-read-attribute :attr_html special-block)))
+ (unless html5-fancy
+ (let ((class (plist-get attributes :class)))
+ (setq attributes (plist-put attributes :class
+ (if class (concat class " " block-type)
+ block-type)))))
+ (setq attributes (org-html--make-attribute-string attributes))
+ (when (not (equal attributes ""))
+ (setq attributes (concat " " attributes)))
+ (if html5-fancy
+ (format "<%s%s>\n%s</%s>" block-type attributes
+ contents block-type)
+ (format "<div%s>\n%s\n</div>" attributes contents))))
;;;; Src Block
--
1.8.2.2
[-- Attachment #3: Type: text/plain, Size: 45 bytes --]
[1]: https://code.google.com/p/html5shiv/
next prev parent reply other threads:[~2013-04-29 5:56 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-04-19 9:57 [PATCH] export to various flavors of (X)HTML Eric Abrahamsen
2013-04-19 15:37 ` Rick Frankel
2013-04-20 2:59 ` Eric Abrahamsen
2013-04-23 1:00 ` Rick Frankel
2013-04-23 4:30 ` Eric Abrahamsen
2013-04-23 4:57 ` Samuel Wales
2013-04-23 6:55 ` Carsten Dominik
2013-04-23 7:54 ` Eric Abrahamsen
2013-04-23 12:09 ` François Pinard
2013-04-24 1:17 ` Christian Wittern
2013-04-24 13:10 ` François Pinard
2013-04-25 21:20 ` Eric Abrahamsen
2013-04-26 13:49 ` Rick Frankel
2013-04-26 17:14 ` Eric Abrahamsen
2013-04-26 18:49 ` Rick Frankel
2013-04-29 6:02 ` Eric Abrahamsen [this message]
2013-04-29 7:45 ` Nicolas Goaziou
2013-04-30 14:38 ` Rick Frankel
2013-04-30 14:40 ` Rick Frankel
2013-05-01 3:26 ` Eric Abrahamsen
2013-05-01 11:55 ` Rick Frankel
2013-05-02 21:07 ` Eric Abrahamsen
2013-05-03 7:17 ` Carsten Dominik
2013-05-06 5:49 ` Carsten Dominik
2013-05-06 7:36 ` Eric Abrahamsen
2013-05-06 7:48 ` Carsten Dominik
2013-05-06 9:05 ` Eric Abrahamsen
2013-05-06 12:56 ` Rick Frankel
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87bo8xeuxd.fsf@ericabrahamsen.net \
--to=eric@ericabrahamsen.net \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).