[elpa] externals/valign 7afe578 182/198: Improve documentation

[Stefan Monnier]

branch: externals/valign
commit 7afe57833bf56808490370262614596487f6c323
Author: Yuan Fu <casouri@gmail.com>
Commit: Yuan Fu <casouri@gmail.com>

    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