branch: externals/valign
commit 7afe57833bf56808490370262614596487f6c323
Author: Yuan Fu <[email protected]>
Commit: Yuan Fu <[email protected]>
Improve documentation
* valign.el (valign--cell): Change docstring.
(Developer): Add detail.
---
valign.el | 46 ++++++++++++++++++++++++++++++++++++++--------
1 file changed, 38 insertions(+), 8 deletions(-)
diff --git a/valign.el b/valign.el
index 383aedd..1700a73 100644
--- a/valign.el
+++ b/valign.el
@@ -16,9 +16,10 @@
;; meantime, the text-based alignment generated by Org mode (or
;; Markdown mode) is left untouched.
;;
-;; To use this package, add `valign-mode' to `org-mode-hook'. If you
-;; want to align a table manually, run M-x valign-table RET on a
-;; table.
+;; To use this package, type M-x valign-mode RET. If you want to
+;; align a table manually, run M-x valign-table RET on a table. If
+;; you want to automatically enable this mode, add `valign-mode' to a
+;; major mode hook like `org-mode-hook'.
;;
;; TODO:
;;
@@ -27,14 +28,41 @@
;;; Developer:
;;
-;; We decide to re-align in jit-lock hook, that means any change that
-;; causes refontification will trigger re-align. This may seem
+;; The trigger condition:
+;;
+;; We decide to re-align in the jit-lock hook, that means any change
+;; that causes refontification will trigger a re-align. This may seem
;; inefficient and unnecessary, but there are just too many things
;; that can mess up a table’s alignment. Therefore it is the most
;; reliable to re-align every time there is a refontification.
;; However, we do have a small optimization for typing in a table: if
;; the last command is 'self-insert-command', we don’t realign. That
;; should improve the typing experience in large tables.
+;;
+;; How does valign align tables:
+;;
+;; The core mechanism used is a text property 'display. Emacs can
+;; display a stretch of space that aligns to a pixel position.
+;; The following snippet
+;;
+;; (put-text-property (point) (1+ (point))
+;; 'display '(space :align-to (500)))
+;;
+;; creates a space that stretches to pixel position 500. You can look
+;; at Info node (elisp) “Display Property” for more detail.
+;;
+;; To align a table, we first look through all its cells to calculate
+;; the appropriate column width, this is done by
+;; `valign--calculate-cell-width'. Then we calculate the alignment of
+;; each column (left/right-aligned) in `valign--calculate-alignment'.
+;; Finally we align each cell by adding text property (or overlay) to
+;; the spaces in the cell which “pushes” the bars to the appropriate
+;; positions.
+;;
+;; Some important auxiliary functions:
+;;
+;; - valign--pixel-width-from-to
+;; - valign--cell-content-config
;;; Code:
;;
@@ -668,13 +696,15 @@ COL-WIDTH (6) Pixel width of the column
ALIGNMENT 'left or 'right
CELL-WIDTH (5) Pixel width of the cell content
CELL-BEG (1) Beginning of the cell
-CONTENT-BEG (2) Beginning of the cell content
-CONTENT-END (3) End of the cell content
+CONTENT-BEG (2) Beginning of the cell content[1]
+CONTENT-END (3) End of the cell content[1]
CELL-END (4) End of the cell
COLUMN-START (1) Pixel x-position of the beginning of the cell
SPACE-WIDTH Pixel width of a space character
-Assumes point is at (2)."
+Assumes point is at (2).
+
+[1] This is not completely true, see `valign--cell-content-config'."
(cl-labels ((valign--put-ov
(beg end xpos)
(valign--put-overlay beg end 'display
