Function: idlwave-help-find-in-doc-header

idlwave-help-find-in-doc-header is a byte-compiled function defined in idlw-help.el.gz.

Signature

(idlwave-help-find-in-doc-header NAME TYPE CLASS KEYWORD &optional EXACT)

Documentation

Find the requested help in the doc-header above point.

First checks if there is a doc-lib header which describes the correct routine. Then tries to find the KEYWORDS section and the KEYWORD, if given. Returns the point which should be window start of the help window. If EXACT is non-nil, the full help position must be found - down to the keyword requested. This setting is for context help, if the exact spot is needed.

If EXACT is nil, the position of the header is returned if it describes the correct routine - even if the keyword description cannot be found. TYPE is ignored.

This function expects a more or less standard routine header. In particular it looks for the NAME: tag, either with a colon, or alone on a line. Then NAME: must be followed by the routine name on the same or the next line. When KEYWORD is non-nil, looks first for a KEYWORDS section. It is amazing how inconsistent this is through some IDL libraries I have seen. We settle for a line containing an upper case "KEYWORD" string. If this line is not found we search for the keyword anyway to increase the hit-rate

When one of these sections exists we check for a line starting with any of

  /KEYWORD KEYWORD- KEYWORD= KEYWORD

with spaces allowed between the keyword and the following dash or equal sign. If there is a match, we assume it is the keyword description.

Source Code

;; Defined in /usr/src/emacs/lisp/progmodes/idlw-help.el.gz
(defun idlwave-help-find-in-doc-header (name _type class keyword
					     &optional exact)
  "Find the requested help in the doc-header above point.

First checks if there is a doc-lib header which describes the correct
routine.  Then tries to find the KEYWORDS section and the KEYWORD, if
given.  Returns the point which should be window start of the help
window.  If EXACT is non-nil, the full help position must be found -
down to the keyword requested.  This setting is for context help, if
the exact spot is needed.

If EXACT is nil, the position of the header is returned if it
describes the correct routine - even if the keyword description cannot
be found.  TYPE is ignored.

This function expects a more or less standard routine header.  In
particular it looks for the `NAME:' tag, either with a colon, or alone
on a line.  Then `NAME:' must be followed by the routine name on the
same or the next line.  When KEYWORD is non-nil, looks first for a
`KEYWORDS' section.  It is amazing how inconsistent this is through
some IDL libraries I have seen.  We settle for a line containing an
upper case \"KEYWORD\" string.  If this line is not found we search
for the keyword anyway to increase the hit-rate

When one of these sections exists we check for a line starting with any of

  /KEYWORD  KEYWORD-  KEYWORD=  KEYWORD

with spaces allowed between the keyword and the following dash or equal sign.
If there is a match, we assume it is the keyword description."
  (let* ((case-fold-search t)
	 (rname (if (stringp class)
		    (concat
		     "\\("
		     ;; Traditional name or class::name
		     "\\("
		     "\\(" (regexp-quote (downcase class)) "::\\)?"
		     (regexp-quote (downcase name))
		     "\\>\\)"
		     (concat
		      "\\|"
		      ;; class__define or just class
		      (regexp-quote (downcase class)) "\\(__define\\)?")
		     "\\)")
		  (regexp-quote (downcase name))))

	 ;; NAME tag plus the routine name.  The new version is from JD.
	 (name-re (concat
		   "\\(^;+\\*?[ \t]*"
		   idlwave-help-doclib-name
		   "\\([ \t]*:\\|[ \t]*$\\)[ \t]*\\(\n;+[ \t]*\\)*"
		   rname
		   "\\|"
		   "^;+[ \t]*"
		   rname
		   ":[ \t]*$\\)"))

	 ;; Header start plus name
	 ;; (header-re (concat "\\(" idlwave-doclib-start "\\).*\n"
	 ;;                 "\\(^;+.*\n\\)*"
	 ;;                 "\\(" name-re "\\)"))
	 ;; A keywords section
	 (kwds-re (concat		                    ; forgiving
		   "^;+\\*?[ \t]*"
		   "\\([-A-Z_ ]*"
		   idlwave-help-doclib-keyword
		   "[-A-Z_ ]*\\)"
		   "\\(:\\|[ \t]*\n\\)"))

	 ;; The individual keyword description line.
	 (kwd-re (if keyword                                ; hard (well...)
		     (concat
		      "^;+[ \t]+"
		      "\\(/" (regexp-quote (upcase keyword))
		      "\\|"  (regexp-quote (upcase keyword)) "[ \t]*[-=:\n]"
		      "\\)")))
	 (kwd-re2 (if keyword                               ; forgiving
		      (concat
		       "^;+[ \t]+"
		       (regexp-quote (upcase keyword))
		      "\\>")))
	 dstart dend name-pos kwds-pos kwd-pos)
    (catch 'exit
      (save-excursion
	(goto-char (point-min))
	(while (and (setq dstart (re-search-forward idlwave-doclib-start nil t))
		    (setq dend (re-search-forward idlwave-doclib-end nil t)))
	  ;; found a routine header
	  (goto-char dstart)
	  (if (setq name-pos (re-search-forward name-re dend t))
	      (progn
		(if keyword
		    ;; We do need a keyword
		    (progn
		      ;; Try to find a keyword section, but don't force it.
		      (goto-char name-pos)
		      (if (let ((case-fold-search nil))
			    (re-search-forward kwds-re dend t))
			  (setq kwds-pos (match-beginning 0)))
		      ;; Find the keyword description
		      (if (or (let ((case-fold-search nil))
				(re-search-forward kwd-re dend t))
			      (re-search-forward kwd-re dend t)
			      (let ((case-fold-search nil))
				(re-search-forward kwd-re2 dend t))
			      (re-search-forward kwd-re2 dend t))
			  (setq kwd-pos (match-beginning 0))
			(if exact
			    (progn
			      (idlwave-help-diagnostics
			       (format "Could not find description of kwd %s"
				       (upcase keyword)))
			      (throw 'exit nil))))))
		;; Return the best position we got
		(throw 'exit (or kwd-pos kwds-pos name-pos dstart)))
	    (goto-char dend))))
      (idlwave-help-diagnostics "Could not find doclib header")
      (throw 'exit nil))))