replace-regexp, the byte-compiler, docstrings, and suggestions

[Emanuel Berg]

First I wrote this:

    (defun block-cite ()
      "Add four spaces to each line in the region."
      (interactive)
      (if mark-active
          (replace-regexp "^" "    " nil (region-beginning) (region-end)) ))

Then the byte-compiler told me:

    In block-cite:
    gnus/message-my.el:39:7:Warning: `replace-regexp' used from Lisp code
    That command is designed for interactive use only

So I checked out the help for `replace-regexp':

    This function is usually the wrong thing to use in a Lisp program.
    What you probably want is a loop like this:
      (while (re-search-forward REGEXP nil t)
        (replace-match TO-STRING nil nil))
    which will run faster and will not set the mark or print anything.

And I wrote:

    (defun replace-regexp-quiet (regexp to-string start end)
      (save-excursion
        (goto-char start)
        (while (re-search-forward regexp end t) ; NOERROR
          (replace-match to-string) )))

And the byte-compiler is happy!

Question:

Is there already a block-cite function? I want it to
make nice looking citations and blocks of data in
Usenet posts and mails. (Actually I would call them
quotes outright only that is spoken for already in
that context.)

As for source code, I'm not entirely sure what is best
practice. The block makes it easier to read but after
a copy/paste (kill/yank), it wouldn't look the same
instantly compared to the source itself (most often).
So I think I'll use it for short code-blocks but for
longer I'll refer to the complete source file. I'm
opposed to the copy/paste culture but I'm also
altruistic/practical (not to mention modest) so this
is a intricate trade-off...

Suggestions:

1. If there isn't a block-cite (or whatever), there
   should be one.

2. Instead of the note in the docstring for
   `replace-regexp', why don't you do an
   interface (like I did) and refer to that? (Both in
   the docstring and when byte-compiling.) The
   explanation why can still be there, of course.

3. In the docstring for `re-search-forward', the
   arguments aren't mentioned explicitly which makes
   them hard to find (actually they are not that
   difficult to find - it is rather that if they are
   not mentioned explicitely, they don't get
   `help-argument-face', so then you *think* they are
   not mentioned and you don't bother looking).

I will send all this as a bug report but I thought I'd
tell you first and if there are discussion I will
include any new "leads" which will perhaps make the
bug report even more to the point.

-- 
underground experts united