[SVN] More name revising

[Mats Persson]

I think this whole naming thing is highly complex and at moments I  
have been struggling with various aspects of it. So please see this  
as me looking for confirmation or correction of my understandings,  
and slightly thinking aloud and putting out some of my ideas for  
others to contemplate. Apologies for any unintentional stupidities  
below ;)

On 4 May 2005, at 13:47, Allan Odgaard wrote:
> One thing I'd like to fix is the keyword group. This is overloaded,  
> and too many different names at the second level, making it hard to  
> apply general styles to everything but keyword itself, but that  
> touches too much IMHO,

I agree fully.

> so here is my proposal:
> Move keyword.function to its own group and let this contain all  
> functions, methods, classes, types and constants defined by a  
> framework, library or similar, e.g. (examples from Cocoa):
>    support.function -- NSBeep, …
>    support.class    -- NSWindow, NSString, …
>    support.type     -- NSRect, …
>    support.constant -- NSZeroRect, …
> support.function include methods (if we really want to match  
> these?!?).

1.   Why use "support" here ? In my mind this is not obvious nor  
logical. The items you describe are very much core language items,  
and therefore wouldn't something like "lang.function", etc be more  
logical (= easier to understand). If "lang" has some special meaning  
that makes it unsuitable for this, then how about "core." (as in core  
parts of the language/framework) ?

2.    "support.constant". Not being a Cocoa developer, I assume that  
NSZeroRect is a language provided constant like E_ERROR in PHP. ie,  
not defined by the user/coder ? (something I've called  
"variable.constant.predefined" previously)

3.    In JavaScript we have event-handlers as well. So should these  
become "support.event-handler" or "support.other.event-handler" or  
something else ??


> Then restrain ourself to these 3 keyword groups:
>    keyword.storage  -- static, final, abstract, class, function,  
> int, var, …
>    keyword.control  -- continue, while, if, return, break, try, do,  
> end, throw, …
>    keyword.operator -- instanceof, dynamic_cast, and, or, not, …
> Keyword.storage should probably be divided into  
> keyword.storage.type and keyword.storage.modifier.

> Another group which is also currently a little diffuse is constant,  
> I suggest these 3:
>    constant.numeric   -- 42, 1.3f, 0x4AB1U, …
>    constant.character -- <, \e, \031, '"', …
>    constant.language  -- true, false, nil, YES, NO, …

"constant.language" & "support.constant". All these various constants  
have me confused, and I hope I'm not alone in that. (slight  
repetition of point asked above)

4.    In my mind a Constant can be two things. Predefined or User  
defined.  If it's predefined then it's really a key part of the code  
language otherwise it's only a part of the user's code.  Either way  
they are really both the same in the end as they are storage  
containers of data just like variables are.

With that in mind, I see this as more logical:
--    "keyword.constant"  ===  TRUE, FALSE, NULL, nil, etc, etc. 
--    "support.constant" or "lang.constant"  === (predefined language  
constants, like E_ERROR, or NSZeroRect )
--    "variable.constant"  ===  user defined constants like  
MY_CONSTANT_IN_PHP if the language supports them and they can be  
regexp'ed into usable form.


> If something doesn't go into either of these defined groups, I'd  
> suggest we put it in <most-appropriate-group>.other.<suggested- 
> category>. This makes it easier to see what goes outside the normal  
> definitions, and should reduce the number of second-level groups,  
> which helps styling.

Agreed.


> I expect the default themes will style only keyword, support, and  
> constant (i.e. all children of these will be styled identical by  
> default). The same goes for comment, string, variable, invalid,  
> entity.name, and entity.parameter.

OK, quick clarification needed before the main point. TM should  
ideally have three Theme options (Bright, Dark, Grey currently) that  
should be possible to rename by the end user, or else have a generic  
naming convention like (Theme1, Theme2, Theme3).  I think of these as  
Style Switchers/Theme Options, whereas in my comments below I am  
using "theme" to mean 'settings group' as in b7 Theme Editor  
individual files.

I would suggest that we adapt something like this when it comes to  
the themes:

<themeName> (default)  ==  all base groups and their default children  
are defined. ie:  "comment.line", "comment.block"

<themeName>_Minimal  ==  only the base groups are defined. ie:   
"comment", "string", etc.

If any languages has items that falls outside of the basic structure,  
then they are defined in separate <Language> themes, such as

<Language>_Specifics  ==  Ruby_Specifics or PHP_Specifics


This structure would give the end user the best options to choose  
from/work with.
-- If you want minimal highlighting, then you would choose the  
"Minimal" theme.  
-- If you want more detailed highlighting, then you would choose the  
default Theme. 
-- If you want language specific parts highlighted on top of your  
chosen theme, then you would enable the Language theme for the  
language you're working with.

I really think the above is the right and only way forward. There are  
of course some further issues to address in relation to this, but  
that's for another day.


> I intend to update the wiki page after making sure that these  
> suggested groups are not too limiting, or there are better naming  
> suggestions.

The "NamingLanguageElements" wiki page should be the law for all the  
various themes/syntaxes, and nothing should go outside of it's remit.


> Something semi-related, when writing language definition files,  
> formatting the rules like this:
>     {   name = "foo";
>         ...
>     },
> Makes it possible to fold rules and still see the name of them. Try  
> e.g. HTML.plist for an example -- it makes it a bit easier to work  
> with the larger files.

Good point, and will do !


Thanks for the word, and if you read this far, hope I didn't bore  
you ;-)


Kind regards,

Mats

----
"TextMate, coding with an incredible sense of joy and ease"
- www.macromates.com -