+;;; @multitable ... @end multitable
+
+;; Produce a multi-column table, with as many columns as desired.
+;;
+;; A multi-column table has this template:
+;;
+;; @multitable {A1} {A2} {A3}
+;; @item A1 @tab A2 @tab A3
+;; @item B1 @tab B2 @tab B3
+;; @item C1 @tab C2 @tab C3
+;; @end multitable
+;;
+;; where the width of the text in brackets specifies the width of the
+;; respective column.
+;;
+;; Or else:
+;;
+;; @multitable @columnfractions .25 .3 .45
+;; @item A1 @tab A2 @tab A3
+;; @item B1 @tab B2 @tab B3
+;; @end multitable
+;;
+;; where the fractions specify the width of each column as a percent
+;; of the current width of the text (i.e., of the fill-column).
+;;
+;; Long lines of text are filled within columns.
+;;
+;; Using the Emacs Lisp formatter, texinfmt.el,
+;; the whitespace between columns can be increased by setting
+;; `texinfo-extra-inter-column-width' to a value greater than 0. By default,
+;; there is at least one blank space between columns.
+;;
+;; The Emacs Lisp formatter, texinfmt.el, ignores the following four
+;; commands that are defined in texinfo.tex for printed output.
+;;
+;; @multitableparskip,
+;; @multitableparindent,
+;; @multitablecolmargin,
+;; @multitablelinespace.
+
+;; How @multitable works.
+;; =====================
+;;
+;; `texinfo-multitable' reads the @multitable line and determines from it
+;; how wide each column should be.
+;;
+;; Also, it pushes this information, along with an identifying symbol,
+;; onto the `texinfo-stack'. At the @end multitable command, the stack
+;; is checked for its matching @multitable command, and then popped, or
+;; else an error is signaled. Also, this command pushes the location of
+;; the start of the table onto the stack.
+;;
+;; `texinfo-end-multitable' checks the `texinfo-stack' that the @end
+;; multitable truly is ending a corresponding beginning, and if it is,
+;; pops the stack.
+;;
+;; `texinfo-multitable-widths' is called by `texinfo-multitable'.
+;; The function returns a list of the widths of each column in a
+;; multi-column table, based on the information supplied by the arguments
+;; to the @multitable command (by arguments, I mean the text on the rest
+;; of the @multitable line, not the remainder of the multi-column table
+;; environment).
+;;
+;; `texinfo-multitable-item' formats a row within a multicolumn table.
+;; This command is executed when texinfmt sees @item inside @multitable.
+;; Cells in row are separated by `@tab's. Widths of cells are specified
+;; by the arguments in the @multitable line. Cells are filled. All cells
+;; are made to be the same height by padding their bottoms, as needed,
+;; with blanks.
+;;
+;; `texinfo-multitable-extract-row' is called by `texinfo-multitable-item'.
+;; This function returns the text in a multitable row, as a string.
+;; The start of a row is marked by an @item and the end of row is the
+;; beginning of next @item or beginning of the @end multitable line.
+;; Cells within a row are separated by @tab.
+;;
+;; Note that @tab, the cell separators, are not treated as independent
+;; Texinfo commands.
+
+(defvar texinfo-extra-inter-column-width 0
+ "*Number of extra spaces between entries (columns) in @multitable.")
+
+(defvar texinfo-multitable-buffer-name "*multitable-temporary-buffer*")
+(defvar texinfo-multitable-rectangle-name "texinfo-multitable-temp-")
+
+;; These commands are defined in texinfo.tex for printed output.
+(put 'multitableparskip 'texinfo-format 'texinfo-discard-line-with-args)
+(put 'multitableparindent 'texinfo-format 'texinfo-discard-line-with-args)
+(put 'multitablecolmargin 'texinfo-format 'texinfo-discard-line-with-args)
+(put 'multitablelinespace 'texinfo-format 'texinfo-discard-line-with-args)
+
+(put 'multitable 'texinfo-format 'texinfo-multitable)
+
+(defun texinfo-multitable ()
+ "Produce multi-column tables.
+
+A multi-column table has this template:
+
+ @multitable {A1} {A2} {A3}
+ @item A1 @tab A2 @tab A3
+ @item B1 @tab B2 @tab B3
+ @item C1 @tab C2 @tab C3
+ @end multitable
+
+where the width of the text in brackets specifies the width of the
+respective column.
+
+Or else:
+
+ @multitable @columnfractions .25 .3 .45
+ @item A1 @tab A2 @tab A3
+ @item B1 @tab B2 @tab B3
+ @end multitable
+
+where the fractions specify the width of each column as a percent
+of the current width of the text (i.e., of the fill-column).
+
+Long lines of text are filled within columns.
+
+Using the Emacs Lisp formatter, texinfmt.el,
+the whitespace between columns can be increased by setting
+`texinfo-extra-inter-column-width' to a value greater than 0. By default,
+there is at least one blank space between columns.
+
+The Emacs Lisp formatter, texinfmt.el, ignores the following four
+commands that are defined in texinfo.tex for printed output.
+
+ @multitableparskip,
+ @multitableparindent,
+ @multitablecolmargin,
+ @multitablelinespace."
+
+;; This function pushes information onto the `texinfo-stack'.
+;; A stack element consists of:
+;; - type-of-command, i.e., multitable
+;; - the information about column widths, and
+;; - the position of texinfo-command-start.
+;; e.g., ('multitable (1 2 3 4) 123)
+;; The command line is then deleted.
+ (texinfo-push-stack
+ 'multitable
+ ;; push width information on stack
+ (texinfo-multitable-widths))
+ (texinfo-discard-line-with-args))
+
+(put 'multitable 'texinfo-end 'texinfo-end-multitable)
+(defun texinfo-end-multitable ()
+ "Discard the @end multitable line and pop the stack of multitable."
+ (texinfo-discard-command)
+ (texinfo-pop-stack 'multitable))
+
+(defun texinfo-multitable-widths ()
+ "Return list of widths of each column in a multi-column table."
+ (let (texinfo-multitable-width-list)
+ ;; Fractions format:
+ ;; @multitable @columnfractions .25 .3 .45
+ ;;
+ ;; Template format:
+ ;; @multitable {Column 1 template} {Column 2} {Column 3 example}
+ ;; Place point before first argument
+ (skip-chars-forward " \t")
+ (cond
+ ;; Check for common misspelling
+ ((looking-at "@columnfraction ")
+ (error "In @multitable, @columnfractions misspelled"))
+ ;; Case 1: @columnfractions .25 .3 .45
+ ((looking-at "@columnfractions")
+ (forward-word 1)
+ (while (not (eolp))
+ (setq texinfo-multitable-width-list
+ (cons
+ (truncate
+ (1-
+ (* fill-column (read (get-buffer (current-buffer))))))
+ texinfo-multitable-width-list))))
+ ;;
+ ;; Case 2: {Column 1 template} {Column 2} {Column 3 example}
+ ((looking-at "{")
+ (let ((start-of-templates (point)))
+ (while (not (eolp))
+ (skip-chars-forward " \t")
+ (let* ((start-of-template (1+ (point)))
+ (end-of-template
+ ;; forward-sexp works with braces in Texinfo mode
+ (progn (forward-sexp 1) (1- (point)))))
+ (setq texinfo-multitable-width-list
+ (cons (- end-of-template start-of-template)
+ texinfo-multitable-width-list))
+ ;; Remove carriage return from within a template, if any.
+ ;; This helps those those who want to use more than
+ ;; one line's worth of words in @multitable line.
+ (narrow-to-region start-of-template end-of-template)
+ (goto-char (point-min))
+ (while (search-forward "
+" nil t)
+ (delete-char -1))
+ (goto-char (point-max))
+ (widen)
+ (forward-char 1)))))
+ ;;
+ ;; Case 3: Trouble
+ (t
+ (error
+ "You probably need to specify column widths for @multitable correctly.")))
+ ;; Check whether columns fit on page.
+ (let ((desired-columns
+ (+
+ ;; between column spaces
+ (length texinfo-multitable-width-list)
+ ;; additional between column spaces, if any
+ texinfo-extra-inter-column-width
+ ;; sum of spaces for each entry
+ (apply '+ texinfo-multitable-width-list))))
+ (if (> desired-columns fill-column)
+ (error
+ (format
+ "Multi-column table width, %d chars, is greater than page width, %d chars."
+ desired-columns fill-column))))
+ texinfo-multitable-width-list))
+
+;; @item A1 @tab A2 @tab A3
+(defun texinfo-multitable-extract-row ()
+ "Return multitable row, as a string.
+End of row is beginning of next @item or beginning of @end.
+Cells within rows are separated by @tab."
+ (skip-chars-forward " \t")
+ (let* ((start (point))
+ (end (progn
+ (re-search-forward "@item\\|@end")
+ (match-beginning 0)))
+ (row (progn (goto-char end)
+ (skip-chars-backward " ")
+ ;; remove whitespace at end of argument
+ (delete-region (point) end)
+ (buffer-substring start (point)))))
+ (delete-region texinfo-command-start end)
+ row))
+
+(put 'multitable 'texinfo-item 'texinfo-multitable-item)
+(defun texinfo-multitable-item ()
+ "Format a row within a multicolumn table.
+Cells in row are separated by @tab.
+Widths of cells are specified by the arguments in the @multitable line.
+All cells are made to be the same height.
+This command is executed when texinfmt sees @item inside @multitable."
+ (let ((original-buffer (current-buffer))
+ (table-widths (reverse (car (cdr (car texinfo-stack)))))
+ (existing-fill-column fill-column)
+ start
+ end
+ (table-column 0)
+ (table-entry-height 0)
+ ;; unformatted row looks like: A1 @tab A2 @tab A3
+ ;; extract-row command deletes the source line in the table.
+ (unformated-row (texinfo-multitable-extract-row)))
+ ;; Use a temporary buffer
+ (set-buffer (get-buffer-create texinfo-multitable-buffer-name))
+ (delete-region (point-min) (point-max))
+ (insert unformated-row)
+ (goto-char (point-min))
+;; 1. Check for correct number of @tab in line.
+ (let ((tab-number 1)) ; one @tab between two columns
+ (while (search-forward "@tab" nil t)
+ (setq tab-number (1+ tab-number)))
+ (if (/= tab-number (length table-widths))
+ (error "Wrong number of @tab's in a @multitable row.")))
+ (goto-char (point-min))
+;; 2. Format each cell, and copy to a rectangle
+ ;; buffer looks like this: A1 @tab A2 @tab A3
+ ;; Cell #1: format up to @tab
+ ;; Cell #2: format up to @tab
+ ;; Cell #3: format up to eob
+ (while (not (eobp))
+ (setq start (point))
+ (setq end (save-excursion
+ (if (search-forward "@tab" nil 'move)
+ ;; Delete the @tab command, including the @-sign
+ (delete-region
+ (point)
+ (progn (forward-word -1) (1- (point)))))
+ (point)))
+ ;; Set fill-column *wider* than needed to produce inter-column space
+ (setq fill-column (+ 1
+ texinfo-extra-inter-column-width
+ (nth table-column table-widths)))
+ (narrow-to-region start end)
+ ;; Remove whitespace before and after entry.
+ (skip-chars-forward " ")
+ (delete-region (point) (save-excursion (beginning-of-line) (point)))
+ (goto-char (point-max))
+ (skip-chars-backward " ")
+ (delete-region (point) (save-excursion (end-of-line) (point)))
+ ;; Temorarily set texinfo-stack to nil so texinfo-format-scan
+ ;; does not see an unterminated @multitable.
+ (let (texinfo-stack) ; nil
+ (texinfo-format-scan))
+ (let (fill-prefix) ; no fill prefix
+ (fill-region (point-min) (point-max)))
+ (setq table-entry-height
+ (max table-entry-height (count-lines (point-min) (point-max))))
+;; 3. Move point to end of bottom line, and pad that line to fill column.
+ (goto-char (point-min))
+ (forward-line (1- table-entry-height))
+ (let* ((beg (point)) ; beginning of line
+ ;; add one more space for inter-column spacing
+ (needed-whitespace
+ (1+
+ (- fill-column
+ (-
+ (progn (end-of-line) (point)) ; end of existing line
+ beg)))))
+ (insert (make-string
+ (if (> needed-whitespace 0) needed-whitespace 1)
+ ? )))
+ ;; now, put formatted cell into a rectangle
+ (set (intern (concat texinfo-multitable-rectangle-name
+ (int-to-string table-column)))
+ (extract-rectangle (point-min) (point)))
+ (delete-region (point-min) (point))
+ (goto-char (point-max))
+ (setq table-column (1+ table-column))
+ (widen))
+;; 4. Add extra lines to rectangles so all are of same height
+ (let ((total-number-of-columns table-column)
+ (column-number 0)
+ here)
+ (while (> table-column 0)
+ (let ((this-rectangle (int-to-string table-column)))
+ (while (< (length this-rectangle) table-entry-height)
+ (setq this-rectangle (append this-rectangle '("")))))
+ (setq table-column (1- table-column)))
+;; 5. Insert formatted rectangles in original buffer
+ (switch-to-buffer original-buffer)
+ (open-line table-entry-height)
+ (while (< column-number total-number-of-columns)
+ (setq here (point))
+ (insert-rectangle
+ (eval (intern
+ (concat texinfo-multitable-rectangle-name
+ (int-to-string column-number)))))
+ (goto-char here)
+ (end-of-line)
+ (setq column-number (1+ column-number))))
+ (kill-buffer texinfo-multitable-buffer-name)
+ (setq fill-column existing-fill-column)))
+
+\f
+;;; @ifinfo, @iftex, @tex, @ifhtml, @html