Re: master 9d2f4a8d5a: Add convenience functions for generating Emacs Lisp files

Re: master 9d2f4a8d5a: Add convenience functions for generating Emacs Lisp files

[Stefan Monnier]

Thank you, Lars.  I can't believe it didn't occur to me earlier.

> +++ b/lisp/emacs-lisp/generate-file.el

I'd put "elisp" or somesuch in the name, to make it clear it's about
generation of ELisp files rather than generation of any other kinds
of files.

> +(cl-defun generate-file-heading (file &key description text (code t))
> +  "Insert a standard header for FILE.
> +This header will specify that this is a generated file that
> +should not be edited.
> +
> +If `standard-output' is bound to a buffer, insert in that buffer.
> +If no, insert at point in the current buffer.
> +
> +DESCRIPTION (if any) will be used in the first line.
> +TEXT (if given) will be inserted as a comment.

I suggest to use names that make it more clear which of the two should
be a single line.  Maybe `title` and `commentary`?

> +If CODE is non-nil (which is the default), a Code: line is
> +inserted."

Why would we ever want to not insert `Code:`?

More importantly, I think this function needs an additional (and
mandatory!) argument, which specifies which function generated it.
I've too often wasted time locating the code responsible for a bug in
the generated file just because that file failed to tell me where this
generated file comes from, so we should make it "harder" to generate
a file without that origin information.

> +            ";; This file is part of GNU Emacs.\n\n")

Hmm... this makes the function unusable for third party packages,
doesn't it?


        Stefan

Re: master 9d2f4a8d5a: Add convenience functions for generating Emacs Lisp files

[Lars Ingebrigtsen]

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

>> +++ b/lisp/emacs-lisp/generate-file.el
>
> I'd put "elisp" or somesuch in the name, to make it clear it's about
> generation of ELisp files rather than generation of any other kinds
> of files.

I'd hoped that having it in emacs-lisp would be enough, but perhaps
that's a too subtle hint?  OK, I'll rename.

> I suggest to use names that make it more clear which of the two should
> be a single line.  Maybe `title` and `commentary`?

Makes sense.  Done.

>> +If CODE is non-nil (which is the default), a Code: line is
>> +inserted."
>
> Why would we ever want to not insert `Code:`?

miscdic/titdic inserts the Code itself after a whopping comment -- I
guess we could require that the callers put all the comments in
:comment, though.

> More importantly, I think this function needs an additional (and
> mandatory!) argument, which specifies which function generated it.
> I've too often wasted time locating the code responsible for a bug in
> the generated file just because that file failed to tell me where this
> generated file comes from, so we should make it "harder" to generate
> a file without that origin information.

Very true.  Now adjusted.

>> +            ";; This file is part of GNU Emacs.\n\n")
>
> Hmm... this makes the function unusable for third party packages,
> doesn't it?

Perhaps it should be disablable? 

(Note that after this adjustment, you may have to say "make bootstrap"
unfortunately, because I don't think all the dependencies here are
correct in our Makefiles...)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no