From: Lars Magne Ingebrigtsen <larsi@quimbies.gnus.org>
Date: Tue, 5 Oct 2010 23:05:53 +0000 (+0200)
Subject: * shr.el: Document the table-rendering algorithm.
X-Git-Url: https://cgit.sxemacs.org/?p=gnus;a=commitdiff_plain;h=51f69ff7ff8e73339ead7bdb807f06a694eb0230;ds=sidebyside

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

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 834fb8306..05350abab 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -2,6 +2,8 @@
 
 	* 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
diff --git a/lisp/shr.el b/lisp/shr.el
index 35c4021f3..c7f94ebc6 100644
--- 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))
 
+;; 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)
+	 ;; Find all suggested widths.
 	 (columns (shr-column-specs cont))
+	 ;; Compute how many characters wide each TD should be.
 	 (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))))
+    ;; Then render the table again with these new "hard" 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))))