* shr.el: Document the table-rendering algorithm.

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 834fb83..05350ab 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -2,6 +2,8 @@
 
        * shr.el (shr-render-td): Allow blank/missing <TD>s.
 
 
        * shr.el (shr-render-td): Allow blank/missing <TD>s.
 

+       * shr.el: Document the table-rendering algorithm.
+

 2010-10-05  Katsumi Yamaoka  <yamaoka@jpl.org>
 
        * dgnushack.el (dgnushack-compile): Exclude shr.el from being compiled
 2010-10-05  Katsumi Yamaoka  <yamaoka@jpl.org>
 
        * dgnushack.el (dgnushack-compile): Exclude shr.el from being compiled

diff --git a/lisp/shr.el b/lisp/shr.el
index 35c4021..c7f94eb 100644 (file)
--- a/lisp/shr.el
+++ b/lisp/shr.el
@@ -427,16 +427,33 @@ Return a string with image data."
   (apply #'shr-fontize-cont cont types)
   (shr-ensure-paragraph))
 
   (apply #'shr-fontize-cont cont types)
   (shr-ensure-paragraph))
 

+;; Table rendering is the only complicated thing here.  We do this by
+;; first counting how many TDs there are in each TR, and registering
+;; how wide they think they should be ("width=45%", etc).  Then we
+;; render each TD separately (this is done in temporary buffers, so
+;; that we can use all the rendering machinery as if we were in the
+;; main buffer).  Now we know how much space each TD really takes, so
+;; we then render everything again with the new widths, and finally
+;; insert all these boxes into the main buffer.

 (defun shr-tag-table (cont)
   (shr-ensure-paragraph)
   (setq cont (or (cdr (assq 'tbody cont))
                 cont))
   (let* ((shr-inhibit-images t)
 (defun shr-tag-table (cont)
   (shr-ensure-paragraph)
   (setq cont (or (cdr (assq 'tbody cont))
                 cont))
   (let* ((shr-inhibit-images t)

+        ;; Find all suggested widths.

         (columns (shr-column-specs cont))
         (columns (shr-column-specs cont))

+        ;; Compute how many characters wide each TD should be.

         (suggested-widths (shr-pro-rate-columns columns))
         (suggested-widths (shr-pro-rate-columns columns))

+        ;; Do a "test rendering" to see how big each TD is (this can
+        ;; be smaller (if there's little text) or bigger (if there's
+        ;; unbreakable text).

         (sketch (shr-make-table cont suggested-widths))
         (sketch-widths (shr-table-widths sketch (length suggested-widths))))
         (sketch (shr-make-table cont suggested-widths))
         (sketch-widths (shr-table-widths sketch (length suggested-widths))))

+    ;; Then render the table again with these new "hard" widths.

     (shr-insert-table (shr-make-table cont sketch-widths t) sketch-widths))
     (shr-insert-table (shr-make-table cont sketch-widths t) sketch-widths))

+  ;; Finally, insert all the images after the table.  The Emacs buffer
+  ;; model isn't strong enough to allow us to put the images actually
+  ;; into the tables.

   (dolist (elem (shr-find-elements cont 'img))
     (shr-tag-img (cdr elem))))
 
   (dolist (elem (shr-find-elements cont 'img))
     (shr-tag-img (cdr elem))))