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

[Lute Kamstra]

"Stefan Monnier" <monnier+gnu/emacs/address@hidden> writes:

>> Currently, lisp-mnt.el has the functions lm-commentary-mark, which
>> returns the beginning of the commentary section, and lm-commentary,
>> which returns the comment section as a string.  checkdoc.el cannot
>> use the latter function as it uses ispell for spell checking and,
>> as I understand it, ispell only works on buffers.  So checkdoc.el
>> additionally needs the end of the commentary section (as a buffer
>> position).  We could introduce lm-commentary-end for this purpose
>> and let lm-commentary use it (as well).  The way lm-commentary now
>> determines the end of the commentary section is not very robust,
>> though.  It depends on the presence of a ChangeLog/History or Code
>> header.  Maybe we should let lm-commentary-end fall back to my
>> method of finding the end of the commentary section (i.e., skipping
>> over all whitespace and comment lines) in case the aforementioned
>> headers are absent?
>
> 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).

> It's a bug for the `commentary' section not to be followed by some
> other section (typically `code', sometimes `history' or `todo' or
> `bugs').

Agreed.  checkdoc.el will inform the user about the absence of a code
section anyway.

> PS: By the way, I think we should introduce a new section whose
>     content is Texinfo prefixed with `;; ', and we should then
>     automatically build an "Emacs Packages Manuals" info page
>     (separate from the emacs manual) that holds the doc of all
>     those packages.

That is a really nice idea.  However, editing Texinfo as comments in
emacs-lisp-mode doesn't appeal to me.  :-(

Lute.