Commits

camlspotter committed 778b0e2

doc update

  • Participants
  • Parent commits a0e11a9

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.

File ocamlspot.el

 ; (*                                                                     *)
 ; (***********************************************************************)
 
-; 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'