Info enhancements

Info enhancements

[Juri Linkov]

I would like to submit a patch that fixes some problems in the Emacs
Info reader and adds features most web browsers already have.
This patch don't change the existing Info file format.  It improves
usability of the Emacs Info reader with the current Info file format.
Any comments are welcome.

New features:

- distinguish visited nodes from unvisited by displaying their
  references in a different color.  Standard colors of web browsers
  are used: blue - for unvisited links, magenta - for visited links.

- show full history list or tree of visited Info nodes.  This list is
  displayed in the Info buffer using "*Note" references, so standard
  Info functions can be used for navigation to visited nodes from the
  history buffer.

- http links are fontified and available for navigation by calling the
  `browse-url' function.

- a new argument `fork' is added to Info-follow-reference,
  Info-follow-nearest-node and Info-try-follow-nearest-node functions,
  so if these functions are called interactively with a prefix arg,
  they show the node in a new info buffer.  This feature is copied
  from the `Info-menu' which works only for menu items.  But this is
  useful for references too, especially for references that carry out
  of the current manual.

- use reference names to move point to the place within the current
  node where reference name is defined.  For example, by following the
  reference "*Note file-coding-system-alist: Default Coding Systems,"
  Info finds a node with the name "Default Coding Systems" and moves
  point to the line where reference name "file-coding-system-alist" is
  defined.  This feature uses the function `Info-find-index-name' that
  currently works only for the function `Info-index'.  Now it works
  also for index items and cross references.  This feature solves
  problems in the Glossary node of the Emacs manual, where links to
  the same node are marked by the "(q.v.)" or "See `text'".  Such text
  can be replaced in references to the same node with this text as a
  reference name.  For example, the text "is shared by an indirect
  buffer (q.v.@:)" can be replaced with "is shared by an
  @ref{Glossary,indirect buffer}", and text "See `filling.'" can be
  replaced with "@xref{Glossary,filling}.".  Following such a
  reference will move point to the place in the same node where this
  glossary term is defined.

- rebind `M-s' key to a new function `Info-search-next' that searches
  for another occurrence of regular expression from a previous
  `Info-search' command (key `s').  Pressing only one key to repeat
  a search is more convenient than pressing two keys (`s RET').

Fixed problems:

- don't hide the newline (with following whitespace) in references when
  Info-hide-note-references is t.  This fixes the problem where hidden
  newlines cause too long (and truncated) lines.

- don't hide the name of external Info file in references in case
  when Info-hide-note-references is t and references lead outside
  the current Info file.  It's important for user to know about
  such situation.

- don't insert the text "See" instead of "Note" because inserting a
  new text in Info buffer breaks the stored point positions. This bug
  can be observed by calling `Info-last', `Info-search' where point is
  moved with some offset to its correct position (the offset is the sum
  of lengths of strings "See" inserted in the buffer above the point).

- add a character ` to the list of prefix characters used to escape
  the literal meaning of the text "*Note".  The wrong fontification
  caused by this bug can be observed in (info "(info)Cross-refs").

Index: emacs/lisp/info.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/info.el,v
retrieving revision 1.374
diff -c -r1.374 info.el
*** emacs/lisp/info.el	 7 Oct 2003 00:04:45 -0000	1.374
--- emacs/lisp/info.el	 1 Dec 2003 11:48:03 -0000
***************
*** 48,53 ****
--- 48,60 ----
    "List of info nodes user has visited.
  Each element of list is a list (FILENAME NODENAME BUFFERPOS).")
  
+ (defvar Info-history-tree nil
+   "Tree of info nodes user has visited.
+ Each element of list is a list (FILENAME NODENAME PARENT-INDEX).")
+ 
+ (defvar Info-history-node -1
+   "Position of the current node on the info nodes tree user has visited.")
+ 
  (defcustom Info-enable-edit nil
    "*Non-nil means the \\<Info-mode-map>\\[Info-edit] command in Info can edit the current node.
  This is convenient if you want to write info files by hand.
***************
*** 76,87 ****
    :group 'info)
  
  (defface info-xref
!   '((((class color) (background light)) (:foreground "magenta4" :weight bold))
!     (((class color) (background dark)) (:foreground "cyan" :weight bold))
!     (t (:weight bold)))
    "Face for Info cross-references."
    :group 'info)
  
  (defcustom Info-fontify-maximum-menu-size 100000
    "*Maximum size of menu to fontify if `font-lock-mode' is non-nil."
    :type 'integer
--- 83,107 ----
    :group 'info)
  
  (defface info-xref
!   '((((class color) (background light)) (:foreground "blue"))
!     (((class color) (background dark)) (:foreground "cyan"))
!     (t (:underline t)))
    "Face for Info cross-references."
    :group 'info)
  
+ (defface info-xref-visited
+   '((((class color) (background light)) (:foreground "magenta4"))
+     (((class color) (background dark)) (:foreground "magenta4"))
+     (t (:underline t)))
+   "Face for visited Info cross-references."
+   :group 'info)
+ 
+ (defcustom Info-visited-nodes t
+   "*Non-nil means to fontify visited nodes in a different color."
+   :version "21.4"
+   :type 'boolean
+   :group 'info)
+ 
  (defcustom Info-fontify-maximum-menu-size 100000
    "*Maximum size of menu to fontify if `font-lock-mode' is non-nil."
    :type 'integer
***************
*** 155,161 ****
  
  (defcustom Info-hide-note-references t
    "*If non-nil, hide the tag and section reference in *note and * menu items.
- Also replaces the \"*note\" text with \"see\".
  If value is non-nil but not t, the reference section is still shown."
    :version "21.4"
    :type '(choice (const :tag "No reformatting" nil)
--- 175,180 ----
***************
*** 205,210 ****
--- 224,232 ----
  (defvar Info-index-alternatives nil
    "List of possible matches for last `Info-index' command.")
  
+ (defvar Info-reference-name nil
+   "Name of the current reference.")
+ 
  (defvar Info-standalone nil
    "Non-nil if Emacs was started solely as an Info browser.")
  \f
***************
*** 787,793 ****
  		       nodename)))
  
  	    (Info-select-node)
! 	    (goto-char (or anchorpos (point-min))))))
      ;; If we did not finish finding the specified node,
      ;; go back to the previous one.
      (or Info-current-node no-going-back (null Info-history)
--- 809,820 ----
  		       nodename)))
  
  	    (Info-select-node)
! 	    (goto-char (or anchorpos (point-min)))
! 
!             ;; Move point to the place where the referer name points to
!             (when Info-reference-name
!               (Info-find-index-name Info-reference-name)
!               (setq Info-reference-name nil)))))
      ;; If we did not finish finding the specified node,
      ;; go back to the previous one.
      (or Info-current-node no-going-back (null Info-history)
***************
*** 1176,1181 ****
--- 1203,1225 ----
  	(if Info-enable-active-nodes (eval active-expression))
  	(Info-fontify-node)
  	(Info-display-images-node)
+ 
+         ;; Add a new history node or use old node from the history tree
+         (let ((tree Info-history-tree)
+               (i 0) res)
+           (while tree
+             (if (and (equal (nth 0 (car tree)) Info-current-file)
+                      (equal (nth 1 (car tree)) Info-current-node))
+                 (setq res i tree nil))
+             (setq tree (cdr tree) i (1+ i)))
+           (if res
+               (setq Info-history-node res)
+             (setq Info-history-tree
+                   (nconc Info-history-tree
+                          (list (list Info-current-file Info-current-node
+                                      Info-history-node)))
+                   Info-history-node (1- (length Info-history-tree)))))
+ 
  	(run-hooks 'Info-selection-hook)))))
  
  (defun Info-set-mode-line ()
***************
*** 1207,1212 ****
--- 1251,1258 ----
    (if fork
        (set-buffer
         (clone-buffer (concat "*info-" (if (stringp fork) fork nodename) "*") t)))
+   (if (equal (buffer-name) "*info-history*")
+       (switch-to-buffer "*info*"))
    (let (filename)
      (string-match "\\s *\\((\\s *\\([^\t)]*\\)\\s *)\\s *\\|\\)\\(.*\\)"
  		  nodename)
***************
*** 1409,1414 ****
--- 1455,1468 ----
  	       (equal ofile Info-current-file))
  	  (setq Info-history (cons (list ofile onode opoint)
  				   Info-history))))))
+ 
+ (defun Info-search-next ()
+   "Search for next regexp from a previous `Info-search' command."
+   (interactive)
+   (if Info-search-history
+       (Info-search (car Info-search-history))
+     ;; If no history then read search string in Info-search
+     (call-interactively 'Info-search)))
  \f
  (defun Info-extract-pointer (name &optional errorname)
    "Extract the value of the node-pointer named NAME.
***************
*** 1481,1495 ****
      (setq Info-history (cdr Info-history))
      (goto-char opoint)))
  
  ;;;###autoload
  (defun Info-directory ()
    "Go to the Info directory node."
    (interactive)
    (Info-find-node "dir" "top"))
  \f
! (defun Info-follow-reference (footnotename)
    "Follow cross reference named FOOTNOTENAME to the node it refers to.
! FOOTNOTENAME may be an abbreviation of the reference name."
    (interactive
     (let ((completion-ignore-case t)
  	 (case-fold-search t)
--- 1535,1594 ----
      (setq Info-history (cdr Info-history))
      (goto-char opoint)))
  
+ ;;;###autoload (add-hook 'same-window-buffer-names "*info-history*")
+ 
+ (defun Info-history-buffer (&optional tree-p)
+   "Create the buffer *info-history* with references to visited nodes.
+ Optional argument TREE-P creates a tree of nodes; the default
+ creates the plain list of nodes."
+   (interactive "P")
+   (let ((curr-node Info-history-node)
+         p)
+     (pop-to-buffer
+      (with-current-buffer (get-buffer-create "*info-history*")
+        (let ((Info-hide-note-references t)
+              (Info-visited-nodes t)
+              (inhibit-read-only t))
+          (erase-buffer)
+          (goto-char (point-min))
+          (setq p (Info-insert-history-tree -1 0 (or curr-node 0) tree-p))
+          (if (not (bobp)) (Info-fontify-node))
+          (or (eq major-mode 'Info-mode) (Info-mode))
+          (let ((Info-current-file "history")
+                (Info-current-node "History"))
+            (Info-set-mode-line))
+          (current-buffer))))
+     (goto-char (or p (point-min)))))
+ 
+ (defun Info-insert-history-tree (index indent curr-node tree-p)
+   "Insert the tree or list of references to visited nodes.
+ Return the position of the current node on the generated tree."
+   (let ((tree Info-history-tree)
+         (i 0) p)
+     (while tree
+       (when (or (null tree-p) (eq (nth 2 (car tree)) index))
+         (if tree-p (insert (make-string indent ?\040)))
+         (if (eq i curr-node) (setq p (point)))
+         (insert  "*Note " (nth 1 (car tree)) ": ("
+                  (file-name-nondirectory (nth 0 (car tree)))
+                  ")" (nth 1 (car tree)) ".\n")
+         (if tree-p (setq p (or (Info-insert-history-tree
+                                 i (1+ indent) curr-node tree-p) p))))
+       (setq tree (cdr tree) i (1+ i)))
+     p))
+ 
  ;;;###autoload
  (defun Info-directory ()
    "Go to the Info directory node."
    (interactive)
    (Info-find-node "dir" "top"))
  \f
! (defun Info-follow-reference (footnotename &optional fork)
    "Follow cross reference named FOOTNOTENAME to the node it refers to.
! FOOTNOTENAME may be an abbreviation of the reference name.
! If FORK is non-nil (interactively with a prefix arg), show the node in
! a new info buffer.  If FORK is a string, it is the name to use for the
! new buffer."
    (interactive
     (let ((completion-ignore-case t)
  	 (case-fold-search t)
***************
*** 1539,1545 ****
  					 "Follow reference named: ")
  				       completions nil t)))
  	   (list (if (equal input "")
! 		     default input)))
         (error "No cross-references in this node"))))
  
    (unless footnotename
--- 1638,1644 ----
  					 "Follow reference named: ")
  				       completions nil t)))
  	   (list (if (equal input "")
! 		     default input) current-prefix-arg))
         (error "No cross-references in this node"))))
  
    (unless footnotename
***************
*** 1561,1567 ****
        (setq target (concat (substring target 0 i) " "
  			   (substring target (match-end 0))))
        (setq i (+ i 1)))
!     (Info-goto-node target)))
  
  (defconst Info-menu-entry-name-re "\\(?:[^:]\\|:[^:,.;() \t\n]\\)*"
    ;; We allow newline because this is also used in Info-follow-reference,
--- 1660,1666 ----
        (setq target (concat (substring target 0 i) " "
  			   (substring target (match-end 0))))
        (setq i (+ i 1)))
!     (Info-goto-node target fork)))
  
  (defconst Info-menu-entry-name-re "\\(?:[^:]\\|:[^:,.;() \t\n]\\)*"
    ;; We allow newline because this is also used in Info-follow-reference,
***************
*** 1968,1974 ****
  (defun Info-next-reference (&optional recur)
    "Move cursor to the next cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:")
  	(old-pt (point))
  	(case-fold-search t))
      (or (eobp) (forward-char 1))
--- 2067,2073 ----
  (defun Info-next-reference (&optional recur)
    "Move cursor to the next cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|http://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (eobp) (forward-char 1))
***************
*** 1988,1994 ****
  (defun Info-prev-reference (&optional recur)
    "Move cursor to the previous cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:")
  	(old-pt (point))
  	(case-fold-search t))
      (or (re-search-backward pat nil t)
--- 2087,2093 ----
  (defun Info-prev-reference (&optional recur)
    "Move cursor to the previous cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|http://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (re-search-backward pat nil t)
***************
*** 2209,2220 ****
         (save-excursion (forward-line 1) (eobp))
         (Info-next-preorder)))
  
! (defun Info-follow-nearest-node ()
    "Follow a node reference near point.
  If point is on a reference, follow that reference.  Otherwise,
  if point is in a menu item description, follow that menu item."
!   (interactive)
!   (or (Info-try-follow-nearest-node)
        (when (save-excursion
  	      (search-backward "\n* menu:" nil t))
  	(save-excursion
--- 2308,2319 ----
         (save-excursion (forward-line 1) (eobp))
         (Info-next-preorder)))
  
! (defun Info-follow-nearest-node (&optional fork)
    "Follow a node reference near point.
  If point is on a reference, follow that reference.  Otherwise,
  if point is in a menu item description, follow that menu item."
!   (interactive "P")
!   (or (Info-try-follow-nearest-node fork)
        (when (save-excursion
  	      (search-backward "\n* menu:" nil t))
  	(save-excursion
***************
*** 2223,2257 ****
  	    (beginning-of-line 0))
  	  (when (looking-at "\\* +\\([^\t\n]*\\):")
  	    (Info-goto-node
! 	     (Info-extract-menu-item (match-string-no-properties 1)))
  	    t)))
        (error "Point neither on reference nor in menu item description")))
  
  ;; Common subroutine.
! (defun Info-try-follow-nearest-node ()
    "Follow a node reference near point.  Return non-nil if successful."
    (let (node)
      (cond
       ((setq node (Info-get-token (point) "\\*note[ \n]"
  				 "\\*note[ \n]\\([^:]*\\):"))
!       (Info-follow-reference node))
       ;; menu item: node name
       ((setq node (Info-get-token (point) "\\* +" "\\* +\\([^:]*\\)::"))
!       (Info-goto-node node))
       ;; menu item: index entry
       ((Info-get-token (point) "\\* +" "\\* +\\(.*\\): ")
        (beginning-of-line)
        (forward-char 2)
        (setq node (Info-extract-menu-node-name))
!       (Info-goto-node node))
       ((setq node (Info-get-token (point) "Up: " "Up: \\([^,\n\t]*\\)"))
!       (Info-goto-node node))
       ((setq node (Info-get-token (point) "Next: " "Next: \\([^,\n\t]*\\)"))
!       (Info-goto-node node))
       ((setq node (Info-get-token (point) "File: " "File: \\([^,\n\t]*\\)"))
!       (Info-goto-node "Top"))
       ((setq node (Info-get-token (point) "Prev: " "Prev: \\([^,\n\t]*\\)"))
!       (Info-goto-node node)))
      node))
  \f
  (defvar Info-mode-map nil
--- 2322,2363 ----
  	    (beginning-of-line 0))
  	  (when (looking-at "\\* +\\([^\t\n]*\\):")
  	    (Info-goto-node
! 	     (Info-extract-menu-item (match-string-no-properties 1)) fork)
  	    t)))
        (error "Point neither on reference nor in menu item description")))
  
  ;; Common subroutine.
! (defun Info-try-follow-nearest-node (&optional fork)
    "Follow a node reference near point.  Return non-nil if successful."
    (let (node)
      (cond
+      ((and (Info-get-token (point) "http://" "\\(http://\\)")
+            (or (featurep 'browse-url) (require 'browse-url nil t)))
+       (setq node t)
+       (browse-url (browse-url-url-at-point)))
       ((setq node (Info-get-token (point) "\\*note[ \n]"
  				 "\\*note[ \n]\\([^:]*\\):"))
!       (setq Info-reference-name (replace-regexp-in-string
!                                  "[ \t\n]+" " " (match-string-no-properties 1)))
!       (Info-follow-reference node fork))
       ;; menu item: node name
       ((setq node (Info-get-token (point) "\\* +" "\\* +\\([^:]*\\)::"))
!       (Info-goto-node node fork))
       ;; menu item: index entry
       ((Info-get-token (point) "\\* +" "\\* +\\(.*\\): ")
+       (setq Info-reference-name (match-string-no-properties 1))
        (beginning-of-line)
        (forward-char 2)
        (setq node (Info-extract-menu-node-name))
!       (Info-goto-node node fork))
       ((setq node (Info-get-token (point) "Up: " "Up: \\([^,\n\t]*\\)"))
!       (Info-goto-node node fork))
       ((setq node (Info-get-token (point) "Next: " "Next: \\([^,\n\t]*\\)"))
!       (Info-goto-node node fork))
       ((setq node (Info-get-token (point) "File: " "File: \\([^,\n\t]*\\)"))
!       (Info-goto-node "Top" fork))
       ((setq node (Info-get-token (point) "Prev: " "Prev: \\([^,\n\t]*\\)"))
!       (Info-goto-node node fork)))
      node))
  \f
  (defvar Info-mode-map nil
***************
*** 2295,2306 ****
    (define-key Info-mode-map "p" 'Info-prev)
    (define-key Info-mode-map "q" 'Info-exit)
    (define-key Info-mode-map "s" 'Info-search)
!   ;; For consistency with Rmail.
!   (define-key Info-mode-map "\M-s" 'Info-search)
    (define-key Info-mode-map "\M-n" 'clone-buffer)
    (define-key Info-mode-map "t" 'Info-top-node)
    (define-key Info-mode-map "u" 'Info-up)
    (define-key Info-mode-map "," 'Info-index-next)
    (define-key Info-mode-map "\177" 'Info-scroll-down)
    (define-key Info-mode-map [mouse-2] 'Info-mouse-follow-nearest-node)
    )
--- 2401,2412 ----
    (define-key Info-mode-map "p" 'Info-prev)
    (define-key Info-mode-map "q" 'Info-exit)
    (define-key Info-mode-map "s" 'Info-search)
!   (define-key Info-mode-map "\M-s" 'Info-search-next)
    (define-key Info-mode-map "\M-n" 'clone-buffer)
    (define-key Info-mode-map "t" 'Info-top-node)
    (define-key Info-mode-map "u" 'Info-up)
    (define-key Info-mode-map "," 'Info-index-next)
+   (define-key Info-mode-map "\\" 'Info-history-buffer)
    (define-key Info-mode-map "\177" 'Info-scroll-down)
    (define-key Info-mode-map [mouse-2] 'Info-mouse-follow-nearest-node)
    )
***************
*** 2335,2344 ****
     ("Reference" ["You should never see this" report-emacs-bug t])
     ["Search..." Info-search
      :help "Search for regular expression in this Info file"]
     ["Go to Node..." Info-goto-node
      :help "Go to a named node"]
!    ["Last" Info-last :active Info-history
      :help "Go to the last node you were at"]
     ("Index..."
      ["Lookup a String" Info-index
       :help "Look for a string in the index items"]
--- 2441,2454 ----
     ("Reference" ["You should never see this" report-emacs-bug t])
     ["Search..." Info-search
      :help "Search for regular expression in this Info file"]
+    ["Search Next" Info-search-next
+     :help "Search for another occurrence of regular expression"]
     ["Go to Node..." Info-goto-node
      :help "Go to a named node"]
!    ["Last (Back)" Info-last :active Info-history
      :help "Go to the last node you were at"]
+    ["History" Info-history-buffer :active Info-history-tree
+     :help "Go to the history buffer"]
     ("Index..."
      ["Lookup a String" Info-index
       :help "Look for a string in the index items"]
***************
*** 2476,2481 ****
--- 2586,2592 ----
  \\[Info-directory]	Go to the Info directory node.
  \\[Info-follow-reference]	Follow a cross reference.  Reads name of reference.
  \\[Info-last]	Move to the last node you were at.
+ \\[Info-history-buffer]	Go to the history buffer.
  \\[Info-index]	Look up a topic in this file's Index and move to that node.
  \\[Info-index-next]	(comma) Move to the next match from a previous `i' command.
  \\[Info-top-node]	Go to the Top node of this file.
***************
*** 2504,2509 ****
--- 2615,2622 ----
  \\[universal-argument] \\[info]	Move to new Info file with completion.
  \\[Info-search]	Search through this Info file for specified regexp,
  	  and select the node in which the next occurrence is found.
+ \\[Info-search-next]	Search for another occurrence of regexp
+ 	  from a previous `Info-search' command.
  \\[Info-next-reference]	Move cursor to next cross-reference or menu item.
  \\[Info-prev-reference]	Move cursor to previous cross-reference or menu item."
    (kill-all-local-variables)
***************
*** 2524,2529 ****
--- 2637,2643 ----
    (make-local-variable 'Info-tag-table-buffer)
    (setq Info-tag-table-buffer nil)
    (make-local-variable 'Info-history)
+   (make-local-variable 'Info-history-node)
    (make-local-variable 'Info-index-alternatives)
    (setq header-line-format
  	(if Info-use-header-line
***************
*** 2833,2841 ****
    "Keymap to put on the Up link in the text or the header line.")
  
  (defun Info-fontify-node ()
!   ;; Only fontify the node if it hasn't already been done.
!   (unless (let ((where (next-property-change (point-min))))
!             (and where (not (= where (point-max)))))
      (save-excursion
        (let ((inhibit-read-only t)
  	    (case-fold-search t)
--- 2947,2957 ----
    "Keymap to put on the Up link in the text or the header line.")
  
  (defun Info-fontify-node ()
!   ;; Only fontify the node if it hasn't already been done
!   ;; or always fontify visited nodes (because of their dynamic nature).
!   (when (or Info-visited-nodes
!             (not (let ((where (next-property-change (point-min))))
!                    (and where (not (= where (point-max)))))))
      (save-excursion
        (let ((inhibit-read-only t)
  	    (case-fold-search t)
***************
*** 2911,2961 ****
  	    (add-text-properties (1- (match-beginning 2)) (match-end 2)
  				 '(invisible t front-sticky nil rear-nonsticky t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\(\\*Note[ \t]*\\)\n?[ \t]*\\([^:]*\\)\\(:[^.,:(]*\\(([^)]*)[^.,:]*\\)?[,:]?\n?\\)" nil t)
! 	  (unless (= (char-after (1- (match-beginning 0))) ?\") ; hack
  	    (let ((start (match-beginning 0))
! 		  (next (point))
! 		  (hide-tag Info-hide-note-references)
! 		  other-tag)
! 	      (when hide-tag
! 		;; *Note is often used where *note should have been
! 		(goto-char start)
! 		(skip-syntax-backward " ")
! 		(setq other-tag
! 		      (cond ((memq (char-before) '(nil ?\. ?! ??))
! 			     "See ")
! 			    ((memq (char-before) '(?\, ?\; ?\: ?-))
! 			     "see ")
! 			    ((memq (char-before) '(?\( ?\[ ?\{))
! 			     ;; Check whether the paren is preceded by
! 			     ;; an end of sentence
! 			     (skip-syntax-backward " (")
! 			     (if (memq (char-before) '(nil ?\. ?! ??))
! 				 "See "
! 			       "see "))
! 			    ((save-match-data (looking-at "\n\n"))
! 			     "See ")))
! 		(goto-char next))
! 	      (if hide-tag
! 		  (add-text-properties (match-beginning 1) (match-end 1)
! 				       '(invisible t front-sticky nil rear-nonsticky t)))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
! 	       (cons 'help-echo
! 		     (cons (if (match-end 4)
! 			       (concat "mouse-2: go to " (match-string 4))
! 			     "mouse-2: go to this node")
! 			   '(font-lock-face info-xref
! 			     mouse-face highlight))))
  	      (when (eq Info-hide-note-references t)
  		(add-text-properties (match-beginning 3) (match-end 3)
! 				     '(invisible t front-sticky nil rear-nonsticky t)))
! 	      (when other-tag
! 		(save-excursion
! 		  (goto-char (match-beginning 1))
! 		  (insert other-tag)))
! 	      (when (and Info-refill-paragraphs
! 			 (or hide-tag (eq Info-hide-note-references t)))
  		(push (set-marker (make-marker) start)
  		      paragraph-markers)))))
  
--- 3027,3101 ----
  	    (add-text-properties (1- (match-beginning 2)) (match-end 2)
  				 '(invisible t front-sticky nil rear-nonsticky t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\(\\*Note[ \t]*\\)\n?[ \t]*\\([^:]*\\)\\(:[^.,:(]*\\((\\([^)]*\\))\\([^.,:]*\\)\\)?[,:]?\n?\\)" nil t)
! 	  (unless (memq (char-after (1- (match-beginning 0))) '(?\" ?\`)) ; hack
  	    (let ((start (match-beginning 0))
! ;; 		  (next (point))
! ;; 		  other-tag
!                   )
! 	      (when Info-hide-note-references
! ;; 		;; *Note is often used where *note should have been
! ;; 		(goto-char start)
! ;; 		(skip-syntax-backward " ")
! ;; 		(setq other-tag
! ;;                       (cond ((memq (char-before) '(nil ?\. ?! ??))
! ;;                              "See ")
! ;;                             ((memq (char-before) '(?\, ?\; ?\: ?-))
! ;;                              "see ")
! ;;                             ((memq (char-before) '(?\( ?\[ ?\{))
! ;;                              ;; Check whether the paren is preceded by
! ;;                              ;; an end of sentence
! ;;                              (skip-syntax-backward " (")
! ;;                              (if (memq (char-before) '(nil ?\. ?! ??))
! ;;                                  "See "
! ;;                                "see "))
! ;;                             ((save-match-data (looking-at "\n\n"))
! ;;                              "See ")))
! ;; 		(goto-char next)
!                 (add-text-properties (match-beginning 1) (match-end 1)
!                                      '(invisible t front-sticky nil rear-nonsticky t)))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
!                (list
!                 'help-echo (if (match-end 4)
!                                (concat "mouse-2: go to " (match-string 4))
!                              "mouse-2: go to this node")
!                 'font-lock-face
!                 ;; Display visited nodes in a different face
!                 (if (and Info-visited-nodes
!                          (save-match-data
!                            (let* ((file (concat (or (match-string 5) Info-current-file) "$"))
!                                   (node (replace-regexp-in-string
!                                          "[ \t\n]+" " "
!                                          (or (match-string 6) (match-string 2))))
!                                   (l Info-history-tree)
!                                   res)
!                              (while l
!                                (if (and (equal (cadr (car l)) node)
!                                         (string-match file (caar l)))
!                                    (setq res (car l) l nil))
!                                (setq l (cdr l)))
!                              res))) 'info-xref-visited 'info-xref)
!                 'mouse-face 'highlight))
  	      (when (eq Info-hide-note-references t)
  		(add-text-properties (match-beginning 3) (match-end 3)
! 				     '(invisible t front-sticky nil rear-nonsticky t))
!                 ;; Unhide the file name of the reference in parens
!                 (if (match-string 5)
!                     (remove-text-properties (1- (match-beginning 5)) (1+ (match-end 5))
!                                             '(invisible t front-sticky nil rear-nonsticky t)))
!                 ;; Unhide newline because hidden newlines cause too long lines
!                 (save-match-data
!                   (let ((start3 (match-beginning 3)))
!                     (if (string-match "\n[ \t]*" (match-string 3))
!                         (remove-text-properties (+ start3 (match-beginning 0)) (+ start3 (match-end 0))
!                                                 '(invisible t front-sticky nil rear-nonsticky t)))))
!                 )
! ;; 	      (when other-tag
! ;; 		(save-excursion
! ;; 		  (goto-char (match-beginning 1))
! ;; 		  (insert other-tag)))
! 	      (when (and Info-refill-paragraphs Info-hide-note-references)
  		(push (set-marker (make-marker) start)
  		      paragraph-markers)))))
  
***************
*** 2997,3009 ****
  				     'font-lock-face 'info-menu-5))
  	      (add-text-properties
  	       (match-beginning 1) (match-end 1)
! 	       (cons 'help-echo
! 		     (cons
! 		      (if (match-end 3)
! 			  (concat "mouse-2: go to " (match-string 3))
! 			"mouse-2: go to this node")
! 		      '(font-lock-face info-xref
! 			mouse-face highlight))))
  	      (when (eq Info-hide-note-references t)
  		(put-text-property (match-beginning 2) (1- (match-end 6))
  				   'invisible t)
--- 3137,3161 ----
  				     'font-lock-face 'info-menu-5))
  	      (add-text-properties
  	       (match-beginning 1) (match-end 1)
!                (list
!                 'help-echo (if (match-end 3)
!                                (concat "mouse-2: go to " (match-string 3))
!                              "mouse-2: go to this node")
!                 'font-lock-face
!                 ;; Display visited nodes in a different face
!                 (if (and Info-visited-nodes
!                          (let ((node (if (equal (match-string 3) "")
!                                          (match-string 1)
!                                        (match-string 3)))
!                                (l Info-history-tree)
!                                res)
!                            (while l
!                              (if (and (equal (cadr (car l)) node)
!                                       (equal Info-current-file (caar l)))
!                                  (setq res (car l) l nil))
!                              (setq l (cdr l)))
!                            res)) 'info-xref-visited 'info-xref)
!                 'mouse-face 'highlight))
  	      (when (eq Info-hide-note-references t)
  		(put-text-property (match-beginning 2) (1- (match-end 6))
  				   'invisible t)
***************
*** 3026,3031 ****
--- 3178,3190 ----
  				       '(space :align-to 24)))
  		  (setq cont t))))))
  
+ 	(goto-char (point-min))
+ 	(while (re-search-forward "http://[-~/[:alnum:]_.${}#%,:?=&]+" nil t)
+           (add-text-properties (match-beginning 0) (match-end 0)
+                                '(font-lock-face info-xref
+                                  mouse-face highlight
+                                  help-echo "mouse-2: go to this URL")))
+ 
  	(Info-fontify-menu-headers)
  	(set-buffer-modified-p nil)))))
  \f
===================================================================

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

I have not yet had the time to look at your patch in detail.  I just
looked at one feature:

   - use reference names to move point to the place within the current
     node where reference name is defined.  For example, by following the
     reference "*Note file-coding-system-alist: Default Coding Systems,"
     Info finds a node with the name "Default Coding Systems" and moves
     point to the line where reference name "file-coding-system-alist" is
     defined.

I applied your patch.  I replaced the @xref{Default Coding Systems}
in nonascii.texi you are referring to by 
@xref{Default Coding Systems, file-coding-system-alist}.

Then I launch info, go to (elisp)Default Coding Systems and click on
that reference.  It indeed carries me to the intended place.  But the
header-line goes blank.  `u' sometimes, but not always makes the
header-line go blank: C-h i m elisp RET m non- RET m text re RET u
Blank header line.  In general, it seems pretty easy to get a blank
header line.  This happens regardless of the value of
Info-hide-note-references.

As an other remark on the feature, it needs help from the .texi source
file.  So either other Info readers will have to adapt to the feature,
or the references in the .texi files will have to be written in such a
way that they look reasonable even in Info readers that do not have your
feature.  (These Info readers behave like the Emacs Info reader with
Info-hide-note-references  set to nil.)  Maybe the latter is no
problem, because "*Note file-coding-system-alist: Default Coding Systems."
makes sense to me, even without your feature.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

Juri Linkov wrote:

   I would like to submit a patch that fixes some problems in the Emacs
   Info reader and adds features most web browsers already have.
   This patch don't change the existing Info file format.  It improves
   usability of the Emacs Info reader with the current Info file format.
   Any comments are welcome.

I now took a look at your other features.  I have not yet looked at
them carefully enough, but at first sight, it looks like all your new
features are useful and real improvements.

You have to do something about that header line going blank problem I
mentioned in my previous message, however.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> I have not yet had the time to look at your patch in detail.  I just
> looked at one feature:
>
>    - use reference names to move point to the place within the current
>      node where reference name is defined.  For example, by following the
>      reference "*Note file-coding-system-alist: Default Coding Systems,"
>      Info finds a node with the name "Default Coding Systems" and moves
>      point to the line where reference name "file-coding-system-alist" is
>      defined.
>
> I applied your patch.  I replaced the @xref{Default Coding Systems}
> in nonascii.texi you are referring to by 
> @xref{Default Coding Systems, file-coding-system-alist}.
>
> Then I launch info, go to (elisp)Default Coding Systems and click on
> that reference.  It indeed carries me to the intended place.  But the
> header-line goes blank.  `u' sometimes, but not always makes the
> header-line go blank: C-h i m elisp RET m non- RET m text re RET u
> Blank header line.  In general, it seems pretty easy to get a blank
> header line.  This happens regardless of the value of
> Info-hide-note-references.

Yes, this is because `Info-fontify-node' was called twice on the same
node where header was already made invisible, so it was copied again
with invisibility property to a header line.  I will fix it by calling
code that re-fontifies only node references.

BTW, I just noticed that `Info-fontify-node' uses the function
`Info-escape-percent' which have very limited applicability.
It doubles all occurrences of only one particular character %.
Seems this function is a copy of `replace-regexp-in-string'
with a little modification.  I think it's too bad to have such
a limited function: it should be removed with making modifications
in the `replace-regexp-in-string'.  What do you think?

> As an other remark on the feature, it needs help from the .texi source
> file.  So either other Info readers will have to adapt to the feature,
> or the references in the .texi files will have to be written in such a
> way that they look reasonable even in Info readers that do not have your
> feature.  (These Info readers behave like the Emacs Info reader with
> Info-hide-note-references  set to nil.)  Maybe the latter is no
> problem, because "*Note file-coding-system-alist: Default Coding Systems."
> makes sense to me, even without your feature.

I just discovered that the stand-alone Info reader already provides
exactly the same feature.  It uses a reference name to move to correct
position within the selected Info node.  It's too surprising to see
a feature the stand-alone Info reader has, but Emacs Info reader hasn't!

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Reiner Steib]

On Mon, Dec 01 2003, Juri Linkov wrote:

> - rebind `M-s' key to a new function `Info-search-next' that searches
>   for another occurrence of regular expression from a previous
>   `Info-search' command (key `s').  Pressing only one key to repeat
>   a search is more convenient than pressing two keys (`s RET').

ACK.  I would even suggest to use an easily accessible single-key [1],
because `Info-search-next' is used often and repeatedly.  Like `,' for
`Info-index-next'.

[1] I'm using (define-key Info-mode-map "/" "s") for this which made
using info much more convenient for me.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo--- PGP key available via WWW   http://rsteib.home.pages.de/

Re: Info enhancements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> - don't hide the newline (with following whitespace) in references when
>   Info-hide-note-references is t.  This fixes the problem where hidden
>   newlines cause too long (and truncated) lines.

I think that change is ok.

> 
> - don't hide the name of external Info file in references in case
>   when Info-hide-note-references is t and references lead outside
>   the current Info file.  It's important for user to know about
>   such situation.

That is a sensible change.

> 
> - don't insert the text "See" instead of "Note" because inserting a
>   new text in Info buffer breaks the stored point positions. This bug
>   can be observed by calling `Info-last', `Info-search' where point is
>   moved with some offset to its correct position (the offset is the sum
>   of lengths of strings "See" inserted in the buffer above the point).

I don't see how this is "fixing a bug"...

Isn't there a way to generate the correct positions some other way?

Or you could add a suitable number of invisible space after each "see".

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Info enhancements

[Juri Linkov]

Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:
> On Mon, Dec 01 2003, Juri Linkov wrote:
>> - rebind `M-s' key to a new function `Info-search-next' that searches
>>   for another occurrence of regular expression from a previous
>>   `Info-search' command (key `s').  Pressing only one key to repeat
>>   a search is more convenient than pressing two keys (`s RET').
>
> ACK.  I would even suggest to use an easily accessible single-key [1],
> because `Info-search-next' is used often and repeatedly.  Like `,' for
> `Info-index-next'.
>
> [1] I'm using (define-key Info-mode-map "/" "s") for this which made
> using info much more convenient for me.

On German and Scandinavian keyboards "/" is placed above the "7" key,
so still two key presses are needed to use it (shift and "7").
But M-s is not a bad choice because <META> key can be held down while
repeating pressing "s" for the next search.  Anyhow, "/" might be
bound to `Info-search-next' as well.

BTW, you didn't use the function `Info-search-next' in your key
binding.  But seems this function could be useful to add it
to the menu and describe it in the `Info-mode' docstring.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
>     > From: Juri Linkov <juri@jurta.org>
>     > Date: Tue, 02 Dec 2003 12:18:09 +0200
>     > 
>     > Yes, using anchors might be a more clean solution, but it has one
>     > drawback: it will generate too many excessive references in the tag
>     > table for its Info file.  And these references will be mixed up with
>     > node names, e.g. in the completion list of `Info-goto-node'.
>
>     Perhaps there should be a way to tell Info-goto-node to complete on
>     node names only, or maybe we should have two distinct commands, one
>     which considers only nodes, the other which considers all entries in
>     the tag tables.
>
> Once again I've been removed from the thread.  What is under discussion now?

There is a problem of more accurate addressing of a position within a
given Info node.  For example, currently the Glossary node of the
Emacs Manual has non-functional references that merely has a form of a
simple text "(q.v.)" or "See `default.'".  There are many other
places in Info documentation where more exact referencing is needed.
This discussion currently goes about two solutions to this problem:

- use anchors

for example:

@item Argument
@xref{Numeric Argument}.
...
@item Numeric Argument
@anchor{Numeric Argument}
A numeric argument is a number, specified before a command, to change

- or use reference names

@item Argument
@xref{Glossary,Numeric Argument}.

This works by selecting an Info node ("Glossary") and then by
using some heuristics to find a needed position in this Info node.
The stand-alone Info reader searches for the first occurrence of the
reference name ("Numeric Argument") and moves point here. The Emacs
Info reader now uses the function `Info-find-index-name' to move point
to the place within the current node where reference name ("Numeric
Argument") is defined (but still sometimes it misses the correct place).

If the solution will be to use anchors, then I can suggest to develop
it further and generate anchors (i.e. Ref: tags in tag tables of
Info files) from all indexing commands (@findex, @vindex, etc.).
Currently their positions are not available in Info files, but it
might be useful to jump unambiguously to positions in Info files where
these index entries were defined in Texinfo source files.

-- 
http://www.jurta.org/emacs/

_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
texinfo-pretest@texinfo.org
http://ff0.org/mailman/listinfo/texinfo-pretest

Re: Info enhancements

[Juri Linkov]

storm@cua.dk (Kim F. Storm) writes:
> Juri Linkov <juri@jurta.org> writes:
>> - don't insert the text "See" instead of "Note" because inserting a
>>   new text in Info buffer breaks the stored point positions. This bug
>>   can be observed by calling `Info-last', `Info-search' where point is
>>   moved with some offset to its correct position (the offset is the sum
>>   of lengths of strings "See" inserted in the buffer above the point).
>
> I don't see how this is "fixing a bug"...
> Isn't there a way to generate the correct positions some other way?
> Or you could add a suitable number of invisible space after each "see".

Fixing all the problems caused by inserting new text into Info
buffers will require too much work.  Moreover, this will vastly
complicate a simple thing while I see no sense in replacing text
"Note" with "See" at all.  People that want to see some leading word
before references will be happy by setting the variable
`Info-hide-note-references' to nil.

If you still think this is needed then adding "See" could be
placed under condition `Info-refill-paragraphs' because of their
similar fragile behavior or under some new separate value of the
`Info-hide-note-references'.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Karl Berry]

    For example, currently the Glossary node of the
    Emacs Manual has non-functional references that merely has a form of a
    simple text "(q.v.)" or "See `default.'".  

I see.  Yes, this is more or less what anchors were invented for.  As
far as glossary entries go, I think that would work ok.

The reference name solution seems too heuristic.

However, I certainly agree with the comment that if we make an anchor
for every index entry, that's too many anchors (it would make the i cmd
a subset of g :).  Instead, I think indexes are important enough that
they deserve special treatment.

In fact, we've had this discussion before, in the context of allowing
arbitrary index names (specifically, ones with a :).  One message from
that thread is from rms, on 26 Jun 2003 01:30:50 -0400, Message-Id:
<E19VPLO-0004C2-6Q@fencepost.gnu.org>.

If we mark index menus with a special tag, then we can also easily the
exact character or line position within the node for the index entry.  I
believe Dave Gillespie (that's my memory, might have been someone else)
implemented a hack for this at one point, but it never made it back
into info.el.
_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
texinfo-pretest@texinfo.org
http://ff0.org/mailman/listinfo/texinfo-pretest

Re: Info enhancements

[Robert J. Chassell]

karl@freefriends.org (Karl Berry) wrote

    .... If we mark index menus with a special tag, then we can also
    easily the exact character or line position within the node for
    the index entry.  I believe Dave Gillespie (that's my memory,
    might have been someone else) implemented a hack for this at one
    point, but it never made it back into info.el.

Here is an example from the `Index of Key Sequences' in calc-2.02f

    * quick-calc:                   Quick Calculator.       6.

which comes from node Quick Calculator in the Texinfo file:

    @pindex quick-calc

Unfortunately, I could not find the source for the hack, just its output.

As far as I can see, a better format would have the line number before
the description rather than after it, with the description indented 6
spaces from the column number to which the description would otherwise
have been indented.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Info enhancements

[Karl Berry]

    As far as I can see, a better format would have the line number before
    the description rather than after it, with the description indented 6

But then it would not follow the standard format for menus, i.e.,
<term>:<node name>.

Re: Info enhancements

[Robert J. Chassell]

       As far as I can see, a better format would have the line number before
       the description rather than after it, with the description indented 6

   But then it would not follow the standard format for menus, i.e.,
   <term>:<node name>.

I must not have been clear.  The format I meant is:

     * MENU-ENTRY-NAME: NODE-NAME.   LINE_NUMBER. DESCRIPTION

instead of Dave Gillespie's

     * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION. LINE_NUMBER. 

or the current

     * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Info enhancements

[Juri Linkov]

"Robert J. Chassell" <bob@rattlesnake.com> writes:
>        As far as I can see, a better format would have the line number before
>        the description rather than after it, with the description indented 6
>
>    But then it would not follow the standard format for menus, i.e.,
>    <term>:<node name>.
>
> I must not have been clear.  The format I meant is:
>
>      * MENU-ENTRY-NAME: NODE-NAME.   LINE_NUMBER. DESCRIPTION
>
> instead of Dave Gillespie's
>
>      * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION. LINE_NUMBER. 
>
> or the current
>
>      * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION

I think that line numbers in index menus can distract users.
Even if newer versions of Info readers could hide them, they still
will be shown by older versions.

But what do you think about recording the locations of index entries
in the tag table?  For example:

^_
Tag Table:
Node: Top^?123
Ref: menu-entry-name^?12345

Then menu entries would have the following format:

     * menu-entry-name::               Description.

Another variant is to generate a separate tag name for every index type,
e.g.:

^_
Tag Table:
Node: Top^?123
findex: menu-entry-name^?12345
vindex: menu-entry-name^?23456
pindex: menu-entry-name^?34567
cindex: menu-entry-name^?45678

I hope this will not break older Info readers, but newer Info readers
might use this advantage and with index menus marked by a special tag
(e.g. the title "* Variable Index:", etc.) they can read corresponding
locations from the tag table.

The information about locations of index entries could be used by the
`i' command as well.  Note also than in the first variant where index
entries are treated as they were anchors (i.e. by generating a "Ref:"
tag in the tag table) the `g' command can replace the `i' command.

-- 
http://www.jurta.org/emacs/

_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
texinfo-pretest@texinfo.org
http://ff0.org/mailman/listinfo/texinfo-pretest

Re: Info enhancements

[Robert J. Chassell]

   > I must not have been clear.  The format I meant is:
   >
   >      * MENU-ENTRY-NAME: NODE-NAME.   LINE_NUMBER. DESCRIPTION

and Juri Linkov <juri@jurta.org>:

   I think that line numbers in index menus can distract users.

Yes, they do.  I found them very distracting when they followed the
description and figured I would be much less bothered by seeing them
in front of the description, like this:

* abs:                          147.  Basic Arithmetic.       
* abs (vectors):                18.   Vector and Matrix Arithmetic.  
* abssqr:                       157.  Basic Arithmetic.       
* accum:                        20.   Reducing.               
* acute:                        55.   TeX Language Mode.      
* add:                          90.   Specifying Operators.   
* afixp:                        21.   Nesting and Fixed Points.  

(Adapted from calc-2.02f-patch-1/calc.info-26 -- those are actual line
numbers.  Basicially, the descriptions are lined up, and I can ignore
the line numbers easily.  In Dave Gillespie's format the line numbers
come after the description.  With short descriptions they, too, are
lined up.  That is fine, except that many descriptions are not short,
so the method breaks down.)

You go on to say

   Even if newer versions of Info readers could hide them, they still
   will be shown by older versions.

Yes.

   But what do you think about recording the locations of index entries
   in the tag table?  

The problem is, I think your fear:

   I hope this will not break older Info readers, ...

If the suggestion does not break older Info readers, then I am all
for it.  But I think it will break them.  Karl, what do you think?

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Info enhancements

[Eli Zaretskii]

> Date: Thu, 4 Dec 2003 13:12:17 +0000 (UTC)
> From: "Robert J. Chassell" <bob@rattlesnake.com>
> 
>    But what do you think about recording the locations of index entries
>    in the tag table?  
> 
> The problem is, I think your fear:
> 
>    I hope this will not break older Info readers, ...
> 
> If the suggestion does not break older Info readers, then I am all
> for it.  But I think it will break them.  Karl, what do you think?

AFAICS, it will break them: the first time Info sees a line in the
tag table that is neither a "Node:" nor a "Ref:" line, it decides
that it's outside the tag table and stops looking for further tags.
So all the nodes and anchors after the first unrecognized line will
be absent from the internal data structure created by the reader from
the tag table, and the corresponding nodes and anchors will not be
found.

Or so it seemed to me when I glanced over the code (of the stand-alone
Info reader).  But you don't need to take my word for it: it is very
easy to edit an Info file, add a line in the tag table that doesn't
match "Node:" and "Ref:" lines, and then see if you can still reach
every node and anchor in that file.

Re: Info enhancements

[Stefan Monnier]

> I think that line numbers in index menus can distract users.

I think they only distract me if they say

  * Index entry:                          Node name.    54.

but not if they say

  * Index entry:                          Node name.    Line 54.


-- Stefan

Re: Info enhancements

[Karl Berry]

       I hope this will not break older Info readers, ...

    If the suggestion does not break older Info readers, then I am all
    for it.  But I think it will break them.  Karl, what do you think?

As Eli said, looking at the code in info/nodes.c, it looks like it will.

When we added @anchor, we broke older Info readers.  The saving grace
there was that only Texinfo documents using @anchor were affected (and
of course there were none of those at the time, and are still relatively
few).  The proposed change would affect all Info documents.

We have to do something compatible.

In this case, I like Stefan's idea of explicitly stating "line".  So my
proposal is to change makeinfo to append "(line NNN)" or the equivalent
to the index lines.  Then the info readers can read it and do the right
thing.  For instance:

* Writing index entries:                 Indexing Commands.  (line 1)
* xdvi:                                  Output Formats.  (line 99)

It is not especially beautiful, but it is 100% compatible, and gets the
job done.  If there is a strong consensus that "Line 1." is preferable
to "(line 1)", I don't mind.

Bob, I don't believe we can put the line numbers in front of the node
names.  That would break existing readers.  (I'm also not entirely
convinced that's more readable, to me having the numbers in front of the
node names is more distracting than the reverse, but that's a moot point.)

I don't see the line indications have to align, but if they do, they
could be right justified to column 79 with maybe four spaces for the
number or something.  Personally I'd just as soon not even try to align
them, as in the example above.

Unless there are vehement objections, I will do this for the next
makeinfo release.  It should be straightforward.

Thanks,
k

Re: Info enhancements

[Robert J. Chassell]

   In this case, I like Stefan's idea of explicitly stating "line".  

Yes, this helps a great deal.

   Bob, I don't believe we can put the line numbers in front of the
   node names.  That would break existing readers.  ....

If you use `(line 999)' or `Line 999.' then the menu looks better when
the line numbers go after the node names.  The parenthetical format
looks better to me.

Will it look better if `(line 999)' is always on one line, rather than
broken over two lines?

Thus we might see

* electric-future-map:                   A Sample Variable Description. (line 
                                           999)

unless we make sure that the formatting produces:

* electric-future-map:                   A Sample Variable Description. 
                                           (line 999)

As far as I can see, using parenthetical line numbers, the node name
must end on column 65 (66 being the period), or else the line
expression should all go to the next line.  This puts the closing
parenthesis on column 78.

   I don't see the line indications have to align, ....

I think they will look better if aligned.  Many manuals, such as the
Calc manual, have lots of short node names.  The line numbers will
look better if also in a nice column -- maybe even with the numbers
themselves padded (invisibly) to four columns, so the right hand
parentheses line up.  Menu entries with longer node names push the
line numbers to the right, and that is that.

Thus a menu might look like this (which I indented to make the filling
more obvious):

    * histogram:                    Manipulating Vectors.   (line   78)
    * hms:                          Conversions.            (line   63)
    * holiday:                      Business Days.          (line  114)
    * hour:                         Date Functions.         (line   27)
    * hypot:                        Basic Arithmetic.       (line  174)
    * idiv:                         Basic Arithmetic.       (line  121)
    * idn:                          Building Vectors.       (line   44)
    * ierf:                         Other Features of Rewrite Rules.  
                                      (line   246)
    * if:                           Logical Operations.     (line   89)
    * ilog:                         Logarithmic Functions.  (line   27)

rather than:

    * histogram:                    Manipulating Vectors. (line   78)
    * hms:                          Conversions. (line   63)
    * holiday:                      Business Days. (line  114)
    * hour:                         Date Functions. (line   27)
    * hypot:                        Basic Arithmetic. (line  174)
    * idiv:                         Basic Arithmetic. (line  121)
    * idn:                          Building Vectors. (line   44)
    * ierf:                         Other Features of Rewrite Rules.  
                                      (line   246)
    * if:                           Logical Operations. (line   89)
    * ilog:                         Logarithmic Functions. (line   27)

With an alternative format a menu looks like this:

    * histogram:                    Manipulating Vectors.   Line   78.
    * hms:                          Conversions.            Line   63.
    * holiday:                      Business Days.          Line  114.
    * hour:                         Date Functions.         Line   27.
    * hypot:                        Basic Arithmetic.       Line  174.
    * idiv:                         Basic Arithmetic.       Line  121.
    * idn:                          Building Vectors.       Line   44.
    * ierf:                         Other Features of Rewrite Rules.  
                                      Line   246.
    * if:                           Logical Operations.     Line   89.
    * ilog:                         Logarithmic Functions.  Line   27.

or even

    * histogram:                    Manipulating Vectors.   Line   78
    * hms:                          Conversions.            Line   63
    * holiday:                      Business Days.          Line  114
    * hour:                         Date Functions.         Line   27
    * hypot:                        Basic Arithmetic.       Line  174
    * idiv:                         Basic Arithmetic.       Line  121
    * idn:                          Building Vectors.       Line   44
    * ierf:                         Other Features of Rewrite Rules. 
                                      Line   246
    * if:                           Logical Operations.     Line   89
    * ilog:                         Logarithmic Functions.  Line   27

rather than

    * histogram:                    Manipulating Vectors. Line   78.
    * hms:                          Conversions. Line   63.
    * holiday:                      Business Days. Line  114.
    * hour:                         Date Functions. Line   27.
    * hypot:                        Basic Arithmetic. Line  174.
    * idiv:                         Basic Arithmetic. Line  121.
    * idn:                          Building Vectors. Line   44.
    * ierf:                         Other Features of Rewrite Rules.  
                                      Line   246.
    * if:                           Logical Operations. Line   89.
    * ilog:                         Logarithmic Functions. Line   27.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Info enhancements

[Karl Berry]

My preference is either (a) maximal alignment:

    * histogram:                    Manipulating Vectors.   (line   78)
    * hms:                          Conversions.            (line   63)

Or my original proposal (b), with no attempt at any alignment:

    * histogram:                    Manipulating Vectors.  (line 78)
    * hms:                          Conversions.  (line 63)

I prefer the parenthetical forms to the "Line N" forms, with or without
period.


Ok, since you prefer alignment, and I guess I rather agree, it will be
nicer in the common case of relatively short node names, I will do (a)
for the next release, barring objections.

Thanks,
k

Re: Info enhancements

[Richard Stallman]

    > I must not have been clear.  The format I meant is:
    >
    >      * MENU-ENTRY-NAME: NODE-NAME.   LINE_NUMBER. DESCRIPTION
    >
    > instead of Dave Gillespie's
    >
    >      * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION. LINE_NUMBER. 


Of those two, I think the latter is better because the line number
will be less intrusive.

However,

     * MENU-ENTRY-NAME: NODE-NAME (LINE_NUMBER).     DESCRIPTION

or something along those lines would be even better.  This makes
it visible that the line number goes with the node name and that
the two together spec the location.

I chose parens for this example but that was arbitrary.  I'm not
attached to that particular detail.

    But what do you think about recording the locations of index entries
    in the tag table?  For example:

Something like this might be ok, depending on details, but it might
be a bigger change.

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
> For instance:
>
> * Writing index entries:                 Indexing Commands.  (line 1)
> * xdvi:                                  Output Formats.  (line 99)
>
> It is not especially beautiful, but it is 100% compatible, and gets the
> job done.

Yes, it is not beautiful.  It is ugly.  The information about line
numbers is useless for users.  Certainly we shouldn't overburden users
with purely technical information.  Moreover, it don't solve the
problem of using index entries in cross-references.  For instance:

     This function looks up the target in *Note
     file-coding-system-alist: Default Coding Systems, *Note
     process-coding-system-alist: Default Coding Systems, or
     *Note network-coding-system-alist: Default Coding Systems,
     depending on OPERATION.

These cross-references refer to variables indexed by the @vindex
command, but there is no place for line numbers here.  So, I urge you
to find a better solution.  If placing this information in the tag
table will break older version (though this should be verified yet),
then we should try to find another safe place in Info files (e.g. some
unreachable Info node).  Do you know such a place?

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Karl Berry]

         This function looks up the target in *Note
         file-coding-system-alist: Default Coding Systems, *Note
         process-coding-system-alist: Default Coding Systems, or
         *Note network-coding-system-alist: Default Coding Systems,
         depending on OPERATION.

    These cross-references refer to variables indexed by the @vindex
    command, but there is no place for line numbers here.  

What is the Texinfo source that is generating this?  Texinfo does not
have a way to make an xref to index entries, as far as I know.

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
>          This function looks up the target in *Note
>          file-coding-system-alist: Default Coding Systems, *Note
>          process-coding-system-alist: Default Coding Systems, or
>          *Note network-coding-system-alist: Default Coding Systems,
>          depending on OPERATION.
>
>     These cross-references refer to variables indexed by the @vindex
>     command, but there is no place for line numbers here.  
>
> What is the Texinfo source that is generating this?  Texinfo does not
> have a way to make an xref to index entries, as far as I know.

This is generated by the `@ref' with two arguments:

     @ref{Default Coding Systems, file-coding-system-alist}

True, the `file-coding-system-alist' is the cross reference name here.
But  it can  be  used to  find  the correct  position  of index  entry
definition.   The  standalone  Info  reader  already  uses  the  cross
reference name  to move point to  its first occurrence  within an Info
node, but this could be improved to search the cross reference name in
the  tag table  of index  entries with  their positions  and  use this
information  for more  accurate navigation  by cross  references.

Another variant is to generate Ref: tags in the tag table for every
index entry and use them as anchors, for instance:

     @ref{file-coding-system-alist}

would move directly to the position where the `@vindex' command was
defined in the Texinfo source.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Fri, 05 Dec 2003 17:57:31 +0200
> >
> > What is the Texinfo source that is generating this?  Texinfo does not
> > have a way to make an xref to index entries, as far as I know.
> 
> This is generated by the `@ref' with two arguments:
> 
>      @ref{Default Coding Systems, file-coding-system-alist}

A digression: My personal view is that this is bad usage of Texinfo.
Instead of saying

   This function looks up the target in @ref{Default Coding Systems,
   file-coding-system-alist}

which looks awkward in Info and downright incomprehensible in the
printed copy, it is much better to say

   This function looks up the target in
   @code{file-coding-system-alist} (@pxref{Default Coding Systems,
   file-coding-system-alist})

Re: Info enhancements

[Luc Teirlinck]

Juri Linkov wrote:

	This function looks up the target in *Note
	file-coding-system-alist: Default Coding Systems, *Note
	process-coding-system-alist: Default Coding Systems, or
	*Note network-coding-system-alist: Default Coding Systems,
	depending on OPERATION.

I will soon commit several changes to (elisp)Non-ASCII Characters.  I
personally believe the xref you are referring to got into
`(elisp)Default Coding Systems' by mistake.  I originally just erased
it.  I am reluctant to do that now since it is used as the prime
example in this thread and with your feature, it might make sense in
Info.  As Eli pointed out, the above is the result of non-standard
Texinfo usage and looks weird.  The xref still makes no sense in the
printed version, since it refers to the beginning of the same section.

I currently have:

===File ~/refs1=============================================
This function looks up the target in @code{file-coding-system-alist},
@code{process-coding-system-alist}, or
@code{network-coding-system-alist}, depending on @var{operation}.
@ifinfo
@ifnotplaintext
@xref{Default Coding Systems, file-coding-system-alist}.
@end ifnotplaintext
@end ifinfo

============================================================

Do you really need those _three_ xrefs?  The three alists are
described in succession starting with `file-coding-system-alist'.  I
am even still not completely sure that we really need any xref here,
since the descriptions are right above, but it certainly makes more
sense with your feature than without it.  It is, of course, trivial to
add the other two xrefs, should this be considered desirable.

Sincerely,

Luc.

Re: Info enhancements

[Karl Berry]

    Certainly we shouldn't overburden users
    with purely technical information.

Well, in Emacs under X, the reader can erase the "(line NNN)" so users
don't have to see it.


As for the xref stuff, I am not at all sure the second arg to xref
should be treated in a special way; that was not its original intent and
nothing has ever been documented about it.  I didn't know standalone
info did any searching based on it.  I'll have to think about that.

I can see that making index entries automatically be xrefable points
could be useful, in a few circumstances.  But that is a separate feature
from handling entries in the indexes themselves, so that the menu
entries there go to the right place.


Luc, my own personal opinion is that the conditional
file-coding-system-alist xref should be deleted as you were going to
do.  If it's in the same section, users shouldn't need an xref (or else
the section should be split, but the section in question seems a
reasonable length to me).

Re: Info enhancements

[Luc Teirlinck]

Karl Berry wrote:

   As for the xref stuff, I am not at all sure the second arg to xref
   should be treated in a special way; that was not its original intent and
   nothing has ever been documented about it.  I didn't know standalone
   info did any searching based on it.  I'll have to think about that.

The standalone info goes to the wrong place in the example we have
been looking at.  Instead of going to the intended place:

 - Variable: file-coding-system-alist

It goes to:

     files and the contents of `file-coding-system-alist' (see below).

in the description of `auto-coding-regexp-alist'.

While it is very useful to go to the intended place, it is a lot
better to just go to the top of the node than to attempt to guess.
Going to the wrong place misleads the user.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my earlier message:

   The standalone info goes to the wrong place in the example we have
   been looking at.

As I now realize, Juri already pointed that out.  Sorry for the redundancy.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

There seems to be a bug in the Info history buffer machinery of your
patch.

Do C-h i m elisp RET \ and press return on the `Top: (elisp)Top.'
line.  We somehow go to `Top: (dir)Top.'.  In fact, any `Top: 'line
seems to go to `Top: (dir)Top.'

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

My previous message was, of course addressed to Juri.  I inadvertently
sent it to myself.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> There seems to be a bug in the Info history buffer machinery of your
> patch.
>
> Do C-h i m elisp RET \ and press return on the `Top: (elisp)Top.'
> line.  We somehow go to `Top: (dir)Top.'.  In fact, any `Top: 'line
> seems to go to `Top: (dir)Top.'

This is due to the limitation of the function `Info-follow-reference'.
It don't follow a reference under point, but instead it searches the
first occurrence of reference name from the buffer beginning.  The
Info history buffer has many references with the name `Top', but
`Info-follow-reference' always follows only the first one.  I already
noticed the same problem in Glossary node where no term name and
node name are allowed with the same name in references.

So currently no references with the same name are allowed in the same
Info node.  I suppose the purpose of such limitation was to make
possible to select a reference from the completion list of all references
where names should be unique.  But we can remove such limitation by
adding a new argument `nodename' to the `Info-follow-reference'.  This
argument can be transfered from the `Info-try-follow-nearest-node'
to explicitly specify a reference under point.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

"Eli Zaretskii" <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Fri, 05 Dec 2003 17:57:31 +0200
>> >
>> > What is the Texinfo source that is generating this?  Texinfo does not
>> > have a way to make an xref to index entries, as far as I know.
>> 
>> This is generated by the `@ref' with two arguments:
>> 
>>      @ref{Default Coding Systems, file-coding-system-alist}
>
> A digression: My personal view is that this is bad usage of Texinfo.
> Instead of saying
>
>    This function looks up the target in @ref{Default Coding Systems,
>    file-coding-system-alist}
>
> which looks awkward in Info and downright incomprehensible in the
> printed copy, it is much better to say
>
>    This function looks up the target in
>    @code{file-coding-system-alist} (@pxref{Default Coding Systems,
>    file-coding-system-alist})

But this looks awkward in Info with Info-hide-note-references equal t:

   This function looks up the target in file-coding-system-alist
   (see file-coding-system-alist).

whereas the first variant is better:

   This function looks up the target in file-coding-system-alist.

So the variant that will look equally good in Info with
Info-hide-note-references equal to t or nil and in the printed copy
has yet to be found.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Juri Linkov wrote:
> 	This function looks up the target in *Note
> 	file-coding-system-alist: Default Coding Systems, *Note
> 	process-coding-system-alist: Default Coding Systems, or
> 	*Note network-coding-system-alist: Default Coding Systems,
> 	depending on OPERATION.
>
> The xref still makes no sense in the printed version, since it
> refers to the beginning of the same section.

What do you think about writing a variable name in a third argument
of @xref with the empty second argument?

============================================================
This function looks up the target in
@ref{Default Coding Systems, , file-coding-system-alist},
@ref{Default Coding Systems, , process-coding-system-alist}, or
@ref{Default Coding Systems, , network-coding-system-alist},
depending on @var{operation}.
============================================================

This would look good in the printed version as well as in Info.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
> As for the xref stuff, I am not at all sure the second arg to xref
> should be treated in a special way; that was not its original intent and
> nothing has ever been documented about it.  I didn't know standalone
> info did any searching based on it.  I'll have to think about that.
>
> I can see that making index entries automatically be xrefable points
> could be useful, in a few circumstances.  But that is a separate feature
> from handling entries in the indexes themselves, so that the menu
> entries there go to the right place.
>
> Luc, my own personal opinion is that the conditional
> file-coding-system-alist xref should be deleted as you were going to
> do.  If it's in the same section, users shouldn't need an xref (or else
> the section should be split, but the section in question seems a
> reasonable length to me).

I agree that references to another part of the same small Info node is
useless.  I used this particular section as an example of enhancements.
But there are many other places in Info documentation where better
references to index entries are needed.  For instance, let's consider the
following excerpt from the Emacs Lisp Manual:

     See also `append' in *Note Building Lists::, `concat' in *Note
     Creating Strings::, and `vconcat' in *Note Vectors::, for other
     ways to copy sequences.

Such kind of references has at least two big drawbacks:

1. Users see too much unimportant information such as node names.
With using function names in reference names users will see only
function names, i.e. only what they need.  Nodes names will be hidden:

     See also append, concat, and vconcat for other ways to copy
     sequences.

2. When a reference contains only a node name, then after going to
   this node user should manually locate a place where needed
   function is described.  Note that nodes `Building Lists' and
   `Creating Strings' are very large, so user must spend a significant
   amount of time to locate this place.  With using index entries
   as reference names, this tedious task will be performed automatically.

   There are two variants of writing index names in references:

     See also *Note append: Building Lists, *Note concat: Creating
     Strings, and *Note vconcat: Vectors, for other ways to copy
     sequences.

   or references to anchors:

     See also *Note append::, *Note concat::, and *Note vconcat::, for
     other ways to copy sequences.

I believe this enhancement can easily be done with the existing Info
format.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> Date: Fri, 5 Dec 2003 14:44:12 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> The standalone info goes to the wrong place in the example we have
> been looking at.

That's the best that could be done using the available information
without any chanegs to the Info format.

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sat, 06 Dec 2003 03:27:37 +0200
> 
>      See also `append' in *Note Building Lists::, `concat' in *Note
>      Creating Strings::, and `vconcat' in *Note Vectors::, for other
>      ways to copy sequences.
> 
> Such kind of references has at least two big drawbacks:

I think these drawbacks stem from the basic limitations of the Info
format.  People nowadays are more accustomed to HTML and similar
hyper-text formats, where the actual pointer is hidden, that's why the
somewhat naive Info format looks bad to them.

> I believe this enhancement can easily be done with the existing Info
> format.

And having spent many hours hacking makeinfo and the stand-alone Info
reader, I believe, like Karl does, that doing that is a complete waste
of time and effort.  I think we basically have reached the point where
no significant improvements could be done to Info without breaking
something somewhere else.  Evene the relatively simple change such as
Info-hide-node-references caused a series of unintended consequences
that we haven't fixed yet to the full extent.  Isn't the experience
drawn from that experiment enough for us to understand the simple
truth that

   THOU SHALT NOT CHANGE INFO ANYMORE

?

I say, if we want a better reader of the docs, let's invest our energy
in an XML-based reader.

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sat, 06 Dec 2003 01:52:01 +0200
> 
> This is due to the limitation of the function `Info-follow-reference'.
> It don't follow a reference under point, but instead it searches the
> first occurrence of reference name from the buffer beginning.

IIRC, the stand-alone Info reader was fixed to prefer the reference
at point, if there is one, and otherwise try the reference that is
closest to point.

> So currently no references with the same name are allowed in the same
> Info node.

If that is so (I'm surprised that it is, btw), it's IMHO a grave bug
in the Emacs Info reader: there are quite a few manuals out there
which do have several references to the same node.  The stand-alone
reader doesn't have this limitation.

> But we can remove such limitation by
> adding a new argument `nodename' to the `Info-follow-reference'.

Please don't.  Let's not introduce yet another haphazard change into
the Info format.  As the case of the stand-alone reader shows, this
limitation can be lifted without any changes to the Info format per
se.

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sat, 06 Dec 2003 02:15:43 +0200
> 
> > it is much better to say
> >
> >    This function looks up the target in
> >    @code{file-coding-system-alist} (@pxref{Default Coding Systems,
> >    file-coding-system-alist})
> 
> But this looks awkward in Info with Info-hide-note-references equal t:

Yet another sign that Info-hide-note-references is not such a good
idea, if you ask me.

> So the variant that will look equally good in Info with
> Info-hide-note-references equal to t or nil and in the printed copy
> has yet to be found.

That might be so, but my point was that the example you've shown is
not something people should follow.  Try to TeX it, and you will
understand what I mean.

Re: Info enhancements

[Karl Berry]

    Note that nodes `Building Lists' and
       `Creating Strings' are very large

Perhaps they should be split up, then.  But obviously that's a different
issue.


As for the general question of making index entries xrefable, as I said
before, I am not sure.  Although it would be useful in the cases you
cite, I am not sure if it would be useful enough in general to
automatically do it for every index entry.  Most index entries (in most
manuals) are long strings of human-readable text that it is not useful
to xref.

Also, the question of conflicts would arise.  If there is both an index
entry and a node with the same name, what to do?  Or two index entries
with the same name?  The xref commands are not set up to handle this.
Making them take a sixth argument or something does not sound all that
appealing, although maybe it is the cleanest thing.

So I don't think it is "easy".  The easy thing to do is accept the
feaure Texinfo already provides for subnode positioning: anchors.  It is
more work for the authors in one way, but on the other hand it actually
works.

Re: Info enhancements

[Karl Berry]

    What do you think about writing a variable name in a third argument

No.  The third arg to xref is for the printed manual.

All the existing args to xref have a meaning (obviously).  It doesn't
make sense to replace one of them willy-nilly with index entries.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 09:49:36 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> Most index entries (in most manuals) are long strings of
> human-readable text that it is not useful to xref.

Yes, it's typical for @cindex entries to be like that.  Entries that
are just symbol names are mostly produced by @vindex and @findex.

> So I don't think it is "easy".  The easy thing to do is accept the
> feaure Texinfo already provides for subnode positioning: anchors.  It is
> more work for the authors in one way, but on the other hand it actually
> works.

I tend to agree that the decision whether to xref an index entry is a
human one, so @anchor is the solution.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   IIRC, the stand-alone Info reader was fixed to prefer the reference
   at point, if there is one, and otherwise try the reference that is
   closest to point.

In my bug report to Juri I was not talking about references (@ref and
the like), but about _menu entries_.  Juri talked about "references".
Juri, is this really what you meant?  I actually made myself a mini
.texi file to check whether there was a similar problem with
references, but everything seemed to work OK.

Menu entries with the same name would give trouble for the `m'
(Info-menu) command.  But we have no control over what winds up in the
user's (dir)Top.  It believe that it is a problem that needs to be
fixed.

   > But we can remove such limitation by
   > adding a new argument `nodename' to the `Info-follow-reference'.

   Please don't.  Let's not introduce yet another haphazard change into
   the Info format.  As the case of the stand-alone reader shows, this
   limitation can be lifted without any changes to the Info format per
   se.

Either I misunderstand you, or you misunderstood Juri or I
misunderstood Juri.  `Info-follow-reference' is a function in info.el.
It has nothing to do with the Info format or formatting, it is a
navigational function.

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 10:45:49 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    IIRC, the stand-alone Info reader was fixed to prefer the reference
>    at point, if there is one, and otherwise try the reference that is
>    closest to point.
> 
> In my bug report to Juri I was not talking about references (@ref and
> the like), but about _menu entries_.  Juri talked about "references".
> Juri, is this really what you meant?  I actually made myself a mini
> .texi file to check whether there was a similar problem with
> references, but everything seemed to work OK.
> 
> Menu entries with the same name would give trouble for the `m'
> (Info-menu) command.

IIRC, the stand-alone reader handles this problems as well (by
preferring the menu entry that is closest to point).

>    > But we can remove such limitation by
>    > adding a new argument `nodename' to the `Info-follow-reference'.
> 
>    Please don't.  Let's not introduce yet another haphazard change into
>    the Info format.  As the case of the stand-alone reader shows, this
>    limitation can be lifted without any changes to the Info format per
>    se.
> 
> Either I misunderstand you, or you misunderstood Juri or I
> misunderstood Juri.  `Info-follow-reference' is a function in info.el.
> It has nothing to do with the Info format or formatting, it is a
> navigational function.

Same difference.  There's no need to do that, IMHO, so let's not.

Really, the only positive outcome of this longish thread is the
more-or-less widespread consensus that we should develop an XML-based
reader.  Could we please drop the (IMHO futile) attempts to ``fix''
the current Info readers by making them slicker than they were
designed to be?

Re: Info enhancements

[Luc Teirlinck]

>From my previous message:

   In my bug report to Juri I was not talking about references (@ref and
   the like), but about _menu entries_.

No I was not.  I got confused.  We _were_ talking about actual
references. I will try to figure out why I did _not_ see the same bug
in the file I constructed.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   Same difference.  There's no need to do that, IMHO, so let's not.

   Really, the only positive outcome of this longish thread is the
   more-or-less widespread consensus that we should develop an XML-based
   reader.  Could we please drop the (IMHO futile) attempts to ``fix''
   the current Info readers by making them slicker than they were
   designed to be?

This thread concerns ten changes proposed by Juri in a patch (which I
personally applied, so I know more or less what it does).  This has
nothing to do with the move to XML, discussed in a variety of threads
unrelated to this one.  In this one we are discussing the ten changes
in Juri's patch.

Of these ten there is _one_ (the playing around with the arguments to
xref and with `Info-find-index-name', to determine where a reference
leads to) to which your last sentence indeed might apply.

The "subthread" you responded to is concerned with the "Info history
buffer" feature in Juri's patch, unrelated to the above feature.

Right now, we are trying to deal with an apparent problem that the
Elisp info reader has with similarly named references (it were really
references, not menu entries, I just got confused for a moment).  I do
not understand in what way your last sentence, quoted above, relates
to this problem, or to the way Juri was proposing to solve it.  There
would be other ways to solve the problem, if Juri's way were
objectionable.  But, your last sentence seems to imply that you
consider _all_ attempts to solve the problem futile and that they
should be dropped immediately.  Is this really what you mean?

Sincerely,

Luc.

Re: Info enhancements

[Karl Berry]

    Right now, we are trying to deal with an apparent problem that the
    Elisp info reader has with similarly named references

Exactly what is the bug and what is the proposed solution?  Sample files?

I had no idea there was an actual patch being applied.
What other changes are being made?  While savannah is down, it's
impossible to know what is being done.

As we know, the standalone Info reader searches for the second arg to
xref in the node.  This is not perfect, as you yourself noted, but I
guess it only hurts occasionally.  So if you want to implement that in
the Emacs reader, fine.  Consistency is nice, anyway.

Other than that, the only practical solution to subnode positioning is
anchors, as far as I can see.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   Exactly what is the bug and what is the proposed solution?  Sample
   files?

I filed a bug report with Yuri, which only makes sense if you apply
Yuri's patch, and which was posted on emacs-devel.  Yuri said that it
was due to a pre-existing bug in Emacs Info.  It is all in the
messages you responded to (and which, hence, I assume you have read).
I am still confused about some of this myself, but Yuri gave the
impression of knowing what is going on.  I do not know anything more
about Yuri's solution than the short line you mentioned and criticized
(maybe because you misunderstood it).

   I had no idea there was an actual patch being applied.
   What other changes are being made?  While savannah is down, it's
   impossible to know what is being done.

I applied the patch to my owm _personal_ Emacs, for testing, _not_ to
the Emacs CVS.

The second part of your message is an unrelated problem.  I may send
my opinion on that one somewhat later.

The ten features in Juri's patch are mostly unrelated.  We can install
some and reject others.  Maybe we should not even be discussing them
all in a single thread.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my previous message:

   It is all in the messages you responded to (and which, hence, I
   assume you have read).

Sorry, I do not know why I assumed the message I responded was sent by
Eli.  It is in the messages Eli responded too.  Sorry, I should pay
attention to the "author" field.  I am in an absent-minded mood, I
guess.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my earlier message:

   Eli Zaretskii wrote:

      Exactly what is the bug and what is the proposed solution?  Sample
      files?

Sorry for misattributing this and following quotes to Eli.  (It was
quoted from Karl Berry)

Sincerely,

Luc.

Re: Info enhancements

[Kai Grossjohann]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

> * electric-future-map:                   A Sample Variable Description. 
>                                            (line 999)

Actually, I found find it nice if the "(line 999)" part would align
with all the other line numbers that aren't on extra lines.  What do
people think?

Kai

Re: Info enhancements

[Luc Teirlinck]

Again, sorry for assuming the wrong author in my previous message,
falsely attributing quotes to Eli and misspelling Juri's name
repeatedly (again).  Let us see how many blunders I manage to commit
in the present post.

This concerns the problem with the place references lead to in info.

As already mentioned, I believe that just going to the top of the node
is better than guessing at the risk of misleading the user.

The ideal would be to have a _reliable_ way to go to the correct place
without requiring any changes in existing .texi files.  Since a
solution of this type is probably impossible, we should, in my
opinion, stick with the @anchor solution.

Juri's change requires rewriting references in .texi files in a way
that departs from the present standard style and I believe that Juri
mentioned himself in a previous post that his method is not 100%
reliable.  Hence I would personally _not_ lean toward making this
particular change.  This is, as I already pointed out before,
independent of the question of whether we adopt the other changes in
the patch.

But what do we want to do with @anchor?  I have always actually
_avoided_ using it, because I saw it barely ever used in any major
manual.  For instance, it is _only_ used in texinfo.txi to illustrate
the @anchor command itself and _never_ used in info.texi.  I deduced
from this an implicit stylistic guideline "by example" that one should
use @anchor very sparingly, that is, only if *really* called for, and
that it would not be appropriate to write five or so @anchors per
node.  If anchors are actually preferred over node names, unless the
top of the node is the _real_ target, that should be clearly pointed
out in texinfo.txi.  Or one might give some guidelines on _when_ to use
@anchor.

If we started using @anchor systematically, the apparent inconsistency
with older Texinfo source might be confusing to the user.  A reference
would lead in a random way either to the top of the node or to the
"correct place".  At the very least, something should be said about it
in (info)Help-Xref.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my previous message:

   If we started using @anchor systematically, the apparent inconsistency
   with older Texinfo source might be confusing to the user.  A reference
   would lead in a random way either to the top of the node or to the
   "correct place".  At the very least, something should be said about it
   in (info)Help-Xref.

I retract that.  You can, of course, make it clear from the name.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   IIRC, the stand-alone Info reader was fixed to prefer the reference
   at point, if there is one, and otherwise try the reference that is
   closest to point.

Let us first decide whether there is a bug in info.el or not.  If not,
I believe that it would be easy for Juri to fix what would, in that
case, be a bug in his patch.  The problem(?) is that a node can not
have two references to two different nodes with exactly the same name.
Maybe this is a reasonable restriction and no bug?  If it is a bug,
here is a test case.

Source file:

===File ~/experiment.texi===================================
\input texinfo    @c -*-texinfo-*-
@comment %**start of header
@setfilename experiment.info
@settitle An experiment.
@comment %**end of header

@node Top
@top Top

@menu
* name:entry.           description.
@end menu

@node entry
@chapter Entry

This node is called @samp{entry}
@xref{Top}.  @xref{(dir)Top}.  @xref{(elisp)Top}. @xref{(elisp)Top, Top}.

@bye
============================================================

The .info file is attached below.

Clicking return on the reference produced by `@xref{(elisp)Top}.'
leads to (elisp)top, but the reference produced by `@xref{(elisp)Top,
Top}.' leads to (experiment)Top in Emacs Info.  Is this a bug?

The stand-alone Info goes to (elisp)top.

@unrelated 
But to a strange place there:

* Related Topics::          Cross-references to specific Lisp primitives

I am afraid to mix two issues up more than they already are.  At the
risk of doing that, note that *on a completely unrelated note*, the
strange place the stand-alone info goes to, once again seems to say:
do not try to guess positions if you are not completely sure.
@end unrelated

.info file:

===File ~/experiment.info===================================
This is experiment.info, produced by makeinfo version 4.6 from
experiment.texi.

\x1f
File: experiment.info,  Node: Top,  Next: entry,  Up: (dir)

Top
***

* Menu:

* name:entry.           description.

\x1f
File: experiment.info,  Node: entry,  Prev: Top,  Up: Top

Entry
*****

This node is called `entry' *Note Top::.  *Note (dir)Top::.  *Note
(elisp)Top::. *Note Top: (elisp)Top.


\x1f
Tag Table:
Node: Top\x7f81
Node: entry\x7f200
\x1f
End Tag Table
============================================================

Re: Info enhancements

[Karl Berry]

Luc, thank you for the clear mail with examples.

    @xref{(elisp)Top}. @xref{(elisp)Top, Top}.

Hmm.  The documentation is not explicit about any assigned meaning for the
second arg to an xref, beyond being the "name of the Info reference",
which is to say, the thing before the first colon.
http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Two-Arguments.html
(and preceding and following nodes).

I had always thought of it as an arbitrary string.

    the reference produced by `@xref{(elisp)Top, Top}.' leads to
    (experiment)Top in Emacs Info.  Is this a bug?

My opinion is yes, it is a bug.  This very example shows it is a
reasonable thing to do -- have references to Top nodes of different
manuals within one node.  In fact, I myself have written nodes that do that.

Thanks,
k

Re: Info enhancements

[Karl Berry]

    *on a completely unrelated note*, the
    strange place the stand-alone info goes to, once again seems to say:
    do not try to guess positions if you are not completely sure.
    @end unrelated

It is a judgement call.  In the case you cited, it goes to the wrong
position.  In most cases, Eli tells me, "amazingly" it goes to the right
place.

If I had written the code (Brian Fox did, it's been part of standalone
Info since early days), I probably would not have done this magic
searching, since, as we all know by now, it is a band-aid on the real
problem of subnode positioning.

If Emacs Info and standalone Info differ in this regard, I think that's
ok.  I'm not sure if I want to remove the code from sa-Info, since it's
been there so long.

Re: Info enhancements

[Karl Berry]

Responding now to Juri's original email, which I did not see before.
(Thanks for forwarding, Luc.)

All the changes look fine to me, except for the one we've been discussing:
    - - use reference names to move point to the place within the current
      node where reference name is defined.  


My only other comment is that the spate of changes around
Info-hide-note-references makes me question whether that is truly a
desirable new feature or not.  It seems like it has potential to cause
endless trouble for relatively little gain.  I hope at least that
Info-hide-note-references=t will not be the default for its first release.

Re: Info enhancements

[Karl Berry]

Responding now to Luc's mail about @anchor in general.

    If anchors are actually preferred over node names, 

I would not say that anchors are "preferred" over names.  Ultimately,
there is a bias in Texinfo toward reasonably short nodes.  When the
nodes are short, subnode positioning does not matter.  Thus, @anchor was
not available in Texinfo for many years -- and thus was not used in most
existing manuals, which predate the feature.

On the other hand, anchors are there to be used, there's no reason to
hesitate about it at this point.

    Or one might give some guidelines on _when_ to use @anchor.

I agree.  From this discussion, the answer forming in my mind is "when
you have a long node, and want to go to an exact location within it".

And I would also say "consider splitting such a long node into several
subnodes" -- but I realize there are cases where that is not desirable.

    A reference would lead in a random way either to the top of the node
    or to the "correct place".

If there were more anchors, users would simply get to the "correct"
place more often.  That's all to the good.

You're right that naming conventions could distinguish, but I'm not sure
that's completely the way to go either.  An xref label like
"file-coding-system-alist" seems perfectly reasonable to me; it is
not apparent whether it is a node or an anchor, but as long as the user
ends up at the description of file-coding-system-alist when they follow
a reference, I don't think it matters.

A couple of sentences in Help-Xref couldn't hurt.

Thanks,
k

Re: Info enhancements

[Luc Teirlinck]

Juri Linkov wrote:

   So currently no references with the same name are allowed in the same
   Info node.  I suppose the purpose of such limitation was to make
   possible to select a reference from the completion list of all references
   where names should be unique.  But we can remove such limitation by
   adding a new argument `nodename' to the `Info-follow-reference'.  This
   argument can be transfered from the `Info-try-follow-nearest-node'
   to explicitly specify a reference under point.

Why do you need an extra argument to Info-follow-reference?  It seems
to me that Info-follow-reference has access to the value of `(point)'
and should be able to get things right from that value.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my previous message:

   Why do you need an extra argument to Info-follow-reference?

Or do you plan to ask the user for more information if the user enters
`f top', `f variables' or whatever and that could refer to nodes in
several different manuals?  In which situations would you use that
extra argument and how?

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> From: Kai Grossjohann <kai@emptydomain.de>
> Date: Sat, 06 Dec 2003 21:01:11 +0000
> 
> > * electric-future-map:                   A Sample Variable Description. 
> >                                            (line 999)
> 
> Actually, I found find it nice if the "(line 999)" part would align
> with all the other line numbers that aren't on extra lines.  What do
> people think?

I tend to agree.  The question is, as always, is it feasible to force
makeinfo to do that?

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 15:40:51 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> But what do we want to do with @anchor?  I have always actually
> _avoided_ using it, because I saw it barely ever used in any major
> manual.  For instance, it is _only_ used in texinfo.txi to illustrate
> the @anchor command itself and _never_ used in info.texi.

This is simply a consequence of the decision made by manual
maintainers (in many packages, not just in Emacs) to not use features
that break old Info readers until @anchor support gets widespread
enough to justify that.  IIRC, Emacs switched to using @anchor only
after v21.1 went into press.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 19:53:22 -0500
> From: karl@freefriends.org (Karl Berry)
> 
>     the reference produced by `@xref{(elisp)Top, Top}.' leads to
>     (experiment)Top in Emacs Info.  Is this a bug?
> 
> My opinion is yes, it is a bug.

It is at least a misfeature that we should try to fix.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 19:59:41 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> My only other comment is that the spate of changes around
> Info-hide-note-references makes me question whether that is truly a
> desirable new feature or not.  It seems like it has potential to cause
> endless trouble for relatively little gain.  I hope at least that
> Info-hide-note-references=t will not be the default for its first release.

Given our experience from its introduction, I tend to agree.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 20:20:17 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> I agree.  From this discussion, the answer forming in my mind is "when
> you have a long node, and want to go to an exact location within it".
> 
> And I would also say "consider splitting such a long node into several
> subnodes" -- but I realize there are cases where that is not desirable.

A typical situation is in nodes that describe command-line arguments
accepted by a program.  These nodes are quite long and essentially
present a large group of almost-unrelated short descriptions.
Splitting such a node is not very desirable, since that would harm
"info --usage".

Perhaps we should specifically recommend use of anchors in such usage
nodes.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   > Date: Sat, 6 Dec 2003 19:59:41 -0500
   > From: karl@freefriends.org (Karl Berry)
   > 
   > My only other comment is that the spate of changes around
   > Info-hide-note-references makes me question whether that is truly a
   > desirable new feature or not.  It seems like it has potential to cause
   > endless trouble for relatively little gain.  I hope at least that
   > Info-hide-note-references=t will not be the default for its first release.

   Given our experience from its introduction, I tend to agree.

Me too.

Sincerely,

Luc.

Re: Info enhancements

[Kai Grossjohann]

"Eli Zaretskii" <eliz@elta.co.il> writes:

>> From: Kai Grossjohann <kai@emptydomain.de>
>> Date: Sat, 06 Dec 2003 21:01:11 +0000
>> 
>> > * electric-future-map:                   A Sample Variable Description. 
>> >                                            (line 999)
>> 
>> Actually, I found find it nice if the "(line 999)" part would align
>> with all the other line numbers that aren't on extra lines.  What do
>> people think?
>
> I tend to agree.  The question is, as always, is it feasible to force
> makeinfo to do that?

Oh, I think I misunderstood.  I thought the original suggestion was to
have makeinfo automatically put "(line 999)" on a new line.  In that
case, I didn't expect that the number of leading spaces (or tabs?) on
that line would make a lot of difference.  (And computing the right
number of spaces to make sure that the ")" is in column 78 doesn't
seem difficult.)

I guess there is some other issue that I'm not seeing.

Kai

Re: Info enhancements

[Eli Zaretskii]

> From: Kai Grossjohann <kai@emptydomain.de>
> Date: Sun, 07 Dec 2003 14:49:52 +0000
> >> 
> >> > * electric-future-map:                   A Sample Variable Description. 
> >> >                                            (line 999)
> >> 
> >> Actually, I found find it nice if the "(line 999)" part would align
> >> with all the other line numbers that aren't on extra lines.  What do
> >> people think?
> >
> > I tend to agree.  The question is, as always, is it feasible to force
> > makeinfo to do that?
> 
> Oh, I think I misunderstood.  I thought the original suggestion was to
> have makeinfo automatically put "(line 999)" on a new line.  In that
> case, I didn't expect that the number of leading spaces (or tabs?) on
> that line would make a lot of difference.  (And computing the right
> number of spaces to make sure that the ")" is in column 78 doesn't
> seem difficult.)
> 
> I guess there is some other issue that I'm not seeing.

What I think you are missing is that the alignment of the text "A
Sample Variable Description" is determined by the Texinfo source.  So
when makeinfo outputs the "(line 999)" thingy, it needs to somehow
``recall' the column number where that text begins (since it is not
known apriori, so cannot be simply a constant in the code).  This
requires that makeinfo ``remembers'' that column when it outputs the
line before the line number.  As makeinfo is essentially a one-pass
translator, I'm not sure it is easy to get it to remember such things.

But I might be mistaken: it's been a while since I last hacked
makeinfo.

Re: Info enhancements

[Juri Linkov]

"Eli Zaretskii" <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Sat, 06 Dec 2003 03:27:37 +0200
>> 
>> I believe this enhancement can easily be done with the existing Info
>> format.
>
> And having spent many hours hacking makeinfo and the stand-alone Info
> reader, I believe, like Karl does, that doing that is a complete waste
> of time and effort.

I appreciate your efforts and time you spent on hacking Info readers.
But I think more improvements are possible without changing the
current Info format.

> I think we basically have reached the point where
> no significant improvements could be done to Info without breaking
> something somewhere else.  Evene the relatively simple change such as
> Info-hide-node-references caused a series of unintended consequences
> that we haven't fixed yet to the full extent.

I think the main question with improvements is whether they are good
for most users or not.  Improvements that cause some troubles
(e.g. Info-hide-node-references) could be turned off by default.  And
users that want to use them should be ready to have some problems.

> Isn't the experience drawn from that experiment enough for us to
> understand the simple truth that
>
>    THOU SHALT NOT CHANGE INFO ANYMORE

But I'd rather say that

   THERE'S PLENTY OF ROOM FOR INFO IMPROVEMENT

And I mean improvement of Info readers, not improvement of the Info
format that might break something.  I think that even in its current
form the Info format is very useful.

> I say, if we want a better reader of the docs, let's invest our energy
> in an XML-based reader.

I see there is an opinion that XML format will solve all problems of
Info format.  But I must warn that

   XML IS NOT A PANACEA

It solves some problems but introduces other problems.  Just to name
one of its problems: even such a trivial operation as text search on
a whole Info document (key `s' in Info readers) in XML will cause
several problems: to search a continuous text split by XML tags
(e.g. the text "abc" in the "a<b>b</b>c") a whole XML document should
be rendered to its textual representation before search, or some
complex rules should be used to collect text squashed between many
XML elements.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Kai Grossjohann]

"Eli Zaretskii" <eliz@elta.co.il> writes:

> What I think you are missing is that the alignment of the text "A
> Sample Variable Description" is determined by the Texinfo source.  So
> when makeinfo outputs the "(line 999)" thingy, it needs to somehow
> ``recall' the column number where that text begins (since it is not
> known apriori, so cannot be simply a constant in the code).  This
> requires that makeinfo ``remembers'' that column when it outputs the
> line before the line number.  As makeinfo is essentially a one-pass
> translator, I'm not sure it is easy to get it to remember such things.

The original post showed something like this:

* foo::         Short description                       (line   42)
* bar::         A very long description causing the line number to wrap
                  (line 999)

I suggested to produce this output:

* foo::         Short description                       (line   42)
* bar::         A very long description causing the line number to wrap
                                                        (line  999)

The "(line  999)" part can be positioned without knowing the column
where "A very long description..." starts.  Instead, you can just go
to column fill-column minus 11 (the width of "(line XXXX)").

Right?

Kai

Re: Info enhancements

[Richard Stallman]

    What do you think about writing a variable name in a third argument
    of @xref with the empty second argument?

    ============================================================
    This function looks up the target in
    @ref{Default Coding Systems, , file-coding-system-alist},
    @ref{Default Coding Systems, , process-coding-system-alist}, or
    @ref{Default Coding Systems, , network-coding-system-alist},
    depending on @var{operation}.

Doesn't the variable name come out in the wrong font?
It ought to be in @code, but it won't be if.

Re: Info enhancements

[Richard Stallman]

I think it would be best if we end the discussion here
of the idea of generating a new XML form from Texinfo.
Those who would like to implement this are welcome to do so,
but discussing it on emacs-devel is not very useful.

Re: Info enhancements

[Richard Stallman]

      Note that nodes `Building Lists' and
       `Creating Strings' are very large, so user must spend a significant
       amount of time to locate this place.

When a node is so large that it is a pain to find something in it,
we should try to split it up.  Would someone like to try to split these?

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
>    Why do you need an extra argument to Info-follow-reference?  It seems
>    to me that Info-follow-reference has access to the value of `(point)'
>    and should be able to get things right from that value.

I thought that since `Info-try-follow-nearest-node' already matches a
reference name regexp, this regexp could be extended to match a node
name too, and its value could be transfered to Info-follow-reference
by extra argument.  However, this can be done in Info-follow-reference
as well given than point is still located on a position with reference.

> Or do you plan to ask the user for more information if the user enters
> `f top', `f variables' or whatever and that could refer to nodes in
> several different manuals?

Yes, there is another problem with similarly named references: how to
select a reference unambiguously from a completion list.  I thought
that node name could be concatenated with a reference name to form one
item string in a completion list to disambiguate them, for instance:

Top::
Top: (elisp)Top

and after an item is selected from the minibuffer to split it to two
values: reference name and node name and use them as function
arguments.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

I just checked that the feature in your patch that we have been mostly
discussing (the alternative to @anchor) actually _breaks_ @anchor.
After applying your patch, @anchor does not work anymore.  So, I
definitely believe that this particular feature should be removed from
your patch.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Karl Berry wrote:
>    As for the xref stuff, I am not at all sure the second arg to xref
>    should be treated in a special way; that was not its original intent and
>    nothing has ever been documented about it.  I didn't know standalone
>    info did any searching based on it.  I'll have to think about that.
>
> The standalone info goes to the wrong place in the example we have
> been looking at.  Instead of going to the intended place:
>
>  - Variable: file-coding-system-alist
>
> It goes to:
>
>      files and the contents of `file-coding-system-alist' (see below).
>
> in the description of `auto-coding-regexp-alist'.
>
> While it is very useful to go to the intended place, it is a lot
> better to just go to the top of the node than to attempt to guess.
> Going to the wrong place misleads the user.

Going to the wrong place will not mislead the user more than going to
the top of the node because when user starts to scan visually the node
by reading it from the top he soon encounters the first and wrong
occurrence of the searched string.  Now the user is exactly in the same
situation as if point was placed here automatically by the Info
reader.  So it is the task of authors of Info manuals to warn the user
that the right place is somewhere below.  And as you can notice this
is already done in the mentioned node.  You can see that authors
already added the warning "(see below)" exactly for this purpose!

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

Juri Linkov wrote:

   I thought that since `Info-try-follow-nearest-node' already matches a
   reference name regexp, this regexp could be extended to match a node
   name too, and its value could be transfered to Info-follow-reference
   by extra argument.  However, this can be done in Info-follow-reference
   as well given than point is still located on a position with reference.

If you are going to fix the bug, then you are probably best placed to
decide what the best way to do so is.

   Yes, there is another problem with similarly named references: how to
   select a reference unambiguously from a completion list.  I thought
   that node name could be concatenated with a reference name to form one
   item string in a completion list to disambiguate them, for instance:

   Top::
   Top: (elisp)Top

   and after an item is selected from the minibuffer to split it to two
   values: reference name and node name and use them as function
   arguments.

I personally believe that we should indeed tell the user that the
completion does not specify a unique alternative and allow him to make
it unique.

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 07 Dec 2003 19:31:41 +0200
> 
> Yes, there is another problem with similarly named references: how to
> select a reference unambiguously from a completion list.

Doesn't the stand-alone reader handle this correctly?  (I don't
remember.)  If it does, we could do something similar in Emacs.

Re: Info enhancements

[Eli Zaretskii]

> From: Kai Grossjohann <kai@emptydomain.de>
> Date: Sun, 07 Dec 2003 16:42:23 +0000
> 
> I suggested to produce this output:
> 
> * foo::         Short description                       (line   42)
> * bar::         A very long description causing the line number to wrap
>                                                         (line  999)
> 
> The "(line  999)" part can be positioned without knowing the column
> where "A very long description..." starts.  Instead, you can just go
> to column fill-column minus 11 (the width of "(line XXXX)").

If you always want to go to a certain column, it should be easy.  I
thought you wanted to align "line 999" on the column with the first
non-blank character of the previous line.

Re: Info enhancements

[Luc Teirlinck]

Richard Stallman wrote:

	 Note that nodes `Building Lists' and
	  `Creating Strings' are very large, so user must spend a significant
	  amount of time to locate this place.

   When a node is so large that it is a pain to find something in it,
   we should try to split it up.  Would someone like to try to split these?

I will take a look at those two.  However these two are not even the
largest nodes in the Elisp manual.  `Creating Strings' has 204 lines,
`Building Lists' 252 lines.  Many sections have more than 204 and a
few have more than 252.  For instance, `Window frame parameters' has
338 lines, `Coding Conventions' has 347.

Probably everything above 100 lines, certainly above 150, can be
inconvenient to search if only one single paragraph in the middle or
the end is referenced.  I believe we can not get all sections below
150 lines.  So there definitely seems to be some need for using
@anchor.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   > From: Juri Linkov <juri@jurta.org>
   > Date: Sun, 07 Dec 2003 19:31:41 +0200
   > 
   > Yes, there is another problem with similarly named references: how to
   > select a reference unambiguously from a completion list.

   Doesn't the stand-alone reader handle this correctly?  (I don't
   remember.)  If it does, we could do something similar in Emacs.

The user invokes `f' and starts typing in the minibuffer.

If the node is not unique because the _file_ is not unique, the
stand-alone reader chooses a node based on the value of point in the
*info* buffer.

But the user is entering input in the minibuffer.  Hence I believe it
would make more sense to ask for extra characters, as `f' does in all
other situations where the node can not be uniquely determined by the
minibuffer contents.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

All occurrences of `section' in my message about node lenghts were
meant to say `node'.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Eli Zaretskii wrote:
>    > From: Juri Linkov <juri@jurta.org>
>    > Date: Sun, 07 Dec 2003 19:31:41 +0200
>    > 
>    > Yes, there is another problem with similarly named references: how to
>    > select a reference unambiguously from a completion list.
>
>    Doesn't the stand-alone reader handle this correctly?  (I don't
>    remember.)  If it does, we could do something similar in Emacs.
>
> The user invokes `f' and starts typing in the minibuffer.
>
> If the node is not unique because the _file_ is not unique, the
> stand-alone reader chooses a node based on the value of point in the
> *info* buffer.

Yes, the stand-alone reader handles this somehow interestingly.
A completion list always has only one unique name, but if point is
somewhere above the first reference with this name in Info node then
after selecting a reference name from a completion list it goes to the
node from the first reference.  If point is somewhere below the second
reference with the same name then it goes to the second node.  If
point is between first and second reference with the same name then it
goes to the closest node.  We could do similar in Emacs if
disambiguating reference names in a completion list by adding node
names to them is undesirable.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
> Also, the question of conflicts would arise.  If there is both an index
> entry and a node with the same name, what to do?  Or two index entries
> with the same name?

There is exactly the same problem with anchors: no anchors with the
same name are allowed within one Info file.  So we can't make anchors
for two index entries with the same name.

The problem with anchors is even worse: both a node and an anchor with
the same name are not allowed in one Info file.  If there are a node
and an anchor with the same name then after following a reference with
their name the stand-alone reader always prefers a node, whereas Emacs
reader prefers an anchor.

There is the same problem with a completion list of all node names and
anchor names (called by the command `g').  Even if we make a separate
command to select an anchor this will break older Info readers that
don't allow to separately select nodes and anchors.  So older readers
will fail on Info files with anchors and nodes with the same name.

> Making them take a sixth argument or something does not sound all that
> appealing, although maybe it is the cleanest thing.

Making a sixth argument is a good idea and deserves to be elaborated
further.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
>     What do you think about writing a variable name in a third argument
>     of @xref with the empty second argument?
>
>     ============================================================
>     This function looks up the target in
>     @ref{Default Coding Systems, , file-coding-system-alist},
>     @ref{Default Coding Systems, , process-coding-system-alist}, or
>     @ref{Default Coding Systems, , network-coding-system-alist},
>     depending on @var{operation}.
>
> Doesn't the variable name come out in the wrong font?
> It ought to be in @code, but it won't be if.

Yes, one disadvantage of this is that it comes out in the wrong font.
So I tend to agree with Eli that it is better to write

   This function looks up the target in
   @code{file-coding-system-alist} (@pxref{Default Coding Systems,
   file-coding-system-alist})

which produces in the printed copy

   This function looks up the target in file-coding-system-alist
   (see Section 33.10.5 [Default Coding Systems], page 686).

and in Info

     This function looks up the target in `file-coding-system-alist'
     (*note file-coding-system-alist: Default Coding Systems.)

Although with Info-hide-note-references=t it looks awkward

   This function looks up the target in file-coding-system-alist
   (file-coding-system-alist.)

but it's desired awkwardness for users that want to hide the note tag.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Richard Stallman wrote:
>
> 	 Note that nodes `Building Lists' and
> 	  `Creating Strings' are very large, so user must spend a significant
> 	  amount of time to locate this place.
>
>    When a node is so large that it is a pain to find something in it,
>    we should try to split it up.  Would someone like to try to split these?
>
> I will take a look at those two.  However these two are not even the
> largest nodes in the Elisp manual.  `Creating Strings' has 204 lines,
> `Building Lists' 252 lines.  Many sections have more than 204 and a
> few have more than 252.  For instance, `Window frame parameters' has
> 338 lines, `Coding Conventions' has 347.

It's much more useful for users if Info nodes are split not by size
but grouped by logically related topics.  This helps to look over all
related information at once.  But it's not the case in some places.
For instance, look at the Emacs Lisp Reference Manual:

Node: Sets And Lists
 - Function: memq object list
 - Function: member-ignore-case object list
 - Function: delq object list
 - Function: member object list
 - Function: delete object sequence
 - Function: remove object sequence

Node: Building Lists
 - ...
 - Function: remq object list
 - ...

The function `remq' is placed in the wrong node and
`member-ignore-case' in the wrong place of the same node.  A better
variant is the following:

Node: Sets And Lists
 - Function: memq object list
 - Function: remq object list
 - Function: delq object list
 - Function: member object list
 - Function: member-ignore-case object list
 - Function: delete object sequence
 - Function: remove object sequence

There are other possible inconsistencies, for instance, functions
`assoc-ignore-case' and `assoc-ignore-representation' are described
in the "Text Comparison" node, but better place would be the
"Association Lists" node.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

I guess you can not update your CVS right now, but at least one of the
things you mentioned has been fixed on November 29:

       (Sets And Lists): Describe `member-ignore-case' after `member'.

Sincerely,

Luc.

Re: Info enhancements

[Kim F. Storm]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Eli Zaretskii wrote:
> 
>    > Date: Sat, 6 Dec 2003 19:59:41 -0500
>    > From: karl@freefriends.org (Karl Berry)
>    > 
>    > My only other comment is that the spate of changes around
>    > Info-hide-note-references makes me question whether that is truly a
>    > desirable new feature or not.  It seems like it has potential to cause
>    > endless trouble for relatively little gain.  I hope at least that
>    > Info-hide-note-references=t will not be the default for its first release.
> 
>    Given our experience from its introduction, I tend to agree.
> 
> Me too.
> 

I can see there are some problems, but IMO, still minor.  But given those
problems, let's change the default setting to nil.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Info enhancements

[Luc Teirlinck]

It might be useful to split up some nodes and, as I already said, I am
willing to help do so.  However, I believe that we might also have to
increase the number of @anchor's in the elisp manual from the current
four.  The two efforts could complement each other.

I believe that, for instance, a node like `(elisp)Documentation Tips'
(216 lines) is best kept together and, at the same time, large enough
to be a nuisance to wade through to find the correct item.

I CC the following proposed change to Emacs devel because I believe
that it is relevant to the discussion we are having.  The somewhat
strange name of the anchor is deliberate, to avoid interfering with
present or, especially, future, anchor or node names, and to avoid
problems with `g' completion.  It is overridden by the third argument
to @xref anyway.  It could, of course be changed.  (The [Tips] refers
to tips.texi.)

I propose to systematically rely on @anchor rather than on Juri's
feature, because it is more reliable, more flexible and because it is
an existing Texinfo feature, that does not require a departure from
current Texinfo style and conventions.

I believe that the @anchor in the diffs below could save the user
quite a bit of searching and confusion.  To me, it seems very helpful
to the user in both Info and the printed manual.  

If desired, I could commit when Savannah starts working again.  We
could start making more of these @anchor's, in similar situations.

===File ~/tips-diff=========================================
*** tips.texi.~1.53.~	Mon Oct 20 14:37:21 2003
--- tips.texi	Sun Dec  7 19:28:58 2003
***************
*** 647,652 ****
--- 647,653 ----
  This prevents the open-parenthesis from being treated as the start of a
  defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
  
+ @anchor{doc-hyperlinks [Tips]}
  @item
  @iftex
  When a documentation string refers to a Lisp symbol, write it as it
============================================================


===File ~/displaydiff=======================================
*** display.texi.~1.106.~	Sun Nov  2 12:23:12 2003
--- display.texi	Sun Dec  7 20:03:32 2003
***************
*** 805,812 ****
  so that it is still Help mode at the end of their execution, then
  @code{with-output-to-temp-buffer} makes this buffer read-only at the
  end, and also scans it for function and variable names to make them
! into clickable cross-references.  @xref{Documentation Tips, , Tips for
! Documentation Strings}.
  
  The string @var{buffer-name} specifies the temporary buffer, which
  need not already exist.  The argument must be a string, not a buffer.
--- 805,813 ----
  so that it is still Help mode at the end of their execution, then
  @code{with-output-to-temp-buffer} makes this buffer read-only at the
  end, and also scans it for function and variable names to make them
! into clickable cross-references.  @xref{doc-hyperlinks [Tips], , Tips
! for Documentation Strings}, more particularly the item on hyperlinks
! in documentation strings, for more details.
  
  The string @var{buffer-name} specifies the temporary buffer, which
  need not already exist.  The argument must be a string, not a buffer.
============================================================

Appendix: Exhaustive list (grep) of all current @anchor's in the Elisp
manual (four total):

@anchor{modifier bits} in (elisp)Character Type, 165 lines.

@anchor{Display Face Attribute Testing} in (elisp)Display Feature
Testing, 133 lines.

@anchor{Text help-echo} and @anchor{Help display}, both in
(elisp)Special Properties, 224 lines.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sun, 7 Dec 2003 12:57:46 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    Doesn't the stand-alone reader handle this correctly?  (I don't
>    remember.)  If it does, we could do something similar in Emacs.
> 
> The user invokes `f' and starts typing in the minibuffer.
> 
> If the node is not unique because the _file_ is not unique, the
> stand-alone reader chooses a node based on the value of point in the
> *info* buffer.
> 
> But the user is entering input in the minibuffer.  Hence I believe it
> would make more sense to ask for extra characters

You can still type more characters if you want, don't you?

The preference given to the reference at or closest to point does
sound like a reasonable feature, doesn't it?

If you agree to those two points, why force the user to type more when
in most cases the alternative suggested by the reader is good?

(I usually press TAB before hitting RET, just to be sure I'm going to
wind up at the right spot.  But even if I didn't, typing `l' will
bring me back to where I was, and then I can type the right node name
explicitly.)

In any case, unless you think the behavior of the stand-alone reader
is undesirable, I think we should for starters make Emacs behave
similarly.

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 07 Dec 2003 21:27:05 +0200
> 
> Yes, the stand-alone reader handles this somehow interestingly.
> A completion list always has only one unique name, but if point is
> somewhere above the first reference with this name in Info node then
> after selecting a reference name from a completion list it goes to the
> node from the first reference.  If point is somewhere below the second
> reference with the same name then it goes to the second node.  If
> point is between first and second reference with the same name then it
> goes to the closest node.

IIRC, it simply chooses the reference that is closest to point, for
some definition of ``closest''.  (Since a reference spans more than a
single character, the precise definition of ``closest'' is somewhat
vague; I needed some simple heuristics to get reasonable results.)

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 07 Dec 2003 22:00:53 +0200
> 
> karl@freefriends.org (Karl Berry) writes:
> > Also, the question of conflicts would arise.  If there is both an index
> > entry and a node with the same name, what to do?  Or two index entries
> > with the same name?
> 
> There is exactly the same problem with anchors: no anchors with the
> same name are allowed within one Info file.  So we can't make anchors
> for two index entries with the same name.
> 
> The problem with anchors is even worse: both a node and an anchor with
> the same name are not allowed in one Info file.

I think that's precisely the problem that Karl was talking about.

(IMHO, having several index entries with the same name is not a good
idea, anyway.  It is much better to disambiguate them by adding a bit
of context information to each entry.  For example, instead of having
two entries that say "@cindex foo", do this:

  @cindex foo, used together with @code{bar}
  @cindex foo, when before @code{baz}

Not only does this help to find the required info faster when looking
at the index of a printed copy, it also allows the user to decide
which completion to select when she types "i foo TAB", whereas given
the two completions "foo<1>" and "foo<2>" such a decision is
impossible.  But I digress...)

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 07 Dec 2003 23:21:45 +0200
> 
> Although with Info-hide-note-references=t it looks awkward
> 
>    This function looks up the target in file-coding-system-alist
>    (file-coding-system-alist.)

I think that, under Info-hide-note-references=t, a reference inside
parens should have a "see " before the reference name.

Re: Info enhancements

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
> The preference given to the reference at or closest to point does
> sound like a reasonable feature, doesn't it?

I agree that using the reference closest to point is a reasonable
feature.  Firstly, the cases with two references with the same name
in one Info node are very rare.  Secondly, mostly users put point on
the reference before following it.  So this feature will work in the
most cases.  So I agree that Emacs should behave similarly.  I'll look
over the source code of the stand-alone reader.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Sun, 07 Dec 2003 23:21:45 +0200
>> 
>> Although with Info-hide-note-references=t it looks awkward
>> 
>>    This function looks up the target in file-coding-system-alist
>>    (file-coding-system-alist.)
>
> I think that, under Info-hide-note-references=t, a reference inside
> parens should have a "see " before the reference name.

I still think that replacing a "note" with "see" has no sense because
if the user prefers to set the Info-hide-note-references to t this
means that he don't want to see any tags before the reference name.
Since references are fontified in a different color the user can
already recognize a reference without an additional hint that
encourages him to follow this reference.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

storm@cua.dk (Kim F. Storm) writes:
> Luc Teirlinck <teirllm@dms.auburn.edu> writes:
>> Eli Zaretskii wrote:
>>    > Date: Sat, 6 Dec 2003 19:59:41 -0500
>>    > From: karl@freefriends.org (Karl Berry)
>>    > 
>>    > My only other comment is that the spate of changes around
>>    > Info-hide-note-references makes me question whether that is truly a
>>    > desirable new feature or not.  It seems like it has potential to cause
>>    > endless trouble for relatively little gain.  I hope at least that
>>    > Info-hide-note-references=t will not be the default for its first release.
>> 
>>    Given our experience from its introduction, I tend to agree.
>> 
>> Me too.
>
> I can see there are some problems, but IMO, still minor.  But given those
> problems, let's change the default setting to nil.

I like the Info-hide-note-references feature very much but I agree
that it might be a bit confusing for unaware users.  So if it will
be changed to nil by default, this feature should be suggested in the
Info manual with an explanation of all its consequences.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Miles Bader]

Juri Linkov <juri@jurta.org> writes:
> I still think that replacing a "note" with "see" has no sense because
> if the user prefers to set the Info-hide-note-references to t this
> means that he don't want to see any tags before the reference name.

`See' makes perfect sense -- it makes the reference into (usually)
correct english without drawing undue attention to itself, which is in
keeping with the style of the documentation, whereas the *Note crap is
just ugly obfuscation.

> Since references are fontified in a different color the user can
> already recognize a reference without an additional hint that
> encourages him to follow this reference.

[Doesn't work too well on non-color displays, and yes those exist.]

-Miles
-- 
Ich bin ein Virus. Mach' mit und kopiere mich in Deine .signature.

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Mon, 08 Dec 2003 12:12:22 +0200
> >
> > I think that, under Info-hide-note-references=t, a reference inside
> > parens should have a "see " before the reference name.
> 
> I still think that replacing a "note" with "see" has no sense because
> if the user prefers to set the Info-hide-note-references to t this
> means that he don't want to see any tags before the reference name.

"See" is not a tag, it's a word that, if added, makes the text in
parens be comprehensible by humans.

> Since references are fontified in a different color the user can
> already recognize a reference without an additional hint that
> encourages him to follow this reference.

Let's imagine that this text is in some HTML page: would you argue
even then that it is a well-written reference?  I think you'd expect
"see" or some such; at least I would.

Re: Info enhancements

[Juri Linkov]

Miles Bader <miles@lsi.nec.co.jp> writes:
> Juri Linkov <juri@jurta.org> writes:
>> I still think that replacing a "note" with "see" has no sense because
>> if the user prefers to set the Info-hide-note-references to t this
>> means that he don't want to see any tags before the reference name.
>
> `See' makes perfect sense -- it makes the reference into (usually)
> correct english without drawing undue attention to itself, which is in
> keeping with the style of the documentation, whereas the *Note crap is
> just ugly obfuscation.

These attempts to fix the *Note to produce correct English cause
too much trouble: inserting the text "See" into Info buffers breaks
some Info functions (e.g. `Info-last', `Info-search').

>> Since references are fontified in a different color the user can
>> already recognize a reference without an additional hint that
>> encourages him to follow this reference.
>
> [Doesn't work too well on non-color displays, and yes those exist.]

It works on non-color displays very well because in this case it
underlines the references (just like web browsers do).

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Mon, 08 Dec 2003 12:46:00 +0200
> 
> inserting the text "See" into Info buffers breaks
> some Info functions (e.g. `Info-last', `Info-search').

You don't need to actually insert "see" into the buffer, you could
define an overlay instead.

Re: Info enhancements

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Mon, 08 Dec 2003 12:46:00 +0200
>> 
>> inserting the text "See" into Info buffers breaks
>> some Info functions (e.g. `Info-last', `Info-search').
>
> You don't need to actually insert "see" into the buffer, you could
> define an overlay instead.

Seems overlays don't interact well with the `invisible' property.
For instance, move point to the beginning of the reference
with Info-hide-note-references=t and evaluate this code:
M-: (overlay-put (make-overlay (point) (point)) 'before-string "See ")
and the reference loses its fontification.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   You don't need to actually insert "see" into the buffer, you could
   define an overlay instead.

Please do not use overlays to insert things that look like regular
text.  It is extremely confusing to users who want to cut and paste,
save things to file, print out hardcopy and do all kind of other
everyday stuff.  We already got rid of similar uses (in info with
Info-hide-note-references set to t) for these reasons and made things
such that only the amount of whitespace was controlled by an overlay
(which is still somewhat bad, but much less bad than regular
non-whitespace text).

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

I intend to replace the `@anchor{doc-hyperlinks [Tips]} in my original
patch with `@anchor{docstring-hyperlinks}'.  Karl Berry thought that
the risk of duplication was not big enough to add the `[Tips]' (whose
intent was to make the name more `unique').

Sincerely,

Luc.

Re: Info enhancements

[Richard Stallman]

      For instance, `Window frame parameters' has
    338 lines, `Coding Conventions' has 347.

There may be difficulties in splitting Window frame parameters.
Splitting Coding Conventions is possible if someone can think
of a good subtopic that a large fraction fit into.

    Probably everything above 100 lines, certainly above 150, can be
    inconvenient to search if only one single paragraph in the middle or
    the end is referenced.  I believe we can not get all sections below
    150 lines.

I agree.

Re: Info enhancements

[Richard Stallman]

Nobody seems to be considering a format line

  * foo: Node (line 42).       A short description.

which I and at least one other person thought would be
more natural and clear.

Re: Info enhancements

[Stefan Monnier]

> Nobody seems to be considering a format line
>   * foo: Node (line 42).       A short description.

> which I and at least one other person thought would be
> more natural and clear.

But indices are a funny kind of menu where there's a lot of space between
`foo' and `Node' and where there is typically no `a short description'.
I.e. it looks like:

  * foo:                               Node.

so your proposal is to use

  * foo:                               Node (line 42).

which is not aesthetically very different from

  * foo:                               Node. (line 42)

or

  * foo:                               Node.  Line 42.

It does have the difference that it puts the line info in the
"location" part of the reference, which is probably a good thing.


        Stefan

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   You can still type more characters if you want, don't you?

No (at least not currently), because `f' is based on the reference
name (not the node name, as we may have abusively said sometimes).
Hence, if two references have the same name you currently can not type
more characters, because the reference name has no file name
component.  I believe Juri wanted to make it possible to append a file
name to the reference name to distinguish. (If I understood
correctly.)

   The preference given to the reference at or closest to point does
   sound like a reasonable feature, doesn't it?

Can give some bad surprises, like typing `f' followed by a reference
one is seeing on the screen and the reader going to a "closer"
off-screen reference of the same name.

Anyway, in practice the situation only occurs in very special buffers
like Juri's history buffer, so it is not worth an endless discussion.

If you and Juri both believe that it is better to go with the
stand-alone reader's behavior, then that is fine with me.

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> Date: Mon, 8 Dec 2003 21:34:15 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    The preference given to the reference at or closest to point does
>    sound like a reasonable feature, doesn't it?
> 
> Can give some bad surprises, like typing `f' followed by a reference
> one is seeing on the screen and the reader going to a "closer"
> off-screen reference of the same name.

Does this really happen in practice?  That is, can you really create a
situation where an off-screen reference wins?  I'd think the
stand-alone reader should avoid that pitfall, but I might be mistaken.

Re: Info enhancements

[Eli Zaretskii]

> Date: Mon, 8 Dec 2003 11:05:44 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    You don't need to actually insert "see" into the buffer, you could
>    define an overlay instead.
> 
> Please do not use overlays to insert things that look like regular
> text.  It is extremely confusing to users who want to cut and paste,
> save things to file, print out hardcopy and do all kind of other
> everyday stuff.

Don't we already see similar adverse effects under
Info-hide-note-references set to t?  If we do, then using overlays
when that same option is in effect will not make things worse than
they already are.

Re: Info enhancements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> Eli Zaretskii <eliz@elta.co.il> writes:
> >> From: Juri Linkov <juri@jurta.org>
> >> Date: Mon, 08 Dec 2003 12:46:00 +0200
> >> 
> >> inserting the text "See" into Info buffers breaks
> >> some Info functions (e.g. `Info-last', `Info-search').
> >
> > You don't need to actually insert "see" into the buffer, you could
> > define an overlay instead.
> 
> Seems overlays don't interact well with the `invisible' property.
> For instance, move point to the beginning of the reference
> with Info-hide-note-references=t and evaluate this code:
> M-: (overlay-put (make-overlay (point) (point)) 'before-string "See ")
> and the reference loses its fontification.

I still think Info-hide-note-references=t is a good default choice
if we can make it work better.  And I think we can.

The following patch seems to work well for me (no lost fontification
of the reference), and it doesn't alter the buffer as before, which
should make references by buffer positions work again.

And copy/paste works at least as well (or equally bad) as before.


*** info.el.~1.374.~	2003-10-06 09:14:21.000000000 +0200
--- info.el	2003-12-09 12:48:04.000000000 +0100
***************
*** 2938,2944 ****
  		(goto-char next))
  	      (if hide-tag
  		  (add-text-properties (match-beginning 1) (match-end 1)
! 				       '(invisible t front-sticky nil rear-nonsticky t)))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
  	       (cons 'help-echo
--- 2938,2946 ----
  		(goto-char next))
  	      (if hide-tag
  		  (add-text-properties (match-beginning 1) (match-end 1)
! 				       (if other-tag
! 					   `(display ,other-tag front-sticky nil rear-nonsticky t)
! 					 '(invisible t front-sticky nil rear-nonsticky t))))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
  	       (cons 'help-echo
***************
*** 2950,2959 ****
  	      (when (eq Info-hide-note-references t)
  		(add-text-properties (match-beginning 3) (match-end 3)
  				     '(invisible t front-sticky nil rear-nonsticky t)))
- 	      (when other-tag
- 		(save-excursion
- 		  (goto-char (match-beginning 1))
- 		  (insert other-tag)))
  	      (when (and Info-refill-paragraphs
  			 (or hide-tag (eq Info-hide-note-references t)))
  		(push (set-marker (make-marker) start)
--- 2952,2957 ----

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Info enhancements

[Richard Stallman]

    I like the Info-hide-note-references feature very much but I agree
    that it might be a bit confusing for unaware users.

The feature will not be much use if it is off by default.
If we conclude that we must leave it off by default, in effect
we are concluding it is a failure.  Perhaps we must reach that
conclusion, but we should not mislead ourselves about what
the conclusion means.

Re: Info enhancements

[Richard Stallman]

    It might be useful to split up some nodes and, as I already said, I am
    willing to help do so.  However, I believe that we might also have to
    increase the number of @anchor's in the elisp manual from the current
    four.  The two efforts could complement each other.

By all means install anchors wherever you find them useful.

Re: Info enhancements

[Richard Stallman]

    (IMHO, having several index entries with the same name is not a good
    idea, anyway.  It is much better to disambiguate them by adding a bit
    of context information to each entry.  For example, instead of having
    two entries that say "@cindex foo", do this:

Our policy is to avoid such duplicates, and disambiguate instead.

Re: Info enhancements

[Richard Stallman]

I will move remq, thanks.  I think that assoc-ignore-* belong where they are.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   > Can give some bad surprises, like typing `f' followed by a reference
   > one is seeing on the screen and the reader going to a "closer"
   > off-screen reference of the same name.

   Does this really happen in practice?  That is, can you really create a
   situation where an off-screen reference wins?

Yes.  In the `Entry' node of the following file, put point at the
start of the line containing the first of the series of a's.  Do:
M-0 C-l.

The `@xref{Top, , , dir}.' is now out of view. We do `f' and see:

Follow xref (Top): 

If we accept the default (or type Top), we go to (dir)Top, an
off-screen reference, whereas `@xref{Top, Top, , elisp}.' is visible.

===File ~/experiment.texi===================================
\input texinfo    @c -*-texinfo-*-
@comment %**start of header
@setfilename experiment.info
@settitle An experiment.
@comment %**end of header

@node Top
@top Top

@menu
* name: entry.           description.
@end menu

@node entry
@chapter Entry

This node is called @samp{entry}
@xref{Top}.  @xref{Top, , , dir}.

a

a

a

a

a

@xref{Top, Top, , elisp}.

@bye
============================================================

Resulting .info file:

===File ~/experiment.info===================================
This is experiment.info, produced by makeinfo version 4.6 from
experiment.texi.

\x1f
File: experiment.info,  Node: Top,  Next: entry,  Up: (dir)

Top
***

* Menu:

* name: entry.           description.

\x1f
File: experiment.info,  Node: entry,  Prev: Top,  Up: Top

Entry
*****

This node is called `entry' *Note Top::.  *Note Top: (dir)Top.

   a

   a

   a

   a

   a

   *Note Top: (elisp)Top.


\x1f
Tag Table:
Node: Top\x7f81
Node: entry\x7f201
\x1f
End Tag Table
============================================================

Re: Info enhancements

[Luc Teirlinck]

I forgot to point out that my previous message applied to the
_stand-alone_ info reader.  (I believe this is obvious to Eli, but
not to people who have not followed prior postings.)  Emacs Info goes
to (experiment)Top, which appears to be definitely wrong, as we
discussed before.  The stand-alone behavior _is_ relevant to Emacs,
because we are discussing whether or not Emacs should adopt the
present stand-alone behavior.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

Richard Stallman wrote:

   There may be difficulties in splitting Window frame parameters.
   Splitting Coding Conventions is possible if someone can think
   of a good subtopic that a large fraction fit into.

I agreed to start splitting nodes.  However, I actually started trying
to do so and very soon I started doubting whether this was, right now,
the best thing to do.  Even though there is no specific deadline, we
are preparing to release a new printed version of the Elisp manual.

Splitting nodes or even moving many items between nodes requires a lot
of work.  Splitting the node itself is not the worst part, the real
work is looking up all references to the old node in all manuals
included with the Emacs distribution and deciding to which of the two
new nodes they should refer.  Often, we will need to reference both
new nodes.  (Moving remq is OK, because there appears to be little
danger with that one.)

We need to do this anew each time we split a node and if we decide
that even `Creating Strings' with its 204 lines is too big, then there
are _many_ nodes to split.  On the other hand, we already decided that
splitting the second largest node in the manual, `Window frame
parameters', 338 lines, is undesirable.

If the only reason to split nodes is so that the reader will have no
difficulties following references, then I believe that it is
substantially less work to systematically go through all references in
the elisp manual and check which ones could use @anchor's.  I did this
for `Non-ASCII Characters' and it is less work than one might expect.

The @anchor solution works well for both info and for the printed
manual.  Since Juri's proposed feature only works for info and does
not adjust page numbers in the printed manual, it is not a real
alternative.

I propose, at least for this edition of the manual, since there
appears to be still so much work to do, to just try to put in
@anchor's in all places where needed and not to split nodes based
solely on their length.

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Tue, 09 Dec 2003 16:48:31 -0500
> 
> If we conclude that we must leave it off by default, in effect
> we are concluding it is a failure.

I'm not sure this is always so.  Some newly introduced options are
deliberately left off by default to avoid drastic changes in the
default behavior (that would surprise users) or if we are uncertain
whether users will like them.  So I don't think every option that's
off by default means a failure.

Re: Info enhancements

[Eli Zaretskii]

> Date: Tue, 9 Dec 2003 20:56:44 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    > Can give some bad surprises, like typing `f' followed by a reference
>    > one is seeing on the screen and the reader going to a "closer"
>    > off-screen reference of the same name.
> 
>    Does this really happen in practice?  That is, can you really create a
>    situation where an off-screen reference wins?
> 
> Yes.  In the `Entry' node of the following file, put point at the
> start of the line containing the first of the series of a's.  Do:
> M-0 C-l.
> 
> The `@xref{Top, , , dir}.' is now out of view. We do `f' and see:
> 
> Follow xref (Top): 
> 
> If we accept the default (or type Top), we go to (dir)Top, an
> off-screen reference, whereas `@xref{Top, Top, , elisp}.' is visible.

Sounds like a bug in the stand-alone reader: it should have filtered
out off-screen references, unless they are the only ones in the node.
I probably failed to consider this possibility (or perhaps there's no
easy way to know what's off screen in the stand-alone reader).

Re: Info enhancements

[Richard Stallman]

      Even though there is no specific deadline, we
    are preparing to release a new printed version of the Elisp manual.

I see your point.  It can wait.

    I propose, at least for this edition of the manual, since there
    appears to be still so much work to do, to just try to put in
    @anchor's in all places where needed and not to split nodes based
    solely on their length.

Please add anchors wherever you think they will be useful.

Re: Info enhancements

[Richard Stallman]

    I'm not sure this is always so.  Some newly introduced options are
    deliberately left off by default to avoid drastic changes in the
    default behavior (that would surprise users) or if we are uncertain
    whether users will like them.

It is true we could leave it off by default temporarily, then ask
people to try it and do a poll.  But if it isn't ultimately enabled by
default, it will be mostly a failure.

Re: Info enhancements

[Juri Linkov]

I'd like to submit the new version of a patch that fixes problems
in the Emacs Info reader and adds new features.  Actually, this is a
patch to the previous patch because below I describe the changes made
after previous changes.  I can send a full patch when needed.
Thanks for all the responses to the previous patch.

* Implemented a new `S' command suggested by Eli.  This command is
  bound to a new function `Info-search-case-sensitively' that searches
  for a regexp case-sensitively.  The `Info-search-next' uses the case
  of a previous `Info-search' or `Info-search-case-sensitively' command.

* Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).

* Added a new variable `Info-search-whitespace-regexp' used to match a
  sequence of whitespace chars in Info search.  I borrowed this idea
  from `search-whitespace-regexp' from isearch.el.

* Removed the history tree feature from the previous patch because
  I found that history tree is less useful than a history list.  There
  are many different variants of tree creation so I couldn't decide
  which is the better one.  But I think that a plain history list
  sorted by node visiting order is good enough.  The history list
  items are represented now by menu instead of references because menu
  is more useful for selecting history nodes (keys 1-9 can be used to
  quickly select a history item in node's menu).

* Unhide a file name in menu items if it has no period after parentheses,
  (i.e. it don't refer to the "Top" node).  This is needed mostly
  for the history list menu where Info file names should be shown.

* Node Tree: this new feature generates a separate buffer with a tree
  of all Info node names collected from an Info file.  The node-subnode
  relationships are extracted from node menus.  The generated buffer
  with a node tree contains the references to Info nodes.  I "stole"
  two functions for this feature from ee-info.el file that builds
  different tree views of Info nodes.  I think that node tree feature
  will be useful even for users not installed the Ee package.  The
  keybinding for this feature is "*".

* A new value 'hide ("Hide tag and reference") of user variable
  `Info-hide-note-references' is added for users that don't want
  to see "see" (no pun intended almost) instead of "*note".  This
  option is also needed for the node tree feature because inserting
  "see" before every node in a node tree is too ugly.

* The function `Info-follow-reference' gives the preference to the
  reference at or closest to point (suggested by Eli to make it
  similar to the standalone Info reader).  However, currently it
  don't handle a situation with off-screen references, because it's
  too impractical to write code for such extremely rare situations.

* The functions `Info-next-reference' and `Info-prev-reference' now
  skip the "*note" tag and move cursor to the position on reference
  immediately after this tag.  This is especially useful when "*note"
  is replaced with "see" by a `display' property as suggested by Kim
  because it's better when point is placed directly on the reference
  instead of the "see" text.

* The command `u' (`Info-up') now relocates point to the menu item
  with the name of a previously visited node.  Very useful to keep
  track of node navigation from menu.

* All anchors are filtered out from a node completion list.  I'm not
  sure whether a separate command with anchor list to select and go to
  a selected anchor by its name is needed or not?  Seems anchors are
  useful only for making references to them, not for selecting them
  from completion list.

* Fixed a bug reported by Luc for the previous patch where anchors
  were disabled by the reference names feature.  I still think this
  feature is very useful especially for moving from indexes directly
  to lines where index items are described.  This feature can be
  replaced later gradually by anchors as suggested by Luc.  However,
  now this feature needs more testing to collect more evidences for
  its usefulness/uselessness/harmfulness.

* Fixed a bug reported by Luc where header-line's gone blank.
  It's fixed by calling fontification only once, but calling
  refontification of visited links every time.

* The function `Info-fontify-menu-headers' is removed and its content
  moved to `Info-fontify-node' where is was called before.

===================================================================
diff -cwB emacs/lisp/info.el~ emacs/lisp/info.el
*** emacs/lisp/info.el~	Tue Dec 02 00:25:29 2003
--- emacs/lisp/info.el	Fri Dec 12 02:45:12 2003
***************
*** 45,59 ****
  
  
  (defvar Info-history nil
!   "List of info nodes user has visited.
  Each element of list is a list (FILENAME NODENAME BUFFERPOS).")
  
! (defvar Info-history-tree nil
!   "Tree of info nodes user has visited.
! Each element of list is a list (FILENAME NODENAME PARENT-INDEX).")
! 
! (defvar Info-history-node -1
!   "Position of the current node on the info nodes tree user has visited.")
  
  (defcustom Info-enable-edit nil
    "*Non-nil means the \\<Info-mode-map>\\[Info-edit] command in Info can edit the current node.
--- 45,56 ----
  
  
  (defvar Info-history nil
!   "Stack of info nodes user has visited.
  Each element of list is a list (FILENAME NODENAME BUFFERPOS).")
  
! (defvar Info-history-list nil
!   "Full list of all info nodes user has ever visited.
! Each element of list is a list (FILENAME NODENAME).")
  
  (defcustom Info-enable-edit nil
    "*Non-nil means the \\<Info-mode-map>\\[Info-edit] command in Info can edit the current node.
***************
*** 175,185 ****
  
  (defcustom Info-hide-note-references t
    "*If non-nil, hide the tag and section reference in *note and * menu items.
  If value is non-nil but not t, the reference section is still shown."
    :version "21.4"
!   :type '(choice (const :tag "No reformatting" nil)
  		 (const :tag "Replace tag and hide reference" t)
! 		 (other :tag "Replace only tag" tag))
    :group 'info)
  
  (defcustom Info-refill-paragraphs nil
--- 172,184 ----
  
  (defcustom Info-hide-note-references t
    "*If non-nil, hide the tag and section reference in *note and * menu items.
+ Also replaces the \"*note\" text with \"see\".
  If value is non-nil but not t, the reference section is still shown."
    :version "21.4"
!   :type '(choice (const :tag "No hiding" nil)
  		 (const :tag "Replace tag and hide reference" t)
! 		 (other :tag "Hide tag and reference" hide)
! 		 (other :tag "Only replace tag" tag))
    :group 'info)
  
  (defcustom Info-refill-paragraphs nil
***************
*** 190,195 ****
--- 189,203 ----
    :type 'boolean
    :group 'info)
  
+ (defcustom Info-search-whitespace-regexp "\\\\(?:\\\\s-+\\\\)"
+   "*If non-nil, regular expression to match a sequence of whitespace chars.
+ This applies to regular expression Info search.
+ You might want to use something like \"[ \\t\\r\\n]+\" instead.
+ In the Customization buffer, that is `[' followed by a space,
+ a tab, a carriage return (control-M), a newline, and `]+'."
+   :type 'regexp
+   :group 'info)
+ 
  (defcustom Info-mode-hook
    ;; Try to obey obsolete Info-fontify settings.
    (unless (and (boundp 'Info-fontify) (null Info-fontify))
***************
*** 225,231 ****
    "List of possible matches for last `Info-index' command.")
  
  (defvar Info-reference-name nil
!   "Name of the current reference.")
  
  (defvar Info-standalone nil
    "Non-nil if Emacs was started solely as an Info browser.")
--- 233,241 ----
    "List of possible matches for last `Info-index' command.")
  
  (defvar Info-reference-name nil
!   "Name of the selected cross-reference.
! Point is moved to the proper occurrence of this name within a node
! after selecting it.")
  
  (defvar Info-standalone nil
    "Non-nil if Emacs was started solely as an Info browser.")
***************
*** 809,820 ****
  		       nodename)))
  
  	    (Info-select-node)
! 	    (goto-char (or anchorpos (point-min)))
! 
!             ;; Move point to the place where the referer name points to
!             (when Info-reference-name
                (Info-find-index-name Info-reference-name)
!               (setq Info-reference-name nil)))))
      ;; If we did not finish finding the specified node,
      ;; go back to the previous one.
      (or Info-current-node no-going-back (null Info-history)
--- 819,829 ----
  		       nodename)))
  
  	    (Info-select-node)
! 	    (goto-char (point-min))
! 	    (cond (anchorpos (goto-char anchorpos))
! 		  (Info-reference-name
  		   (Info-find-index-name Info-reference-name)
! 		   (setq Info-reference-name nil))))))
      ;; If we did not finish finding the specified node,
      ;; go back to the previous one.
      (or Info-current-node no-going-back (null Info-history)
***************
*** 1201,1225 ****
  					    (read (current-buffer))))))
  			    (point-max)))
  	(if Info-enable-active-nodes (eval active-expression))
  	(Info-fontify-node)
  	(Info-display-images-node)
- 
-         ;; Add a new history node or use old node from the history tree
-         (let ((tree Info-history-tree)
-               (i 0) res)
-           (while tree
-             (if (and (equal (nth 0 (car tree)) Info-current-file)
-                      (equal (nth 1 (car tree)) Info-current-node))
-                 (setq res i tree nil))
-             (setq tree (cdr tree) i (1+ i)))
-           (if res
-               (setq Info-history-node res)
-             (setq Info-history-tree
-                   (nconc Info-history-tree
-                          (list (list Info-current-file Info-current-node
-                                      Info-history-node)))
-                   Info-history-node (1- (length Info-history-tree)))))
- 
  	(run-hooks 'Info-selection-hook)))))
  
  (defun Info-set-mode-line ()
--- 1210,1221 ----
  					    (read (current-buffer))))))
  			    (point-max)))
  	(if Info-enable-active-nodes (eval active-expression))
+ 	;; Add a new unique history item to full history list
+ 	(let ((new-history (list Info-current-file Info-current-node)))
+ 	  (setq Info-history-list
+ 		(cons new-history (delete new-history Info-history-list))))
  	(Info-fontify-node)
  	(Info-display-images-node)
  	(run-hooks 'Info-selection-hook)))))
  
  (defun Info-set-mode-line ()
***************
*** 1251,1257 ****
    (if fork
        (set-buffer
         (clone-buffer (concat "*info-" (if (stringp fork) fork nodename) "*") t)))
!   (if (equal (buffer-name) "*info-history*")
        (switch-to-buffer "*info*"))
    (let (filename)
      (string-match "\\s *\\((\\s *\\([^\t)]*\\)\\s *)\\s *\\|\\)\\(.*\\)"
--- 1247,1253 ----
    (if fork
        (set-buffer
         (clone-buffer (concat "*info-" (if (stringp fork) fork nodename) "*") t)))
!   (if (member (buffer-name) '("*info-history*" "*info-tree*"))
        (switch-to-buffer "*info*"))
    (let (filename)
      (string-match "\\s *\\((\\s *\\([^\t)]*\\)\\s *)\\s *\\|\\)\\(.*\\)"
***************
*** 1327,1335 ****
  		  (widen)
  		  (goto-char marker)
  		  (while (re-search-forward "\n\\(Node\\|Ref\\): \\(.*\\)\177" nil t)
  		    (setq compl
  			  (cons (list (match-string-no-properties 2))
! 				compl))))
  	      (widen)
  	      (goto-char (point-min))
  	      ;; If the buffer begins with a node header, process that first.
--- 1323,1332 ----
  		  (widen)
  		  (goto-char marker)
  		  (while (re-search-forward "\n\\(Node\\|Ref\\): \\(.*\\)\177" nil t)
+ 		    (or (string-equal "Ref" (match-string 1))
  			(setq compl
  			      (cons (list (match-string-no-properties 2))
! 				    compl)))))
  	      (widen)
  	      (goto-char (point-min))
  	      ;; If the buffer begins with a node header, process that first.
***************
*** 1361,1366 ****
--- 1358,1366 ----
  (defvar Info-search-history nil
    "The history list for `Info-search'.")
  
+ (defvar Info-search-case-fold nil
+   "The value of `case-fold-search' from previous `Info-search' command.")
+ 
  (defun Info-search (regexp)
    "Search for REGEXP, starting from point, and select node it's found in."
    (interactive (list (read-string
***************
*** 1380,1385 ****
--- 1380,1389 ----
  	  (opoint (point))
  	  (ostart (window-start))
  	  (osubfile Info-current-subfile))
+       (when Info-search-whitespace-regexp
+         (setq regexp (replace-regexp-in-string
+                       "[ \t\n]+" Info-search-whitespace-regexp regexp)))
+       (setq Info-search-case-fold case-fold-search)
        (save-excursion
  	(save-restriction
  	  (widen)
***************
*** 1456,1468 ****
  	  (setq Info-history (cons (list ofile onode opoint)
  				   Info-history))))))
  
  (defun Info-search-next ()
    "Search for next regexp from a previous `Info-search' command."
    (interactive)
    (if Info-search-history
        (Info-search (car Info-search-history))
!     ;; If no history then read search string in Info-search
!     (call-interactively 'Info-search)))
  \f
  (defun Info-extract-pointer (name &optional errorname)
    "Extract the value of the node-pointer named NAME.
--- 1460,1478 ----
  	  (setq Info-history (cons (list ofile onode opoint)
  				   Info-history))))))
  
+ (defun Info-search-case-sensitively ()
+   "Search for a regexp case-sensitively."
+   (interactive)
+   (let ((case-fold-search nil))
+     (call-interactively 'Info-search)))
+ 
  (defun Info-search-next ()
    "Search for next regexp from a previous `Info-search' command."
    (interactive)
+   (let ((case-fold-search Info-search-case-fold))
      (if Info-search-history
          (Info-search (car Info-search-history))
!       (call-interactively 'Info-search))))
  \f
  (defun Info-extract-pointer (name &optional errorname)
    "Extract the value of the node-pointer named NAME.
***************
*** 1514,1525 ****
    "Go to the superior node of this node.
  If SAME-FILE is non-nil, do not move to a different Info file."
    (interactive)
!   (let ((node (Info-extract-pointer "up")))
      (and (or same-file (not (stringp Info-current-file)))
  	 (string-match "^(" node)
  	 (error "Up node is in another Info file"))
!     (Info-goto-node node))
!   (Info-restore-point Info-history))
  
  (defun Info-last ()
    "Go back to the last node visited."
--- 1524,1547 ----
    "Go to the superior node of this node.
  If SAME-FILE is non-nil, do not move to a different Info file."
    (interactive)
!   (let ((old-node Info-current-node)
!         (old-file Info-current-file)
!         (node (Info-extract-pointer "up")) p)
      (and (or same-file (not (stringp Info-current-file)))
  	 (string-match "^(" node)
  	 (error "Up node is in another Info file"))
!     (Info-goto-node node)
!     (setq p (point))
!     (goto-char (point-min))
!     (if (and (search-forward "\n* Menu:" nil t)
!              (re-search-forward
!               (if (string-equal old-node "Top")
!                   (concat "\n\\*.+: (" (file-name-nondirectory old-file) ")")
!                 (concat "\n\\* +" old-node ":"))
!               nil t))
!         (beginning-of-line)
!       (goto-char p)
!       (Info-restore-point Info-history))))
  
  (defun Info-last ()
    "Go back to the last node visited."
***************
*** 1535,1587 ****
      (setq Info-history (cdr Info-history))
      (goto-char opoint)))
  
  ;;;###autoload (add-hook 'same-window-buffer-names "*info-history*")
  
! (defun Info-history-buffer (&optional tree-p)
!   "Create the buffer *info-history* with references to visited nodes.
! Optional argument TREE-P creates a tree of nodes; the default
! creates the plain list of nodes."
!   (interactive "P")
!   (let ((curr-node Info-history-node)
          p)
      (pop-to-buffer
       (with-current-buffer (get-buffer-create "*info-history*")
!        (let ((Info-hide-note-references t)
!              (Info-visited-nodes t)
!              (inhibit-read-only t))
           (erase-buffer)
           (goto-char (point-min))
!          (setq p (Info-insert-history-tree -1 0 (or curr-node 0) tree-p))
!          (if (not (bobp)) (Info-fontify-node))
           (or (eq major-mode 'Info-mode) (Info-mode))
!          (let ((Info-current-file "history")
!                (Info-current-node "History"))
!            (Info-set-mode-line))
           (current-buffer))))
      (goto-char (or p (point-min)))))
  
! (defun Info-insert-history-tree (index indent curr-node tree-p)
!   "Insert the tree or list of references to visited nodes.
! Return the position of the current node on the generated tree."
!   (let ((tree Info-history-tree)
!         (i 0) p)
!     (while tree
!       (when (or (null tree-p) (eq (nth 2 (car tree)) index))
!         (if tree-p (insert (make-string indent ?\040)))
!         (if (eq i curr-node) (setq p (point)))
!         (insert  "*Note " (nth 1 (car tree)) ": ("
!                  (file-name-nondirectory (nth 0 (car tree)))
!                  ")" (nth 1 (car tree)) ".\n")
!         (if tree-p (setq p (or (Info-insert-history-tree
!                                 i (1+ indent) curr-node tree-p) p))))
!       (setq tree (cdr tree) i (1+ i)))
!     p))
  
! ;;;###autoload
! (defun Info-directory ()
!   "Go to the Info directory node."
    (interactive)
!   (Info-find-node "dir" "top"))
  \f
  (defun Info-follow-reference (footnotename &optional fork)
    "Follow cross reference named FOOTNOTENAME to the node it refers to.
--- 1557,1758 ----
      (setq Info-history (cdr Info-history))
      (goto-char opoint)))
  
+ 
+ ;;;###autoload
+ (defun Info-directory ()
+   "Go to the Info directory node."
+   (interactive)
+   (Info-find-node "dir" "top"))
+ \f
  ;;;###autoload (add-hook 'same-window-buffer-names "*info-history*")
  
! (defun Info-history-buffer ()
!   "Create the buffer *info-history* with references to visited nodes."
!   (interactive)
!   (let ((curr-file Info-current-file)
!         (curr-node Info-current-node)
          p)
      (pop-to-buffer
       (with-current-buffer (get-buffer-create "*info-history*")
!        (let ((inhibit-read-only t))
           (erase-buffer)
           (goto-char (point-min))
!          (insert "Node: History\n\n* Menu:\n\n")
!          (let ((hl Info-history-list))
!            (while hl
!              (let ((file (nth 0 (car hl)))
!                    (node (nth 1 (car hl))))
!                (if (and (equal file curr-file)
!                         (string-equal node curr-node))
!                    (setq p (point)))
!                (insert "* " node ": (" (file-name-nondirectory file)
!                        ")" node ".\n"))
!              (setq hl (cdr hl))))
           (or (eq major-mode 'Info-mode) (Info-mode))
!          (setq Info-current-file "info-history")
!          (setq Info-current-node "Info History")
!          (Info-set-mode-line)
!          (if (not (bobp)) (Info-fontify-node))
           (current-buffer))))
      (goto-char (or p (point-min)))))
  
! ;;;###autoload (add-hook 'same-window-buffer-names "*info-tree*")
  
! (defun Info-node-tree-buffer ()
!   "Create the buffer *info-tree* with Info node tree."
    (interactive)
!   (let ((curr-file Info-current-file)
!         (curr-node Info-current-node)
!         p)
!     (pop-to-buffer
!      (with-current-buffer (get-buffer-create "*info-tree*")
!        (if (not (equal Info-current-file curr-file))
!            (let ((inhibit-read-only t)
!                  (node-list (Info-node-tree-collect-menus curr-file)))
!              (erase-buffer)
!              (goto-char (point-min))
!              (insert "Node: Node Tree\n\n")
!              (Info-node-tree-insert
!               (delq nil (mapcar (lambda (node)
!                                   (if (nth 1 node)
!                                       (nth 0 node))) node-list))
!               node-list 0)
!              (set (make-local-variable 'Info-current-file) curr-file)
!              (or (eq major-mode 'Info-mode) (Info-mode))
!              (setq Info-current-node "Info Node Tree")
!              (Info-set-mode-line)))
!        (if (not (bobp))
!            (let ((Info-hide-note-references 'hide))
!              (Info-fontify-node)))
!        (goto-char (point-min))
!        (if (setq p (search-forward (concat "*Note " curr-node "::") nil t))
!            (setq p (- p (length curr-node) 8)))       (current-buffer)))
!     (goto-char (or p (point-min)))))
! 
! (defun Info-node-tree-insert (nodes node-list level)
!   "Insert the node tree of references to nodes."
!   (while nodes
!     (insert (make-string (* level 4) ?\040))
!     (insert "*Note " (car nodes) "::\n")
!     (Info-node-tree-insert (nth 2 (assoc (car nodes) node-list))
!                            node-list
!                            (1+ level))
!     (setq nodes (cdr nodes))))
! 
! (defvar Info-node-tree-section-names nil
!   "Global variable to hold association list during data collection.
! The elements of list are (\"section name\" . \"node name\").")
! 
! (defun Info-node-tree-collect-menus (filename)
!   "Collect all node names and subnodes from current Info file."
!   (save-excursion
!     (let ((res))
!       (set-buffer (get-buffer-create " *info-node-tree*"))
!       (or (eq major-mode 'Info-mode) (Info-mode))
!       (Info-find-node filename "Top")
!       (setq Info-node-tree-section-names '(("Top" "Top")))
!       ;; Read menus from info file of Top node
!       ;; (setq res (Info-node-tree-collect-menus-current))
!       ;; Read menus from info subfiles
!       (let ((list ())
!             (osubfile ))
!         ;; Get list of subfiles (code borrowed from `Info-search')
!         (save-excursion
!           (set-buffer (marker-buffer Info-tag-table-marker))
!           (goto-char (point-min))
!           (if (search-forward "\n\^_\nIndirect:" nil t)
!               (save-restriction
!                 (narrow-to-region (point)
!                                   (progn (search-forward "\n\^_")
!                                          (1- (point))))
!                 (goto-char (point-min))
!                 (beginning-of-line)
!                 (while (not (eobp))
!                   (re-search-forward "\\(^.*\\): [0-9]+$")
!                   (goto-char (+ (match-end 1) 2))
!                   (setq list (cons (cons (read (current-buffer))
!                                          (buffer-substring-no-properties
!                                           (match-beginning 1) (match-end 1)))
!                                    list))
!                   (goto-char (1+ (match-end 0))))
!                 (setq list (nreverse list)
!                       list (cdr list)))))
!         (while list
!           (message "Searching subfile %s..." (cdr (car list)))
!           (Info-read-subfile (car (car list)))
!           (setq res (append (Info-node-tree-collect-menus-current) res))
!           (setq list (cdr list)))
!         (nreverse res)))))
! 
! (defun Info-node-tree-collect-menus-current ()
!   "Return list of menus extracted from current Info file.
! Return all nodes, even those that are not accessible from menus.
! Output: ((\"nodename1\",\"sectname1\",(\"subnode2\",\"subnode3\")))."
!   (let ((res))
!     (save-excursion
!       (save-restriction
!         (widen)
!         (goto-char (point-min))
!         (while (and (search-forward "\n\^_\nFile:" nil 'move)
!                     (search-forward "Node: " nil 'move))
!           (let (nodename section-name menu-items index-items ref-items beg bound)
!             (setq nodename (substring-no-properties (Info-following-node-name)))
!             (forward-line 1)
!             (setq beg (point))
!             (search-forward "\n\^_" nil 'move)
!             (beginning-of-line)
!             (forward-line -1)
!             (setq bound (point))
!             (goto-char beg)
!             (when (re-search-forward "^\\* Menu:" bound t)
!               (forward-line 1)
!               (beginning-of-line)
!               (cond
!                ((equal nodename "Top")
!                 (while (and (< (point) bound)
!                             (not (looking-at "^[ \t]*-+ The Detailed Node Listing")))
!                   (cond
!                    ;; Menu line
!                    ((looking-at "^\\* +\\([^:\t\n]*\\):")
!                     (beginning-of-line)
!                     (forward-char 2)
!                     (let ((menu-node-name (substring-no-properties (Info-extract-menu-node-name))))
!                       (setq menu-items
!                             (cons menu-node-name ;; (list menu-node-name section-name)
!                                   ;; (match-string-no-properties 1)
!                                   menu-items))
!                       (setq Info-node-tree-section-names
!                             (cons (list menu-node-name (or section-name "Top"))
!                                    Info-node-tree-section-names))))
!                    ;; Other non-empty strings in the dir buffer are section names
!                    ((looking-at "^\\([^ \t\n][^:\n]*\\)")
!                     (setq section-name (match-string-no-properties 1))))
!                   (forward-line 1)
!                   (beginning-of-line)))
!                ((string-match "Index" nodename)
!                 ;; Accept index menu items, e.g.:
!                 ;; * forward-list:                          List Motion.
!                 (while (re-search-forward "\n\\* +\\([^:\t\n]*\\):" bound t)
!                   (beginning-of-line)
!                   (forward-char 2)
!                   (setq index-items (cons (substring-no-properties (Info-extract-menu-node-name))
!                                           ;; (match-string-no-properties 1)
!                                           index-items))))
!                (t
!                 (while (re-search-forward "\n\\* +\\([^:\t\n]*\\):" bound t)
!                   (beginning-of-line)
!                   (forward-char 2)
!                   (setq menu-items (cons (substring-no-properties (Info-extract-menu-node-name))
!                                          ;; (match-string-no-properties 1)
!                                          menu-items))))))
!             (setq res (cons (list nodename
!                                   (cadr (assoc nodename Info-node-tree-section-names))
!                                   (if (not (equal nodename "Top")) ; hack
!                                       (nreverse menu-items))
!                                   (nreverse index-items))
!                             res))
!             (goto-char bound)))))
!     res))
  \f
  (defun Info-follow-reference (footnotename &optional fork)
    "Follow cross reference named FOOTNOTENAME to the node it refers to.
***************
*** 1650,1661 ****
        (setq str (concat (substring str 0 i) "[ \t\n]+" (substring str (1+ i))))
        (setq i (+ i 6)))
      (save-excursion
!       (goto-char (point-min))
!       (or (re-search-forward str nil t)
! 	  (error "No cross-reference named %s" footnotename))
!       (goto-char (+ (match-beginning 0) 5))
!       (setq target
! 	    (Info-extract-menu-node-name t)))
      (while (setq i (string-match "[ \t\n]+" target i))
        (setq target (concat (substring target 0 i) " "
  			   (substring target (match-end 0))))
--- 1821,1848 ----
        (setq str (concat (substring str 0 i) "[ \t\n]+" (substring str (1+ i))))
        (setq i (+ i 6)))
      (save-excursion
!       ;; Move point to the beginning of reference if point is on reference
!       (or (looking-at "\\*note[ \n\t]*")
!           (and (looking-back "\\*note[ \n\t]*")
!                (goto-char (match-beginning 0)))
!           (if (and (save-excursion
!                      (goto-char (+ (point) 5)) ; skip a possible *note
!                      (search-backward "\*note " nil t)
!                      (looking-at (concat "\\*note " (Info-following-node-name-re))))
!                    (<= (point) (match-end 0)))
!               (goto-char (match-beginning 0))))
!       ;; Go to the reference closest to point
!       (let ((next-ref (save-excursion (and (re-search-forward str nil t)
!                                            (+ (match-beginning 0) 5))))
!             (prev-ref (save-excursion (and (re-search-backward str nil t)
!                                            (+ (match-beginning 0) 5)))))
!         (goto-char (cond ((and next-ref prev-ref)
!                           (if (< (abs (- next-ref (point)))
!                                  (abs (- prev-ref (point))))
!                               next-ref prev-ref))
!                          ((or next-ref prev-ref))
!                          ((error "No cross-reference named %s" footnotename))))
!         (setq target (Info-extract-menu-node-name t))))
      (while (setq i (string-match "[ \t\n]+" target i))
        (setq target (concat (substring target 0 i) " "
  			   (substring target (match-end 0))))
***************
*** 2067,2073 ****
  (defun Info-next-reference (&optional recur)
    "Move cursor to the next cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|http://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (eobp) (forward-char 1))
--- 2254,2260 ----
  (defun Info-next-reference (&optional recur)
    "Move cursor to the next cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|[hf]t?tp://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (eobp) (forward-char 1))
***************
*** 2079,2084 ****
--- 2266,2273 ----
  		(goto-char old-pt)
  		(error "No cross references in this node")))))
      (goto-char (match-beginning 0))
+     (if (looking-at "\\*note[ \n\t]*")
+         (forward-char (- (match-end 0) (match-beginning 0))))
      (if (looking-at "\\* Menu:")
  	(if recur
  	    (error "No cross references in this node")
***************
*** 2087,2093 ****
  (defun Info-prev-reference (&optional recur)
    "Move cursor to the previous cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|http://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (re-search-backward pat nil t)
--- 2276,2282 ----
  (defun Info-prev-reference (&optional recur)
    "Move cursor to the previous cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|[hf]t?tp://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (re-search-backward pat nil t)
***************
*** 2098,2103 ****
--- 2287,2294 ----
  		(goto-char old-pt)
  		(error "No cross references in this node")))))
      (goto-char (match-beginning 0))
+     (if (looking-at "\\*note[ \n\t]*")
+         (forward-char (- (match-end 0) (match-beginning 0))))
      (if (looking-at "\\* Menu:")
  	(if recur
  	    (error "No cross references in this node")
***************
*** 2331,2337 ****
    "Follow a node reference near point.  Return non-nil if successful."
    (let (node)
      (cond
!      ((and (Info-get-token (point) "http://" "\\(http://\\)")
             (or (featurep 'browse-url) (require 'browse-url nil t)))
        (setq node t)
        (browse-url (browse-url-url-at-point)))
--- 2522,2528 ----
    "Follow a node reference near point.  Return non-nil if successful."
    (let (node)
      (cond
!      ((and (Info-get-token (point) "[hf]t?tp://" "[hf]t?tp://\\([^ \t\n\"`({<>})']+\\)")
             (or (featurep 'browse-url) (require 'browse-url nil t)))
        (setq node t)
        (browse-url (browse-url-url-at-point)))
***************
*** 2345,2351 ****
        (Info-goto-node node fork))
       ;; menu item: index entry
       ((Info-get-token (point) "\\* +" "\\* +\\(.*\\): ")
!       (setq Info-reference-name (match-string-no-properties 1))
        (beginning-of-line)
        (forward-char 2)
        (setq node (Info-extract-menu-node-name))
--- 2536,2543 ----
        (Info-goto-node node fork))
       ;; menu item: index entry
       ((Info-get-token (point) "\\* +" "\\* +\\(.*\\): ")
!       (or (member Info-current-file '("dir" "info-history"))
!           (setq Info-reference-name (match-string-no-properties 1)))
        (beginning-of-line)
        (forward-char 2)
        (setq node (Info-extract-menu-node-name))
***************
*** 2401,2412 ****
--- 2593,2607 ----
    (define-key Info-mode-map "p" 'Info-prev)
    (define-key Info-mode-map "q" 'Info-exit)
    (define-key Info-mode-map "s" 'Info-search)
+   (define-key Info-mode-map "S" 'Info-search-case-sensitively)
+   (define-key Info-mode-map "/" 'Info-search-next)
    (define-key Info-mode-map "\M-s" 'Info-search-next)
    (define-key Info-mode-map "\M-n" 'clone-buffer)
    (define-key Info-mode-map "t" 'Info-top-node)
    (define-key Info-mode-map "u" 'Info-up)
    (define-key Info-mode-map "," 'Info-index-next)
    (define-key Info-mode-map "\\" 'Info-history-buffer)
+   (define-key Info-mode-map "*" 'Info-node-tree-buffer)
    (define-key Info-mode-map "\177" 'Info-scroll-down)
    (define-key Info-mode-map [mouse-2] 'Info-mouse-follow-nearest-node)
    )
***************
*** 2441,2454 ****
     ("Reference" ["You should never see this" report-emacs-bug t])
     ["Search..." Info-search
      :help "Search for regular expression in this Info file"]
     ["Search Next" Info-search-next
      :help "Search for another occurrence of regular expression"]
     ["Go to Node..." Info-goto-node
      :help "Go to a named node"]
     ["Last (Back)" Info-last :active Info-history
      :help "Go to the last node you were at"]
!    ["History" Info-history-buffer :active Info-history-tree
      :help "Go to the history buffer"]
     ("Index..."
      ["Lookup a String" Info-index
       :help "Look for a string in the index items"]
--- 2636,2653 ----
     ("Reference" ["You should never see this" report-emacs-bug t])
     ["Search..." Info-search
      :help "Search for regular expression in this Info file"]
+    ["Search Case-Sensitively..." Info-search-case-sensitively
+     :help "Search for regular expression case sensitively"]
     ["Search Next" Info-search-next
      :help "Search for another occurrence of regular expression"]
     ["Go to Node..." Info-goto-node
      :help "Go to a named node"]
     ["Last (Back)" Info-last :active Info-history
      :help "Go to the last node you were at"]
!    ["History" Info-history-buffer :active Info-history-list
      :help "Go to the history buffer"]
+    ["Node Tree" Info-node-tree-buffer
+     :help "Go to the node tree buffer"]
     ("Index..."
      ["Lookup a String" Info-index
       :help "Look for a string in the index items"]
***************
*** 2587,2592 ****
--- 2786,2792 ----
  \\[Info-follow-reference]	Follow a cross reference.  Reads name of reference.
  \\[Info-last]	Move to the last node you were at.
  \\[Info-history-buffer]	Go to the history buffer.
+ \\[Info-node-tree-buffer]	Go to the node tree buffer.
  \\[Info-index]	Look up a topic in this file's Index and move to that node.
  \\[Info-index-next]	(comma) Move to the next match from a previous `i' command.
  \\[Info-top-node]	Go to the Top node of this file.
***************
*** 2615,2620 ****
--- 2815,2822 ----
  \\[universal-argument] \\[info]	Move to new Info file with completion.
  \\[Info-search]	Search through this Info file for specified regexp,
  	  and select the node in which the next occurrence is found.
+ \\[Info-search-case-sensitively]	Search through this Info file
+ 	  for specified regexp case-sensitively.
  \\[Info-search-next]	Search for another occurrence of regexp
  	  from a previous `Info-search' command.
  \\[Info-next-reference]	Move cursor to next cross-reference or menu item.
***************
*** 2637,2643 ****
    (make-local-variable 'Info-tag-table-buffer)
    (setq Info-tag-table-buffer nil)
    (make-local-variable 'Info-history)
-   (make-local-variable 'Info-history-node)
    (make-local-variable 'Info-index-alternatives)
    (setq header-line-format
  	(if Info-use-header-line
--- 2839,2844 ----
***************
*** 2907,2923 ****
        (push (substring string start end) matches)
        (apply #'concat (nreverse matches)))))
  
- (defun Info-fontify-menu-headers ()
-   "Add the face `info-menu-header' to any header before a menu entry."
-   (save-excursion
-     (goto-char (point-min))
-     (when (re-search-forward "^\\* Menu:" nil t)
-       (put-text-property (match-beginning 0) (match-end 0)
- 			 'font-lock-face 'info-menu-header)
-       (while (re-search-forward "\n\n\\([^*\n ].*\\)\n\n?[*]" nil t)
- 	(put-text-property (match-beginning 1) (match-end 1)
- 			   'font-lock-face 'info-menu-header)))))
- 
  (defvar Info-next-link-keymap
    (let ((keymap (make-sparse-keymap)))
      (define-key keymap [header-line mouse-1] 'Info-next)
--- 3108,3113 ----
***************
*** 2947,2963 ****
    "Keymap to put on the Up link in the text or the header line.")
  
  (defun Info-fontify-node ()
!   ;; Only fontify the node if it hasn't already been done
!   ;; or always fontify visited nodes (because of their dynamic nature).
!   (when (or Info-visited-nodes
!             (not (let ((where (next-property-change (point-min))))
!                    (and where (not (= where (point-max)))))))
      (save-excursion
!       (let ((inhibit-read-only t)
  	    (case-fold-search t)
! 	    paragraph-markers)
  	(goto-char (point-min))
! 	(when (looking-at "^\\(File: [^,: \t]+,?[ \t]+\\)?")
  	  (goto-char (match-end 0))
  	  (while (looking-at "[ \t]*\\([^:, \t\n]+\\):[ \t]+\\([^:,\t\n]+\\),?")
  	    (goto-char (match-end 0))
--- 3137,3158 ----
    "Keymap to put on the Up link in the text or the header line.")
  
  (defun Info-fontify-node ()
!   "Fontify the node."
    (save-excursion
!     (let* ((inhibit-read-only t)
             (case-fold-search t)
!            paragraph-markers
!            (not-fontified-p ; the node hasn't already been fontified
!             (not (let ((where (next-property-change (point-min))))
!                    (and where (not (= where (point-max)))))))
!            (fontify-visited-p ; visited nodes need to be re-fontified
!             (and Info-visited-nodes
!                  ;; Don't take time to refontify visited nodes in huge nodes
!                  (< (- (point-max) (point-min)) Info-fontify-maximum-menu-size))))
! 
!       ;; Fontify header line
        (goto-char (point-min))
!       (when (and not-fontified-p (looking-at "^\\(File: [^,: \t]+,?[ \t]+\\)?"))
          (goto-char (match-end 0))
          (while (looking-at "[ \t]*\\([^:, \t\n]+\\):[ \t]+\\([^:,\t\n]+\\),?")
            (goto-char (match-end 0))
***************
*** 3009,3015 ****
--- 3203,3212 ----
                ;; Hide the punctuation at the end, too.
                (skip-chars-backward " \t,")
                (put-text-property (point) header-end 'invisible t)))))
+ 
+       ;; Fontify titles
        (goto-char (point-min))
+       (when not-fontified-p
          (while (re-search-forward "\n\\([^ \t\n].+\\)\n\\(\\*+\\|=+\\|-+\\|\\.+\\)$"
                                    nil t)
            (let* ((c (preceding-char))
***************
*** 3025,3105 ****
  	  ;; on frames that can display the font above.
  	  (when (memq (framep (selected-frame)) '(x pc w32 mac))
  	    (add-text-properties (1- (match-beginning 2)) (match-end 2)
! 				 '(invisible t front-sticky nil rear-nonsticky t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\(\\*Note[ \t]*\\)\n?[ \t]*\\([^:]*\\)\\(:[^.,:(]*\\((\\([^)]*\\))\\([^.,:]*\\)\\)?[,:]?\n?\\)" nil t)
  	  (unless (memq (char-after (1- (match-beginning 0))) '(?\" ?\`)) ; hack
  	    (let ((start (match-beginning 0))
! ;; 		  (next (point))
! ;; 		  other-tag
!                   )
  	      (when Info-hide-note-references
! ;; 		;; *Note is often used where *note should have been
! ;; 		(goto-char start)
! ;; 		(skip-syntax-backward " ")
! ;; 		(setq other-tag
! ;;                       (cond ((memq (char-before) '(nil ?\. ?! ??))
! ;;                              "See ")
! ;;                             ((memq (char-before) '(?\, ?\; ?\: ?-))
! ;;                              "see ")
! ;;                             ((memq (char-before) '(?\( ?\[ ?\{))
! ;;                              ;; Check whether the paren is preceded by
! ;;                              ;; an end of sentence
! ;;                              (skip-syntax-backward " (")
! ;;                              (if (memq (char-before) '(nil ?\. ?! ??))
! ;;                                  "See "
! ;;                                "see "))
! ;;                             ((save-match-data (looking-at "\n\n"))
! ;;                              "See ")))
! ;; 		(goto-char next)
!                 (add-text-properties (match-beginning 1) (match-end 1)
!                                      '(invisible t front-sticky nil rear-nonsticky t)))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
                 (list
!                 'help-echo (if (match-end 4)
!                                (concat "mouse-2: go to " (match-string 4))
                               "mouse-2: go to this node")
                  'font-lock-face
                  ;; Display visited nodes in a different face
!                 (if (and Info-visited-nodes
!                          (save-match-data
!                            (let* ((file (concat (or (match-string 5) Info-current-file) "$"))
                                    (node (replace-regexp-in-string
                                           "[ \t\n]+" " "
!                                          (or (match-string 6) (match-string 2))))
!                                   (l Info-history-tree)
                                    res)
!                              (while l
!                                (if (and (equal (cadr (car l)) node)
!                                         (string-match file (caar l)))
!                                    (setq res (car l) l nil))
!                                (setq l (cdr l)))
!                              res))) 'info-xref-visited 'info-xref)
!                 'mouse-face 'highlight))
! 	      (when (eq Info-hide-note-references t)
  		(add-text-properties (match-beginning 3) (match-end 3)
  				     '(invisible t front-sticky nil rear-nonsticky t))
                  ;; Unhide the file name of the reference in parens
!                 (if (match-string 5)
!                     (remove-text-properties (1- (match-beginning 5)) (1+ (match-end 5))
                                              '(invisible t front-sticky nil rear-nonsticky t)))
                  ;; Unhide newline because hidden newlines cause too long lines
                  (save-match-data
                    (let ((start3 (match-beginning 3)))
                      (if (string-match "\n[ \t]*" (match-string 3))
                          (remove-text-properties (+ start3 (match-beginning 0)) (+ start3 (match-end 0))
!                                                 '(invisible t front-sticky nil rear-nonsticky t)))))
!                 )
! ;; 	      (when other-tag
! ;; 		(save-excursion
! ;; 		  (goto-char (match-beginning 1))
! ;; 		  (insert other-tag)))
  	      (when (and Info-refill-paragraphs Info-hide-note-references)
  		(push (set-marker (make-marker) start)
! 		      paragraph-markers)))))
  
! 	(when (and Info-refill-paragraphs
  		   paragraph-markers)
  	  (let ((fill-nobreak-invisible t)
  		(fill-individual-varying-indent nil)
--- 3222,3313 ----
            ;; on frames that can display the font above.
            (when (memq (framep (selected-frame)) '(x pc w32 mac))
              (add-text-properties (1- (match-beginning 2)) (match-end 2)
!                                  '(invisible t front-sticky nil rear-nonsticky t)))))
! 
!       ;; Fontify cross references
        (goto-char (point-min))
!       (when (or not-fontified-p fontify-visited-p)
!         (while (re-search-forward "\\(\\*Note[ \t]*\\)\n?[ \t]*\\([^:]*\\)\\(:[ \t]*\\([^.,:(]*\\)\\((\\([^)]*\\))\\([^.,:]*\\)\\)?[,:]?\n?\\)" nil t)
            (unless (memq (char-after (1- (match-beginning 0))) '(?\" ?\`)) ; hack
              (let ((start (match-beginning 0))
!                   (next (point))
!                   other-tag)
!               (when not-fontified-p
                  (when Info-hide-note-references
!                   ;; *Note is often used where *note should have been
!                   (goto-char start)
!                   (skip-syntax-backward " ")
!                   (setq other-tag
!                         (cond ((memq (char-before) '(nil ?\. ?! ??))
!                                "See ")
!                               ((memq (char-before) '(?\, ?\; ?\: ?-))
!                                "see ")
!                               ((memq (char-before) '(?\( ?\[ ?\{))
!                                ;; Check whether the paren is preceded by
!                                ;; an end of sentence
!                                (skip-syntax-backward " (")
!                                (if (memq (char-before) '(nil ?\. ?! ??))
!                                    "See "
!                                  "see "))
!                               ((save-match-data (looking-at "\n\n"))
!                                "See ")))
!                   (goto-char next)
!                   (add-text-properties
!                    (match-beginning 1) (match-end 1)
!                    (if (and other-tag (not (eq Info-hide-note-references 'hide)))
!                        `(display ,other-tag front-sticky nil rear-nonsticky t)
!                      '(invisible t front-sticky nil rear-nonsticky t))))
                  (add-text-properties
                   (match-beginning 2) (match-end 2)
                   (list
!                   'help-echo (if (or (match-end 5) (not (equal (match-string 4) "")))
!                                  (concat "mouse-2: go to " (or (match-string 5) (match-string 4)))
                                 "mouse-2: go to this node")
+                   'mouse-face 'highlight)))
+               (when (or not-fontified-p fontify-visited-p)
+                 (add-text-properties
+                  (match-beginning 2) (match-end 2)
+                  (list
                    'font-lock-face
                    ;; Display visited nodes in a different face
!                   (if (save-match-data
!                         (let* ((file (concat (or (match-string 6)
!                                                  Info-current-file) "$"))
                                 (node (replace-regexp-in-string
                                        "[ \t\n]+" " "
!                                       (or (match-string 7)
!                                           (and (not (equal (match-string 4) ""))
!                                                (match-string 4))
!                                           (match-string 2))))
!                                (hl Info-history-list)
                                 res)
!                           (while hl
!                             (if (and (string-equal node (nth 1 (car hl)))
!                                      (string-match file (nth 0 (car hl))))
!                                 (setq res (car hl) hl nil))
!                             (setq hl (cdr hl)))
!                           res)) 'info-xref-visited 'info-xref))))
!               (when not-fontified-p
!                 (when (memq Info-hide-note-references '(t hide))
                    (add-text-properties (match-beginning 3) (match-end 3)
                                         '(invisible t front-sticky nil rear-nonsticky t))
                    ;; Unhide the file name of the reference in parens
!                   (if (match-string 6)
!                       (remove-text-properties (1- (match-beginning 6)) (1+ (match-end 6))
                                                '(invisible t front-sticky nil rear-nonsticky t)))
                    ;; Unhide newline because hidden newlines cause too long lines
                    (save-match-data
                      (let ((start3 (match-beginning 3)))
                        (if (string-match "\n[ \t]*" (match-string 3))
                            (remove-text-properties (+ start3 (match-beginning 0)) (+ start3 (match-end 0))
!                                                   '(invisible t front-sticky nil rear-nonsticky t))))))
                  (when (and Info-refill-paragraphs Info-hide-note-references)
                    (push (set-marker (make-marker) start)
!                         paragraph-markers)))))))
  
!       ;; Refill paragraphs (experimental feature)
!       (when (and not-fontified-p
!                  Info-refill-paragraphs
                   paragraph-markers)
          (let ((fill-nobreak-invisible t)
                (fill-individual-varying-indent nil)
***************
*** 3119,3126 ****
  		      (goto-char beg))))
  		(set-marker m nil)))))
  
  	(goto-char (point-min))
! 	(when (and (search-forward "\n* Menu:" nil t)
  		   (not (string-match "\\<Index\\>" Info-current-node))
  		   ;; Don't take time to annotate huge menus
  		   (< (- (point-max) (point)) Info-fontify-maximum-menu-size))
--- 3327,3336 ----
                      (goto-char beg))))
                (set-marker m nil)))))
  
+       ;; Fontify menu items
        (goto-char (point-min))
!       (when (and (or not-fontified-p fontify-visited-p)
!                  (search-forward "\n* Menu:" nil t)
                   (not (string-match "\\<Index\\>" Info-current-node))
                   ;; Don't take time to annotate huge menus
                   (< (- (point-max) (point)) Info-fontify-maximum-menu-size))
***************
*** 3130,3164 ****
  		    (concat "^\\* +\\(" Info-menu-entry-name-re "\\)\\(:"
  			    Info-node-spec-re "\\([ \t]*\\)\\)")
  		    nil t)
  	      (setq n (1+ n))
  	      (if (and (<= n 9) (zerop (% n 3))) ; visual aids to help with 1-9 keys
  		  (put-text-property (match-beginning 0)
  				     (1+ (match-beginning 0))
! 				     'font-lock-face 'info-menu-5))
  	      (add-text-properties
  	       (match-beginning 1) (match-end 1)
                 (list
                  'help-echo (if (match-end 3)
                                 (concat "mouse-2: go to " (match-string 3))
                               "mouse-2: go to this node")
                  'font-lock-face
!                 ;; Display visited nodes in a different face
!                 (if (and Info-visited-nodes
                           (let ((node (if (equal (match-string 3) "")
                                           (match-string 1)
                                         (match-string 3)))
!                                (l Info-history-tree)
                                 res)
!                            (while l
!                              (if (and (equal (cadr (car l)) node)
!                                       (equal Info-current-file (caar l)))
!                                  (setq res (car l) l nil))
!                              (setq l (cdr l)))
!                            res)) 'info-xref-visited 'info-xref)
!                 'mouse-face 'highlight))
! 	      (when (eq Info-hide-note-references t)
  		(put-text-property (match-beginning 2) (1- (match-end 6))
  				   'invisible t)
  		;; We need a stretchable space like :align-to but with
  		;; a minimum value.
  		(put-text-property (1- (match-end 6)) (match-end 6) 'display
--- 3340,3388 ----
                    (concat "^\\* +\\(" Info-menu-entry-name-re "\\)\\(:"
                            Info-node-spec-re "\\([ \t]*\\)\\)")
                    nil t)
+             (when not-fontified-p
                (setq n (1+ n))
                (if (and (<= n 9) (zerop (% n 3))) ; visual aids to help with 1-9 keys
                    (put-text-property (match-beginning 0)
                                       (1+ (match-beginning 0))
!                                      'font-lock-face 'info-menu-5)))
!             (when not-fontified-p
                (add-text-properties
                 (match-beginning 1) (match-end 1)
                 (list
                  'help-echo (if (match-end 3)
                                 (concat "mouse-2: go to " (match-string 3))
                               "mouse-2: go to this node")
+                 'mouse-face 'highlight)))
+             (when (or not-fontified-p fontify-visited-p)
+               (add-text-properties
+                (match-beginning 1) (match-end 1)
+                (list
                  'font-lock-face
!                 ;; Display visited menu items in a different face
!                 (if (save-match-data
                        (let ((node (if (equal (match-string 3) "")
                                        (match-string 1)
                                      (match-string 3)))
!                             (file (concat Info-current-file "$"))
!                             (hl Info-history-list)
                              res)
!                         (if (string-match "(\\([^)]+\\))" node)
!                             (setq file (concat (match-string 1 node) "$")
!                                   node "Top"))
!                         (while hl
!                           (if (and (string-equal node (nth 1 (car hl)))
!                                    (string-match file (nth 0 (car hl))))
!                               (setq res (car hl) hl nil))
!                           (setq hl (cdr hl)))
!                         res)) 'info-xref-visited 'info-xref))))
!             (when (and not-fontified-p (memq Info-hide-note-references '(t hide)))
                (put-text-property (match-beginning 2) (1- (match-end 6))
                                   'invisible t)
+               ;; Unhide the file name in parens
+               (if (and (match-end 4) (not (eq (char-after (match-end 4)) ?.)))
+                   (remove-text-properties (match-beginning 4) (match-end 4)
+                                           '(invisible t)))
                ;; We need a stretchable space like :align-to but with
                ;; a minimum value.
                (put-text-property (1- (match-end 6)) (match-end 6) 'display
***************
*** 3178,3192 ****
  				       '(space :align-to 24)))
  		  (setq cont t))))))
  
  	(goto-char (point-min))
! 	(while (re-search-forward "http://[-~/[:alnum:]_.${}#%,:?=&]+" nil t)
            (add-text-properties (match-beginning 0) (match-end 0)
                                 '(font-lock-face info-xref
                                   mouse-face highlight
!                                  help-echo "mouse-2: go to this URL")))
  
! 	(Info-fontify-menu-headers)
! 	(set-buffer-modified-p nil)))))
  \f
  
  ;; When an Info buffer is killed, make sure the associated tags buffer
--- 3402,3426 ----
                                       '(space :align-to 24)))
                  (setq cont t))))))
  
+       ;; Add the face `info-xref' to http links
        (goto-char (point-min))
!       (when not-fontified-p
!         (while (re-search-forward "[hf]t?tp://[^ \t\n\"`({<>})']+" nil t)
            (add-text-properties (match-beginning 0) (match-end 0)
                                 '(font-lock-face info-xref
                                                  mouse-face highlight
!                                                 help-echo "mouse-2: go to this URL"))))
! 
!       ;; Add the face `info-menu-header' to any header before a menu entry
!       (goto-char (point-min))
!       (when (and not-fontified-p (re-search-forward "^\\* Menu:" nil t))
!         (put-text-property (match-beginning 0) (match-end 0)
!                            'font-lock-face 'info-menu-header)
!         (while (re-search-forward "\n\n\\([^*\n ].*\\)\n\n?[*]" nil t)
!           (put-text-property (match-beginning 1) (match-end 1)
!                              'font-lock-face 'info-menu-header)))
  
!       (set-buffer-modified-p nil))))
  \f
  
  ;; When an Info buffer is killed, make sure the associated tags buffer
===================================================================

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Karl Berry]

    Seems anchors are useful only for making references to them, not for
    selecting them from completion list.

I don't see any a priori reason to suppose it's not useful to "g"o to an
anchor.  One document's anchor is another document's node.  (I mean, the
division into nodes vs. subnode positioning via anchors is a judgement
call, not an absolute fact.)

That said, I don't feel terribly strongly about whether "g" includes
anchor names in possible completions or not.  Standalone Info does.

      ... the reference names feature.  I still think this feature is
      very useful especially for moving from indexes directly to lines
      where index items are described.  This feature can be replaced
      later gradually by anchors as suggested by Luc.

I don't understand.  I thought that this required index entries to be
used as the second or third arg of xrefs, and I am not aware of any
manuals which make xrefs like that.  Nor is that how @xref is intended
to be used.  Am I confused?  Are you somehow implicitly inserting
references to index definitions?

The other changes seem good, as far as I understand them.  (Discounting
my aversion to Info-hide-note-references.)

Thanks,
karl

Re: Info enhancements

[Eli Zaretskii]

> Date: Fri, 12 Dec 2003 09:24:06 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> That said, I don't feel terribly strongly about whether "g" includes
> anchor names in possible completions or not.  Standalone Info does.

Perhaps an Emacs option is in order.

Re: Info enhancements

[Stefan Monnier]

>> That said, I don't feel terribly strongly about whether "g" includes
>> anchor names in possible completions or not.  Standalone Info does.
> Perhaps an Emacs option is in order.

How do you spell overkill again?


        Stefan

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
>     Seems anchors are useful only for making references to them, not for
>     selecting them from completion list.
>
> I don't see any a priori reason to suppose it's not useful to "g"o to an
> anchor.  One document's anchor is another document's node.  (I mean, the
> division into nodes vs. subnode positioning via anchors is a judgement
> call, not an absolute fact.)
>
> That said, I don't feel terribly strongly about whether "g" includes
> anchor names in possible completions or not.  Standalone Info does.

Since the name of the function bound to "g" is `Info-goto-node'
and its documentation says that this function works only with nodes,
so I thought that it's more correct to omit anchors from a list
of node completions.  I see no harm in removing anchors from a node
list because all nodes still can be reached by the "g" command.
Anchors only provide additional locations within one Info node.
When Info file has many anchors it would be undesirable to overfill
a node list with names that lead to the same Info node.  I think
anchors are only useful in references, for instance, as demonstrated
recently by Luc: @xref{doc-hyperlinks, , Tips for Documentation Strings}.
However, if there is need to go to anchors by selecting their names
from a completion list, then possible solution is either to implement
an additional command with an anchor completion list or to add anchor
names to a completion list of the `Info-index' command because
in fact anchors are more like index items than node names.

>       ... the reference names feature.  I still think this feature is
>       very useful especially for moving from indexes directly to lines
>       where index items are described.  This feature can be replaced
>       later gradually by anchors as suggested by Luc.
>
> I don't understand.  I thought that this required index entries to be
> used as the second or third arg of xrefs, and I am not aware of any
> manuals which make xrefs like that.  Nor is that how @xref is intended
> to be used.  Am I confused?  Are you somehow implicitly inserting
> references to index definitions?

Actually I meant not xrefs but menu entries of Info index nodes,
for instance, like this:

* auto-fill-mode:                        Auto Fill.

Currently, the `Info-index' command (`i') moves point to the place
within a node where an index name is defined, but its functional
equivalent - selecting an index from index menu still don't move point
to the place where an index name is defined.  This patch tries to
improve this (but now it works only if index entries are selected
by the `Info-follow-nearest-node', not by the `Info-menu', this can
be implemented later).

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: 12 Dec 2003 14:23:04 -0500
> 
> >> That said, I don't feel terribly strongly about whether "g" includes
> >> anchor names in possible completions or not.  Standalone Info does.
> > Perhaps an Emacs option is in order.
> 
> How do you spell overkill again?

It is spelled "whenever we are not sure which behavior to make the
default, have an option so that users can decide."

Re: Info enhancements

[Richard Stallman]

    Since the name of the function bound to "g" is `Info-goto-node'
    and its documentation says that this function works only with nodes,
    so I thought that it's more correct to omit anchors from a list
    of node completions.

I see no harm in letting it include anchors in completion, given that
it does handle anchor names.  We could rename it "Info-goto"
to avoid the conflict between the name (which comes from a time
before there were anchors) and the functionality (which reflects
the existence of anchors).

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Fri, 12 Dec 2003 23:38:56 +0200
> 
> However, if there is need to go to anchors by selecting their names
> from a completion list, then possible solution is either to implement
> an additional command with an anchor completion list or to add anchor
> names to a completion list of the `Info-index' command because
> in fact anchors are more like index items than node names.

I disagree with the latter suggestion.  Info-index should provide
completion for index entries; adding anchor names would not add any
useful possible completions, since anchor names are just tags, not
meaningful phrases.

Re: Info enhancements

[Richard Stallman]

    It is spelled "whenever we are not sure which behavior to make the
    default, have an option so that users can decide."

Our principle is to add an option only if it seems important.  Many
issues are not important enough to justify one.  If a few users really
care, they can change the code.  An option is useful when each
alternative is preferred by many users.

Re: Info enhancements

[Richard Stallman]

Most of the features are good ones, but I think these two
should have different interfaces.

    * Implemented a new `S' command suggested by Eli.  This command is
      bound to a new function `Info-search-case-sensitively' that searches
      for a regexp case-sensitively.  The `Info-search-next' uses the case
      of a previous `Info-search' or `Info-search-case-sensitively' command.

It would be more consistent with the rest of Emacs to make the user
interface be to specify this with a capital letter in the regexp.

    * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).

I think that `s RET' would be a good way to specify this,
also more consistent with other search commands in Emacs.

Re: Info enhancements

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 14 Dec 2003 21:35:35 -0500
> 
>     * Implemented a new `S' command suggested by Eli.  This command is
>       bound to a new function `Info-search-case-sensitively' that searches
>       for a regexp case-sensitively.  The `Info-search-next' uses the case
>       of a previous `Info-search' or `Info-search-case-sensitively' command.
> 
> It would be more consistent with the rest of Emacs to make the user
> interface be to specify this with a capital letter in the regexp.

I think these are two independent features.  (The stand-alone reader
supports both.)  The problem is that sometimes you may wish to find an
all-lowercase string in a case-sensitive fashion; starting the regexp
with a capital letter doesn't help in that case.

>     * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).
> 
> I think that `s RET' would be a good way to specify this,
> also more consistent with other search commands in Emacs.

I think `/' should be simply another binding for `Info-search', for
compatibility with the stand-alone reader.  Then, `s RET' and `/ RET'
will find the next occurrence (the former of these already works in
Emacs, and both work in the stand-alone reader).

Re: Info enhancements

[Richard Stallman]

    >     * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).
    > 
    > I think that `s RET' would be a good way to specify this,
    > also more consistent with other search commands in Emacs.

    I think `/' should be simply another binding for `Info-search', for
    compatibility with the stand-alone reader.

That sounds ok to me.

Re: Info enhancements

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
> I see no harm in letting it include anchors in completion, given that
> it does handle anchor names.  We could rename it "Info-goto"
> to avoid the conflict between the name (which comes from a time
> before there were anchors) and the functionality (which reflects
> the existence of anchors).

Yes, I remember that you already suggested two weeks ago to create
a new function to go to any locator.  This is the function that you
suggest to name Info-goto.  At the same time, Info-goto-node could
be changed to go to node names only, and it makes sense to create also
a new function Info-goto-anchor to go to anchors only.

So, what do you think about this patch?  It provides three functions
Info-goto, Info-goto-node and Info-goto-anchor that differ only by
their completion lists.  I'm still unsure about keybindings to these
functions.  Maybe, "g" - for Info-goto-node, "G" - for Info-goto
and no keybindings for Info-goto-anchor because Info-goto-anchor will
be rarely used (actually, I added Info-goto-anchor because it was too
easy to add it when a completion list creation function was changed
to handle anchor and node names separately).

===================================================================
*** emacs/lisp/info.el	Fri Dec 12 03:29:35 2003
--- emacs/lisp/info.el	Tue Dec 16 03:31:18 2003
***************
*** 227,233 ****
    "Buffer used for indirect tag tables.")
  
  (defvar Info-current-file-completions nil
!   "Cached completion list for current Info file.")
  
  (defvar Info-index-alternatives nil
    "List of possible matches for last `Info-index' command.")
--- 227,236 ----
    "Buffer used for indirect tag tables.")
  
  (defvar Info-current-file-completions nil
!   "Cached node completion list for current Info file.")
! 
! (defvar Info-current-file-anchor-completions nil
!   "Cached anchor completion list for current Info file.")
  
  (defvar Info-index-alternatives nil
    "List of possible matches for last `Info-index' command.")
***************
*** 715,720 ****
--- 718,724 ----
                (setq Info-current-file nil
                      Info-current-subfile nil
                      Info-current-file-completions nil
+                     Info-current-file-anchor-completions nil
                      buffer-file-name nil)
                (erase-buffer)
                (if (eq filename t)
***************
*** 1234,1248 ****
  ;; of the sort that is found in pointers in nodes.
  
  (defun Info-goto-node (nodename &optional fork)
!   "Go to info node named NODENAME.  Give just NODENAME or (FILENAME)NODENAME.
! If NODENAME is of the form (FILENAME)NODENAME, the node is in the Info file
! FILENAME; otherwise, NODENAME should be in the current Info file (or one of
  its sub-files).
  Completion is available, but only for node names in the current Info file.
  If FORK is non-nil (interactively with a prefix arg), show the node in
  a new info buffer.
  If FORK is a string, it is the name to use for the new buffer."
!   (interactive (list (Info-read-node-name "Go to node: ") current-prefix-arg))
    (info-initialize)
    (if fork
        (set-buffer
--- 1238,1266 ----
  ;; of the sort that is found in pointers in nodes.
  
  (defun Info-goto-node (nodename &optional fork)
!   "Go to info node named NODENAME."
!   (interactive (list (Info-read-node-name "Go to node: ")
!                      current-prefix-arg))
!   (Info-goto nodename fork))
! 
! (defun Info-goto-anchor (anchorname &optional fork)
!   "Go to info anchor named ANCHORNAME."
!   (interactive (list (Info-read-node-name "Go to anchor: " nil 'anchor)
!                      current-prefix-arg))
!   (Info-goto anchorname fork))
! 
! (defun Info-goto (nodename &optional fork)
!   "Go to info node or anchor named NODENAME.
! Give just NODENAME or (FILENAME)NODENAME.  If NODENAME is of the
! form (FILENAME)NODENAME, the node is in the Info file FILENAME;
! otherwise, NODENAME should be in the current Info file (or one of
  its sub-files).
  Completion is available, but only for node names in the current Info file.
  If FORK is non-nil (interactively with a prefix arg), show the node in
  a new info buffer.
  If FORK is a string, it is the name to use for the new buffer."
!   (interactive (list (Info-read-node-name "Go to node or anchor: " nil t)
!                      current-prefix-arg))
    (info-initialize)
    (if fork
        (set-buffer
***************
*** 1300,1317 ****
     (t
      (test-completion string Info-read-node-completion-table predicate))))
  
! (defun Info-read-node-name (prompt &optional default)
    (let* ((completion-ignore-case t)
! 	 (Info-read-node-completion-table (Info-build-node-completions))
  	 (nodename (completing-read prompt 'Info-read-node-name-1 nil t)))
      (if (equal nodename "")
  	(or default
! 	    (Info-read-node-name prompt))
        nodename)))
  
  (defun Info-build-node-completions ()
    (or Info-current-file-completions
        (let ((compl nil)
  	    ;; Bind this in case the user sets it to nil.
  	    (case-fold-search t)
  	    (node-regexp "Node: *\\([^,\n]*\\) *[,\n\t]"))
--- 1318,1345 ----
     (t
      (test-completion string Info-read-node-completion-table predicate))))
  
! (defun Info-read-node-name (prompt &optional default anchor)
    (let* ((completion-ignore-case t)
!          (node-completions (Info-build-node-completions))
!          ;; On the first call of `Info-build-node-completions'
!          ;; it should set `Info-current-file-anchor-completions'
!          (anchor-completions Info-current-file-anchor-completions)
! 	 (Info-read-node-completion-table
!           (append
!            ;; Include node names if anchor is nil or t
!            (if (not (eq anchor 'anchor)) node-completions)
!            ;; Include anchor names if anchor is 'anchor or t
!            (if anchor anchor-completions)))
  	 (nodename (completing-read prompt 'Info-read-node-name-1 nil t)))
      (if (equal nodename "")
  	(or default
! 	    (Info-read-node-name prompt anchor))
        nodename)))
  
  (defun Info-build-node-completions ()
    (or Info-current-file-completions
        (let ((compl nil)
+             (compl-anchors nil)
  	    ;; Bind this in case the user sets it to nil.
  	    (case-fold-search t)
  	    (node-regexp "Node: *\\([^,\n]*\\) *[,\n\t]"))
***************
*** 1323,1332 ****
  		  (widen)
  		  (goto-char marker)
  		  (while (re-search-forward "\n\\(Node\\|Ref\\): \\(.*\\)\177" nil t)
! 		    (or (string-equal "Ref" (match-string 1))
! 			(setq compl
  			      (cons (list (match-string-no-properties 2))
! 				    compl)))))
  	      (widen)
  	      (goto-char (point-min))
  	      ;; If the buffer begins with a node header, process that first.
--- 1351,1363 ----
  		  (widen)
  		  (goto-char marker)
  		  (while (re-search-forward "\n\\(Node\\|Ref\\): \\(.*\\)\177" nil t)
! 		    (if (string-equal "Ref" (match-string 1))
! 			(setq compl-anchors
  			      (cons (list (match-string-no-properties 2))
! 				    compl-anchors))
! 			(setq compl
! 			    (cons (list (match-string-no-properties 2))
! 				  compl)))))
  	      (widen)
  	      (goto-char (point-min))
  	      ;; If the buffer begins with a node header, process that first.
***************
*** 1342,1347 ****
--- 1373,1379 ----
  			    (cons (list (match-string-no-properties 1))
  				  compl))))))))
  	(setq compl (cons '("*") compl))
+ 	(set (make-local-variable 'Info-current-file-anchor-completions) compl-anchors)
  	(set (make-local-variable 'Info-current-file-completions) compl))))
  \f
  (defun Info-restore-point (hl)
===================================================================

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
>>     * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).
>> 
>> I think that `s RET' would be a good way to specify this,
>> also more consistent with other search commands in Emacs.
>
> I think `/' should be simply another binding for `Info-search', for
> compatibility with the stand-alone reader.  Then, `s RET' and `/ RET'
> will find the next occurrence (the former of these already works in
> Emacs, and both work in the stand-alone reader).

If `/' will be another binding for `Info-search', then perhaps its
counterpart character `\' would be bound to `Info-search-next'.
However, I already used `\' for `Info-history' buffer.  So, if someone
suggests a better keybinding for `Info-history', then `\' could be used
for `Info-search-next'.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> Eli Zaretskii <eliz@elta.co.il> writes:
> >>     * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).
> >> 
> >> I think that `s RET' would be a good way to specify this,
> >> also more consistent with other search commands in Emacs.
> >
> > I think `/' should be simply another binding for `Info-search', for
> > compatibility with the stand-alone reader.  Then, `s RET' and `/ RET'
> > will find the next occurrence (the former of these already works in
> > Emacs, and both work in the stand-alone reader).
> 
> If `/' will be another binding for `Info-search', then perhaps its
> counterpart character `\' would be bound to `Info-search-next'.
> However, I already used `\' for `Info-history' buffer.  So, if someone
> suggests a better keybinding for `Info-history', then `\' could be used
> for `Info-search-next'.

What if / would run Info-search-next if previous command 
was Info-search or Info-search-next.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Info enhancements

[Richard Stallman]

    What if / would run Info-search-next if previous command 
    was Info-search or Info-search-next.

That is very inconsistent with other Emacs interfaces, so I would
rather not do that.  I'd rather tell people to use s RET or / RET.

Re: Info enhancements

[Richard Stallman]

    So, what do you think about this patch?  It provides three functions
    Info-goto, Info-goto-node and Info-goto-anchor that differ only by
    their completion lists.  I'm still unsure about keybindings to these
    functions.  Maybe, "g" - for Info-goto-node, "G" - for Info-goto

Do we really need Info-goto-anchor?
Do we really need Info-goto-node, except as an alias
for compatibility?  I don't see a need for them.

Re: Info enhancements

[Richard Stallman]

    If `/' will be another binding for `Info-search', then perhaps its
    counterpart character `\' would be bound to `Info-search-next'.

That seems too inconsistent with the rest of Emacs.

Re: Info enhancements

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
>     So, what do you think about this patch?  It provides three functions
>     Info-goto, Info-goto-node and Info-goto-anchor that differ only by
>     their completion lists.  I'm still unsure about keybindings to these
>     functions.  Maybe, "g" - for Info-goto-node, "G" - for Info-goto
>
> Do we really need Info-goto-anchor?

We don't need Info-goto-anchor.

> Do we really need Info-goto-node, except as an alias
> for compatibility?  I don't see a need for them.

I think Info-goto-node with a completion list without anchors might be
useful for users that want to see only node names.  For instance,
currently Info-goto-node called on the Emacs manual adds anchors
useless for users:

Coding Systems-Footnote-1          Debugger Operation-Footnote-1
Dissociated Press-Footnote-1       Expressions-Footnote-1
File Names with $                  Fontsets-Footnote-1
General Variables-Footnote-1       Language Environments-Footnote-1
Language Environments-Footnote-2   MS-DOS Printing-Footnote-1
MS-DOS and MULE-Footnote-1         MS-DOS and MULE-Footnote-2
Mail Amusements-Footnote-1         Man Page-Footnote-1
Man Page-Footnote-2                Manifesto-Footnote-1
Manifesto-Footnote-2               Manifesto-Footnote-3
Manifesto-Footnote-4               Manifesto-Footnote-5
Menu Mouse Clicks-Footnote-1       Non-ASCII Rebinding-Footnote-1
Scroll Bars-Footnote-1             Several Buffers-Footnote-1
Shell Mode-Footnote-1              TeX Mode-Footnote-1

But since now anchors are very infrequent in Info files they don't
cause a problem yet.  However, with more widespread use of anchors
completion lists of node names will grow significantly.  So, I think
this discussion should be postponed until Info files have more anchors
and thus it will be clear how many real problems anchors cause.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Richard Stallman]

    I think Info-goto-node with a completion list without anchors might be
    useful for users that want to see only node names.  For instance,
    currently Info-goto-node called on the Emacs manual adds anchors
    useless for users:

Maybe we should make a convention to distinguish between anchors that
users might find interesting and anchors users would never want to
visit.  For instance, maybe we could put spaces into the anchor names
that users should not see, and exclude them from completion.

    But since now anchors are very infrequent in Info files they don't
    cause a problem yet.  However, with more widespread use of anchors
    completion lists of node names will grow significantly.  So, I think
    this discussion should be postponed until Info files have more anchors
    and thus it will be clear how many real problems anchors cause.

That is ok.

Re: Info enhancements

[Luc Teirlinck]

The following is an apparent bug in your proposed patch to info.el.

Do C-h i g (texinfo)example

If you click on the ` of the `@verbatim': reference you indeed go
there, but clicking elsewhere on the reference produces an error.
Same thing for the other two references in that node:

Info-follow-reference: No cross-reference named      `@verbatim'
Info-follow-reference: No cross-reference named `@noindent'
Info-follow-reference: No cross-reference named `@code'

Your patch still seems to try to guess places in the node when one
follows cross-references.  I believe that it would be better to
give up on that, since it would use the second or third argument to
@xref and friends in a way that was not intended.  I believe it is OK
in index menus.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> If you click on the ` of the `@verbatim': reference you indeed go
> there, but clicking elsewhere on the reference produces an error.

It was caused by an incomplete regexp for references.  I will post
a fix in the next version of the full patch to info.el.

> Your patch still seems to try to guess places in the node when one
> follows cross-references.

No, this is not related to guessing places in the node.

> I believe that it would be better to give up on that, since it would
> use the second or third argument to @xref and friends in a way that
> was not intended.

I still think this is a useful feature.  And currently it works
exactly as the standalone Info reader does.  But we could add an
option for users willing to disable this feature.

> I believe it is OK in index menus.

But even going from index menus it sometimes misses the right place.
After adding information about positions of index entries to Info
files it would work better than guessing.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
>     For example, currently the Glossary node of the
>     Emacs Manual has non-functional references that merely has a form of a
>     simple text "(q.v.)" or "See `default.'".  
>
> I see.  Yes, this is more or less what anchors were invented for.
> As far as glossary entries go, I think that would work ok.  The
> reference name solution seems too heuristic.

Anchors wouldn't work in this case because many glossary entries have
the same names as Info nodes (e.g. "Filling", "Global Mark Ring" and
many others).  Making anchors for them is not possible because anchors
and nodes can't have the same names.  So, using the reference name
solution seems inevitable here.

> However, I certainly agree with the comment that if we make an anchor
> for every index entry, that's too many anchors (it would make the i cmd
> a subset of g :).  Instead, I think indexes are important enough that
> they deserve special treatment.
>
> In fact, we've had this discussion before, in the context of allowing
> arbitrary index names (specifically, ones with a :).  One message from
> that thread is from rms, on 26 Jun 2003 01:30:50 -0400, Message-Id:
> <E19VPLO-0004C2-6Q@fencepost.gnu.org>.

I found this message, but I have one question to administrators of the
emacs-devel mailing list: does the emacs-devel archive exist in mbox
format available for download?  Often there is a need to read old
discussions, but web interface to archives is too inconvenient.  Much
better is to browse mail archives in a local mbox file by one of the
Emacs mail readers.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Karl Berry]

    does the emacs-devel archive exist in mbox
    format available for download?

ftp://mail.gnu.org/emacs-devel/  (by month).

All the GNU lists are available there, as far as I know.

HTH,
k

Re: Info enhancements

[Reiner Steib]

On Wed, Dec 03 2003, Juri Linkov wrote:

> Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:
>> On Mon, Dec 01 2003, Juri Linkov wrote:
>>> - rebind `M-s' key to a new function `Info-search-next' that searches
>>>   for another occurrence of regular expression from a previous
>>>   `Info-search' command (key `s').  Pressing only one key to repeat
>>>   a search is more convenient than pressing two keys (`s RET').
>>
>> ACK.  I would even suggest to use an easily accessible single-key [1],
>> because `Info-search-next' is used often and repeatedly.  Like `,' for
>> `Info-index-next'.
>>
>> [1] I'm using (define-key Info-mode-map "/" "s") for this which made
>> using info much more convenient for me.
>
> On German and Scandinavian keyboards "/" is placed above the "7" key,
> so still two key presses are needed to use it (shift and "7").
> But M-s is not a bad choice because <META> key can be held down while
> repeating pressing "s" for the next search.  Anyhow, "/" might be
> bound to `Info-search-next' as well.
>
> BTW, you didn't use the function `Info-search-next' in your key
> binding.  But seems this function could be useful to add it
> to the menu and describe it in the `Info-mode' docstring.

I used Emacs 21.3 at that time where `Info-search-next' wasn't
available, IIRC.

Now I use the CVS version, but apparently there still is no key
binding for `Info-search-next' (it in the menu, though).  Was there
any objection against binding `Info-search-next' to `M-s' (or `/')?

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Info enhancements

[Juri Linkov]

Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:
> I used Emacs 21.3 at that time where `Info-search-next' wasn't
> available, IIRC.
>
> Now I use the CVS version, but apparently there still is no key
> binding for `Info-search-next' (it in the menu, though).  Was there
> any objection against binding `Info-search-next' to `M-s' (or `/')?

I remember Richard objected against binding `Info-search-next'
to `M-s' and `/'.

But fortunately, now `Info-search-next' (with possible `M-s' and `/'
bindings) as well as `Info-search' with `s' binding are basically
obsoleted by the ability to use C-M-s and C-M-r to isearch for a regexp
across Info nodes.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Info enhancements

[Richard Stallman]

    But fortunately, now `Info-search-next' (with possible `M-s' and `/'
    bindings) as well as `Info-search' with `s' binding are basically
    obsoleted by the ability to use C-M-s and C-M-r to isearch for a regexp
    across Info nodes.

Could you write an update for info.texi?  If you make the text
basically correct, I can polish up the English.