comparison lisp/textmodes/texnfo-upd.el @ 18259:379252f79147

Many doc fixes. (texinfo-all-menus-update): Check for @detailmenu. (texinfo-master-menu): Likewise. (texinfo-multiple-files-update): Likewise. (texinfo-insert-master-menu-list): Put in @detailmenu if appropriate.

18258:e83bc8150072

      (push-mark (point-max) t)
      (goto-char (point-min))
      (message "Checking for a master menu in %s ... "(buffer-name))
      (save-excursion
        (if (re-search-forward texinfo-master-menu-header nil t)
            ;; Remove detailed master menu listing
            (progn
              (setq master-menu-p t)
              (goto-char (match-beginning 0))
              (let ((end-of-detailed-menu-descriptions
                     (save-excursion     ; beginning of end menu line
                       (goto-char (texinfo-menu-end))

old description into the new entry.

For this function, the new menu is a list made up of lists of dotted
pairs in which the first element of the pair is the node name and the
second element the description.  The new menu is changed destructively.
The old menu is the menu as it appears in the texinfo file."
  
  (let ((new-menu-list-pointer new-menu-list)
        (end-of-menu (texinfo-menu-end)))
    (while new-menu-list
      (save-excursion                   ; keep point at beginning of menu 

         (end-of-line)                  ; go to end of last description line
         (point)))
    ""))

(defun texinfo-menu-end ()
  "Return position of end of menu. Does not change location of point.
Signal an error if not end of menu."
  (save-excursion
    (if (re-search-forward "^@end menu" nil t)
        (point)
      (error "Menu does not have an end."))))

    (save-excursion (insert title))))


;;; Handling description indentation

; Since the make-menu functions indent descriptions, these functions
; are useful primarily for indenting a single menu specially.

(defun texinfo-indent-menu-description (column &optional region-p)
  "Indent every description in menu following point to COLUMN.  
Non-nil argument (prefix, if interactive) means indent every
description in every menu in the region.  Does not indent second and

           (save-excursion
             (or (re-search-forward "^@node" nil t)
                 (error "Too few nodes for a master menu!"))
             (point))))
      (if (re-search-forward texinfo-master-menu-header first-chapter t)
          ;; Remove detailed master menu listing
          (progn
            (goto-char (match-beginning 0))
            (let ((end-of-detailed-menu-descriptions
                   (save-excursion     ; beginning of end menu line
                     (goto-char (texinfo-menu-end))
                     (beginning-of-line) (forward-char -1)

      (goto-char (point-min))
      
      (if (re-search-forward texinfo-master-menu-header nil t)
          (progn
            (goto-char (match-beginning 0))
            (insert "\n")
            (delete-blank-lines)
            (goto-char (point-min))))

      (re-search-forward "^@menu")

  (beginning-of-line)
  (delete-region      ; buffer must have ordinary top menu
   (point)   
   (save-excursion (re-search-forward "^@end menu") (point)))
  
  (save-excursion                       ; leave point at beginning of menu
    ;; Handle top of menu
    (insert "\n@menu\n")
    ;; Insert chapter menu entries
    (setq this-very-menu-list (reverse (car (car master-menu-list))))
    ;; Tell user what is going on.
    (message "Inserting chapter menu entry: %s ... " this-very-menu-list)
    (while this-very-menu-list
      (insert "* " (car this-very-menu-list) "\n")
      (setq this-very-menu-list (cdr this-very-menu-list)))
    
    (setq master-menu-list (cdr master-menu-list))
    
    ;; Now, insert all the other menus (if we have any).
    
    ;; The menu master-menu-list has a form like this:
    ;; ((("beta"  "alpha") "title-A")
    ;;  (("delta" "gamma") "title-B"))

    (if (car (car master-menu-list))
	(progn
	  (insert "\n@detailmenu\n")
	  (insert texinfo-master-menu-header)
    
	  (while master-menu-list

	    (message
	     "Inserting menu for %s .... " (car (cdr (car master-menu-list))))
	    ;; insert title of menu section
	    (insert "\n" (car (cdr (car master-menu-list))) "\n\n")

	    ;; insert each menu entry
	    (setq this-very-menu-list (reverse (car (car master-menu-list))))
	    (while this-very-menu-list
	      (insert "* " (car this-very-menu-list) "\n")
	      (setq this-very-menu-list (cdr this-very-menu-list)))

	    (setq master-menu-list (cdr master-menu-list)))

	  (insert "@end detaimenu\n")))
    
    ;; Finish menu
    (insert "@end menu\n\n")))

(defun texinfo-locate-menu-p ()
  "Find the next menu in the texinfo file.
If found, leave point after word `menu' on the `@menu' line, and return t.
If a menu is not found, do not move point and return nil."

        (delete-region (1- (point)) eol-point)))
  (beginning-of-line))

(defun texinfo-find-pointer (beginning end level direction)
  "Move point to section associated with next, previous, or up pointer.
Return type of pointer (either 'normal or 'no-pointer).

The first and second arguments bound the search for a pointer to the
beginning and end, respectively, of the enclosing higher level
section.  The third argument is a string specifying the general kind
of section such as \"chapter\" or \"section\".  When looking for the

          (t
           (error "texinfo-find-pointer: lack proper arguments")))))

(defun texinfo-pointer-name (kind)
  "Return the node name preceding the section command.
The argument is the kind of section, either normal or no-pointer."
  (let (name)
    (cond ((eq kind 'normal)
           (end-of-line)                ; this handles prev node top case
           (re-search-backward          ; when point is already 
            "^@node"                    ; at the beginning of @node line
            (save-excursion (forward-line -3))
            t)
           (setq name (texinfo-copy-node-name)))
	  ((eq kind 'no-pointer)
	   (setq name " ")))	; put a blank in the pointer slot
    name))

(defun texinfo-insert-pointer (beginning end level direction)
  "Insert the `Next', `Previous' or `Up' node name at point.

The first and second arguments bound the search for a pointer to the
beginning and end, respectively, of the enclosing higher level
section.  The third argument is the hierarchical level of the Texinfo
file, a string such as \"section\".  The fourth argument is direction
towards which the pointer is directed, one of `next, `previous, or
'up."

  (end-of-line)
  (insert
   ", "
   (save-excursion

  (skip-chars-backward ", ")
  (delete-region (point) (save-excursion (end-of-line) (point))))


;;; Updating nodes sequentially
; These sequential update functions insert `Next' or `Previous'
; pointers that point to the following or preceding nodes even if they
; are at higher or lower hierarchical levels.  This means that if a
; section contains one or more subsections, the section's `Next'
; pointer will point to the subsection and not the following section.
; (The subsection to which `Next' points will most likely be the first
; item on the section's menu.)

;;;###autoload
(defun texinfo-sequential-node-update (&optional region-p)
  "Update one node (or many) in a Texinfo file with sequential pointers.

(defun texinfo-sequentially-find-pointer (level direction)
  "Find next or previous pointer sequentially in Texinfo file, or up pointer.
Move point to section associated with the pointer.  Find point even if
it is in a different section.

Return type of pointer (either 'normal or 'no-pointer).

The first argument is a string specifying the general kind of section
such as \"chapter\" or \"section\".  The section found will be at the
same hierarchical level in the Texinfo file, or, in the case of the up
pointer, some level higher.  The second argument (one of 'next,
'previous, or 'up) specifies whether to find the `Next', `Previous',
or `Up' pointer."
  (let ((case-fold-search t))  
    (cond ((eq direction 'next)
           (forward-line 3)             ; skip over current node
           (if (re-search-forward 

  "Insert the `Next', `Previous' or `Up' node name at point.
Move point forward.  

The first argument is the hierarchical level of the Texinfo file, a
string such as \"section\".  The second argument is direction, one of
`next, `previous, or 'up."

  (end-of-line)
  (insert
   ", "
   (save-excursion
     (texinfo-pointer-name
      (texinfo-sequentially-find-pointer level direction)))))


;;; Inserting `@node' lines
; The `texinfo-insert-node-lines' function inserts `@node' lines as needed
; before the `@chapter', `@section', and such like lines of a region
; in a Texinfo file.

(defun texinfo-insert-node-lines (beginning end &optional title-p)
  "Insert missing `@node' lines in region of Texinfo file.
Non-nil argument (prefix, if interactive) means also to insert the
section titles as node names; and also to insert the section titles as
node names in pre-existing @node lines that lack names."
  (interactive "r\nP")

  ;; Use marker; after inserting node lines, leave point at end of
  ;; region and mark at beginning.

  * each of the included files must contain exactly one highest
    hierarchical level node, 
  * this node must be the first node in the included file,
  * each highest hierarchical level node must be of the same type.

Thus, normally, each included file contains one, and only one,
chapter."

; The menu-list has the form:
; 
;     \(\(\"node-name1\" . \"title1\"\) 
;       \(\"node-name2\" . \"title2\"\) ... \)
; 
; However, there does not need to be a title field and this function
; does not fill it; however a comment tells you how to do so.
; You would use the title field if you wanted to insert titles in the
; description slot of a menu as a description.
  
  (let ((case-fold-search t)
        menu-list)
    
    ;; Find the name of the first node of the first included file.

    (nreverse menu-list)))

(defun texinfo-multi-files-insert-main-menu (menu-list)
  "Insert formatted main menu at point.
Indents the first line of the description, if any, to the value of
texinfo-column-for-description."

  (insert "@menu\n")
  (while menu-list
    ;; Every menu entry starts with a star and a space.
    (insert "* ")

  (if make-master-menu
      (progn
        ;; First, removing detailed part of any pre-existing master menu
        (goto-char (point-min))
        (if (re-search-forward texinfo-master-menu-header nil t)
            ;; Remove detailed master menu listing
            (progn
              (goto-char (match-beginning 0))
              (let ((end-of-detailed-menu-descriptions
                     (save-excursion     ; beginning of end menu line
                       (goto-char (texinfo-menu-end))
                       (beginning-of-line) (forward-char -1)
                       (point))))

18259:379252f79147

      (push-mark (point-max) t)
      (goto-char (point-min))
      (message "Checking for a master menu in %s ... "(buffer-name))
      (save-excursion
        (if (re-search-forward texinfo-master-menu-header nil t)
            (progn
              ;; Check if @detailmenu kludge is used;
              ;; if so, leave point before @detailmenu.
              (search-backward "\n@detailmenu" 
			       (save-excursion (forward-line -3) (point))
			       t)
	      ;; Remove detailed master menu listing
              (setq master-menu-p t)
              (goto-char (match-beginning 0))
              (let ((end-of-detailed-menu-descriptions
                     (save-excursion     ; beginning of end menu line
                       (goto-char (texinfo-menu-end))

old description into the new entry.

For this function, the new menu is a list made up of lists of dotted
pairs in which the first element of the pair is the node name and the
second element the description.  The new menu is changed destructively.
The old menu is the menu as it appears in the Texinfo file."
  
  (let ((new-menu-list-pointer new-menu-list)
        (end-of-menu (texinfo-menu-end)))
    (while new-menu-list
      (save-excursion                   ; keep point at beginning of menu 

         (end-of-line)                  ; go to end of last description line
         (point)))
    ""))

(defun texinfo-menu-end ()
  "Return position of end of menu, but don't move point.
Signal an error if not end of menu."
  (save-excursion
    (if (re-search-forward "^@end menu" nil t)
        (point)
      (error "Menu does not have an end."))))

    (save-excursion (insert title))))


;;; Handling description indentation

;; Since the make-menu functions indent descriptions, these functions
;; are useful primarily for indenting a single menu specially.

(defun texinfo-indent-menu-description (column &optional region-p)
  "Indent every description in menu following point to COLUMN.  
Non-nil argument (prefix, if interactive) means indent every
description in every menu in the region.  Does not indent second and

           (save-excursion
             (or (re-search-forward "^@node" nil t)
                 (error "Too few nodes for a master menu!"))
             (point))))
      (if (re-search-forward texinfo-master-menu-header first-chapter t)
          (progn
            ;; Check if @detailmenu kludge is used;
            ;; if so, leave point before @detailmenu.
            (search-backward "\n@detailmenu" 
			     (save-excursion (forward-line -3) (point))
			     t)
	    ;; Remove detailed master menu listing
            (goto-char (match-beginning 0))
            (let ((end-of-detailed-menu-descriptions
                   (save-excursion     ; beginning of end menu line
                     (goto-char (texinfo-menu-end))
                     (beginning-of-line) (forward-char -1)

      (goto-char (point-min))
      
      (if (re-search-forward texinfo-master-menu-header nil t)
          (progn
            (goto-char (match-beginning 0))
            ;; Check if @detailmenu kludge is used;
            ;; if so, leave point before @detailmenu.
            (search-backward "\n@detailmenu" 
			     (save-excursion (forward-line -3) (point))
			     t)
            (insert "\n")
            (delete-blank-lines)
            (goto-char (point-min))))

      (re-search-forward "^@menu")

  (beginning-of-line)
  (delete-region      ; buffer must have ordinary top menu
   (point)   
   (save-excursion (re-search-forward "^@end menu") (point)))
  
  (save-excursion 
    ;; `master-menu-inserted-p' is a kludge to tell 
    ;; whether to insert @end detailmenu (see bleow)
    (let (master-menu-inserted-p)
      ;; Handle top of menu
      (insert "\n@menu\n")
      ;; Insert chapter menu entries
      (setq this-very-menu-list (reverse (car (car master-menu-list))))
      ;; Tell user what is going on.
      (message "Inserting chapter menu entry: %s ... " this-very-menu-list)
      (while this-very-menu-list
        (insert "* " (car this-very-menu-list) "\n")
        (setq this-very-menu-list (cdr this-very-menu-list)))
    
      (setq master-menu-list (cdr master-menu-list))
    
      ;; Only insert detailed master menu if there is one....
      (if (car (car master-menu-list))
          (progn (setq master-menu-inserted-p t)
                 (insert (concat "\n@detailmenu" texinfo-master-menu-header))))

      ;; @detailmenu added 5 Sept 1996 to `texinfo-master-menu-header'
      ;; at Karl Berry's request to avert a bug in `makeinfo';
      ;; all agree this is a bad kludge and should eventually be removed.
      ;; @detailmenu ... @end detailmenu is a noop in `texinfmt.el'.
      ;; See @end detailmenu below;
      ;; also see `texinfo-all-menus-update' above, `texinfo-master-menu',
      ;; `texinfo-multiple-files-update'.

      ;; Now, insert all the other menus
    
      ;; The menu master-menu-list has a form like this:
      ;; ((("beta"  "alpha") "title-A")
      ;;  (("delta" "gamma") "title-B"))
    
      (while master-menu-list
      
        (message
         "Inserting menu for %s .... " (car (cdr (car master-menu-list))))
        ;; insert title of menu section
        (insert "\n" (car (cdr (car master-menu-list))) "\n\n")
      
        ;; insert each menu entry
        (setq this-very-menu-list (reverse (car (car master-menu-list))))
        (while this-very-menu-list
          (insert "* " (car this-very-menu-list) "\n")
          (setq this-very-menu-list (cdr this-very-menu-list)))
      
        (setq master-menu-list (cdr master-menu-list)))
    
      ;; Finish menu

      ;; @detailmenu (see note above)
      ;; Only insert @end detailmenu if a master menu was inserted.
      (if master-menu-inserted-p
          (insert "\n@end detailmenu"))
      (insert "\n@end menu\n\n"))))

(defun texinfo-locate-menu-p ()
  "Find the next menu in the texinfo file.
If found, leave point after word `menu' on the `@menu' line, and return t.
If a menu is not found, do not move point and return nil."

        (delete-region (1- (point)) eol-point)))
  (beginning-of-line))

(defun texinfo-find-pointer (beginning end level direction)
  "Move point to section associated with next, previous, or up pointer.
Return type of pointer (either `normal' or `no-pointer').

The first and second arguments bound the search for a pointer to the
beginning and end, respectively, of the enclosing higher level
section.  The third argument is a string specifying the general kind
of section such as \"chapter\" or \"section\".  When looking for the

          (t
           (error "texinfo-find-pointer: lack proper arguments")))))

(defun texinfo-pointer-name (kind)
  "Return the node name preceding the section command.
The argument is the kind of section, either `normal' or `no-pointer'."
  (let (name)
    (cond ((eq kind 'normal)
           (end-of-line)                ; this handles prev node top case
           (re-search-backward          ; when point is already 
            "^@node"                    ; at the beginning of @node line
            (save-excursion (forward-line -3))
            t)
           (setq name (texinfo-copy-node-name)))
	  ((eq kind 'no-pointer)
           ;; Don't need to put a blank in the pointer slot,
           ;; since insert "' " always has a space
	   (setq name " ")))	; put a blank in the pointer slot
    name))

(defun texinfo-insert-pointer (beginning end level direction)
  "Insert the `Next', `Previous' or `Up' node name at point.

The first and second arguments bound the search for a pointer to the
beginning and end, respectively, of the enclosing higher level
section.  The third argument is the hierarchical level of the Texinfo
file, a string such as \"section\".  The fourth argument is direction
towards which the pointer is directed, one of `next', `previous', or `up'."

  (end-of-line)
  (insert
   ", "
   (save-excursion

  (skip-chars-backward ", ")
  (delete-region (point) (save-excursion (end-of-line) (point))))


;;; Updating nodes sequentially
;; These sequential update functions insert `Next' or `Previous'
;; pointers that point to the following or preceding nodes even if they
;; are at higher or lower hierarchical levels.  This means that if a
;; section contains one or more subsections, the section's `Next'
;; pointer will point to the subsection and not the following section.
;; (The subsection to which `Next' points will most likely be the first
;; item on the section's menu.)

;;;###autoload
(defun texinfo-sequential-node-update (&optional region-p)
  "Update one node (or many) in a Texinfo file with sequential pointers.

(defun texinfo-sequentially-find-pointer (level direction)
  "Find next or previous pointer sequentially in Texinfo file, or up pointer.
Move point to section associated with the pointer.  Find point even if
it is in a different section.

Return type of pointer (either `normal' or `no-pointer').

The first argument is a string specifying the general kind of section
such as \"chapter\" or \"section\".  The section found will be at the
same hierarchical level in the Texinfo file, or, in the case of the up
pointer, some level higher.  The second argument (one of `next',
`previous', or `up') specifies whether to find the `Next', `Previous',
or `Up' pointer."
  (let ((case-fold-search t))  
    (cond ((eq direction 'next)
           (forward-line 3)             ; skip over current node
           (if (re-search-forward 

  "Insert the `Next', `Previous' or `Up' node name at point.
Move point forward.  

The first argument is the hierarchical level of the Texinfo file, a
string such as \"section\".  The second argument is direction, one of
`next', `previous', or `up'."

  (end-of-line)
  (insert
   ", "
   (save-excursion
     (texinfo-pointer-name
      (texinfo-sequentially-find-pointer level direction)))))


;;; Inserting `@node' lines
;; The `texinfo-insert-node-lines' function inserts `@node' lines as needed
;; before the `@chapter', `@section', and such like lines of a region
;; in a Texinfo file.

(defun texinfo-insert-node-lines (beginning end &optional title-p)
  "Insert missing `@node' lines in region of Texinfo file.
Non-nil argument (prefix, if interactive) means also to insert the
section titles as node names; and also to insert the section titles as
node names in pre-existing `@node' lines that lack names."
  (interactive "r\nP")

  ;; Use marker; after inserting node lines, leave point at end of
  ;; region and mark at beginning.

  * each of the included files must contain exactly one highest
    hierarchical level node, 
  * this node must be the first node in the included file,
  * each highest hierarchical level node must be of the same type.

Thus, normally, each included file contains one, and only one, chapter."

;; The menu-list has the form:
;; 
;;     \(\(\"node-name1\" . \"title1\"\) 
;;       \(\"node-name2\" . \"title2\"\) ... \)
;; 
;; However, there does not need to be a title field and this function
;; does not fill it; however a comment tells you how to do so.
;; You would use the title field if you wanted to insert titles in the
;; description slot of a menu as a description.
  
  (let ((case-fold-search t)
        menu-list)
    
    ;; Find the name of the first node of the first included file.

    (nreverse menu-list)))

(defun texinfo-multi-files-insert-main-menu (menu-list)
  "Insert formatted main menu at point.
Indents the first line of the description, if any, to the value of
`texinfo-column-for-description'."

  (insert "@menu\n")
  (while menu-list
    ;; Every menu entry starts with a star and a space.
    (insert "* ")

  (if make-master-menu
      (progn
        ;; First, removing detailed part of any pre-existing master menu
        (goto-char (point-min))
        (if (re-search-forward texinfo-master-menu-header nil t)
            (progn
              (goto-char (match-beginning 0))
	      ;; Check if @detailmenu kludge is used;
	      ;; if so, leave point before @detailmenu.
	      (search-backward "\n@detailmenu" 
			       (save-excursion (forward-line -3) (point))
			       t)
	      ;; Remove detailed master menu listing
              (let ((end-of-detailed-menu-descriptions
                     (save-excursion     ; beginning of end menu line
                       (goto-char (texinfo-menu-end))
                       (beginning-of-line) (forward-char -1)
                       (point))))