New tips/200805

New tips May 2008

For each proposed new tip:

Is it worth keeping as a separate tip?
Should it be merged into an existing tip? Which?
If it should be kept, is it ready for release? Which points need fixing? Should it be renamed?

Please edit this page (not the talk page) in the appropriate section below the following table.
Alternatively, comments can be posted on the mailing list.

Proposed new tip	Link	Current consensus
Beautifying plain text in Vim	discuss	Note 1
Create new subroutines	discuss	Fix then keep
Less.bat : Now less is more on Windows, too	discuss	Note 1
Return to previous indent	discuss	Fix then keep
Twitter	discuss	Note 1
Use eval to create dynamic templates	discuss	Keep
Vim setup to edit MoinMoin wiki files	discuss	Rename and keep
VimBlock - Numblock mode for Vim	discuss	Rename and keep

Note 1 A summary of this tip has been placed on Vim scripts, and the author has been asked to expand the tip to include generic information if it is desired that the tip should be kept, in addition to the summary.

Please add your comment (sign with ~~~~) below the appropriate heading. Use ---- between comments.

Tips linking to external sites

Here are some rambling thoughts on how we should handle tips whose main purpose is to link to an external site (tips that rely on an external site for content). If we get consensus, I might convert this to a guideline.

On the original vim.org tips site, before the Vim Tips wiki, there was no way to update tips: incorrect or inadequate information couldn't be fixed; related tips couldn't be merged; obsolete or unhelpful tips couldn't be deleted. As a result, we still have many defective imported tips (although we have made considerable progress merging, deleting and fixing tips since the import in June 2007).

Most of our editors have accepted the point of view that radical pruning is required to merge helpful material, and to delete unhelpful material. Just the fact that we have a large number of tips (1250) makes finding useful information difficult.

While clean-up continues slowly, we have agreed to carefully consider new tips before they are added. The procedure, and examples of past practice, can be seen on the new tips page. Since the import, we have accepted 58 new tips, deleted 7 proposed new tips, and merged another 10 proposed new tips (that is, 17 tips were not accepted).

General agreement has been reached that it would be best for tips to have substantive content: a tip should be self contained; a reader should find useful information in the tip; a tip should not depend on another site for the main content.

We have rejected at least two tips that did little more than link to an external site. The main problem with such tips is that once a precedent is set, there is no limit to the number of such tips that could be written. There are over 200,000 hits for vim tutorial in Google.

We rejected a tip that consisted of a link to a script on vim.org with the comment:

A tip should do more than link to some interesting feature. There are perhaps 2000 Vim scripts – it would not be helpful to have a tip linking to each.

See the Create a new tip page for guidelines.

The tips proposed for May include:

Beautifying plain text in Vim
Less.bat : Now less is more on Windows, too
Twitter

Each of these raises concern because their main purpose is to link to useful information on another site. If tips have a low quality, or the linked external information is unhelpful, I would quickly recommend their deletion because most readers already have too many links to handy sites.

However, I am not happy to recommend deletion of these proposed tips at the moment. Instead, I am wondering if each could have additional information added so a reader would feel that they had learned something, just from reading the tip.

An alternative may be for us to have a new feature on the Main Page with some kind of Announcements section. The tips above would be good choices for a temporary page (with at least six month's lifetime) that would highlight interesting features available on external sites. See also the brief discussion on my talk page.

--JohnBeckett 05:35, 27 May 2008 (UTC)

Update: Please see the summary of these tips on Vim scripts. --JohnBeckett 05:42, 8 July 2008 (UTC)

How about keeping a categorised list of useful Vim scripts with a one-line summary of each. Then it becomes a no-brainer what to do with such tips: reduce to one line and file in the appropriate category. There's not the dilemma between deleting something useful and needing to expand its content. This could also be a nice alternative to the relatively poor vimscript search function on vim.org, plus it could link to the most recent versions (e.g. when maintainers change so the script can't be updated). Sightless 09:12, 21 July 2008 (UTC)

General comments (not for a specific tip)

Beautifying plain text in Vim

See the tips linking to external sites discussion above.

Keep, but first fix. See my suggestions on the tip. --JohnBeckett 00:44, 2 June 2008 (UTC)

I left a message on the author's talk page asking that they check the summary I have put on Vim scripts, and asking that the tip be expanded with some more generic information, if they want the tip kept in addition to the summary. --JohnBeckett 10:07, 8 July 2008 (UTC)

Brett (the author) left this message on the tip page (JohnBeckett 22:47, 9 July 2008 (UTC)):

This tip can be removed now that the information is on the Vim scripts page. Brett Stahlman 12:49, 9 July 2008 (UTC)

Okay to delete as noted by tip author. --Fritzophrenic 15:06, 14 July 2008 (UTC)

Create new subroutines

Keep, but first fix. Need to clarify that the "__xxx__" stuff is for a Perl program. Fix the script using Fritzophrenic's suggestion in the Comments. --JohnBeckett 00:44, 2 June 2008 (UTC)

Why not. It is not much different from the tips that show how to insert C header-gates. --Luc Hermitte 12:34, 4 June 2008 (UTC)

Incorporate the comments into the tip, explain what the __XXX__ stuff is about and then keep. --BenArmston 21:19, 21 July 2008 (UTC)

Less.bat : Now less is more on Windows, too

See the tips linking to external sites discussion above.

I haven't had any feedback from the author since alerting Ewfalor to my dilemma. If the tip hasn't been greatly generalised before the end of June, I think we should delete it and move the link to an "Announcements" and/or "Information" page, as outlined earlier. --JohnBeckett 00:44, 2 June 2008 (UTC)

Update: Ewfalor has replied on his talk page. Let's see how it develops. --JohnBeckett 11:48, 4 June 2008 (UTC)

Okay to delete, but I think sometime we need a tip about the Vim command line, if one does not exist. Until looking at the batch file for this tip, I had no idea that Vim could take input from the command line with "-"! Not very useful by itself, but as soon as you start piping output into Vim...oh, man. Now, I'm having all sorts of fun with version control "history" or "log" commands, script output, etc.

--Fritzophrenic 15:06, 14 July 2008 (UTC)

Deleting this tip is OK with me too.

I also agree with Fritzophrenic that a tip about the Vim command line would be good. As well as mentioning that Vim can take the file contents from standard input, it should mention that the commands to run can be specified on the command line, (e.g. vim -c "d5|wq" ~/.ssh/known_hosts deletes line 5 from the given file) and that the resulting buffer can be written to a further command (w !<cmd>). I think that this tip along with the batch file would make a good example for this suggested tip.

--BenArmston 12:20, 16 July 2008 (UTC)

OK but I need some specific guidance (there is some conflict between the initial "ok to delete" and the following suggestions): What will we do? Suppose that at the end of July no change has happened to this tip. Our options are:

Keep it as is (with the "proposed" template and no tip number).
Delete it (it can be re-created if someone later feels inspired).
Add a "todo" with the comments above and assign a tip number (and rename to "Command line options" or similar?).

--JohnBeckett 00:17, 17 July 2008 (UTC)

The inclusion on Vim scripts should be sufficient for someone who is looking for this functionality, so I see little point in keeping it as it is. If it isn't changed by the end of July, I suggest option 3.

--BenArmston 12:48, 17 July 2008 (UTC)

The above "3" was meant to be a "2". Sorry for the confusion. BenArmston 21:44, 6 August 2008 (UTC)

I'd actually go for option 2. I think if we are going to rename the tip to a general "command line options" tip, and then create the entire content (the tip itself currently doesn't include any code), we may as well just create a brand new tip, and avoid the pointless redirect from a moved tip that really has very little to do with what would be the final product.

--Fritzophrenic 13:01, 22 July 2008 (UTC)

Some existing command line tips:

Not sure what to do about them...the "read from stdin" option is mentioned briefly in the comments of the first tip, nothing more. I see no mention of the --cmd option anywhere. We also have lots of tips using the --remote series of commands:

Some of these can probably be merged, but I think in may be best to create a category rather than a single tip. A title could be "Using Command-Line Arguments" or just "Command-Line Arguments" under "Usage" might mean the same thing. I have probably missed some command-line related tips, so I think a new category would be the best way to go about collecting them all in one place. In addition to the obvious benefits of having related tips in a category, I have found that if tips are properly categorized, it is much easier to find merge candidates.

--Fritzophrenic 16:30, 24 July 2008 (UTC)

Return to previous indent

Keep. I invited the author Arnar to explain the issue mentioned, and I intend to consider the resulting comments in the tip. We need to do something with those comments. --JohnBeckett 00:44, 2 June 2008 (UTC)

Worth keeping for the comments section alone ;-). It would be good to see an example of "complex (and creative) indentation such as Haskell source files" included in the tip. --BenArmston 21:27, 21 July 2008 (UTC)

Twitter

See the tips linking to external sites discussion above.

This is an understandable position. I agree, that in general it is better if a tip is self-contained, but to follow that as a hard and fast rule all the way then the Vim wiki must also host downloads or reject any tips that require installing external tools. I think that the case for Twit is a different than someone creating an article that does little more than say "Check out the cool info I found on this site here." That clearly doesn't add much. On the other hand, I'm not sure how you would make a formal rule to distinguish the two. It seems like you have to judge on a case-by-case basis and decide which ones are appropriate and add to the Vim Wiki and which ones are noise.

The Twitter tip is not very elaborate to be sure But I think it is philosophically valid for the Vim Wiki. Some tips are valid yet do little more than make you aware of external tools and how they can be used in Vim. And if you are going to describe an external tool then surely you want to provide a link where the tool can be found and downloaded? In the case of the Twitter tip, the external link does little more than bring you to a download page. Otherwise, I'm not sure how you would handle this case within the Vim Wiki.

--Noahspurrier 21:34, 27 May 2008 (UTC)

I want to keep this tip, but IMHO it should first be enhanced. I totally agree that this tip is more than a "check out the cool..." post. Also, the external link leads to a quality site.

However, it would not be helpful to have lots of tips that rely on an external link for their content, so I want to have a reason to keep this tip, while deleting others with less value. Or, perhaps Noah (the author) would be happy if a brief summary and the link were placed on an Announcements/Information page, as outlined earlier.

I suggest that the tip should start with an outline of the fact that Vim can interact with external apps, and how this tip illustrates that. Give a brief outline of what is involved so a reader does not have to download and examine a script to work out the concepts.

The tip needs to say what Twitter is: each tip should start by briefly explaining what it actually does, and why you might want it. We should (IMHO) also aim to have each tip provide some technical content, for example, by outlining the associated concepts and implementation issues. Otherwise, our tips would be just a poor substitute for Google. --JohnBeckett 00:44, 2 June 2008 (UTC)

I think that, if this tip relied on settings within Vim, whether a Vim Script function, option settings, vimrc/autocmd magic, etc., I could see an argument for keeping this tip. However, since the tip entirely relies on an external Python script, and I assume we already have tips or help links about sending the current buffer to an external tool, and we may even have a tip about running embedded Python, I think the note on the scripts page is plenty for this particular tip. It may be very useful, it may be well-developed and professional, but because it is only an external tool, the best place for it is the summary on the Vim scripts page.

--Fritzophrenic 15:06, 14 July 2008 (UTC)

I think that there is a difference between well known standard external tools, such as any that are included in the posix standard (diff, grep, etc..) and arbitary user defined tools.

That pedantry out of the way, the twit tool looks very nice and is certainly useful to any vim user who twits so having it somewhere on the wiki would be good. As for the tip itself, if it could be expanded to include the above suggestions, using the twit script as an example it should be kept.

--BenArmston 12:48, 16 July 2008 (UTC)

Same issue as for "Less.bat": What will we do? The summary at Vim scripts is perfectly adequate. If you enter "twitter" in the search box and click 'Search', you will see the summary listed (at the moment, because this tip exists, if you click 'Go' then you will go straight to this tip). What will we do if no developments have occurred by the end of July?

--JohnBeckett 00:17, 17 July 2008 (UTC)

If no developments have been made by the end of July, I'd suggest removing it. The core idea (using an external tool to accomplish something complex) could be covered in the renamed less.bat page. I think that the python script is good and the idea of sending text to twitter directly from Vim is fantastic, but as the tip stands at the moment it is of little general use. Sorry Noahspurrier.

--BenArmston 12:59, 17 July 2008 (UTC)

Use eval to create dynamic templates

Keep. If we were to merge this info with the other template tips, the result would be too complex. --JohnBeckett 00:44, 2 June 2008 (UTC)

Keep -- even if I don't see the point in yet another template expander plugin, and if I've concluded that this approach doesn't scale very well. I've added a comment next to Fritzophrenic's one in the comments section of the tip.

I don't see how it could be easily merged. The only evolution I can think of consists in making this tip as the first part of a not-exactly-tutorial on how a templates expander plugin is designed and written: e.g. 1- the expander engine, 2- triggering expansion: auto-commands, mappings, commands and menus, 3-fetching the templates-files from a 'rtp'-like directory list, 4- all the little extras (i18n, folding, automated-indentation, placeholders).

--Luc Hermitte 12:21, 4 June 2008 (UTC)

While you're fundamentally correct, I rather like Fritzophrenic's approach of making a small yet working example, with explanations. I prefer to get by with very few plugins, mainly because I have simple requirements, and this kind of tip allows my kind of user to learn something while doing probably all that is needed for simple cases. So if your proposed tutorial were created, I would suggest doing it in yet another tip to avoid making this one overly complex. --JohnBeckett 01:51, 5 June 2008 (UTC)

That being said, I'm sure that many plugins do a more complete job for some purposes. Add your concerns to the tip (in a "limitations" section?), and we can emphasize the "related plugins" section a little more...that should do the trick, no?

For the record, the reason I created this tip in the first place, is that I'm apparently similar to John in my use of Vim...very few plugins, and many little self-made tweaks that do just what I need them to, and nothing more.

--Fritzophrenic 02:48, 5 June 2008 (UTC)

I just noticed the list of plugins in Category:Automated Text Insertion, as well as the existence of Category:Templates. I moved my template tip (and several others) into this category. I would suggest taking all the template plugins and putting them on this category page as well. Then, my tip can just emphasize that you should check the list of tips and scripts in Category:Templates rather than trying to list them all explicitly.

--Fritzophrenic 16:30, 5 June 2008 (UTC)

The Template category is quite "new" -- it was used for vim.wikia templates until a few days ago, IIRC. Several ATI tips need to be moved to this category.

Otherwise, we indeed have a different way of using vim ^^

--Luc Hermitte 16:53, 5 June 2008 (UTC)

Keep. Also, +1 for another tip containing the tutorial suggested by Luc. Whilst waiting for the tutorial, a limitations section in the tip along with links to the versions of mu-template mentioned would help the curious reader to investigate further.--BenArmston 21:44, 21 July 2008 (UTC)

Vim setup to edit MoinMoin wiki files

Keep. Probably merge my comments into the tip, replacing the original script. Needs a little more work on explaining exactly where to put all the relevant bits and pieces (I'm not entirely happy with my personal setup which, while working for me, is not quite "correct"). --JohnBeckett 00:44, 2 June 2008 (UTC)

I have reworded this tip and replaced the original script. It is ready for release, although I think it should be renamed, perhaps to "Edit MoinMoin wiki files with folding". --JohnBeckett 06:07, 28 June 2008 (UTC)

Keep. I think that "Edit MoinMoin wiki files with folding" is a better title than it currently has. I'm not sure of the usefulness of all of the text relating to home folders. Are there really people using Vim who don't know what a home folder is and how to find it?--BenArmston 21:57, 21 July 2008 (UTC)

VimBlock - Numblock mode for Vim

Keep, I suppose, although should rename. I think the general concept is useful and interesting, although I'm not sure why you would want to remap letters to digits. A couple of things should be cleaned up, like that <C-I> is tab, and some explanation of the key that maps to '0'. --JohnBeckett 00:44, 2 June 2008 (UTC)

I don't see the point of this particular example as well. However, I often use a similar technique in scratch buffers. There, several usual keys are locally (<buffer>) hijacked. The technique presented is likely the starting point to implement a feature present in emacs' yasnippet: what the user types is updated in real time in several place(holder)s of the current buffer. BTW, I'd have used inoremap instead of imap. --Luc Hermitte 12:33, 4 June 2008 (UTC)

I've got a lot more enthusiastic about the tip, and have significantly reworded it, including changing imap to inoremap and more. I guess the name "VimBlock" is to indicate a block of keys that have been mapped, but I found that name quite confusing and changed it to "VimLock" (like "NumLock") in the tip, and I think the tip should be renamed to "VimLock mode to enter numbers". --JohnBeckett 11:35, 25 June 2008 (UTC)

A nice idea, though not one I can see myself ever using. I think we should keep it. Changing the name to VimLock sounds good, though I'm not taken on "mode to enter numbers" as it seems to imply that this tip is somehow required to enter numbers.--BenArmston 22:26, 21 July 2008 (UTC)

@@ Line 160: / Line 160: @@
 --[[User:BenArmston|BenArmston]] 12:48, 17 July 2008 (UTC)
+:The above "3" was meant to be a "2". Sorry for the confusion. [[User:BenArmston|BenArmston]] 21:44, 6 August 2008 (UTC)
 ----

Changes: Vim Tips Wiki:New tips/200805

Revision as of 21:44, 6 August 2008

Tips linking to external sites

General comments (not for a specific tip)

Beautifying plain text in Vim

Create new subroutines

Less.bat : Now less is more on Windows, too

Return to previous indent

Twitter

Use eval to create dynamic templates

Vim setup to edit MoinMoin wiki files

VimBlock - Numblock mode for Vim