Re: Spell checking of the commentary section by checkdoc.el.

[Lute Kamstra]

Lute Kamstra <address@hidden> writes:

>> We should probably introduce a lm-section-start and lm-section-end,
>> where the end of a section is defined as "just before the beginning
>> of the next section".
>
> Agreed.  
>
> Best make lm-section-mark an alias of lm-section-start.
>
> I think lm-section-end should be section-nesting aware.  I'm in favor
> of adhering to the nesting system that is used in emacs-lisp-mode's
> settings for outline-minor-mode.  In this system, section headers are
> preceded by at least three semicolons and (sub)*sections are produced
> by adding extra semicolons, one for each nesting level.  So
> lm-section-end should first determine the nesting level of the section
> and then look for the next section header on the same level or higher
> (that is, more important).

I implemented this.  See the two patches below.

Stefan, is this what you had in mind?

Regarding the implementation: I'm a bit uncertain on two points.

1. I did a defalias to define a defsubst.  Does this work?  I.e., if I
   do (defsubst A ...) and then (defalias 'B 'A), is then B inline as
   well?

2. I used the function lisp-outline-level from lisp-mode.el and
   required lisp-mode in the function definition that called
   lisp-outline-level.  Is this good practice?

Note furthermore that I changed the description of lisp-mnt.el in the
header line, the commentary section, and in the customize group.
These descriptions used to say that lisp-mnt provides a minor mode,
which it does not.

Regards,

  Lute.




*** lisp/emacs-lisp/checkdoc.el.~1.36.~ 2003-03-28 18:38:50.000000000 +0100
--- lisp/emacs-lisp/checkdoc.el 2003-05-22 12:16:23.000000000 +0200
***************
*** 2346,2367 ****
        ;; section that is easy to pick out, and it is also the most
        ;; visible section (with the finder).
        (let ((cm (lm-commentary-mark)))
!       (if cm
!           (save-excursion
!             (goto-char (lm-commentary-mark))
!             ;; Spellcheck between the commentary, and the first
!             ;; non-comment line.  We could use lm-commentary, but that
!             ;; returns a string, and Ispell wants to talk to a buffer.
!             ;; Since the comments talk about Lisp, use the specialized
!             ;; spell-checker we also used for doc strings.
!             (let ((e (save-excursion (re-search-forward "^[^;]" nil t)
!                                      (point))))
!               (checkdoc-sentencespace-region-engine (point) e)
!               (checkdoc-proper-noun-region-engine (point) e)
!               (checkdoc-ispell-docstring-engine e)))))
! ;;; test comment out code
! ;;;       (foo 1 3)
! ;;;       (bar 5 7)
        (setq
         err
         (or
--- 2346,2361 ----
        ;; section that is easy to pick out, and it is also the most
        ;; visible section (with the finder).
        (let ((cm (lm-commentary-mark)))
!       (when cm
!           (save-excursion
!             (goto-char cm)
!             (let ((e (copy-marker (lm-commentary-end))))
!               ;; Since the comments talk about Lisp, use the
!               ;; specialized spell-checker we also used for doc
!               ;; strings.
!               (checkdoc-sentencespace-region-engine (point) e)
!               (checkdoc-proper-noun-region-engine (point) e)
!               (checkdoc-ispell-docstring-engine e)))))
        (setq
         err
         (or


*** lisp/emacs-lisp/lisp-mnt.el.~1.37.~ 2003-02-04 13:53:34.000000000 +0100
--- lisp/emacs-lisp/lisp-mnt.el 2003-05-22 17:40:43.000000000 +0200
***************
*** 1,4 ****
! ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
  
  ;; Copyright (C) 1992, 1994, 1997, 2000, 2001 Free Software Foundation, Inc.
  
--- 1,4 ----
! ;;; lisp-mnt.el --- utility functions for Emacs Lisp maintainers
  
  ;; Copyright (C) 1992, 1994, 1997, 2000, 2001 Free Software Foundation, Inc.
  
***************
*** 27,33 ****
  
  ;;; Commentary:
  
! ;; This minor mode adds some services to Emacs-Lisp editing mode.
  ;;
  ;; First, it knows about the header conventions for library packages.
  ;; One entry point supports generating synopses from a library directory.
--- 27,33 ----
  
  ;;; Commentary:
  
! ;; This library adds some services to Emacs-Lisp editing mode.
  ;;
  ;; First, it knows about the header conventions for library packages.
  ;; One entry point supports generating synopses from a library directory.
***************
*** 79,85 ****
  ;; in this file is mildly bogus because the maintainer line is redundant.
  ;;    The idea behind these two fields is to be able to write a Lisp function
  ;; that does "send mail to the author" without having to mine the name out by
! ;; hand. Please be careful about surrounding the network address with <> if
  ;; there's also a name in the field.
  ;;
  ;;    * Created line --- optional, gives the original creation date of the
--- 79,85 ----
  ;; in this file is mildly bogus because the maintainer line is redundant.
  ;;    The idea behind these two fields is to be able to write a Lisp function
  ;; that does "send mail to the author" without having to mine the name out by
! ;; hand.  Please be careful about surrounding the network address with <> if
  ;; there's also a name in the field.
  ;;
  ;;    * Created line --- optional, gives the original creation date of the
***************
*** 124,130 ****
  ;;; Variables:
  
  (defgroup lisp-mnt nil
!   "Minor mode for Emacs Lisp maintainers."
    :prefix "lm-"
    :group 'maint)
  
--- 124,130 ----
  ;;; Variables:
  
  (defgroup lisp-mnt nil
!   "Utility functions for Emacs Lisp maintainers."
    :prefix "lm-"
    :group 'maint)
  
***************
*** 156,161 ****
--- 156,166 ----
    :type 'integer
    :group 'lisp-mnt)
  
+ (defcustom lm-any-header ".*"
+   "Regexp which matches start of any section."
+   :type 'regexp
+   :group 'lisp-mnt)
+ 
  (defcustom lm-commentary-header "Commentary\\|Documentation"
    "Regexp which matches start of documentation section."
    :type 'regexp
***************
*** 188,217 ****
                    (match-end 1)))
        (match-string-no-properties 1))))
  
! (defun lm-section-mark (header &optional after)
    "Return the buffer location of a given section start marker.
  The HEADER is the section mark string to search for.
! If AFTER is non-nil, return the location of the next line."
    (save-excursion
      (let ((case-fold-search t))
        (goto-char (point-min))
        (if (re-search-forward (lm-get-header-re header 'section) nil t)
!         (progn
!           (beginning-of-line)
!           (if after (forward-line 1))
!           (point))))))
  
! (defsubst lm-code-mark ()
    "Return the buffer location of the `Code' start marker."
!   (lm-section-mark "Code"))
  
! (defsubst lm-commentary-mark ()
    "Return the buffer location of the `Commentary' start marker."
!   (lm-section-mark lm-commentary-header))
  
! (defsubst lm-history-mark ()
    "Return the buffer location of the `History' start marker."
!   (lm-section-mark lm-history-header))
  
  (defsubst lm-copyright-mark ()
    "Return the buffer location of the `Copyright' line."
--- 193,258 ----
                    (match-end 1)))
        (match-string-no-properties 1))))
  
! (defun lm-section-start (header &optional after)
    "Return the buffer location of a given section start marker.
  The HEADER is the section mark string to search for.
! If AFTER is non-nil, return the location of the next line.
! If the given section does not exist, return nil."
    (save-excursion
      (let ((case-fold-search t))
        (goto-char (point-min))
        (if (re-search-forward (lm-get-header-re header 'section) nil t)
!           (line-beginning-position (if after 2))))))
! (defalias 'lm-section-mark 'lm-section-start)
  
! (defun lm-section-end (header)
!   "Return the buffer location of the end of a given section.
! The HEADER is the section string marking the beginning of the
! section.  If the given section does not exist, return nil.
! 
! The end of the section is defined as the beginning of the next
! section of the same level or lower.  The function
! `lisp-outline-level' is used to compute the level of a section.
! If no such section exists, return the end of the buffer."
!   (require 'lisp-mode)
!   (let ((start (lm-section-start header)))
!     (when start
!       (save-excursion
!         (goto-char start)
!         (let ((level (lisp-outline-level))
!               (case-fold-search t)
!               next-section-found)
!           (beginning-of-line 2)
!           (while (and (setq next-section-found
!                             (re-search-forward
!                              (lm-get-header-re lm-any-header 'section)
!                              nil t))
!                       (> (save-excursion
!                            (beginning-of-line)
!                            (lisp-outline-level))
!                          level)))
!           (if next-section-found
!               (line-beginning-position)
!             (point-max)))))))
! 
! (defsubst lm-code-start ()
    "Return the buffer location of the `Code' start marker."
!   (lm-section-start "Code"))
! (defalias 'lm-code-mark 'lm-code-start)
  
! (defsubst lm-commentary-start ()
    "Return the buffer location of the `Commentary' start marker."
!   (lm-section-start lm-commentary-header))
! (defalias 'lm-commentary-mark 'lm-commentary-start)
! 
! (defsubst lm-commentary-end ()
!   "Return the buffer location of the `Commentary' section end."
!   (lm-section-end lm-commentary-header))
  
! (defsubst lm-history-start ()
    "Return the buffer location of the `History' start marker."
!   (lm-section-start lm-history-header))
! (defalias 'lm-history-mark 'lm-history-start)
  
  (defsubst lm-copyright-mark ()
    "Return the buffer location of the `Copyright' line."
***************
*** 219,226 ****
      (let ((case-fold-search t))
        (goto-char (point-min))
        (if (re-search-forward lm-copyright-prefix nil t)
!         (point))))
!   )
  
  (defun lm-header (header)
    "Return the contents of the header named HEADER."
--- 260,266 ----
      (let ((case-fold-search t))
        (goto-char (point-min))
        (if (re-search-forward lm-copyright-prefix nil t)
!         (point)))))
  
  (defun lm-header (header)
    "Return the contents of the header named HEADER."
***************
*** 431,448 ****
  
  (defun lm-commentary (&optional file)
    "Return the commentary in file FILE, or current buffer if FILE is nil.
! The value is returned as a string.  In the file, the commentary starts
! with the tag `Commentary' or `Documentation' and ends with one of the
! tags `Code', `Change Log' or `History'."
    (lm-with-file file
!     (let ((commentary (lm-commentary-mark))
!         (change-log (lm-history-mark))
!         (code (lm-code-mark)))
!       (cond
!        ((and commentary change-log)
!       (buffer-substring-no-properties commentary change-log))
!        ((and commentary code)
!       (buffer-substring-no-properties commentary code))))))
  
  ;;; Verification and synopses
  
--- 471,484 ----
  
  (defun lm-commentary (&optional file)
    "Return the commentary in file FILE, or current buffer if FILE is nil.
! Return the value as a string.  In the file, the commentary
! section starts with the tag `Commentary' or `Documentation' and
! ends just before the next section.  If the commentary section is
! absent, return nil."
    (lm-with-file file
!     (let ((start (lm-commentary-start)))
!       (when start
!         (buffer-substring-no-properties start (lm-commentary-end))))))
  
  ;;; Verification and synopses