Updated to reflect new source location as well as new samples install instructions
[vimdoclet.git] / doc / README.txt
blobe6c4385163e135f57058129d3b7b5226c74037d8
1 = Vim Helpfile Doclet =
2 David Copeland <davetron5000@NOSPAM.gmail.com>
3 v1.0, Nov 2007
5 The Vim Doclet is a Doclet for Java 1.4 and above that generates documentation in the VIM Help File format. This format is a very rudimentary form of hypertext and allows a vim user to call up the documentation on a Java class in the same manner as searching the VIM help. This allows the developer to read documentation without exiting VIM.
7 == Trying it Out ==
9 Before installing and running, go to link:http://sourceforge.net/project/showfiles.php?group_id=210533[the files section] and download the sample zip. Unzip this and follow the instructions in README.txt.  Once you've done that, you can try out the javadoc in vim via `:help String`. This will bring up the documentation for `java.lang.String`. The sample includes the JDK6 version of the `java.lang` and `java.util` packages.
11 image:vimdoclet1.png[Screenshot of what the documentation looks like]
13 == Installation == 
15 Download the latest distribution at link:http://sourceforge.net/projects/vimdoclet/[the SourceForge project page]. The distribution contains both source and binary (it's only one source file).  As this is a custom doclet, installation is largely just putting the `vimdoclet.jar` into your classpath before running javadoc. How you do this depends highly on your development environment.
17 == Running == 
19 The doclet takes two parameters, one of which is required:
21 outputDir:: 
22     This is the location of a directory that should contain the generated documentation. You may want to put this to a temp directory first, however if you set this to `+++~/.vim/doc+++` this would be the easiest way to make the documentation available to vim
24 lineLength:: 
25     This defaults to 80 and specifies the number of characters per line for the documentation. You can use this to increase the size of your documentation if you know you will be using vim in a particular size.
27 Aside from simply configuration `javadoc` to use this doclet, you also need source to run it on. The most useful source is the source code for Java itself. Fortunately, this is available from Sun link:https://jdk6.dev.java.net/[here (click on "Latest JDK 6 Source Snapshots")]. Once you download this, extract it somewhere and have your javadoc point to that (though you will need to point it to `j2se/src/share/classes` unless you want a ton of superfluous classes documented).
29 === Running from Ant ===
31 The `run.xml` file included in the distribution has a target called `run` that will run the doclet on java source code. It is set up assuming you are running on the JDK source, as it will skip certain superfluous classes and delete the documentation for `java.awt.List` (see below). To use it, specify two parameters on the command line to ant as properties:
33 * *vimdoclet.source.root* - This is the root of the source, presumably the JDK. If you downloaded the JDK source, you should point this to `$JDK_SOURCE_ROOT/j2se/src/share/classes` as the JDK source package contains a lot more than what you probably want to document
34 * *vimdoclet.outputDir* - This is the *outputDir* command line to the doclet and is where the generated source will go
36 == Using the Documentation == 
38 Once you've generated the documentation, you need to generate Vim's tag index. If you've put your documents in `+++~/.vim/doc+++`, you can just do `:helptags +++~/.vim/doc+++` from within vim and, after a very long time of indexing your documentation is ready for use. Try it by doing `:help String` in vim.
40 If you've never used the vim help browser, highlighted text typically represents hyperlinks that can be followed by +++^]+++ (control and right bracket). You can navigate "back" via +++^T+++ (control and T).
42 See the vim documentation for further ways in which you can streamline your experience.
44 === Possible Issues ===
46 The main issue you may find with this documentation is in the way Vim handles classes with the same name (e.g. `java.util.Date` vs `java.sql.Date`). Basically, it doesn't. If you do `:help Date` you will always go to `java.sql.Date`. You can to `help java.util.Date`, however vim doesn't know which Date you need to lookup without the entire package.
48 I find it useful to remove the documentation for `java.awt.List` because I almost never need it and find the documentation for `java.util.List` much more useful.
50 == Source ==
52 The source is freely available via the Gnu GPL and can be retrieved via link:http://git.or.cz[Git] at link:http://repo.or.cz/w/vimdoclet.git[the repo.or.cz site]
54 == Links ==
56 * link:http://repo.or.cz/w/vimdoclet.git[Git Repo/Source for Vimdoclet]
57 * link:http://sourceforge.net/project/showfiles.php?group_id=210533[Download]
58 * link:http://sourceforge.net/tracker/?group_id=210533[Tracker, report bugs, request features]
59 * link:https://jdk6.dev.java.net/[JDK6 Dev page (source available here)]
60 * link:http://www.vim.org[VIM Homepage]
61 * link:http://java.sun.com/j2se/javadoc/[Javadoc homepage]
62 * link:http://vim.wikia.com/wiki/Vim_Doclet[Vim wikia entry]
64 == Screenshots ==
65 image:vimdoclet1.png[Screenshot of what the documentation looks like]
66 image:vimdoclet2.png[Screenshot of the method list]
67 image:vimdoclet3.png[Screenshot a method's javadoc]
69 ''''
71 image:sflogo.png[link="http://www.sourceforge.net"]