From: Charles McGarvey Date: Wed, 2 Jan 2013 19:42:45 +0000 (-0700) Subject: add the user manual to readme file as markdown X-Git-Tag: v0.3.4~5 X-Git-Url: https://git.brokenzipper.com/gitweb?a=commitdiff_plain;h=0260938e8ee893954f4b6e142132bad4d0374d60;p=chaz%2Fvimcoder add the user manual to readme file as markdown --- diff --git a/COPYING b/COPYING index d9e6552..5daf74a 100644 --- a/COPYING +++ b/COPYING @@ -1,7 +1,7 @@ The Simplified BSD License -Copyright (c) 2010-2012, Charles McGarvey et al. +Copyright (c) 2010-2013, Charles McGarvey et al. All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/README b/README deleted file mode 100644 index b968544..0000000 --- a/README +++ /dev/null @@ -1,27 +0,0 @@ - -Vim + TopCoder = VimCoder -------------------------- - -The TopCoder Arena editor plug-in providing support for Vim, written by -Charles McGarvey. For detailed instructions, check out the user manual -online at . - - -Quick Installation Instructions: - -- Download the latest version of the VimCoder jar file. -- Run the TopCoder Arena applet. -- Click the "Options" menu and select "Editor" to show the editor - preferences. -- Click the "Add" button to bring up a new window. -- For "Name," type "Vim" or whatever you want to represent this plug-in. -- For "EntryPoint," type "com.dogcows.VimCoder" without the quotes. -- For "ClassPath," click on "Browse" and locate the VimCoder jar file. The - third field should now have the path to the jar file. -- Click "OK" to close the window with the three fields. -- Click "Save." - -You should now be able select "Vim" (or whatever you entered the first -field) as your editor from the pull-down list on any problem statement -window. - diff --git a/README.md b/README.md new file mode 100644 index 0000000..4c9754f --- /dev/null +++ b/README.md @@ -0,0 +1,350 @@ + +Vim + TopCoder = VimCoder +========================= + +![VimCoder Logo](http://chazmcgarvey.github.com/vimcoder/img/vimcoder.png) + +This plug-in makes it easy to use [Vim](http://www.vim.org/) as your +text editor in the [TopCoder Competition Arena](http://topcoder.com/tc). +It aims to be minimal in comparison to other editors such as +[KawigiEdit](http://topcoder.yajags.com/) or +[CodeProcessor](http://www.topcoder.com/tc?module=Static&d1=applet&d2=plugins) +plug-in chains while also providing enough functionality to also be useful. + +### Features + +* Works on any platform that the TopCoder Arena applet itself supports. +* Works with any language supported by TopCoder. +* Keeps track of your code files locally so you always have a copy. +* Downloads and stores a copy of the problem statement with your code for + off-line viewing. +* Has support for simple templates (default templates provided only for C++ + and Java). +* Test-case "drivers" can be generated locally with the example test-case data + (currently C++ only). + +### License + +This software is licensed according to the terms and conditions of the +[BSD 2-Clause License](http://www.opensource.org/licenses/bsd-license.php). +Please see the COPYING file for more information. +This project is neither supported nor endorsed by TopCoder, Inc. + +### Download + +The latest VimCoder jar files can be downloaded from +[this FTP server](ftp://ftp.brokenzipper.com/pub/vimcoder/). + +### Install + +Unfortunately, installation is a bit cumbersome, but it is what it is: + +1. Download the latest version of the VimCoder jar file. +2. Run the TopCoder Arena applet and log in. +3. Click the "Options" menu and select "Editor" to show the editor + preferences. +4. Click the "Add" button to bring up a new window. +5. For "Name," type "Vim" or whatever you want to represent this plug-in. +6. For "EntryPoint," type "com.dogcows.VimCoder" without the quotes. +7. For "ClassPath," click on "Browse" and locate the VimCoder jar file. The + third field should now have the path to the jar file. +8. Click "OK" to close the window with the three fields. +9. Click "Save." + +You should now be able select "Vim" (or whatever you entered the first +field) as your editor from the pull-down list on any problem statement +window. + +### Configure + +Depending on your preference or system attributes, you may want or need to +first configure the plug-in so that it will work how you want it to. You can +bring up the plug-in preferences window by following these steps: + +1. Run the TopCoder Arena applet and log in. +2. Click the "Options" menu and select "Editor." +3. In the new window, make sure the entry for VimCoder is selected from the + list, and click the "Configure" button. + +![VimCoder Preferences](http://chazmcgarvey.github.com/vimcoder/img/prefs.png) + +##### Storage Directory + +VimCoder saves the problem files and the code you're working on in +a particular directory you can set. By default, this directory is `.vimcoder` +in your home directory. This is an "invisible" directory on most systems. +Within this storage directory are several sub-directories, one for each +problem you open. Each sub-directory is named after the problem identifier +and contains your source code and other files related to the problem. + +If you want to change the storage directory, click the "Browse" button in the +VimCoder preferences window and navigate to the directory you would like to +use. If you have already saved some problems to the previous storage +directory, you may also want to actually move the directory to the new +location so that VimCoder can find the work you've already done. + +##### Vim Command + +By default, VimCoder tries to invoke Vim using the `gvim` command (or +`C:\WINDOWS\gvim.bat` on Windows). This will typically work just fine unless +you don't have gvim in your PATH (or your installation of Vim on Windows +didn't include the wrappers for the command line). If you get errors about +the vim process not being able to run and no Vim session comes up when you use +the VimCoder plug-in, you need to either make sure the Vim command exists in +your PATH, or else change the Vim command in the VimCoder preferences window +to something else. + +You may use an absolute path to your vim executable, such as +`/usr/local/bin/gvim` or `C:\Program Files\Vim\vim73\gvim.exe` +or wherever your actual Vim executable is. You may also invoke vim through +some other command (e.g. `xterm -e vim`). + +The xterm example demonstrates using Vim without the GUI, running in +a terminal emulator. You can enter any elaborate command you want as long Vim +ultimately gets executed with the arguments that will be appended to the +command when it is invoked. After changing this value and saving your +preferences, the command you enter will be used the next time you open +a problem. + +### Usage + +To use VimCoder once it is installed and configured, go to a room in the +TopCoder Arena applet and open one of the problems. If you have set VimCoder +as your default editor, you will see the usual problem statement window come +up as well as a Vim editor window. Otherwise, you can change the editor from +the problem statement window, and the Vim editor window will come up. You +will see that the area usually devoted to editor will be used for log +messages; you will do your actual coding in the Vim window that comes up. + +Just enter your code into the Vim window and use the regular TopCoder Arena +applet buttons to compiled, test, and submit your code. + +**Pro Tip:** If you accidentally close your Vim session, you can get it back +by switching to a different editor and then switching back to VimCoder +Alternatively, the session will also reappear if you switch languages. + +### Problem and Solution Files + +Knowing about the files created by VimCoder is useful if you ever need to do +anything advanced with VimCoder. + +When you open a problem, VimCoder will check to see if you have already opened +that problem by looking for the problem and solution files. If these files +are found, it will load your previous work. Otherwise, it will fill out the +templates based on the problem class name, parameter types, and so on, and +will create several files in a sub-directory of the main storage directory: + +##### `$CLASSNAME$`.`$LANGUAGE$` + +This is the file where you write your solution code. If the class name for +the problem was BinaryCode and your language was Java, the name of this file +would be `BinaryCode.java`. When you open a problem, Vim will load this file +into a new buffer so that you can start coding. If there is a template for +the language you're using, that template will be used to fill in this file to +give you a reasonable place to start. When you save your code to TopCoder or +compile remotely, this is also the file that will be read to provide the code +for your solution. + +##### testcases.txt + +This file contains the example test cases that are associated with the +problem. The format is pretty simple. For each test case, there is one line +for the expected return value followed by each of the method parameters, each +on its own line. This file typically read by the driver program (more on this +later) in order to run the test cases against your code. While you are coding +a solution, you may also want to add additional test cases to make sure your +code is doing what you think it is and to make sure your code doesn't mess up +on edge cases for which an example test case was not provided. + +##### Problem.html + +This file contains the problem statement which is what you see in the top half +of the problem window. You can load this in a browser to read the particulars +of the problem when you aren't running the TopCoder Arena applet. You +typically shouldn't edit this file. + +##### Makefile + +If there exists a Makefile template for the selected language, it will also be +filled out and saved in the problem directory. The purpose of the Makefile is +to compile your code locally. Vim contains the command :make which you can +use to interact with the Makefile. You also shouldn't need to edit this file +directly. Exactly what happens when you use the :make command depends on the +Makefile template. + +If you are using the default Makefile template for C++, typing ":make" without +any arguments will compile your code. Typing ":make run" will run all of the +test cases against your code. Typing ":make test" will also run the test +cases against your code, up until the first failed test at which point it will +abort. + +A Makefile template is not yet provided for any other language, but you can +write one yourself if you are so inclined. Read on to learn how templates +work. + +**Important:** Make sure you understand the difference between compiling +locally and compiling remotely (on the TopCoder servers). If you use the +Makefile to compile your solution (and maybe run the tests), you are not +interacting with the TopCoder servers at all. When you compile *remotely*, +you are sending a snapshot of your current solution to the servers for +processing. The distinction becomes important when it comes time for you to +submit your solution. When you push the "Submit" button, you are submitting +the **last version that was uploaded to the TopCoder servers** (by compiling +remotely), and that may be different from what is currently in your Vim +buffer, even if your Vim buffer was saved to disk. Therefore, it is very +important that you get into the habit of always pushing the "Compile" button +right before you submit your code. This point can't be overemphasized. + +##### driver.`$LANGUAGE$` + +If there exists a driver template for the selected language, it will also be +filled out and saved in the problem directory. If the language was currently +set to C++, the driver code would be in the driver.cc file. You normally +don't have to do anything with this file. It just provides supporting code +for running the test cases against your code. + +A default driver template is currently only provided for the C++ language. +You could write your own template if you wanted to. + +##### `$CLASSNAME$` + +Sometimes the TopCoder Arena applet will pass back what source code it has +saved. This will be saved in a file named after the class, without any file +extension. You can open this file if you need to access this code for any +reason (say, you messed up some code and need to revert back to the last time +you saved from the TopCoder Arena applet). + +### Templates + +VimCoder comes with default templates for C++ and Java, but you can create +your own customized templates for any language supported by TopCoder. To use +your own template, you need to add a file to the storage directory with a file +name depending on the language. The file name should start with the name of +the language and end with "Template" with no other file extension. For +example, if you wanted to create a C# template and your storage directory was +`/home/foo/.topcoder`, you would need to create the file +`/home/foo/.topcoder/C#Template`. + +A template is like a regular source code file with special keywords that will +be replaced as the template is "filled out" whenever you open a new problem. +Keywords are surrounded by two dollar signs so they're not confused with other +parts of the source code. The template expansion process is rather +simplistic, so if you can't get the right format for the terms you need, you +might have to change the plug-in source code to get the effect you're trying +to achieve. Here are the possible keywords and replacement terms: + +##### `$CLASSNAME$` + +This keyword is replaced by the name of the class you must use in your +solution to the problem. + +##### `$METHODNAME$` + +This keyword is replaced by the name of the public method your class needs to +have. + +##### `$RETURNTYPE$` + +This keyword is replaced by the type of the return variable of your public +method. + +##### `$METHODPARAMS$` + +This keyword is replaced by a comma-separated list of method parameter types +and names. + +---- + +Other keywords are also available, but the rest are intended to be used in +driver or Makefile templates. You can also create these templates by adding +specially-named files to the storage directory. Driver templates are named +starting with the name of the language and ending with "Driver" with no other +file extension. Similarly, Makefile templates are named starting with the +name of the language and ending with "Makefile" with no other file extension. + +Drivers provide additional code to implement running the test cases. +Currently, a default driver template is only provided for C++. Makefiles +should have the commands needed to compile the solution source code and/or +make a driver program that will perform the tests. Since there is only +a driver template for C++, there is similarly only a default Makefile template +provided for C++. If you want automatic building and testing for one of the +other languages, you will need to create a driver and Makefile template for +that language. Here are more keywords that may be useful for these types of +templates: + +##### `$METHODPARAMDECLARES$` + +This keyword is replaced by C-style declarations of the method parameters. In +other words, each parameter is declared with its type on its own line +terminated by a semicolon. + +##### `$METHODPARAMNAMES$` + +This keyword is replaced by a comma-separated list of only the method +parameter names. + +##### `$METHODPARAMSTREAMOUT$` + +This keyword is replaced by a list of the method parameter names separated by +the C++ output stream operator (<<). The C++ driver template uses this to +display the input values of the test case data. + +##### `$METHODPARAMSTREAMIN$` + +This keyword is replaced by a list of the method parameter names separated by +the C++ input stream operator (>>). The C++ driver template uses this to read +in the test case data from testcases.txt. + +---- + +To give you an idea of how this all fits together, here is an example template +for Java: + +```java +import static java.lang.Math.*; +import static java.math.BigInteger.*; +import static java.util.Arrays.*; +import static java.util.Collections.*; +import java.math.*; +import java.util.*; + +public class $CLASSNAME$ { + public $RETURNTYPE$ $METHODNAME$($METHODPARAMS$) { + } +} +``` + +Something like this should be saved in a filed named `JavaTemplate` in your +VimCoder storage directory. + +### Gotchas + +##### Vim Client/Server + +VimCoder requires Vim's client/server feature in order to work. If the log is +showing errors with the invocation of Vim or if it's just not working and has +other strange symptoms, make sure your version of Vim supports the +client/server feature. If you are unsure, use Vim's `:version` command and +look for "+clientserver" in the output. If you see "-clientserver" instead, +then you'll need to get yourself another version of Vim. + +I think this feature was introduced in Vim 6.x, but I haven't done any testing +with any versions of Vim less than 7.2. If you're still on 6.x, you should +really upgrade anyway. + +##### Vim Settings Not Applied + +The problem is that sometimes your settings (in your vimrc file) are not being +applied as you would expect. This may be because you are using `setlocal` in +your vimrc file rather than `set`. The `setlocal` command applies settings +only to the current buffer or window (see `:help setlocal` for more +information), but VimCoder works by first launching Vim and then loading +a brand new buffer. + +The solution is to consider whether or not such settings should actually be +global; if they should be global, change `setlocal` to `set` in your vimrc +file. Alternatively, if you want certain settings to be set only for certain +kinds of buffers, you can use the `autocmd` command to selectively set +settings according to file path pattern and various events. +See `:help autocmd` for more information. +