Re: ensure that generated files are read-only

[Jim Meyering]

Bruno Haible <address@hidden> wrote:
> Jim Meyering wrote:
>> > 2) For the user who needs to fix a compilation problem, or do minor
>> >    developments in a package.
>> >
>> >    In this case I _do_ want to change the Makefile or config.h, to see
>> >    the results. Because if I change Makefile.am or *.m4, I will have to
>> >    wait 5 minutes until aclocal, automake, autoheader, configure have
>> >    completed their business. Or even worse, I will get errors because
>> >    I don't have the "right" automake and autoconf versions installed.
>> >
>> >    When I modify a Makefile and, when trying to save it, am told
>> >    that I cannot save it, it's a major annoyance.
>>
>> If it's really a major annoyance
>
> Yes. In "vi" I don't know how to make a buffer read-write when it is
> read-only. And since it's read-only, I also cannot remove the line that
> makes it read-only.

I wonder if you're making a hypothetical argument, since I can't reproduce
the behavior that you describe.

I tried it, and Vim doesn't prevent me from making the changes.
Rather, :w and :x don't save the file, but instead give a bright red
warning saying that I have to append a "!" to override the advisory
"read-only" mode.  So, if I follow the instructions and use ":w!", it
does save the modified file.  A classic "vi" on Solaris doesn't honor
the setting at all, so I don't see any problem with vi-like editors.

Remember, we're talking about a file owned and writable by you,
with these two lines at the top:

  -*- buffer-read-only: t -*- vi: set ro:
  DO NOT EDIT! GENERATED AUTOMATICALLY!

> Similarly in emacs: I know where to find the read-only/
> read-write toggle in the menus. But in console mode ("emacs -nw"), I don't
> know how to access the menus.

With newer versions of emacs, it will ask you if you'd like to apply
the settings implied by the "local variables list".  If you would
rather avoid a read-only setting, just say "No".  If you're using emacs
with -nw, and without menu-bar-mode, then I think it's reasonable to
expect that you are capable of using M-x command-apropos to search for
"read-only".  That finds the needed command: "M-x toggle-read-only".

Even if someone is unable to modify a file with vi or emacs, they can
always use some other editor, or revert to "tail -n+3" or "grep -v".
Before you argue that that's asking too much, think whether you want
a bug report from someone who can't be bothered to search their editor
documentation (or google) for "read-only".

> In summary, it's a major annoyance for people who are not wizards of
> their particular editor.

Does something about the above imply editor _wizardry_?
Don't forget who the target audience is, here: people who are
modifying source files in a package based on gnulib.  I think
it's more than fair to assume such people are capable of the above.

>> you should switch to
>> an editor that lets you circumvent such things more easily.
>> In Emacs, C-xC-q is the typical binding to toggle read-only.
>> For Vi, to save a file owned by you, in spite of its read-only
>> setting, just use :w!
>
> It's you who should do something about your environment, not me.

Think of it as a self-regulating barrier to entry.
If someone is unable to figure out how to edit a file s/he owns,
then they should not be editing it in the first place.
Think of the how many misguided bug reports it will save us.

> The issue comes down to different personal preferences: On one hand
> we have the people who want to have complete control of their editing
> actions. On the other hand, we have you who want some guidance from the
> editor about your actions.

Hey, if hints to one's editor can save newbies the trouble of searching
visually for a "GENERATED AUTOMATICALLY" comment, and help keep them
from modifying a downstream file and later losing those changes when
a build clobbers the product of their hard work, then that's a good thing.

> It's like a command-line tool user and a GUI
> user. These expectations are incompatible. It's impossible to satisfy
> both without considering some personal files such as ~/.emacs, ~/.vimrc.
>
> So my proposal is that we add the string
>
>         DO NOT EDIT! GENERATED AUTOMATICALLY!

That's a fine start, and more than enough for very small files.
For larger ones, say more than 30 or 40 lines, we should do more,
since that top line may not be visible.  And even if it is visible,
who's to say the reader will even see it?

> at the top of each generated file, and that you program the
> 'find-file-hooks' of your Emacs so that it scans the first few lines of
> the buffer and sets the buffer read-only if it finds this string.

Obviously I can do that, but my concern was not for myself, but rather
for those less familiar with how autoconf, make, and gnulib work.
My itch was scratched when I fixed coreutils' bootstrap script.

The change that prompted all this for me was coreutils' move to using a
bootstrap/gnulib-tool-based system.  Now, files in lib and m4 that I'm
used to "owning" (since they were version-controlled in the coreutils
repository) are now pulled from gnulib.  This is a good thing.  However,
for anyone doing coreutils development there was no convenient and
reliable way to know which {m4,lib}/*.[ch] files should be changed
directly in the coreutils repo, and which now come from gnulib.
I've changed coreutils' bootstrap script so that most generated files
in coreutils have those two lines at the top.  So that's the part that
affected me personally.

My "fixing" the gnulib/modules' Makefile.am snippets was an extension
of this idea, since it was "obvious" to me that others (especially
novices) would benefit from something similar in gnulib.  They don't
necessarily know that files like fcntl.h, inttypes.h, and stdint.h
are generated.  I understand the arguments against making the files
read-only in the chmod sense, and hence backed out those changes.
The point is that I personally don't need (and most certainly won't
benefit from) the proposed gnulib changes.

However, I confess that I'm surprised that the compromise of adding
advisory comments rubs you (Bruno) so hard the wrong way.  Does anyone
else object to adding both lines?

On one hand, providing the hint seems to be the right thing to do.
On the other, so few people are going to end up modifying *those*
generated files (especially once things stabilize) that it might
not even be worth discussing any more, if there are real objections.