*** TeXmacs-1.0.0.18-src/TeXmacs-1.0.0.18/progs/boot/base.scm
--- TeXmacs-1.0.0.18-src/TeXmacs-1.0.0.18/progs/boot/base.scm
***************
*** 3,9 ****
  ;;
  ;; MODULE      : base.scm
  ;; DESCRIPTION : frequently used TeXmacs-independent Scheme subroutines
! ;; COPYRIGHT   : (C) 2002  Joris van der Hoeven
  ;;
  ;; This software falls under the GNU general public license and comes WITHOUT
  ;; ANY WARRANTY WHATSOEVER. See the file $TEXMACS_PATH/LICENSE for details.
--- 3,9 ----
  ;;
  ;; MODULE      : base.scm
  ;; DESCRIPTION : frequently used TeXmacs-independent Scheme subroutines
! ;; COPYRIGHT   : (C) 2002  Joris van der Hoeven, David Allouche
  ;;
  ;; This software falls under the GNU general public license and comes WITHOUT
  ;; ANY WARRANTY WHATSOEVER. See the file $TEXMACS_PATH/LICENSE for details.
***************
*** 18,29 ****
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  
  (define (display-list l)
    (if (not (null? l))
        (begin
  	(display (car l))
  	(display-list (cdr l)))))
  
! (define (display* . l) (display-list l))
  
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;; Utility
--- 18,32 ----
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  
  (define (display-list l)
+   "Display the elements of the list l. Unspecified value."
    (if (not (null? l))
        (begin
  	(display (car l))
  	(display-list (cdr l)))))
  
! (define (display* . l)
!   "(display* [x1 .. xN]) -> unspecifed. Display x1 .. xN)."
!   (display-list l))
  
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;; Utility
*************** (define (c121r l) (caadar l))
*** 45,69 ****
  (define (c112r l) (caaadr l))
  (define (c1111r l) (caaaar l))
  
! (define (cAr l) (car (reverse l)))
! (define (cDr l) (reverse (cdr (reverse l))))
! (define (cADr l) (cadr (reverse l)))
! (define (cDDr l) (reverse (cddr (reverse l))))
! (define (cDdr l) (cDr (cdr l)))
  
  (define (cons* . l)
    (let ((r (reverse l)))
      (append (reverse (cdr r)) (car r))))
  
! (define (rcons l x) (append l (list x)))
! 
! (define (rcons* l . xs) (append l xs))
  
  (define (map-unary f l)
    (if (null? l) l
        (cons (f (car l)) (map-unary f (cdr l)))))
  
  (define (exec-unary f l)
    (if (not (null? l))
        (begin
  	(f (car l))
--- 48,84 ----
  (define (c112r l) (caaadr l))
  (define (c1111r l) (caaaar l))
  
! (define (cAr l) "Last element of list."
!   (car (reverse l)))
! (define (cDr l) "Copy of list without last element."
!   (reverse (cdr (reverse l))))
! (define (cADr l) "One to last element of list."
!   (cadr (reverse l)))
! (define (cDDr l) "Copy of list l without its last two elements."
!   (reverse (cddr (reverse l))))
! (define (cDdr l) "Copy of list without first and last elements."
!   (cDr (cdr l)))
  
  (define (cons* . l)
+   "(cons* [x1 .. xN] l) -> List l with elements x1..xN prepended."
    (let ((r (reverse l)))
      (append (reverse (cdr r)) (car r))))
  
! (define (rcons l x)
!   "Copy of list l with element x appended."
!   (append l (list x)))
! 
! (define (rcons* l . xs)
!   "(rcons* l [x1 .. xN]) -> List l with element x1..xN appended."
!   (append l xs))
  
  (define (map-unary f l)
+   "Equivalent to map for unary functions and with known application order."
    (if (null? l) l
        (cons (f (car l)) (map-unary f (cdr l)))))
  
  (define (exec-unary f l)
+   "Equivalent to for-each for unary functions."
    (if (not (null? l))
        (begin
  	(f (car l))
*************** (define (exec-unary f l)
*** 74,90 ****
--- 89,108 ----
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  
  (define (in? x l)
+   "Is there one element of list l which is 'equal?' to x?"
    (cond ((null? l) #f)
  	((equal? (car l) x) #t)
  	(else (in? x (cdr l)))))
  
  (define (list-starts? l what)
+   "Does the list 'what' match (equal?) the head of the list l?"
    (cond ((null? what) #t)
  	((null? l) #f)
  	(else (and (equal? (car l) (car what))
  		   (list-starts? (cdr l) (cdr what))))))
  
  (define (sublist l i j)
+   "Copy of sublist of list l from index i inclusive to index j exclusive."
    (if (> i 0)
        (if (null? l) l (sublist (cdr l) (- i 1) (- j 1)))
        (if (> j 0)
*************** (define (sublist l i j)
*** 92,97 ****
--- 110,116 ----
  	  '())))
  
  (define (list-replace l what by)
+   "Replace all occurrences of sublist 'what' by sublist 'by' in l."
    (cond ((null? l) l)
  	((list-starts? l what)
  	 (let ((tail (sublist l (length what) (length l))))
*************** (define (list-replace l what by)
*** 99,104 ****
--- 118,127 ----
  	(else (cons (car l) (list-replace (cdr l) what by)))))
  
  (define (split l pred)
+   "(split l pred) -> (l1 l2). Split l into l1 and l2 where pred is true.
+ 
+ l1 is the longest head of l2 where the unary predicate pred maps all
+ elements to true."
    (if (null? l) (list l l)
        (if (pred (car l))
  	  (list '() l)
*************** (define (split l pred)
*** 106,121 ****
--- 129,147 ----
  	    (list (cons (car l) (car p)) (cadr p))))))
  
  (define (filter l pred?)
+   "List of all elements of l which are mapped to true by 'pred?'."
    (cond ((null? l) l)
  	((pred? (car l)) (cons (car l) (filter (cdr l) pred?)))
  	(else (filter (cdr l) pred?))))
  
  (define (list-sort-insert x l comp)
+   "Insert x in the list l sorted by the complete ordering 'comp'."
    (cond ((null? l) (list x))
  	((comp x (car l)) (cons x l))
  	(else (cons (car l) (list-sort-insert x (cdr l) comp)))))
  
  (define (list-sort l comp)
+   "Sort the list l according to the complete ordering 'comp'."
    (if (null? l) l
        (let ((r (list-sort (cdr l) comp)))
  	(list-sort-insert (car l) r comp))))
*************** (define (list-sort l comp)
*** 124,135 ****
  ;; Booleans
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  
! (define (xor-sub l)
    (cond ((null? l) #f)
  	((car l) (not (xor-sub (cdr l))))
  	(else (xor-sub (cdr l)))))
  
! (define (xor . l) (xor-sub l))
  
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;; Strings
--- 150,162 ----
  ;; Booleans
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  
! (define (xor-sub l) "Internal procedure used by xor."
    (cond ((null? l) #f)
  	((car l) (not (xor-sub (cdr l))))
  	(else (xor-sub (cdr l)))))
  
! (define (xor . l) "(xor [x1 .. xN]) -> boolean. Exclusive or of N values."
!   (xor-sub l))
  
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;; Strings
*************** (define (xor . l) (xor-sub l))
*** 138,156 ****
--- 165,187 ----
  (define (char->string c) (list->string (list c)))
  
  (define (char-in-string? c s)
+   "Is c a character present in the string s?"
    (not (equal? (string-index s c) #f)))
  
  (define (string-starts? s what)
+   "Does the string 'what' match the head of the string s?"
    (let ((n (string-length s))
  	(k (string-length what)))
      (and (>= n k) (equal? (substring s 0 k) what))))
  
  (define (string-ends? s what)
+   "Does the string 'what' match the tail of the string s?"
    (let ((n (string-length s))
  	(k (string-length what)))
      (and (>= n k) (equal? (substring s (- n k) n) what))))
  
  (define (string-replace s what by)
+   "Replace all occurences of string 'what' by string 'by' in string s."
    (list->string
     (list-replace
      (string->list s)
*************** (define (string-replace s what by)
*** 158,166 ****
--- 189,201 ----
      (string->list by))))
  
  (define (force-string s)
+   "Return s or \"\" if s in not a string."
    (if (string? s) s ""))
  
  (define (func? . l)
+   "(func? x f [n]) -> boolean. Test car, and optionally length, of list x.
+ 
+ Is x a list [of n elements] whose first element 'equal?' f?"
    (let ((n (length l)))
      (cond ((= n 2)
  	   (let ((x (car l)) (f (cadr l)))
*************** (define (func? . l)
*** 172,177 ****
--- 207,215 ----
  	  (else #f))))
  
  (define (tuple? . args)
+   "(tuple? x [f [n]]) -> boolean. Applies 'list?' or 'func?'.
+ 
+ Equivalent to 'list?' if f and n are ommited, or equivalent to 'func?'." 
    (if (null? (cdr args)) (list? (car args)) (apply func? args)))
  
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
*************** (define (tuple? . args)
*** 179,184 ****
--- 217,223 ----
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  
  (define (match-list? l pattern)
+   "Internal routine used by 'match?'. Matches pattern lists."
    (cond ((null? pattern) (null? l))
  	((number? (car pattern))
  	 (and (>= (length l) (car pattern))
*************** (define (match-list? l pattern)
*** 189,194 ****
--- 228,234 ----
  		   (match-list? (cdr l) (cdr pattern))))))
  
  (define (match-sub? x pattern)
+   "Internal routine used by 'match?'. Matches logical expression patterns."
    (let ((first (car pattern)))
      (cond ((equal? first 'and)
  	   (and (match? x (c2r pattern)) (match? x (c3r pattern))))
*************** (define (match-sub? x pattern)
*** 201,206 ****
--- 241,268 ----
  	  (else #f))))
  
  (define (match? x pattern)
+   "Does x match the pattern?
+ 
+ The pattern language is a recursive rule based language.
+ 
+             pattern --> matching objects
+ Atom patterns:
+     (), empty list  --> only '()'.
+     symbol ending in '?', must be bound to unary predicate
+                     --> objects that this predicate maps to true.
+     other non-list  --> objects 'equal?' to pattern.
+ Logical expression patterns:
+     (and pat1 pat2) --> objects matching pat1 AND pat2.
+     (or  pat2 pat2) --> objects matching pat1 OR pat2.
+     (not pat1)      --> objects NOT matching pat1.
+     (quote obj)     --> objects 'equal?' to obj.
+ Pattern lists:
+     (N . pats)      --> lists whose Nth tail matches pats.
+     (*)             --> any list, including empty list.
+     (pat1 . pats)   --> lists whose car match pat1 and cdr matches pats.
+ 
+ Notations: 'pat1', 'pat2': patterns. 'pats': pattern list or ().
+            'N' -> number. 'obj' -> any object."
    (cond ((null? pattern) (null? x))
  	((list? pattern) (match-sub? x pattern))
  	((and (symbol? pattern) (string-ends? (symbol->string pattern) "?"))
*************** (define (match? x pattern)
*** 212,223 ****
--- 274,290 ----
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  
  (define (fill-dictionary-entry d key im)
+   "Map all the values in the 'key' list to 'im' in the hash d."
    (if (not (null? key))
        (begin
  	(hash-set! d (car key) im)
  	(fill-dictionary-entry d (cdr key) im))))
  
  (define (fill-dictionary d l)
+   "Fill the hash d with the list of dictionary entries l.
+ 
+   l is a list whose cDr is a list 'keys' and cAr is 'im'.
+   For each element of l, applies (fill-dictionnary-entry d keys im)."
    (if (not (null? l))
        (begin
  	(let* ((r (reverse (car l))))
*************** (define (fill-dictionary d l)
*** 225,230 ****
--- 292,298 ----
  	(fill-dictionary d (cdr l)))))
  
  (define (fill-set d l)
+   "Map every element of the list l to #t in the hash d." 
    (if (not (null? l))
        (begin
  	(hash-set! d (car l) #t)