emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [PATCH] Simplifying the handling of HTML preamble/postamble
@ 2011-02-10 13:01 Bastien
  2011-02-10 15:04 ` Manuel Giraud
  0 siblings, 1 reply; 6+ messages in thread
From: Bastien @ 2011-02-10 13:01 UTC (permalink / raw)
  To: emacs-orgmode

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

Here is a patch against latest git Org that tries to simplify the
handling of HTML preamble/postamble: I find the interaction between
:preamble and :auto-preamble a bit confusing and a recent questions by
Jeff on customizing org-export-html-preamble raised this issue.

So here is what I suggest:

- `org-export-html-preamble' is a custom variable to tell whether a HTML
  preamble should be included or not;

- `org-export-html-preamble-format' is a format string controlling what
  is included in the preamble;

- In publishing project, everything is done from :html-preamble:

  + when `t', inserts a preamble with the default formatting
  + when an alist, insert a preamble with this alist formatting
  + when nil, no preamble is inserted.

  (Same for postamble).

This also let people use their own HTML classes, language-based
preamble/postamble, etc.

Would people welcome such a simplification?

Thanks!


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Rewrite-the-handling-of-HTML-preamble-postamble.patch --]
[-- Type: text/x-patch, Size: 11560 bytes --]

From 823130bde38a5fb644292f4fa98b29f418c36262 Mon Sep 17 00:00:00 2001
From: Bastien Guerry <bzg@altern.org>
Date: Thu, 10 Feb 2011 13:19:37 +0100
Subject: [PATCH] Rewrite the handling of HTML preamble/postamble.

* org-html.el (org-export-html-auto-preamble)
(org-export-html-auto-postamble): Remove.
(org-export-html-preamble, org-export-html-postamble): Turn
into custom variables.  Update the docstrings.
(org-export-html-preamble-format)
(org-export-html-postamble-format): New custom variables.
(org-export-as-html): Use org-export-html-postamble-format and
org-export-html-preamble-format.
(org-export-html-title-format): delete.

* org-exp.el (org-export-plist-vars): Remove
:auto-preamble and :auto-postamble.  Rename :preamble and
:postamble to :html-preamble and :html-postamble.

* org-publish.el (org-publish-project-alist): Remove
:auto-preamble and :auto-postamble.  Rename :preamble and
:postamble to :html-preamble and :html-postamble.

* org.texi (Publishing options): replace :preamble and
:auto-preamble by :html-preamble (same for postamble.)
---
 doc/org.texi        |   11 +---
 lisp/org-exp.el     |    6 +--
 lisp/org-html.el    |  137 ++++++++++++++++++++++++++++++--------------------
 lisp/org-publish.el |    6 +--
 4 files changed, 89 insertions(+), 71 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 8838295..a029e4b 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10837,8 +10837,6 @@ respective variable for details.
 @vindex org-export-publishing-directory
 @vindex org-export-html-preamble
 @vindex org-export-html-postamble
-@vindex org-export-html-auto-preamble
-@vindex org-export-html-auto-postamble
 @vindex user-full-name
 @vindex user-mail-address
 @vindex org-export-select-tags
@@ -10886,10 +10884,8 @@ respective variable for details.
 @item @code{:expand-quoted-html}    @tab @code{org-export-html-expand}
 @item @code{:timestamp}             @tab @code{org-export-html-with-timestamp}
 @item @code{:publishing-directory}  @tab @code{org-export-publishing-directory}
-@item @code{:preamble}              @tab @code{org-export-html-preamble}
-@item @code{:postamble}             @tab @code{org-export-html-postamble}
-@item @code{:auto-preamble}         @tab @code{org-export-html-auto-preamble}
-@item @code{:auto-postamble}        @tab @code{org-export-html-auto-postamble}
+@item @code{:html-preamble}         @tab @code{org-export-html-preamble}
+@item @code{:html-postamble}        @tab @code{org-export-html-postamble}
 @item @code{:author}                @tab @code{user-full-name}
 @item @code{:email}                 @tab @code{user-mail-address} : @code{addr;addr;..}
 @item @code{:select-tags}           @tab @code{org-export-select-tags}
@@ -11101,8 +11097,7 @@ right place on the web server, and publishing images to it.
           :table-of-contents nil
           :style "<link rel=\"stylesheet\"
                   href=\"../other/mystyle.css\" type=\"text/css\"/>"
-          :auto-preamble t
-          :auto-postamble nil)
+          :html-preamble t)
 
          ("images"
           :base-directory "~/images/"
diff --git a/lisp/org-exp.el b/lisp/org-exp.el
index c38436a..6350983 100644
--- a/lisp/org-exp.el
+++ b/lisp/org-exp.el
@@ -629,10 +629,8 @@ table.el tables."
     (:expand-quoted-html      "@"	  org-export-html-expand)
     (:timestamp		      nil	  org-export-html-with-timestamp)
     (:publishing-directory    nil	  org-export-publishing-directory)
-    (:preamble		      nil	  org-export-html-preamble)
-    (:postamble		      nil	  org-export-html-postamble)
-    (:auto-preamble	      nil	  org-export-html-auto-preamble)
-    (:auto-postamble	      nil	  org-export-html-auto-postamble)
+    (:html-preamble	      nil	  org-export-html-preamble)
+    (:html-postamble	      nil	  org-export-html-postamble)
     (:author		      nil	  user-full-name)
     (:email		      nil	  user-mail-address)
     (:select-tags	      nil	  org-export-select-tags)
diff --git a/lisp/org-html.el b/lisp/org-html.el
index 58c65bf..508165a 100644
--- a/lisp/org-html.el
+++ b/lisp/org-html.el
@@ -29,6 +29,7 @@
 ;;; Code:
 
 (require 'org-exp)
+(require 'format-spec)
 
 (eval-when-compile (require 'cl))
 
@@ -342,8 +343,41 @@ CSS classes, then this prefix can be very useful."
   :group 'org-export-html
   :type 'string)
 
-(defcustom org-export-html-title-format "<h1 class=\"title\">%s</h1>\n"
-  "Format for typesetting the document title in HTML export."
+(defcustom org-export-html-preamble t
+  "Non-nil means insert a preamble in HTML export.
+The format of the preamble is set as `org-export-html-preamble-format'.
+Setting :html-preamble in publishing projects will override this."
+  :group 'org-export-html
+  :type 'boolean)
+
+(defcustom org-export-html-preamble-format
+  '(("en" "<h1 class=\"title\">%t</h1>"))
+  "The format for the HTML preamble.
+
+%t stands for the title."
+  :group 'org-export-html
+  :type 'string)
+
+(defcustom org-export-html-postamble t
+  "Non-nil means insert a postamble in HTML export.
+The format of the postamble is set as `org-export-html-postamble-format'.
+Setting :html-postamble in publishing projects will override this."
+  :group 'org-export-html
+  :type 'boolean)
+
+(defcustom org-export-html-postamble-format
+  '(("en" "<p class=\"author\">Author: %a (%e)</p>
+<p class=\"date\">Date: %d</p>
+<p class=\"creator\">Generated by %c</p>
+<p class=\"xhtml-validation\">%v</p>
+"))
+  "The format for the HTML postamble.
+
+%a stands for the author.
+%e stands for the email(s).
+%d stands for the date.
+%c will be replaced by information about Org/Emacs.
+%v will be replaced by `org-export-html-validation-link'."
   :group 'org-export-html
   :type 'string)
 
@@ -469,13 +503,11 @@ When nil, also column one will use data tags."
   :group 'org-export-tables
   :type 'boolean)
 
-(defcustom org-export-html-validation-link nil
-  "Non-nil means add validation link to postamble of HTML exported files."
+(defcustom org-export-html-validation-link
+  "<a href=\"http://validator.w3.org/check?uri=referer\">Validate XHTML 1.0</a>"
+  "Link to HTML validation service."
   :group 'org-export-html
-  :type '(choice
-	  (const :tag "Nothing" nil)
-	  (const :tag "XHTML 1.0" "<p class=\"xhtml-validation\"><a href=\"http://validator.w3.org/check?uri=referer\">Validate XHTML 1.0</a></p>")
-	  (string :tag "Specify full HTML")))
+  :type 'string)
 
 (defcustom org-export-html-with-timestamp nil
   "If non-nil, write timestamp into the exported HTML text.
@@ -534,19 +566,6 @@ with a link to this URL."
 	  (const :tag "Keep internal css" nil)
 	  (string :tag "URL or local href")))
 
-;;; Variables, constants, and parameter plists
-
-(defvar org-export-html-preamble nil
-  "Preamble, to be inserted just after <body>.  Set by publishing functions.
-This may also be a function, building and inserting the preamble.")
-(defvar org-export-html-postamble nil
-  "Postamble, to be inserted just before </body>.  Set by publishing functions.
-This may also be a function, building and inserting the postamble.")
-(defvar org-export-html-auto-preamble t
-  "Should default preamble be inserted?  Set by publishing functions.")
-(defvar org-export-html-auto-postamble t
-  "Should default postamble be inserted?  Set by publishing functions.")
-
 ;;; Hooks
 
 (defvar org-export-html-after-blockquotes-hook nil
@@ -1241,11 +1260,18 @@ lang=\"%s\" xml:lang=\"%s\">
 		      "\n")
 		   "")))
 
-        (org-export-html-insert-plist-item opt-plist :preamble opt-plist)
-
-	(when (plist-get opt-plist :auto-preamble)
-	  (if title (insert (format org-export-html-title-format
-				    (org-html-expand title))))))
+	;; insert html preamble (for now the title)
+	(when (plist-get opt-plist :html-preamble)
+	  (let* ((html-preamble (plist-get opt-plist :html-preamble))
+		 (html-preamble-format 
+		  (if (stringp html-preamble)
+		      html-preamble
+		    (or (cadr (assoc (nth 0 lang-words)
+				     org-export-html-preamble-format))
+			(cadr (assoc "en" org-export-html-preamble-format))))))
+	    (insert (format-spec html-preamble-format
+				 `((?t . ,(org-html-expand title))
+				   (?a . ,author) (?d . ,date) (?e . ,email)))))))
 
       (if (and org-export-with-toc (not body-only))
 	  (progn
@@ -1698,36 +1724,37 @@ lang=\"%s\" xml:lang=\"%s\">
       (let ((bib (org-export-html-get-bibliography)))
 	(when bib
 	  (insert "\n" bib "\n")))
+
+      ;; export html postamble
       (unless body-only
-	(when (plist-get opt-plist :auto-postamble)
-	  (insert "<div id=\"postamble\">\n")
-	  (when (and org-export-author-info author)
-	    (insert "<p class=\"author\"> "
-		    (nth 1 lang-words) ": " author "\n")
-	    (when (and org-export-email-info email (string-match "\\S-" email))
-	      (if (listp (split-string email ",+ *"))
-		  (mapc (lambda(e)
-			  (insert "<a href=\"mailto:" e "\">&lt;"
-				  e "&gt;</a>\n"))
-			(split-string email ",+ *"))
-		(insert "<a href=\"mailto:" email "\">&lt;"
-			email "&gt;</a>\n")))
-	    (insert "</p>\n"))
-	  (when (and date org-export-time-stamp-file)
-	    (insert "<p class=\"date\"> "
-		    (nth 2 lang-words) ": "
-		    date "</p>\n"))
-	  (when org-export-creator-info
-	    (insert (format "<p class=\"creator\">HTML generated by org-mode %s in emacs %s</p>\n"
-			    org-version emacs-major-version)))
-	  (when org-export-html-validation-link
-	    (insert org-export-html-validation-link "\n"))
-	  (insert "</div>"))
-
-	(if org-export-html-with-timestamp
-	    (insert org-export-html-html-helper-timestamp))
-        (org-export-html-insert-plist-item opt-plist :postamble opt-plist)
-	(insert "\n</div>\n</body>\n</html>\n"))
+	(when (plist-get opt-plist :html-postamble)
+	  (let* ((html-postamble (plist-get opt-plist :html-postamble))
+		 (html-postamble-format 
+		  (if (stringp html-postamble)
+		      html-postamble
+		    (or (cadr (assoc (nth 0 lang-words)
+				     org-export-html-postamble-format))
+			(cadr (assoc "en" org-export-html-postamble-format)))))
+		 (email
+		  (mapconcat (lambda(e)
+			       (format "<a href=\"mailto:%s\">%s</a>" e e))
+			     (split-string email ",+ *")
+			     ", "))
+		 (creator-info
+		  (concat "Org version " org-version " with Emacs version "
+			  (number-to-string emacs-major-version))))
+	    (insert "<div id=\"postamble\">\n")
+	    (insert (format-spec html-postamble-format
+				 `((?a . ,author) (?e . ,email)
+				   (?d . ,date)   (?c . ,creator-info)
+				   (?v . ,org-export-html-validation-link))))
+	    (insert "</div>")
+	    )))
+
+      (if org-export-html-with-timestamp
+	  (insert org-export-html-html-helper-timestamp))
+
+      (insert "\n</div>\n</body>\n</html>\n")
 
       (unless (plist-get opt-plist :buffer-will-be-killed)
 	(normal-mode)
diff --git a/lisp/org-publish.el b/lisp/org-publish.el
index 98e09f3..a7aaee2 100644
--- a/lisp/org-publish.el
+++ b/lisp/org-publish.el
@@ -155,10 +155,8 @@ learn more about their use and default values.
   :expand-quoted-html    `org-export-html-expand'
   :timestamp             `org-export-html-with-timestamp'
   :publishing-directory  `org-export-publishing-directory'
-  :preamble              `org-export-html-preamble'
-  :postamble             `org-export-html-postamble'
-  :auto-preamble         `org-export-html-auto-preamble'
-  :auto-postamble        `org-export-html-auto-postamble'
+  :html-preamble         `org-export-html-preamble'
+  :html-postamble        `org-export-html-postamble'
   :author                `user-full-name'
   :email                 `user-mail-address'
 
-- 
1.7.4


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


-- 
 Bastien

[-- Attachment #4: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

^ permalink raw reply related	[flat|nested] 6+ messages in thread
* Re: [PATCH] Simplifying the handling of HTML preamble/postamble
  2011-02-10 13:01 [PATCH] Simplifying the handling of HTML preamble/postamble Bastien
@ 2011-02-10 15:04 ` Manuel Giraud
  2011-02-10 15:47   ` Bastien
  0 siblings, 1 reply; 6+ messages in thread
From: Manuel Giraud @ 2011-02-10 15:04 UTC (permalink / raw)
  To: Bastien; +Cc: emacs-orgmode

Bastien <bastien.guerry@wikimedia.fr> writes:

> Would people welcome such a simplification?

I've tried it and find it better (and simpler) then with
:auto-preamble/:preamble.

Some comments:

     + example in info file is not the same as before because postamble
       is on by default (maybe we could put a formated string as example
       here)

     + I was confused by /html/ in :html-preamble but since only html
       exports use it I guess that makes sense.

-- 
Manuel Giraud

^ permalink raw reply	[flat|nested] 6+ messages in thread
* Re: [PATCH] Simplifying the handling of HTML preamble/postamble
  2011-02-10 15:04 ` Manuel Giraud
@ 2011-02-10 15:47   ` Bastien
  2011-02-10 16:25     ` Manuel Giraud
  0 siblings, 1 reply; 6+ messages in thread
From: Bastien @ 2011-02-10 15:47 UTC (permalink / raw)
  To: Manuel Giraud; +Cc: emacs-orgmode

Manuel Giraud <manuel.giraud@univ-nantes.fr> writes:

> Bastien <bastien.guerry@wikimedia.fr> writes:
>
>> Would people welcome such a simplification?
>
> I've tried it and find it better (and simpler) then with
> :auto-preamble/:preamble.

Thanks for the feedback!

> Some comments:
>
>      + example in info file is not the same as before because postamble
>        is on by default (maybe we could put a formated string as example
>        here)

I'll put two examples, one with :html-preamble t and another one with
:html-postamble using a format string.

As for org-export-html-preamble and -postamble being t by default, it's 
a mistake I made.  I think they should default to nil.  But I'd welcome 
another opinion!

>      + I was confused by /html/ in :html-preamble but since only html
>        exports use it I guess that makes sense.

Yes, I think it clarifies things.

-- 
 Bastien

^ permalink raw reply	[flat|nested] 6+ messages in thread
* Re: [PATCH] Simplifying the handling of HTML preamble/postamble
  2011-02-10 15:47   ` Bastien
@ 2011-02-10 16:25     ` Manuel Giraud
  2011-02-10 17:03       ` Jeff Horn
  2011-02-10 17:13       ` Bastien
  0 siblings, 2 replies; 6+ messages in thread
From: Manuel Giraud @ 2011-02-10 16:25 UTC (permalink / raw)
  To: Bastien; +Cc: emacs-orgmode

Bastien <bastien.guerry@wikimedia.fr> writes:

> As for org-export-html-preamble and -postamble being t by default, it's 
> a mistake I made.  I think they should default to nil.  But I'd welcome 
> another opinion!

For the postamble maybe. But for the preamble, I don't think it is a
good idea to remove the <h1> title by default (but maybe I'm wrong : how
is it done in others export formats?)

-- 
Manuel Giraud

^ permalink raw reply	[flat|nested] 6+ messages in thread
* Re: [PATCH] Simplifying the handling of HTML preamble/postamble
  2011-02-10 16:25     ` Manuel Giraud
@ 2011-02-10 17:03       ` Jeff Horn
  2011-02-10 17:13       ` Bastien
  1 sibling, 0 replies; 6+ messages in thread
From: Jeff Horn @ 2011-02-10 17:03 UTC (permalink / raw)
  To: Manuel Giraud; +Cc: emacs-orgmode, Bastien

This looks great to me. Seems like a relatively "more sane" or perhaps
"more intuitive" way of doing things. Solves the problem I had
earlier, and makes it clear that these variables can be set in an init
file.

On Thu, Feb 10, 2011 at 11:25 AM, Manuel Giraud
<manuel.giraud@univ-nantes.fr> wrote:
> Bastien <bastien.guerry@wikimedia.fr> writes:
>
>> As for org-export-html-preamble and -postamble being t by default, it's
>> a mistake I made.  I think they should default to nil.  But I'd welcome
>> another opinion!
>
> For the postamble maybe. But for the preamble, I don't think it is a
> good idea to remove the <h1> title by default (but maybe I'm wrong : how
> is it done in others export formats?)
>
> --
> Manuel Giraud
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>



-- 
Jeffrey Horn
http://www.failuretorefrain.com/jeff/

^ permalink raw reply	[flat|nested] 6+ messages in thread
* Re: [PATCH] Simplifying the handling of HTML preamble/postamble
  2011-02-10 16:25     ` Manuel Giraud
  2011-02-10 17:03       ` Jeff Horn
@ 2011-02-10 17:13       ` Bastien
  1 sibling, 0 replies; 6+ messages in thread
From: Bastien @ 2011-02-10 17:13 UTC (permalink / raw)
  To: Manuel Giraud; +Cc: emacs-orgmode

Manuel Giraud <manuel.giraud@univ-nantes.fr> writes:

> Bastien <bastien.guerry@wikimedia.fr> writes:
>
>> As for org-export-html-preamble and -postamble being t by default, it's 
>> a mistake I made.  I think they should default to nil.  But I'd welcome 
>> another opinion!
>
> For the postamble maybe. But for the preamble, I don't think it is a
> good idea to remove the <h1> title by default (but maybe I'm wrong : how
> is it done in others export formats?)

My bad.  Preamble *and* postamble are currently inserted by default.
The HTML export behaves as if :auto-preamble and :auto-postamble are 
set to t.

So I guess I'll commit my patch as it is.

-- 
 Bastien

^ permalink raw reply	[flat|nested] 6+ messages in thread
end of thread, other threads:[~2011-02-10 17:13 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-02-10 13:01 [PATCH] Simplifying the handling of HTML preamble/postamble Bastien
2011-02-10 15:04 ` Manuel Giraud
2011-02-10 15:47   ` Bastien
2011-02-10 16:25     ` Manuel Giraud
2011-02-10 17:03       ` Jeff Horn
2011-02-10 17:13       ` Bastien

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).