camlspotter avatar camlspotter committed 778b0e2

doc update

Comments (0)

Files changed (2)

 with the name of your OCaml compiler version. 
 When you report bugs, please note the revision hash with your issue description please.
 
-Installation and Usage
+Installation
 ============================
 
-To compile OCamlSpotter, just type ``make`` and ``make install``.
+To compile OCamlSpotter::
+
+   % make
+   % make opt           (This is optional but recommended)
+   % make install     
  
+Setup
+============================
+
 If you are Emacs user, see ``ocamlspot.el``. It explains how to set up
-and use it:
-
-* Set ``load-path``.
-* Set your ``ocamlspot`` binary in your emacs setting (``M-x customize-group => ocamlspot``)
-* Add caml or tuareg mode hook.
-* See the buffer ``*ocamlspot-process*`` if you thing something goes wrong.
-
-If you have done properly, move your cursor to OCaml identifier and
-press ``C-c ;``. Emacs should display the definition of the identifier.
-Otherwise... you made mistake or a bug of OCamlSpotter. Yes, it has bugs.
+and use it.
 
 I have also written Vim script ``ocamlspot.vim``, but it is not tested at all.
 Sorry but I do not use Vim.
 
 
-If something goes wrong...
---------------------------------
+How to use
+===============================
 
-To browse modules correctly, 
+Before using, it is better to know what to do if something goes wrong
+---------------------------------------------------------------------------
 
 * Use the correct ``ocamlspot`` matching with your OCaml compiler version.
 * Compile OCaml modules with ``-bin-annot`` ocaml compiler option.
 * Keep the source code and produced cmt/cmti files.
 * Install cmt/cmti files along with cmi/cma/cmxa files.
+* Use ``ocamlspot.opt`` if you have done ``make opt``. It is much faster than ``ocamlspot``.
+* CamlP4 has lots of location issues. In many cases, OCamlSpotter cannot workaround them.
+* OCamlSpotter has its own bugs.
 
-Otherwise OCamlSpotter complains that it cannot find required cmt/cmti files.
+Browsing your code
+-------------------------------------------------
 
-Browsing libraries, packages and OCaml stdlibs 
-=======================================================
+Compile your OCaml source code with ``-bin-annot`` option, 
+then it should create ``\*.cmt`` and ``\*.cmti`` files.
 
-Libraries and packages
------------------------------
+Open the source code in your Emacs and move the cursor to an identifier
+usage, then type ``C-c ;``. If things are properly installed and set up,
+Emacs should display the definition of the identifier.
+
+Browsing libraries and packages
+----------------------------------------------
 
 Normally OCaml libraries and packages are not always compiled with -bin-annot option
 and do not always install the annotation files.
 * Do not remove the original source files, otherwise browsing cannot work.
 
 Browsing OCaml stdlib and otherlibs
-------------------------------------------
+---------------------------------------------------
 
 If you want to browse OCaml's standard library (stdlib and otherlibs), 
-you must recompile those modules with -bin-annot option to create cmt/cmti files.
+you must recompile those modules with -bin-annot option to create cmt/cmti files. 
+It should require some Makefile changes and reinstallation of the compiler.
 
 Automation
 ------------------------------------
 
-To facilitate these you may want to use SpotInstall( https://bitbucket.org/camlspotter/spotinstall ). SpotInstall provides:
+Recompilation of libraries and compiler with fixing their build scripts is very lousy. To facilitate these you may want to use SpotInstall( https://bitbucket.org/camlspotter/spotinstall ). SpotInstall provides:
 
 * A small OCaml compiler patch to automatically enable -bin-annot by the existence of OCAML_ANNOT environment variable; no need to fix build scripts.
 * An automatic cmt/cmti post installation command, spotinstall.
+
+Even with SpotInstall, you have to still recompile the compiler and the libraries. But you do no longer need to fix the build scripts.
 ; (*                                                                     *)
 ; (***********************************************************************)
 
-; How-to-use
+; # How-to-use: Write the following to your .emacs
 ;
-; Write the following to your .emacs
-
-; CR jfuruse: no tree node found is displayed when ocamlspot program is not found
-
-;; load-path
-; (setq load-path (cons "WHERE-YOU-HAVE-INSTALLED-THE-ELISP" load-path))
+;     ; load-path
+;      (setq load-path (cons "WHERE-YOU-HAVE-INSTALLED-THIS-ELISP" load-path))
+;     
+;      (require 'ocamlspot)
+;     
+;     ; tuareg mode hook (use caml-mode-hook instead if you use caml-mode)
+;        (add-hook 'tuareg-mode-hook
+;              '(lambda ()
+;                 (local-set-key "\C-c;" 'ocamlspot-query)
+;      	     (local-set-key "\C-c:" 'ocamlspot-query-interface)
+;                 (local-set-key "\C-c'" 'ocamlspot-query-uses)
+;                 (local-set-key "\C-c\C-t" 'ocamlspot-type)
+;                 (local-set-key "\C-c\C-i" 'ocamlspot-xtype)
+;                 (local-set-key "\C-c\C-y" 'ocamlspot-type-and-copy)
+;                 (local-set-key "\C-cx" 'ocamlspot-expand)
+;                 (local-set-key "\C-c\C-u" 'ocamlspot-use)
+;                 (local-set-key "\C-ct" 'caml-types-show-type)
+;                 (local-set-key "\C-cp" 'ocamlspot-pop-jump-stack)))
+;     
+;     ; set the path of the ocamlspot binary. If you did make opt, ocamlspot.opt is recommended.
+;      (setq ocamlspot-command "WHERE-YOU-HAVE-INSTALLED-THE-BINARIES/ocamlspot")
+;     
+;     ; You can also change overlay colors as follows:
+;      (set-face-background 'ocamlspot-spot-face "#660000")
+;      (set-face-background 'ocamlspot-tree-face "#006600")
 ;
-;; set the path of the ocamlspot binary
-;; this can be a shell command, e.g., "ocamlfind ocamlspot"
-; (setq ocamlspot-command "WHERE-YOU-HAVE-INSTALLED-THE-BINARIES/ocamlspot")
 ;
-; (require 'ocamlspot)
+; # Setup
 ;
-;; tuareg mode hook (use caml-mode-hook instead if you use caml-mode)
-;   (add-hook 'tuareg-mode-hook
-;         '(lambda ()
-;            (local-set-key "\C-c;" 'ocamlspot-query)
-; 	     (local-set-key "\C-c:" 'ocamlspot-query-interface)
-;            (local-set-key "\C-c'" 'ocamlspot-query-uses)
-;            (local-set-key "\C-c\C-t" 'ocamlspot-type)
-;            (local-set-key "\C-c\C-i" 'ocamlspot-xtype)
-;            (local-set-key "\C-c\C-y" 'ocamlspot-type-and-copy)
-;            (local-set-key "\C-cx" 'ocamlspot-expand)
-;            (local-set-key "\C-c\C-u" 'ocamlspot-use)
-;            (local-set-key "\C-ct" 'caml-types-show-type)
-;            (local-set-key "\C-cp" 'ocamlspot-pop-jump-stack)))
+; M-x customize-group => ocamlspot
 ;
-;; You can also change overlay colors as follows:
-; (set-face-background 'ocamlspot-spot-face "#660000")
-; (set-face-background 'ocamlspot-tree-face "#006600")
-
-
-
+; # Commands
+;
 ; ocamlspot-query
 ;   Show the type of the inner-most subexpression under the cursor.
 ;   If there is an identifier under the cursor, browse and show its definition
 ;   Same as ocamlspot-type but it shows you more detailed information: 
 ;   path id numbers. You can browse path names in this result using C-c;
 
+
+
+; CR jfuruse: no tree node found is displayed when ocamlspot program is not found
+
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Configurable variables
 
 (eval-when-compile (require 'cl)) ; for `destructuring-bind'
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.