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

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

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

[John Mastro]

Hi,

I sent this from my phone. I think the formatting should be okay, but apologies in advance if I'm wrong about that. 

> Emanuel Berg <embe8573@student.uu.se> wrote:
> 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.)

Would indent-rigidly (or, less likely, indent-code-rigidly) do what you want?

To indent by four spaces you would do something like C-4 C-x <tab>

-- 
john

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

[Robert Thorpe]

Emanuel Berg <embe8573@student.uu.se> writes:

> 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.)

There's Supercite.  It doesn't do the style you want by default, but if
you configure it, it can do it.

(info "sc")

BR,
Robert Thorpe

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

[Emanuel Berg]

John Mastro <john.b.mastro@gmail.com> writes:

> I sent this from my phone. I think the formatting
> should be okay, but apologies in advance if I'm wrong
> about that.

No, looks good.

> Would indent-rigidly (or, less likely,
> indent-code-rigidly) do what you want?

Yeah, indent-rigidly is close only this

    (indent-rigidly (region-beginning) (region-end) 4)

seems to sometimes insert tabs (one tab and one space
in text-mode, but four spaces in message-mode what I
can see). If you can have it not do that (insert tabs,
ever) I'm happy. (I have tabs removed on save but I
still don't like to insert them for the same reason I
have them removed.)

Question is (which I didn't mention in my OP), should
the region be refilled after it gets the new margin,
and, if so, what should the fill-column be?

> To indent by four spaces you would do something like
> C-4 C-x <tab>

Yeah, you mean `C-u 4 C-x TAB'? (`C-x TAB' is
`indent-rigidly'.)

-- 
underground experts united

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

[Drew Adams]

> (indent-rigidly (region-beginning) (region-end) 4)
> seems to sometimes insert tabs (one tab and one space
> in text-mode, but four spaces in message-mode what I
> can see). If you can have it not do that (insert tabs,
> ever) I'm happy.

C-h v indent-tabs-mode

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

[Emanuel Berg]

Drew Adams <drew.adams@oracle.com> writes:

>> (indent-rigidly (region-beginning) (region-end) 4)
>> seems to sometimes insert tabs (one tab and one
>> space in text-mode, but four spaces in message-mode
>> what I can see). If you can have it not do that
>> (insert tabs, ever) I'm happy.
>
> C-h v indent-tabs-mode

Interesting!

Now I have this to get away with tabs:

(defun untab-all ()
  (if (not (member major-mode '(makefile-gmake-mode
                                makefile-mode) )) ; exceptions
      (untabify (point-min) (point-max)) )
  nil) ; tell 'did not write buffer to disk'

(setq before-save-hook '(untab-all delete-trailing-whitespace))

Note the Makefile exceptions because what it seems they
don't reason with whitespaces instead of tabs. (Yes, a
bit surprising, like Python, only I don't remember if
that compulsory indentation stretched to include the
indentation-char(s) as well.)

Anyway I just might remove all that stuff since I
myself never include tabs and if the indentation
doesn't either, where should they come from to begin
with?

Only with the Makefile stuff I have to invert the
current situation to instead have the Makefiles
actually keep indent-tabs-mode as t. Ha ha, and to
think some people think programming is difficult!

-- 
underground experts united

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

[Drew Adams]

> Only with the Makefile stuff I have to invert the
> current situation to instead have the Makefiles
> actually keep indent-tabs-mode as t. Ha ha, and to
> think some people think programming is difficult!

C-h v indent-tabs-mode

,----
| indent-tabs-mode is a variable defined in `C source code'.
| Its value is nil
| Original value was t
| 
|   Automatically becomes buffer-local when set.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

|   This variable is safe as a file local variable if its value
|   satisfies the predicate `booleanp'.
| 
| Documentation:
| Indentation can insert tabs if this is non-nil.
| 
| You can customize this variable.
`----

Use `setq-default' to set the value you want in most modes.
Set the value to non-nil on whatever mode hook you like.

See (emacs) `Just Spaces' and (emacs) `Locals'.
See (elisp) `Primitive Indent'

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

[Robert Thorpe]

Emanuel Berg <embe8573@student.uu.se> writes:
> (defun untab-all ()
>   (if (not (member major-mode '(makefile-gmake-mode
>                                 makefile-mode) )) ; exceptions
>       (untabify (point-min) (point-max)) )
>   nil) ; tell 'did not write buffer to disk'
>
> (setq before-save-hook '(untab-all delete-trailing-whitespace))

Code like this can be useful if you only deal with your own code.  If
you program in collaboration with others it's troublesome.  Converting
all the whitespace in a file causes version control programs to indicate
a lot of changes have happened.

In my opinion it's better to work this way:
* Write a script to remove all of the tabs in all your personal file.
Do that as a one-off operation
* Set indent-tabs-mode so Emacs never generates new tabs.
* Don't untab files before saving them.

The advantage of this is that your own stuff will always be tab-clean
but you can still cooperate with others who use VC.

BR,
Robert Thorpe

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

[John Mastro]

Emanuel Berg <embe8573@student.uu.se> wrote:
> Yeah, indent-rigidly is close only this
>
>     (indent-rigidly (region-beginning) (region-end) 4)
>
> seems to sometimes insert tabs (one tab and one space
> in text-mode, but four spaces in message-mode what I
> can see). If you can have it not do that (insert tabs,
> ever) I'm happy. (I have tabs removed on save but I
> still don't like to insert them for the same reason I
> have them removed.)

You can keep tabs from being inserted by setting `indent-tabs-mode' to
nil. It's a buffer-local variable, so what I do is `setq-default' it to
nil and then override that in hooks for modes where I really do want
tabs (e.g. `makefile-mode').

> Question is (which I didn't mention in my OP), should
> the region be refilled after it gets the new margin,
> and, if so, what should the fill-column be?

So far I deal with that on a case-by-case basis. If I'm quoting code, I
probably don't want it to be filled, but if it's text I probably do.
Off-hand I can't think of a reason to use a different `fill-column' than
whatever is already set for the buffer.

>> To indent by four spaces you would do something like
>> C-4 C-x <tab>
>
> Yeah, you mean `C-u 4 C-x TAB'? (`C-x TAB' is
> `indent-rigidly'.)

`C-N foo' and `C-u N foo' both give `foo' a numeric argument `N' (for
any N 0-9). I often find the former a bit nicer since, for example, I
can do something like press control with my right hand and (without
releasing control) press 4 and then x with my left hand. You can also
use `M-N' in exactly the same way. Of course, which is more convenient
varies a lot by the specific key sequence and, even more so, by taste.

--
john

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

[Stefan Monnier]

> You can keep tabs from being inserted by setting `indent-tabs-mode' to
> nil. It's a buffer-local variable, so what I do is `setq-default' it to
> nil and then override that in hooks for modes where I really do want
> tabs (e.g. `makefile-mode').

Of course, makefile-mode already sets it for you.


        Stefan

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

[Emanuel Berg]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> You can keep tabs from being inserted by setting
>> `indent-tabs-mode' to nil. It's a buffer-local
>> variable, so what I do is `setq-default' it to nil
>> and then override that in hooks for modes where I
>> really do want tabs (e.g. `makefile-mode').
>
> Of course, makefile-mode already sets it for you.

Yes, what I can see, the only thing you have to do is

(setq-default indent-tabs-mode nil)

to get spaces in .emacs and tabs in Makefile.

-- 
underground experts united

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

[Emanuel Berg]

John Mastro <john.b.mastro@gmail.com> writes:

> So far I deal with that on a case-by-case basis. If
> I'm quoting code, I probably don't want it to be
> filled, but if it's text I probably do. Off-hand I
> can't think of a reason to use a different
> fill-column' than whatever is already set for the
> buffer.

Well, maybe you'd like a nice frame which includes the
right side?

But I agree, this is over-engineering. Just because it
is easily done doesn't mean one should do it.
Every time I do something good I do like three layers
or something like that. The first layer does something
good. The second layer does the same thing, only
modified for a special use case and invoked with a
prefix keystroke or whatever. The third layer is just
hacking-overdrive. Then when I start use it I almost
never use even the second layer. And if I do, I don't
use it by means of the second layer because I have
forgotten all about it - instead I use the first
layer, only with modified arguments (e.g., an absolute
path or explicit user).

>> Yeah, you mean `C-u 4 C-x TAB'? (`C-x TAB' is
>> indent-rigidly'.)
>
> `C-N foo' and `C-u N foo' both give `foo' a numeric
> argument `N' (for any N 0-9).

Are you sure? Try 'emacs -Q' and try to do that. I
don't get C-N to work but `C-u N' works.

-- 
underground experts united

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

[Stefan Monnier]

> Are you sure? Try 'emacs -Q' and try to do that. I
> don't get C-N to work but `C-u N' works.

My crystal ball says it's because you can't really send C-N to Emacs
because you're running Emacs inside a text terminal and this terminal
doesn't send those properly (e.g. it turns them into plain N).


        Stefan

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

[Emanuel Berg]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> My crystal ball says it's because you can't really
> send C-N to Emacs because you're running Emacs
> inside a text terminal and this terminal doesn't
> send those properly (e.g. it turns them into plain
> N).

Yeah, probably. I tried in the Linux VT and in X (with
xterm), with and without tmux on both: in the console
C-4 just inserts a "4", in X C-4 is C-\. I only have
emacs-nox installed but I'm happy with `C-u N' so this
doesn't bother me.

-- 
underground experts united

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

[Stefan Monnier]

> Yeah, probably. I tried in the Linux VT and in X (with
> xterm), with and without tmux on both: in the console
> C-4 just inserts a "4", in X C-4 is C-\. I only have
> emacs-nox installed but I'm happy with `C-u N' so this
> doesn't bother me.

You can also use M-N, BTW, which should work also in text terminals.


        Stefan

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

[Emanuel Berg]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Yeah, probably. I tried in the Linux VT and in X
>> (with xterm), with and without tmux on both: in the
>> console C-4 just inserts a "4", in X C-4 is C-\. I
>> only have emacs-nox installed but I'm happy with
>> `C-u N' so this doesn't bother me.
>
> You can also use M-N, BTW, which should work also in
> text terminals.

True!

OK, so I won't suggest a "block cite" function as
there is one, perhaps two, already.

Still, any comments on:

- instead of offering Elisp in the help, give a
  function that does exactly that
  
- have the byte-compiler give this reference as well
  (optimally the same information as in the help, so
  no need to compile and then check out the help)

- could this be optimized transparently? (perhaps a
  bit risky? with a very small gain at that - no, I'm
  happy with what I originally proposed)

- even as it stands, the reason the "interactive"
  `replace-regexp' shouldn't be used is:

    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.

but the interface to `replace-regexp' is:
    
(replace-regexp REGEXP TO-STRING &optional DELIMITED
START END)

So we offer a function. When someone uses it the
compiler complains. Because the compiler doesn't say
much, the user has to check out the help where he is
given the code. But the code doesn't even cover the
interface of the "forbidden" `replace-regexp'. So he
has to figure out the missing parts. By this time
frustration will run high especially because
`replace-regexp' - the incorrect use - probably worked
just fine.

I'm telling you. It is not a big deal. It is a detail.
But it is the details that make the big picture.
    
-- 
underground experts united