[gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Michał Górny]

Change the unset value tag to '@DEFAULT-UNSET' to ensure consistent use
of hyphen/underscore throughout eclassdoc. Before, one tag
(@ECLASS-VARIABLE) has used hyphen while also one (@DEFAULT_UNSET) used
underscore. Unify them to use the former since @ECLASS-VARIABLE tag is
more common (and hyphens do not require holding shift).

Fixing all existing uses is perfectly within our power; however, I think
it would be reasonable to delay it and combine with other eclass changes
to avoid unnecessary cache regen. The script still allows the old tag
name for compatibility.
---
 app-portage/eclass-manpages/files/eclass-to-manpage.awk | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
index 0b65162c04ec..8ff9f71a2022 100644
--- a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
+++ b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
@@ -36,7 +36,7 @@
 
 # The format of function-specific variables:
 # @VARIABLE: foo
-# [@DEFAULT_UNSET]
+# [@DEFAULT-UNSET]
 # [@INTERNAL]
 # [@REQUIRED]
 # @DESCRIPTION:
@@ -45,7 +45,7 @@
 
 # The format of eclass variables:
 # @ECLASS-VARIABLE: foo
-# [@DEFAULT_UNSET]
+# [@DEFAULT-UNSET]
 # [@INTERNAL]
 # [@REQUIRED]
 # @DESCRIPTION:
@@ -284,9 +284,12 @@ function _handle_variable() {
 	opts = 1
 	while (opts) {
 		getline
-		if ($2 == "@DEFAULT_UNSET")
+		if ($2 == "@DEFAULT-UNSET")
 			default_unset = 1
-		else if ($2 == "@INTERNAL")
+		else if ($2 == "@DEFAULT_UNSET") {
+			warn(var_name ": use @DEFAULT-UNSET instead of @DEFAULT_UNSET")
+			default_unset = 1
+		} else if ($2 == "@INTERNAL")
 			internal = 1
 		else if ($2 == "@REQUIRED")
 			required = 1
-- 
2.13.0.rc1

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 172 bytes --]

>>>>> On Fri, 28 Apr 2017, Michał Górny wrote:

> (and hyphens do not require holding shift).

So they are awkward to type inside a string that is all-caps?

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 419 bytes --]

On sob, 2017-04-29 at 05:41 +0200, Ulrich Mueller wrote:
> > > > > > On Fri, 28 Apr 2017, Michał Górny wrote:
> > (and hyphens do not require holding shift).
> 
> So they are awkward to type inside a string that is all-caps?
> 

Funny enough, yes. I naturally let shift go when pushing '-' ;-).
Some habit, probably. And I bet some people might actually use caps
lock.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 963 bytes --]

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Davide Pesavento]

On Sat, Apr 29, 2017 at 1:57 AM, Michał Górny <mgorny@gentoo.org> wrote:
> On sob, 2017-04-29 at 05:41 +0200, Ulrich Mueller wrote:
>> > > > > > On Fri, 28 Apr 2017, Michał Górny wrote:
>> > (and hyphens do not require holding shift).
>>
>> So they are awkward to type inside a string that is all-caps?
>>
>
> Funny enough, yes. I naturally let shift go when pushing '-' ;-).
> Some habit, probably. And I bet some people might actually use caps
> lock.

So please remind me why everyone else has to adapt to your habits?

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Michał Górny]

Dnia 29 kwietnia 2017 19:23:49 CEST, Davide Pesavento <pesa@gentoo.org> napisał(a):
>On Sat, Apr 29, 2017 at 1:57 AM, Michał Górny <mgorny@gentoo.org>
>wrote:
>> On sob, 2017-04-29 at 05:41 +0200, Ulrich Mueller wrote:
>>> > > > > > On Fri, 28 Apr 2017, Michał Górny wrote:
>>> > (and hyphens do not require holding shift).
>>>
>>> So they are awkward to type inside a string that is all-caps?
>>>
>>
>> Funny enough, yes. I naturally let shift go when pushing '-' ;-).
>> Some habit, probably. And I bet some people might actually use caps
>> lock.
>
>So please remind me why everyone else has to adapt to your habits?

Because I cared enough to do the work. If you want it the other way around, then send the reverse patch instead of giving asshole comments.

-- 
Best regards,
Michał Górny (by phone)

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Davide Pesavento]

On Sat, Apr 29, 2017 at 1:40 PM, Michał Górny <mgorny@gentoo.org> wrote:
> Dnia 29 kwietnia 2017 19:23:49 CEST, Davide Pesavento <pesa@gentoo.org> napisał(a):
>>On Sat, Apr 29, 2017 at 1:57 AM, Michał Górny <mgorny@gentoo.org>
>>wrote:
>>> On sob, 2017-04-29 at 05:41 +0200, Ulrich Mueller wrote:
>>>> > > > > > On Fri, 28 Apr 2017, Michał Górny wrote:
>>>> > (and hyphens do not require holding shift).
>>>>
>>>> So they are awkward to type inside a string that is all-caps?
>>>>
>>>
>>> Funny enough, yes. I naturally let shift go when pushing '-' ;-).
>>> Some habit, probably. And I bet some people might actually use caps
>>> lock.
>>
>>So please remind me why everyone else has to adapt to your habits?
>
> Because I cared enough to do the work. If you want it the other way around, then send the reverse patch instead of giving asshole comments.
>

Fair enough. FTR, I have no preference either way, this is 100%
bikeshedding if you ask me.

Also, I didn't mean to be rude, just wanted to point out that what you
said about being easier to type might not apply to everybody (in fact,
the opposite is probably true for most people). Another point against
hyphens is that all ebuild variables use underscore. But as I said I'm
fine either way.

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1807 bytes --]

On sob, 2017-04-29 at 14:05 -0400, Davide Pesavento wrote:
> On Sat, Apr 29, 2017 at 1:40 PM, Michał Górny <mgorny@gentoo.org> wrote:
> > Dnia 29 kwietnia 2017 19:23:49 CEST, Davide Pesavento <pesa@gentoo.org> napisał(a):
> > > On Sat, Apr 29, 2017 at 1:57 AM, Michał Górny <mgorny@gentoo.org>
> > > wrote:
> > > > On sob, 2017-04-29 at 05:41 +0200, Ulrich Mueller wrote:
> > > > > > > > > > On Fri, 28 Apr 2017, Michał Górny wrote:
> > > > > > 
> > > > > > (and hyphens do not require holding shift).
> > > > > 
> > > > > So they are awkward to type inside a string that is all-caps?
> > > > > 
> > > > 
> > > > Funny enough, yes. I naturally let shift go when pushing '-' ;-).
> > > > Some habit, probably. And I bet some people might actually use caps
> > > > lock.
> > > 
> > > So please remind me why everyone else has to adapt to your habits?
> > 
> > Because I cared enough to do the work. If you want it the other way around, then send the reverse patch instead of giving asshole comments.
> > 
> 
> Fair enough. FTR, I have no preference either way, this is 100%
> bikeshedding if you ask me.
> 
> Also, I didn't mean to be rude, just wanted to point out that what you
> said about being easier to type might not apply to everybody (in fact,
> the opposite is probably true for most people).

But you were. I get it, you don't have to get it when I try to make
a funny remark. But that's not an excuse to behave like that.

As the commit message said, the only real reason was that hyphen is
around 3.5x more common. Which means changing the other one is 3.5x less
work, and 3.5x smaller problem of changing the habits.

$ grep '@ECLASS-VARIABLE' *.eclass | wc -l
770
$ grep '@DEFAULT_UNSET' *.eclass | wc -l
222

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 963 bytes --]

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Kent Fredric]

[-- Attachment #1: Type: text/plain, Size: 1424 bytes --]

On Fri, 28 Apr 2017 16:39:45 +0200
Michał Górny <mgorny@gentoo.org> wrote:

> Change the unset value tag to '@DEFAULT-UNSET' to ensure consistent
> use of hyphen/underscore throughout eclassdoc. Before, one tag
> (@ECLASS-VARIABLE) has used hyphen while also one (@DEFAULT_UNSET)
> used underscore. Unify them to use the former since @ECLASS-VARIABLE
> tag is more common (and hyphens do not require holding shift).
> 
> Fixing all existing uses is perfectly within our power; however, I
> think it would be reasonable to delay it and combine with other
> eclass changes to avoid unnecessary cache regen. The script still
> allows the old tag name for compatibility.

I have a counter suggestion:

1. Leave @ECLASS-VARIABLE as-is
2. Leave @DEFAULT_UNSET as is
3. Document that underscores are to be used for all new tags
4. Add support for @ECLASS_VARIABLE that works the same as
   @ECLASS-VARIABLE
5. Don't go out of our way to migrate to @ECLASS_VARIABLE, just let it
   occur over time, particularly in conjunction with other major
   changes.

Mostly because @FOO_VARIABLE is suspiciously similar syntax to me as
other ALL CAPS variables used as ENV tokens in Bash.

And I can't think of a single instance where I've seen a language with
a convention that used ALL CAPS terms in conjunctions with hyphens,
( and regex with _ are ultimately simpler to reason about than ones
with - )


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1919 bytes --]

On nie, 2017-04-30 at 06:03 +1200, Kent Fredric wrote:
> On Fri, 28 Apr 2017 16:39:45 +0200
> Michał Górny <mgorny@gentoo.org> wrote:
> 
> > Change the unset value tag to '@DEFAULT-UNSET' to ensure consistent
> > use of hyphen/underscore throughout eclassdoc. Before, one tag
> > (@ECLASS-VARIABLE) has used hyphen while also one (@DEFAULT_UNSET)
> > used underscore. Unify them to use the former since @ECLASS-VARIABLE
> > tag is more common (and hyphens do not require holding shift).
> > 
> > Fixing all existing uses is perfectly within our power; however, I
> > think it would be reasonable to delay it and combine with other
> > eclass changes to avoid unnecessary cache regen. The script still
> > allows the old tag name for compatibility.
> 
> I have a counter suggestion:
> 
> 1. Leave @ECLASS-VARIABLE as-is
> 2. Leave @DEFAULT_UNSET as is
> 3. Document that underscores are to be used for all new tags

Don't forget to write a complete policy on what names for ebuild
variables should developers use. And then a policy on making new
policies regarding vocabulary. And maybe document some on preferred
words to be used in mailing list messages.

> 4. Add support for @ECLASS_VARIABLE that works the same as
>    @ECLASS-VARIABLE
> 5. Don't go out of our way to migrate to @ECLASS_VARIABLE, just let it
>    occur over time, particularly in conjunction with other major
>    changes.
> 
> Mostly because @FOO_VARIABLE is suspiciously similar syntax to me as
> other ALL CAPS variables used as ENV tokens in Bash.
> 
> And I can't think of a single instance where I've seen a language with
> a convention that used ALL CAPS terms in conjunctions with hyphens,
> ( and regex with _ are ultimately simpler to reason about than ones
> with - )

From now on I'm not going to listen to any suggestions that do not come
with a patch.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 963 bytes --]

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 340 bytes --]

>>>>> On Sun, 30 Apr 2017, Michał Górny wrote:

> From now on I'm not going to listen to any suggestions that do not
> come with a patch.

You have posted a patch for review. So IMHO, asking others to do the
work when you receive criticism isn't a reasonable request. All the
more since the suggested changes are trivial.

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Michał Górny]

Dnia 1 maja 2017 09:32:40 CEST, Ulrich Mueller <ulm@gentoo.org> napisał(a):
>>>>>> On Sun, 30 Apr 2017, Michał Górny wrote:
>
>> From now on I'm not going to listen to any suggestions that do not
>> come with a patch.
>
>You have posted a patch for review. So IMHO, asking others to do the
>work when you receive criticism isn't a reasonable request. All the
>more since the suggested changes are trivial.

You are confusing constructive criticism with meaningless style bikeshed which serves no purpose except creating more work on everyone. If you want to force a change, volunteer to do the work.

While at it, I would really appreciate if you fixed the issue causing underscores to be invisible in some applications, e.g. Quassel.

>
>Ulrich


-- 
Best regards,
Michał Górny (by phone)

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: @DEFAULT_UNSET -> @DEFAULT-UNSET

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 641 bytes --]

>>>>> On Mon, 01 May 2017, Michał Górny wrote:

> You are confusing constructive criticism with meaningless style
> bikeshed which serves no purpose except creating more work on
> everyone.

What's creating more work for everybody is changing the name of the
token. All I was saying was that "hyphens do not require holding
shift" doesn't convince me as an argument.

> If you want to force a change, volunteer to do the work.

> While at it, I would really appreciate if you fixed the issue
> causing underscores to be invisible in some applications, e.g.
> Quassel.

How is that related to eclass documentation?

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]