Hello,
I'm not sure who this stephen fellow is (he's not listed in the wiki [list of aliases][alias]), but he just committed an absolute monster of a bundle to the subversion repository, in the form of a "C Library" bundle consisting of 1299 snippets, each of which takes the name of a function as a tab trigger, and then fills in a skeleton body for that library function. I have a few notes about this.
[alias]: http://macromates.com/wiki/Main/Aliases
1. This doesn't really follow Allan's recently posted [style guide][sg] for bundles, which clearly explains how bundles should be constructed. Though, to be sure, that style guide needs to be a lot clearer about what *not* to do. Of note: this bundle falls in the "what not to do" category.
2. There are a few recently added code completion commands which work much better, don't require the user to remember the whole function name, only require one menu item, instead of 1299, don't clog up menus (in fact they can just be added to the language bundle instead of requiring a specialized bundle just for snippets), and are pretty much better in every way.
3. Note: Snippets ARE NOT DESIGNED for GENERIC CODE COMPLETION. This is not their purpose, and if you do want to use them this way, you should keep such monstrosities in your personal bundles, and not pollute the subversion repository with them. If you absolutely positively must distribute such things, please do it on your own server.
4. Yes, there are similar things in existing bundles, which should be excised. This includes the OCamlCodeCompletion bundle, and the recently added ColdFusion bundle. Hopefully something will be done about these soon.
5. I hope it becomes slightly easier to make generic completion commands in the future, because at the moment, I'm not sure it can be done by a complete newbie, and it's a useful enough feature that it would be nice to give even new users such power. Allan is hopefully considering such things for TextMate 2.0.
6. I'm going to remove this new bundle tomorrow if there isn't a very compelling reason not to. If anyone wants to pitch in a code completion bundle which does the same thing, only better, I'm sure the C coders who use TextMate would be overjoyed. Hopefully it could be made in a general enough fashion to read in arbitrary new header files (like the ones included in the current «foo».c file, that is), and complete on those functions, as well as functions in the usual C libraries (all the stuff like malloc and printf etc. etc.)
Okay, I think that's all. Hope that didn't come off too strongly. I don't mean to discourage contributions, but please ask around a bit before checking in bundles with ~1300 items.
Thanks, Jacob Rus
Jacob Rus wrote:
- This doesn't really follow Allan's recently posted [style guide][sg]
for bundles, which clearly explains how bundles should be constructed. Though, to be sure, that style guide needs to be a lot clearer about what *not* to do. Of note: this bundle falls in the "what not to do" category.
And, silly me, I forgot the link. Whoops.
Jacob Rus schrieb:
- I hope it becomes slightly easier to make generic completion
commands in the future, because at the moment, I'm not sure it can be done by a complete newbie, and it's a useful enough feature that it would be nice to give even new users such power. Allan is hopefully considering such things for TextMate 2.0.
Bit of the wrong topic... Having function completion like SubEthaEdit or Xcode ( even better would be if the completion also inserts the paramters a function takes) is TOP1 on my Wishlist for TM2. I always have to look this up in the docs :) see http://schlabber-dog.com/ext/function_completion.jpg
On Wed, 6 Dec 2006, Jacob Rus wrote:
- I'm going to remove this new bundle tomorrow if there isn't a very
compelling reason not to.
And the compelling reason to remove it is what, exactly?
* In the current state of the world, it's really not that large of a file, plus once it's pulled in via svn, that's it... it's been downloaded. And unless significant changes are made to it, any updates are going to be barely noticable (especially in comparison to the bundles like Latex and Subversion which seem to get modified constantly).
* It doesn't seem to affect startup time on my machine whether it's been filtered out or not.
* It doesn't appear to conflict with any other bundles, though I haven't looked at this too closely.
So... what's the problem again?
William D. Neumann
---
"There's just so many extra children, we could just feed the children to these tigers. We don't need them, we're not doing anything with them.
Tigers are noble and sleek; children are loud and messy."
-- Neko Case
Life is unfair. Kill yourself or get over it. -- Black Box Recorder
William D. Neumann wrote:
On Wed, 6 Dec 2006, Jacob Rus wrote:
- I'm going to remove this new bundle tomorrow if there isn't a very
compelling reason not to.
And the compelling reason to remove it is what, exactly?
Three reasons:
1. It serves very little useful need. A user needs to type the full name of the function in order to use it, and so it saves exactly 1 typed character per parameter (you hit ⇥ instead of '(' after typing function name, and then hit ⇥ again instead of ', '). It is like using a hammer to sand wood smooth; yes, it may be possible in some cases, and yes it may not permanently harm the hammer (other than emotionally), but that no reason to do it.
2. The things which are in the subversion repository represent the consensus of the TextMate community. When something gets in there, it says that it is fit for use, and it is reasonable to expect new bundle developers to emulate existing bundles. The more of these types of bundles get into the repository, the more users will be justified in saying "if his can go in, why not mine", etc.
3. It is not impossibly difficult to make a completion command which is vastly more useful, can be pushed into the existing C bundle (meaning I don't need to go to my list and filter something else out), works the way users coming from other editors would expect it to, is more flexible (i.e. can be adapted for unanticipated libraries), and is just in every respect better.
4. I'll toss in a fourth reason: it's inelegant. Its very existence bothers the soul of this TextMate user.
"It does no harm" is not a compelling reason to include extra confusion and mental overhead.
- In the current state of the world, it's really not that large of a
file, plus once it's pulled in via svn, that's it... it's been downloaded. And unless significant changes are made to it, any updates are going to be barely noticable (especially in comparison to the bundles like Latex and Subversion which seem to get modified constantly).
- It doesn't seem to affect startup time on my machine whether it's been
filtered out or not.
- It doesn't appear to conflict with any other bundles, though I haven't
looked at this too closely.
I don't care about any of these reasons.
Mainly, it should have never been added. There was no discussion before it went in, and I would imagine that within 3-4 days, a better solution will exist, as there are plenty of enterprising users on this list who could make such a thing happen.
-Jacob
On Wed, 6 Dec 2006, Jacob Rus wrote:
Three reasons:
- It serves very little useful need.
The need it serves seems more to be providing useful documentation regarding the types and purpose of the parameters than to save on typing. Which, according to section 7.1 of the textmate help is a valid reason for using a snippet.
- The things which are in the subversion repository represent the consensus
of the TextMate community.
Really? Since when? I don't remember getting any ballots to help judge the consensus. And as far as I can tell, yours is the only complaint so far against the C Library bundle. Do your wishes now equal community consensus?
- It is not impossibly difficult to make a completion command which is
vastly more useful, can be pushed into the existing C bundle (meaning I don't need to go to my list and filter something else out), works the way users coming from other editors would expect it to, is more flexible (i.e. can be adapted for unanticipated libraries), and is just in every respect better.
"It doesn't work as well as it could" <> "compelling reason to delete". I think most folk here would agree that the current syntax definition system isn't working as well as it could. Should we just go ahead and scrap all bundles that contain a syntax definition?
- I'll toss in a fourth reason: it's inelegant. Its very existence bothers
the soul of this TextMate user.
Which is about as compelling a reason for deletion as "I don't personally use language X," if that's the case, I can give you a huge list of bundles that I'd appreciate if you could delete as well.
I don't care about any of these reasons.
So? Pretty much the only discussions I see before new bundles appear are along the lines of:
A: Hey, is there a bundle for X? B: Nope. Why don't you whip one up and add it to the repository?
Mainly, it should have never been added. There was no discussion before it went in, and I would imagine that within 3-4 days, a better solution will exist, as there are plenty of enterprising users on this list who could make such a thing happen.
So why not leave it in until those better solutions appear?
William D. Neumann
---
"There's just so many extra children, we could just feed the children to these tigers. We don't need them, we're not doing anything with them.
Tigers are noble and sleek; children are loud and messy."
-- Neko Case
Life is unfair. Kill yourself or get over it. -- Black Box Recorder
Personally, I'm against this bundle being in the official repo too. I have about 7 bundles that I actively maintain that aren't part of the official repo. I have never added them because I don't want to be banned from the repo ;) I'm not sure what SOP is with the repo, but I have never added anything before asking a few people, usually Allan at least.
I think this bundle is potentially extremely useful and a wonderful addition to someone's bundle collection. But, I think it should be hosted somewhere else.
I want to encourage people to contribute this stuff. But we have to work together to make sure we keep the official repo lean and tidy.
Eventually, I see the official repo being culled even further. Once we have a good place to host all the non-core bundles, we should move them all out of the official repo and make the official repo only the stuff that is included in the application when you download it.
Now, about this bundle in particular.
It's obvious that a lot of time and energy was spent making this bundle. It obvious to all of us that this bundle is extremely useful to some people. But, better solutions are on their way.
Let's remove this bundle from the official repo and host it somewhere else. I suggest just zipping the thing up and hosting it somewhere.
If whoever developed the bundle doesn't have a host they can use, I'd be happy to host it for them.
Hopefully we will have a BundleForge or something to host all of our non-core bundles.
I see it like the Rails stuff. Only so much stuff goes into Rails core, everything else is a plugin and is hosted somewhere else.
On Dec 6, 2006, at 8:15 PM, William D. Neumann wrote:
On Wed, 6 Dec 2006, Jacob Rus wrote:
Three reasons:
- It serves very little useful need.
The need it serves seems more to be providing useful documentation regarding the types and purpose of the parameters than to save on typing. Which, according to section 7.1 of the textmate help is a valid reason for using a snippet.
perhaps for using *a* snippet, not *1299* snippets.
The "documentation" part can be served much more simply with a flat text file with 4-5 lines for each command, so that a quick lookup in that file can tell you a lot more and more detailed information about the function in question. It could even be accompanied with a link to more online documentation perhaps.
This is the job for the various ctrl-H documentation commands, not for 5.3MB worth of snippets. (by comparison, all the repository is 48MB).
- The things which are in the subversion repository represent the
consensus of the TextMate community.
Really? Since when? I don't remember getting any ballots to help judge the consensus. And as far as I can tell, yours is the only complaint so far against the C Library bundle. Do your wishes now equal community consensus?
Sure you have gotten ballots, you can review commands and voice your opinion. Theoretically you can even go right in there in the bundles and change things, you have commit access IIRC (though of course you should avoid messing with bundles you are not the maintainer of, unless you really really know what you are doing). A lot of such discussion takes place in the channel all the time. In this particular case, there are a number of main maintainers against this bundle, including myself, Jacob Rus (jacobolous), Kevin Ballard (Eridius) and Michael Sheets (Infininight).
There is a fair amount of thought being given before something is added to the repository, and we try to keep things in a similar form.
We appreciate the effort that went into this bundle, but we think there are better and simpler ways to implement equivalent functionality. We do encourage contributions to the repository, but ideally with some discussion first. We do try to keep the bundles at a high standard.
- It is not impossibly difficult to make a completion command
which is vastly more useful, can be pushed into the existing C bundle (meaning I don't need to go to my list and filter something else out), works the way users coming from other editors would expect it to, is more flexible (i.e. can be adapted for unanticipated libraries), and is just in every respect better.
"It doesn't work as well as it could" <> "compelling reason to delete". I think most folk here would agree that the current syntax definition system isn't working as well as it could. Should we just go ahead and scrap all bundles that contain a syntax definition?
It doesn't work at all I would say, but creating a command with similar functionality is trivial. We can create even better functionality with a single command that reads the current word, and then uses a dictionary read from a property list to match this word among the keys, and insert the appropriate text based on the value for the key. The advantage would be further that we could have the command even partially match keys, so that typing say "conv" will provide a popup of all the conversion commands. The popup could perhaps even use a possible command "description" to offer more details to the user.
This command can be done in about 10 lines of Ruby, and the corresponding dictionary file can be in a format that allows the user to add their own commands to this list. This has already been done in the LaTeX bundle, with the two "Insert ... Based on Current Word" commands, which use the configuration file that the user can edit to their heart's content via the "Edit Configuration File" command. It's simple to do, all the commands are defined in the same file and adding 20 new snippets amounts to simply adding 20 lines to this one file.
We could even, with a couple more lines of code, simulate this daedalus of nested menus via a series of tm_dialog screens.
I'll stop here for now.
William D. Neumann
Haris
On Wed, 6 Dec 2006, Charilaos Skiadas wrote:
This command can be done in about 10 lines of Ruby, and the corresponding dictionary file can be in a format that allows the user to add their own commands to this list.
I can't seem to find a way to make this sound not snarky, so I'd like to add the explicit note that I say this with much sincerity and respect:
If it's so trivial a program, why didn't you just write those 10 lines of Ruby instead of the 36 lines of response to my email? Problem solved (or on it's way to being solved), delete the monster, everyone cheers and has a drink.
William D. Neumann
---
"There's just so many extra children, we could just feed the children to these tigers. We don't need them, we're not doing anything with them.
Tigers are noble and sleek; children are loud and messy."
-- Neko Case
Life is unfair. Kill yourself or get over it. -- Black Box Recorder
On Dec 7, 2006, at 11:16 AM, William D. Neumann wrote:
If it's so trivial a program, why didn't you just write those 10 lines of Ruby instead of the 36 lines of response to my email?
Because as I already said, I have already written these 10 lines of Ruby, and the code is in the LaTeX bundle. I have no interest whatsoever in C, so this would be better done by the original bundle poster, or someone else with some use for it. Responding to this email however, and discussing the presence of this bundle as it stands, is of interest to me. And it would take a bit longer to write than the 36 lines of the response, it is still 10 lines of code, that need testing etc.
Anyway, it's no skin off my nose if the bundle gets deleted or not. I've probably written 100 lines of C in the entire year. But what I do have a problem with is the seemingly single-handed decision (well, now I guess it's triple handed or so)
This is the opinion of at least five of the top 10 committers to the repository, I wouldn't call it exactly "single-handed". and so far we have only heard one opinion against removing it. I would say the majority of the committers who have expressed an opinion on the matter is in favor of removing the bundle in its present form, and as you can see from the other thread an effort for something better and greater has already started.
to delete someone else's bundle without a compelling reason. If that's what Alan wants that's fine -- it's his playground and his ball. But it doesn't sit right when it's the intramural squad that wants to take down the nets.
Since Allan is on vacation at the moment, we'll have to wait a couple of weeks to find out what his views are. But I can tell you that he is very much against large menus and menus with more than two levels deep. This is one of the reasons the LaTeX bundle doesn't have 1500 snippets for all sorts of text, Allan wouldn't even hear of cluttering the bundle in that way.
William D. Neumann
Haris
On Thu, 7 Dec 2006, Charilaos Skiadas wrote:
Because as I already said, I have already written these 10 lines of Ruby, and the code is in the LaTeX bundle.
Which has its disadvantages over the snippet solution as well as its advantages. Let's say you want to insert one a union symbol, but you can't remember the latex name for the symbol... What's easier, going into menus that take you along, say, math symbols -> set symbols -> Union (bigcup), or selecting Edit configuration file, looking for the symbol section, then reading through them until you find what looks right?
Not to mention that, frankly it can be pretty damn unintuitive. Say you type in "cong" and you realize you forgot the preceeding . So you hit Cmd-\ and get back "complement" ??? Really?
OK, so that might not happen too often. Say you want to insert a diamond, so you type "dia" then Cmd-\ and you get "dia" What? Is this thing broken? No... you need to start with "di" then hit Cmd-\ three times... of course! God help you if you want bigcirc... nothing like 14 keypresses (12 with a modifier) for an 8 character symbol.
Basically what I'm saying is that it's not so trivial... Sure, a somewhat less functional, yet more elegont version of the Monster bundle is trivial to whip up (one could likely even whip up a script to convert the snippets to an equivalent config file pretty quickly), but you are loosing the organization that goes with the bundle menus unless you're willing to use a more complex command.
This is the opinion of at least five of the top 10 committers to the repository, I wouldn't call it exactly "single-handed".
OK, five-handed. And that's out of how many people pulling from the repository ond/or reading this mailing list?
Meh. Whatever, pull it if you must. Just don't be surprised if people start messing with other bundles if they can get buy-in from a couple of others...
William D. Neumann
---
"There's just so many extra children, we could just feed the children to these tigers. We don't need them, we're not doing anything with them.
Tigers are noble and sleek; children are loud and messy."
-- Neko Case
Life is unfair. Kill yourself or get over it. -- Black Box Recorder
On Dec 7, 2006, at 2:24 PM, William D. Neumann wrote:
OK, five-handed. And that's out of how many people pulling from the repository ond/or reading this mailing list?
I'm not a committer or a serious bundle author, but I can say that based on my experiences with existing bundles and the description of this one, it doesn't sit right with me.
As for the 1 or 3 or 5 people who have spoken up, I don't think they're "casting votes" based on their power. I think they're making a statement of fact based on their knowledge and experience that this isn't appropriate. If that's the case, then it doesn't matter if 0 people commented on it. It's not appropriate and should be removed.
--- Rob McBroom http://www.skurfer.com/ I didn't "switch" to Apple... my OS did.
On Dec 7, 2006, at 2:24 PM, William D. Neumann wrote:
Which has its disadvantages over the snippet solution as well as its advantages. Let's say you want to insert one a union symbol, but you can't remember the latex name for the symbol... What's easier, going into menus that take you along, say, math symbols -> set symbols -> Union (bigcup), or selecting Edit configuration file, looking for the symbol section, then reading through them until you find what looks right?
Actually I was not referring to the cmd-\ command, the one for generating symbols. This is indeed very counterintuitive atm, and should be done better. I am not using it myself at all, which is one of the reasons it is in the state it is. But now you reminded me of it, which means it will get better soon.
The cmd-\ stuff is actually supposed to follow a certain logic, that unfortunately did not made it to the help file, because I had completely forgotten the command even existed. The logic is: one letter + cmd-\ ---> command for a Greek letter two letters + cmd-\ ---> cycle among the various symbol commands starting with those letters, with a few marked exceptions, namely BT, BH, BQ, BZ etc generate \mathbb{...} three letters + cmd-\ ---> cycle through appropriate arrow commands, like "dar" is for down arrows, "har" is for harpoons etc.
This should definitely be made more clear in the documentation. And this is absolutely not the command I was referring to as an example of what to do.
I was in fact referring to the "Insert Environment Based On Current Word" and "Insert Command Based On Current Word" commands, which are much closer to a code completion thing. Completing a single word does not qualify as code completion in my book, we can do that with the standard word completion mechanism in existence just fine (try for instance to type "\dia" followed by pressing esc, or "\big" followed by esc. Much better than the cmd-\ stuff in many ways.)
But my point was simply that there are exactly two reasons that I can think of for the presence of the bundle. The one is locating a command without knowing its name, and for that a single "smart topic search" command, with an appropriate accompanying file, is much better. The other is code completion, and for that a single 10 line (20 if you want smart behavior) script with an accompanying data file is also much better. This bundle is the wrong tool for the job.
Haris
On Dec 6, 2006, at 8:15 PM, William D. Neumann wrote:
On Wed, 6 Dec 2006, Jacob Rus wrote:
Three reasons:
- It serves very little useful need.
The need it serves seems more to be providing useful documentation regarding the types and purpose of the parameters than to save on typing. Which, according to section 7.1 of the textmate help is a valid reason for using a snippet.
Man pages already exist to document this stuff. Having more documentation of the same stuff isn't any better.
- The things which are in the subversion repository represent the
consensus of the TextMate community.
Really? Since when? I don't remember getting any ballots to help judge the consensus. And as far as I can tell, yours is the only complaint so far against the C Library bundle. Do your wishes now equal community consensus?
There's been discussion all day on the IRC channel about your bundle. It's not just Jacob that doesn't like this.
- It is not impossibly difficult to make a completion command
which is vastly more useful, can be pushed into the existing C bundle (meaning I don't need to go to my list and filter something else out), works the way users coming from other editors would expect it to, is more flexible (i.e. can be adapted for unanticipated libraries), and is just in every respect better.
"It doesn't work as well as it could" <> "compelling reason to delete". I think most folk here would agree that the current syntax definition system isn't working as well as it could. Should we just go ahead and scrap all bundles that contain a syntax definition?
That's a ridiculous exaggeration.
- I'll toss in a fourth reason: it's inelegant. Its very
existence bothers the soul of this TextMate user.
Which is about as compelling a reason for deletion as "I don't personally use language X," if that's the case, I can give you a huge list of bundles that I'd appreciate if you could delete as well.
It bothers the soul of this TextMate user as well. There's a big difference between saying "I don't use that" and saying "the mere fact that it exists bothers me".
I don't care about any of these reasons.
So? Pretty much the only discussions I see before new bundles appear are along the lines of:
A: Hey, is there a bundle for X? B: Nope. Why don't you whip one up and add it to the repository?
That's because most bundles aren't comprised of 1300 snippets. Usually this sort of talk is about creating a bundles for a new language, which in the general case there's no need for discussion about.
Mainly, it should have never been added. There was no discussion before it went in, and I would imagine that within 3-4 days, a better solution will exist, as there are plenty of enterprising users on this list who could make such a thing happen.
So why not leave it in until those better solutions appear?
Because it causes problems. Your bundle is 5.3MB in size (not counting the .svn metadata). This is a pretty big chunk of stuff to download for everybody doing a simple `svn update`. For comparison, the entire repository (minus your bundle) is only 43MB (again, not counting the .svn metadata). I for one have been putting off updating my checkout until your bundle has been removed.
If you want an uncommon but reasonable example of how your bundle might cause problems, think of user Joe Shmoe who has a repository checkout and is on dialup most of the day. Sure, the checkout itself is large, but he got it by letting svn work overnight (or perhaps he was at his friend's house with DSL). But he updates his checkout regularly over dialup, since the vast majority of updates are small in size, and doing it regularly means each individual checkout doesn't take long. Now he tries to update after your commit, and, oops, that's a few hours wasted while svn updates. And he doesn't want to cancel it because that would just mean he has to do it later.
On Wed, 6 Dec 2006, Kevin Ballard wrote:
Man pages already exist to document this stuff. Having more documentation of the same stuff isn't any better.
It's documentation available quickly and easily inbthe same app that the person is doing the coding in with no exrtaneous clutter. That's better in my book.
There's been discussion all day on the IRC channel about your bundle. It's not just Jacob that doesn't like this.
A) It's not my bundle. You may have noticed that "stephen" <> "william". B) What percentage of the TextMate users are on the irc channel? I've never gone on it and I see no reason to. There had been (prior to your email) no other complaints about this bundle on either of the mailing lists and now we're up to what... three? Yowza! Burn it to the ground.
"It doesn't work as well as it could" <> "compelling reason to delete". I think most folk here would agree that the current syntax definition system isn't working as well as it could. Should we just go ahead and scrap all bundles that contain a syntax definition?
That's a ridiculous exaggeration.
How is it ridiculous? Oh! I know! It's ridiculous in the same sense as Jacob's original assertion... Imagine that... someone using exaggeration to highlight exaggeration.
It bothers the soul of this TextMate user as well. There's a big difference between saying "I don't use that" and saying "the mere fact that it exists bothers me".
Not much.
But hey, languages like C, Perl, and Python offend my sensibilities and preferences -- and all the GTD stuff, it bugs me to the core. But somehow I've managed to refrain from calling for the removal of those bundles. Perhaps I should just give a day's warning and then delete them?
If you want an uncommon but reasonable example of how your bundle might cause problems, think of user Joe Shmoe who has a repository checkout and is on dialup most of the day. Sure, the checkout itself is large, but he got it by letting svn work overnight (or perhaps he was at his friend's house with DSL). But he updates his checkout regularly over dialup, since the vast majority of updates are small in size, and doing it regularly means each individual checkout doesn't take long. Now he tries to update after your commit, and, oops, that's a few hours wasted while svn updates. And he doesn't want to cancel it because that would just mean he has to do it later.
Of course, his life would have been made much easier if the bundle distribution system were set up differently in the first place. A quick look at my filter bundles list shows 97 bundles that I have turned off, and 40 turned on. And those 40 are essentially bundles that I may at some point in the next year have a greater than 1% chance to actually use. If I wanted to limit it to bundles that I have a 5% chance of using in the next week, I could pare it down to 15. If I bump that up to 50%, then it's down to 5 (probably 4) -- and I suspect other people have similar useage patterns. Yet here we are, having to manage this diverse suite of bundles anyway... how many of those 40-whatever MB of data could have never been downloaded for anyone? Of course that's neither here nor there, I suppose.
Anyway, it's no skin off my nose if the bundle gets deleted or not. I've probably written 100 lines of C in the entire year. But what I do have a problem with is the seemingly single-handed decision (well, now I guess it's triple handed or so) to delete someone else's bundle without a compelling reason. If that's what Alan wants that's fine -- it's his playground and his ball. But it doesn't sit right when it's the intramural squad that wants to take down the nets.
William D. Neumann
---
"There's just so many extra children, we could just feed the children to these tigers. We don't need them, we're not doing anything with them.
Tigers are noble and sleek; children are loud and messy."
-- Neko Case
Life is unfair. Kill yourself or get over it. -- Black Box Recorder
On 7 Dec 2006, at 16:06, William D. Neumann wrote:
Man pages already exist to document this stuff. Having more documentation of the same stuff isn't any better.
It's documentation available quickly and easily inbthe same app that the person is doing the coding in with no exrtaneous clutter. That's better in my book.
It is good to get documentation within your editor. There were two issues I think. One is the conflation of autocompletion and accessing documentation. Since Thomas Aylott is addressing autocompletion, let me make a remark about documentation. I don't think that it is useful to have documentation inserted into the document that you are working on. Far better to have a command that will open the documentation in a separate window. It is easy to pipe man pages into an html window (and you can take advantage of the built in CSS to boot). So I must agree that it would be better if the documentation for the C library followed the model provided by control-H in other bundles.
All the best, Mark
On Dec 7, 2006, at 1:16 PM, Mark Eli Kalderon wrote:
It is good to get documentation within your editor. There were two issues I think. One is the conflation of autocompletion and accessing documentation. Since Thomas Aylott is addressing autocompletion, let me make a remark about documentation. I don't think that it is useful to have documentation inserted into the document that you are working on. Far better to have a command that will open the documentation in a separate window. It is easy to pipe man pages into an html window (and you can take advantage of the built in CSS to boot). So I must agree that it would be better if the documentation for the C library followed the model provided by control-H in other bundles.
This already exists. Make sure the "Shell Script" bundle is not filtered out (the relevant command is there, that's why it needs to be not filtered out. It can however not be the current language, C would do just fine as well). Then ctrl-H offers man pages documentation for the current word, and this includes all the C Library commands I believe. And all without ever having to leave TM!
For instance try "utime + ctrl-H"
All the best, Mark
Haris
On Thu, 7 Dec 2006, Mark Eli Kalderon wrote:
It is good to get documentation within your editor. There were two issues I think. One is the conflation of autocompletion and accessing documentation. Since Thomas Aylott is addressing autocompletion, let me make a remark about documentation. I don't think that it is useful to have documentation inserted into the document that you are working on. Far better to have a command that will open the documentation in a separate window. It is easy to pipe man pages into an html window (and you can take advantage of the built in CSS to boot). So I must agree that it would be better if the documentation for the C library followed the model provided by control-H in other bundles.
That's not what I'm talking about when I say documentation. Say you need to use function F, and you know that it takes parameters X Y and Z, but you can't remember which order they're in. And also, you think there might be a W in there as well, but that could just be in function G.
Now what's easier, F*tab* (up pops "F (Z, X, Y)" and you've gotten all you need to know) or some command that opens up a new window with a man page in it that hopefully has the information you want clearly visible, where you then have to get the info from the aux window into your code and or hide the aux window so you can get back to coding? Is this bundle the best way to do things? Not really, but it's certainly better than the half-assed method of piping a man page to a new window.
And of course what if you're using some language where the documentation isn't available as easily? Perhaps it's in a PDF file -- sure, you could open it in Preview or some other similar app and leaf through it or search in it for what you want, but that still pulls you out of the editing environment.
William D. Neumann
---
"There's just so many extra children, we could just feed the children to these tigers. We don't need them, we're not doing anything with them.
Tigers are noble and sleek; children are loud and messy."
-- Neko Case
Life is unfair. Kill yourself or get over it. -- Black Box Recorder
William et al,
I am a casual observer, and would not know how to build a bundle to save my life, so my opinion could be meaningless.
I don't think it is a redherring to delve into what kind of reference is helpful. If I were a C developer I could definitely see the value of a bundle such as you have done. However, for whatever reason, TM does not have the ability to do what you envision in an elegant way.
Having a bundle that is 2+ mb ddoes not mean that it is not a useful bundle. Rather, because it is really "pushing the envelope" of tm's capabilities, it should be seen as prototype/alpha. I think the operating assumption is that the macromates svn is for more "mature" (in a technical sense), bundles.
Just my $.02
On 12/7/06, William D. Neumann wneumann@cs.unm.edu wrote:
On Thu, 7 Dec 2006, Mark Eli Kalderon wrote:
It is good to get documentation within your editor. There were two issues I think. One is the conflation of autocompletion and accessing documentation. Since Thomas Aylott is addressing autocompletion, let me make a remark about documentation. I don't think that it is useful to have documentation inserted into the document that you are working on. Far better to have a command that will open the documentation in a separate window. It is easy to pipe man pages into an html window (and you can take advantage of the built in CSS to boot). So I must agree that it would be better if the documentation for the C library followed the model provided by control-H in other bundles.
That's not what I'm talking about when I say documentation. Say you need to use function F, and you know that it takes parameters X Y and Z, but you can't remember which order they're in. And also, you think there might be a W in there as well, but that could just be in function G.
Now what's easier, F*tab* (up pops "F (Z, X, Y)" and you've gotten all you need to know) or some command that opens up a new window with a man page in it that hopefully has the information you want clearly visible, where you then have to get the info from the aux window into your code and or hide the aux window so you can get back to coding? Is this bundle the best way to do things? Not really, but it's certainly better than the half-assed method of piping a man page to a new window.
And of course what if you're using some language where the documentation isn't available as easily? Perhaps it's in a PDF file -- sure, you could open it in Preview or some other similar app and leaf through it or search in it for what you want, but that still pulls you out of the editing environment.
William D. Neumann
"There's just so many extra children, we could just feed the children to these tigers. We don't need them, we're not doing anything with them.
Tigers are noble and sleek; children are loud and messy."
-- Neko CaseLife is unfair. Kill yourself or get over it. -- Black Box Recorder
For new threads USE THIS: textmate@lists.macromates.com (threading gets destroyed and the universe will collapse if you don't) http://lists.macromates.com/mailman/listinfo/textmate
On 12/7/06, William D. Neumann wneumann@cs.unm.edu wrote:
So? Pretty much the only discussions I see before new bundles appear are along the lines of:
A: Hey, is there a bundle for X? B: Nope. Why don't you whip one up and add it to the repository?
Not true. There is quite a lot of discussion here and on the SVN list about new bundles. Another factor is that Allan request changes or revert what he think doesn't fit well. He often removes one or two commands (compared to 1299!) he thinks are not necessary for common usage. I can't speak for him but I'm pretty sure Allan would have remove the bundle even faster.
So why not leave it in until those better solutions appear?
Why don't you host it? A lot of bundles are not in the TM repository at first and are included later eventually, as there is a controversy, it seems a good path to follow.
Seriously William, 1299 snippets! Get real. I agree with jacob that it would be a bad precedent.
Just my 0.2 EUR
On Dec 6, 2006, at 5:52 PM, William D. Neumann wrote:
On Wed, 6 Dec 2006, Jacob Rus wrote:
- I'm going to remove this new bundle tomorrow if there isn't a
very compelling reason not to.
So... what's the problem again?
William D. Neumann
I haven't looked at that bundle specifically, but if it's just code completion snippets… there should be better ways to do code completion than having a snippet file for all 100 brazillion functions and everything.
I totally agree that there is a need for code completion, but snippet files are the wrong way round imho.
Hence my multiple attempts to instigate a standard way of doing codecompletion with tm_dialog--menu
thomas Aylott — design42 — subtleGradient — CrazyEgg
-
Charilaos Skiadas -
David Clark -
Fred B -
Jacob Rus -
Kevin Ballard -
Mark Eli Kalderon -
Max -
Rob McBroom -
thomas Aylott -
William D. Neumann