Extending emacs convention for first line

Extending emacs convention for first line

[Christopher Dimech]

Emacs convention states that the format for the first line is

;;; filename --- description  -*- lexical-binding: t; -*-

Because at the times one does notice longer filenames and descriptions,
it would be favorable if the convention would be extended to handle longer
filenames and descriptions.

For instance, using ;;; to distinguish, with "lexical-binding" still written first.

;;; -*- lexical-binding: t; -*-

;;; filename

;;; description

Or some other way that would work nicely.

Re: Extending emacs convention for first line

[Stefan Monnier via Users list for the GNU Emacs text editor]

Christopher Dimech [2022-10-17 21:40:14] wrote:
> Emacs convention states that the format for the first line is
> ;;; filename --- description  -*- lexical-binding: t; -*-
>
> Because at the times one does notice longer filenames and descriptions,
> it would be favorable if the convention would be extended to handle longer
> filenames and descriptions.
>
> For instance, using ;;; to distinguish, with "lexical-binding" still written first.
>
> ;;; -*- lexical-binding: t; -*-
>
> ;;; filename
>
> ;;; description
>
> Or some other way that would work nicely.

I don't have a strong opinion on this, but I'll note that I hope we can
get rid of the `-*- lexical-binding: t -*-` cookie in the not too
distant future.

I think we're slowly working our way up to the point where we can change
the default to t such that the cookie will be needed only (in the form
`-*- lexical-binding: nil -*-`) for those files still using the old
dynbound dialect of ELisp.


        Stefan

Re: Extending emacs convention for first line

[Emanuel Berg]

Stefan Monnier via Users list for the GNU Emacs text editor wrote:

> I don't have a strong opinion on this, but I'll note that
> I hope we can get rid of the `-*- lexical-binding: t -*-`
> cookie in the not too distant future.
>
> I think we're slowly working our way up to the point where
> we can change the default to t such that the cookie will be
> needed only (in the form `-*- lexical-binding: nil -*-`) for
> those files still using the old dynbound dialect of ELisp.

Awesome!

-- 
underground experts united
https://dataswamp.org/~incal

Re: Extending emacs convention for first line

[Christopher Dimech]

> Sent: Tuesday, October 18, 2022 at 1:33 PM
> From: "Stefan Monnier via Users list for the GNU Emacs text editor" <help-gnu-emacs@gnu.org>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Extending emacs convention for first line
>
> Christopher Dimech [2022-10-17 21:40:14] wrote:
> > Emacs convention states that the format for the first line is
> > ;;; filename --- description  -*- lexical-binding: t; -*-
> >
> > Because at the times one does notice longer filenames and descriptions,
> > it would be favorable if the convention would be extended to handle longer
> > filenames and descriptions.
> >
> > For instance, using ;;; to distinguish, with "lexical-binding" still written first.
> >
> > ;;; -*- lexical-binding: t; -*-
> >
> > ;;; filename
> >
> > ;;; description
> >
> > Or some other way that would work nicely.
>
> I don't have a strong opinion on this, but I'll note that I hope we can
> get rid of the `-*- lexical-binding: t -*-` cookie in the not too
> distant future.
>
> I think we're slowly working our way up to the point where we can change
> the default to t such that the cookie will be needed only (in the form
> `-*- lexical-binding: nil -*-`) for those files still using the old
> dynbound dialect of ELisp.
>
>
>         Stefan

The suggestion is more focused on allowing descriptions longer
than a single line.  And which would avoid us long lines.

Re: Extending emacs convention for first line

[Stefan Monnier]

>> I don't have a strong opinion on this, but I'll note that I hope we can
>> get rid of the `-*- lexical-binding: t -*-` cookie in the not too
>> distant future.
>>
>> I think we're slowly working our way up to the point where we can change
>> the default to t such that the cookie will be needed only (in the form
>> `-*- lexical-binding: nil -*-`) for those files still using the old
>> dynbound dialect of ELisp.
>>
> The suggestion is more focused on allowing descriptions longer
> than a single line.  And which would avoid us long lines.

My note above was only tangentially related to your suggestion, indeed.

W.r.t the length of the description, the limited length is (up to
a point) a *feature*, since that description can appear in various other
places (e.g. the https://elpa.gnu.org/packages/ web page) where an overly
long description would be inconvenient.

So, I definitely don't want to allow multi-line descriptions here.
There's already the `Commentary:` section for a longer description.
So I only see two cases where the current convention is problematic:

- when the -*- lexical-binding: t -*- cookie pushes the line length
  beyond 80 columns.
- when the filename is itself so long that even with a short description
  the line length beyond 80 columns.

As I mention in my remark, I hope the first problem is transitory (tho
it'll still be with us for a few more years).


        Stefan


PS: for some packages, the `Commentary:` can be too long for some uses,
e.g. release announcements for GNU ELPA packages don't include the
commentary.  So maybe we could introduce a new convention for a "short
multi-line description" (something like 4-5 lines, we could call it
"Summary" or "Abstract", maybe), in addition to the short single-line
description.  It could be used in release announcements, or appear in
https://elpa.gnu.org/packages/ when you hover over a package description
(or appear when you click something to "unfold" the description,
maybe?).

Re: Extending emacs convention for first line

[Christopher Dimech]

> Sent: Friday, October 21, 2022 at 6:06 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: Extending emacs convention for first line
>
> >> I don't have a strong opinion on this, but I'll note that I hope we can
> >> get rid of the `-*- lexical-binding: t -*-` cookie in the not too
> >> distant future.
> >>
> >> I think we're slowly working our way up to the point where we can change
> >> the default to t such that the cookie will be needed only (in the form
> >> `-*- lexical-binding: nil -*-`) for those files still using the old
> >> dynbound dialect of ELisp.
> >>
> > The suggestion is more focused on allowing descriptions longer
> > than a single line.  And which would avoid us long lines.
>
> My note above was only tangentially related to your suggestion, indeed.
>
> W.r.t the length of the description, the limited length is (up to
> a point) a *feature*, since that description can appear in various other
> places (e.g. the https://elpa.gnu.org/packages/ web page) where an overly
> long description would be inconvenient.
>
> So, I definitely don't want to allow multi-line descriptions here.
> There's already the `Commentary:` section for a longer description.
> So I only see two cases where the current convention is problematic:
>
> - when the -*- lexical-binding: t -*- cookie pushes the line length
>   beyond 80 columns.
> - when the filename is itself so long that even with a short description
>   the line length beyond 80 columns.
>
> As I mention in my remark, I hope the first problem is transitory (tho
> it'll still be with us for a few more years).
>
>
>         Stefan
>
>
> PS: for some packages, the `Commentary:` can be too long for some uses,
> e.g. release announcements for GNU ELPA packages don't include the
> commentary.  So maybe we could introduce a new convention for a "short
> multi-line description" (something like 4-5 lines, we could call it
> "Summary" or "Abstract", maybe), in addition to the short single-line
> description.  It could be used in release announcements, or appear in
> https://elpa.gnu.org/packages/ when you hover over a package description
> (or appear when you click something to "unfold" the description,
> maybe?).

I do not see it would be necessary.  What can be done is take first paragraph
in the commentary.  And leave the single line brief intact.

Re: Extending emacs convention for first line

[Stefan Monnier via Users list for the GNU Emacs text editor]

Christopher Dimech [2022-10-20 22:11:02] wrote:
>> PS: for some packages, the `Commentary:` can be too long for some uses,
>> e.g. release announcements for GNU ELPA packages don't include the
>> commentary.  So maybe we could introduce a new convention for a "short
>> multi-line description" (something like 4-5 lines, we could call it
>> "Summary" or "Abstract", maybe), in addition to the short single-line
>> description.  It could be used in release announcements, or appear in
>> https://elpa.gnu.org/packages/ when you hover over a package description
>> (or appear when you click something to "unfold" the description,
>> maybe?).
>
> I do not see it would be necessary.  What can be done is take first paragraph
> in the commentary.  And leave the single line brief intact.

IOW, you're suggesting to introduce the convention that the first
paragraph be considered as the "summary/abstract".  I like that, tho
I haven't checked to see if it would work well in practice.


        Stefan

Re: Extending emacs convention for first line

[Christopher Dimech]

> Sent: Friday, October 21, 2022 at 10:57 AM
> From: "Stefan Monnier via Users list for the GNU Emacs text editor" <help-gnu-emacs@gnu.org>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Extending emacs convention for first line
>
> Christopher Dimech [2022-10-20 22:11:02] wrote:
> >> PS: for some packages, the `Commentary:` can be too long for some uses,
> >> e.g. release announcements for GNU ELPA packages don't include the
> >> commentary.  So maybe we could introduce a new convention for a "short
> >> multi-line description" (something like 4-5 lines, we could call it
> >> "Summary" or "Abstract", maybe), in addition to the short single-line
> >> description.  It could be used in release announcements, or appear in
> >> https://elpa.gnu.org/packages/ when you hover over a package description
> >> (or appear when you click something to "unfold" the description,
> >> maybe?).
> >
> > I do not see it would be necessary.  What can be done is take first paragraph
> > in the commentary.  And leave the single line brief intact.
>
> IOW, you're suggesting to introduce the convention that the first
> paragraph be considered as the "summary/abstract".  I like that, tho
> I haven't checked to see if it would work well in practice.
>
>
>         Stefan

Correct.  Even then, you can consider showing the first
N lines of the first paragraph, and if there are more lines
in first paragraph, add "..." at the end of Nth line.