Best way to get hang of an elisp file?

Best way to get hang of an elisp file?

[Marcin Borkowski]

Hi all,

I'd like to look at AUCTeX sources.  This means that I have a rather
large elisp file, and I'd like to skim through it.  Since I want to
know more or less /what/ functions, variables etc. there are and what
they /do/ instead of how they are implemented, I'm curious whether
there exists something like "outline mode", hiding everything but the
signature of a function and its docstring etc.  (Or better yet,
generating a file with everything but signatures and docstrings etc.
deleted.)  Or is there any other way to accomplish my goal?

I know that there are tags etc., but this is not what I want: I'd
prefer to skim through the file /sequentially/, just to learn what's in
there, I'm not interested in jumping to a function whose name I know -
since I don't know these names, and I want to learn them.

I also know that I can navigate through sexps, and probably jumping "to
the end of the outermost sexp" could be easy.  But I don't want to
limit myself to Emacs when reading the file: my workflow would be to
transfer it to an ebook reader (I spend more than one hour commuting
almost every day, you know;)).  (Of course, in this case hiding won't
help.)

I am also aware that there exists a Perl script doing exactly this
(http://cpansearch.perl.org/src/DOOM/Emacs-Run-ExtractDocs-0.03/lib/Emacs/Run/ExtractDocs.pm),
but for some strange reason I get the feeling that using Perl to
manipulate Elisp sources is... strange at least.

Any hints?

(If not, I'll try to implement something like this myself.)

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Best way to get hang of an elisp file?

[Thorsten Jolitz]

Marcin Borkowski <mbork@wmi.amu.edu.pl> writes:

 Hi,

> I'm curious whether there exists something like "outline mode", hiding
> everything but the signature of a function and its docstring etc. (Or
> better yet, generating a file with everything but signatures and
> docstrings etc. deleted.)

Sounds like a perfect use case for
[[https://github.com/tj64/navi][navi-mode.el]]. Instead of describing it
(again) I'll just give some examples of possible views on tex.el:

* Outline structure (level 1-8)

type 1 in *Navi* buffer (-> level 1)

,-----------------------------------------------------------------------
| 45 matches for "^;;; " in buffer: tex.el
|       1:;;; tex.el --- Support for TeX documents.
|      27:;;; Commentary:
|      33:;;; Code:
|      61:;;; Site Customization
|     541:;;; Portability.
|     572:;;; Documentation for Info-goto-emacs-command-node and similar
|     597:;;; Special support for XEmacs
|     688:;;; Special support for GNU Emacs
|     762:;;; Buffer
|    [...]
|    5053:;;; Dollars
|    5144:;;; Simple Commands
|    5379:;;; Documentation
|    5508:;;; Ispell Support
|    5573:;;; Special provisions for other modes and libraries
|    5598:;;; tex.el ends here
`-----------------------------------------------------------------------

type 3 (level 1-3)

[... same thing as above, tex.el seems to have only level 1 headlines]

* Keyword Searches

type h for help:

,-------------------------------------------
| [KEY] : [SEARCH]
| ================
|                         a : ALL
|                         f : FUN
|                         v : VAR
|                         x : OBJ
|                         b : DB
|                         F : defun
|                         V : defvar
|                         C : defconst
|                         G : defgroup
|                         U : defcustom
|                         A : defadvice
|                         M : defmarcro
|                         D : defface
|                         S : defstruct
|                         B : defsubst
|                         L : defclass
|                         I : define
|                         J : declare
|                         K : global-set-key
|                         T : add-to-list
|                         Q : setq
|                         H : add-hook
|                         O : hook
|                         X : lambda
|                         R : require
`-------------------------------------------

(type q to quit help buffer)

type f

,---------------------------------------------------------------------------
| 186 matches for "^[[:space:]]*(def[maus][^et][a-z]*\*? " in buffer: tex.el
| 547:      (defun TeX-maybe-remove-help (menu)
| 562:    (defun TeX-maybe-remove-help (menu)
| 566:  (defmacro TeX-menu-with-help (menu)
| 601:  (defun TeX-read-string
| 608:  (defun TeX-mark-active ()
| 614:  (defun TeX-active-mark ()
| 622:    (defalias 'line-beginning-position 'point-at-bol))
| 624:    (defalias 'line-end-position 'point-at-eol))
| 626:  (defun TeX-overlay-prioritize (start end)
| 665:    (defalias 'TeX-completing-read-multiple 'completing-read-multiple)
| 666:  (defun TeX-completing-read-multiple
| 675:    (defalias 'TeX-line-number-at-pos 'line-number-at-pos)
| [...]
`--------------------------------------------------------------------------

type v

,-------------------------------------------------------------------
| 186 matches for "^[[:space:]]*(def[vcgf][^l][a-z]+ " in buffer: tex.el
|      43:(defgroup TeX-file nil
|      47:(defgroup TeX-command nil
|      51:(defgroup LaTeX nil
|      57:(defgroup TeX-misc nil
|      81:(defcustom TeX-print-command "%(o?)dvips -P%p %r %s"
|      91:(defcustom TeX-command "tex"
|      96:(defcustom TeX-Omega-command "omega"
|     101:(defcustom LaTeX-command "latex"
|     106:(defcustom LaTeX-Omega-command "lambda"
|     111:(defcustom ConTeXt-engine nil
|     118:(defcustom ConTeXt-Omega-engine TeX-Omega-command
|     127:(defcustom TeX-queue-command "lpq -P%p"
`-------------------------------------------------------------------

type R

,------------------------------------------------------------
| 5 matches for "^[[:space:]]*([a-z-]*require " in buffer: tex.el
|      38:(require 'custom)
|      39:(require 'tex-site)
|      41:  (require 'cl))
|     543:(require 'easymenu)
|    5348:  (require 'reporter)
`------------------------------------------------------------

* Combine Headline and Keyword searches

type C-1 C

   ,-------------------------------------------------------------------
   | [...]
   | 3021:;;; Hilighting
   | 3032:;;; Parsing
   | 3049:(defconst TeX-auto-parser-temporary 1)
   | 3050:(defconst TeX-auto-parser-add 2)
   | 3051:(defconst TeX-auto-parser-local 3)
   | 3052:(defconst TeX-auto-parser-change 4)
   | 3508:;;; Utilities
   | 3862:;;; Syntax Table
   | 3891:;;; Menu Support
   | 3961:(defconst TeX-command-menu-name "Command"
   | 3964:;;; Keymap
   | 4218:;;; Menus for plain TeX mode
   | 4303:;;; AmSTeX
   | 4348:;;; Verbatim constructs
   | 4363:;;; Comments
   | 4599:;;; Indentation
   | 4637:;;; Navigation
   | 4916:;;; Fonts
   | 5053:;;; Dollars
   | 5066:(defconst TeX-dollar-string (char-to-string TeX-dollar-sign))
   | 5067:(defconst TeX-dollar-regexp
   | 5144:;;; Simple Commands
   | [...]
   `-------------------------------------------------------------------

* Narrow to Headline

type 1

with point (in *Navi* buffer) on

,-----------------
| 3032:;;; Parsing
`-----------------

type r

type a

,-------------------------------------------------------------------------------
| 40 matches for "^[[:space:]]*(def[a-z]+ " in buffer: tex.el
|       3:(defgroup TeX-parse nil
|       7:(defvar TeX-auto-parser '((styles TeX-auto-file TeX-run-style-hooks)))
|      18:(defconst TeX-auto-parser-temporary 1)
|      19:(defconst TeX-auto-parser-add 2)
|      20:(defconst TeX-auto-parser-local 3)
|      21:(defconst TeX-auto-parser-change 4)
|      23:(defun TeX-auto-add-type (name prefix &optional plural)
|      55:(defun TeX-auto-add-information (name entries)
|      67:(defun TeX-auto-list-information (name)
|     100:(defvar TeX-auto-apply-hook nil
|     103:(defun TeX-auto-apply ()
|     109:(defun TeX-auto-apply-entry (entry)
|     [...]
|     320:(defvar TeX-auto-prepare-hook nil
|     323:(defvar TeX-auto-cleanup-hook nil
|     326:(defcustom TeX-auto-parse-length 999999
|     332:(defcustom TeX-auto-x-parse-length 0
|     340:(defcustom TeX-auto-x-regexp-list 'LaTeX-auto-label-regexp-list
|     357:(defun TeX-regexp-group-count (regexp)
|     367:(defun TeX-auto-parse-region (regexp-list beg end)
|     422:(defun TeX-auto-parse ()
|     456:(defun TeX-auto-clear-entry (entry)
|     460:(defvar LaTeX-auto-end-symbol nil)
|     462:(defun TeX-auto-symbol-check (match)
`-------------------------------------------------------------------------------

type w to widen again.

* Other Stuff

use n, p, space and <= for navigation, d to show point in associated source-code
buffer, s and o to switch to the source-code buffer, M-s M-s to switch back to
*Navi* buffer, type E to make the *Navi* buffer editable (excellent for
keyboard macros) and C-c C-c to make it read-only again. You can even search,
mark, copy, kill, paste the original buffer from the *Navi* buffer and of
course cycle visibility (locally and globally).

--
cheers,
Thorsten

RE: Best way to get hang of an elisp file?

[Drew Adams]

> I have a rather large elisp file, and I'd like to skim through it.
> I want to know more or less /what/ functions, variables etc. there
> are and what they /do/ instead of how they are implemented
...
> But I don't want to limit myself to Emacs when reading the file

I don't have an answer for use outside Emacs.  But this can help in
Emacs:

In Icicle minor mode, `C-=' is by default `icicle-imenu'.  It is a
multi-command that uses Imenu definition-recognizing regexps.  It
lets you navigate among definitions (of functions, vars, macros, etc.,
depending on the language).  You can use pattern matching, sorting,
and cycling.

But you can also ask for information about any definitions by
hitting one of the help keys during completion: `C-M-RET' (help on
the current definition), `C-M-down' (cycle to the next definition
and show its help), `C-M-mouse-2' (help on the definition clicked
in buffer *Completions*), etc.

The help for a given definition is shown in buffer *Help*.  In the
case of Emacs things it is just what you would see using `C-h f',
`C-h v', `decribe-face', etc.: help on the particular Emacs-Lisp
object.

So you have three levels of information (3 lists) for such objects:
(1) their names, (2) their descriptions (help), and (3) their
definitions.

[There are also Icicles imenu commands for particular kinds of
things, e.g., `icicle-imenu-command', `icicle-imenu-user-option',
etc.  There are also "full" versions of each of these commands.
The full versions use the whole definitions (e.g. whole defuns)
as search contexts - you can either navigate among them, as usual,
or search them and navigate among specific search hits.]

* http://www.emacswiki.org/Icicles_-_Search_Commands%2c_Overview

* http://www.emacswiki.org/Icicles_-_Other_Search_Commands#IciclesImenu

Re: Best way to get hang of an elisp file?

[Stefan Monnier]

> they /do/ instead of how they are implemented, I'm curious whether
> there exists something like "outline mode", hiding everything but the

Yes, it's called outline-minor-mode ;-)
For Elisp, I additionally use:

(add-hook 'outline-minor-mode-hook
          (lambda ()
            (when (and outline-minor-mode (derived-mode-p 'emacs-lisp-mode))
              (hide-sublevels 1000))))

which starts outline-minor-mode by hiding all the bodies of functions.
I also use `reveal-mode' which automatically unhides the bodies when you
try to move the cursor into them (so you don't need to remember the key
sequences to use for opening/closing elements).


        Stefan

RE: Best way to get hang of an elisp file?

[Drew Adams]

> > I'm curious whether there exists something like "outline mode",
> > hiding everything but the signature of a function and its docstring
> > etc.
> 
> Yes, it's called outline-minor-mode ;-) For Elisp, I additionally use:
>
> (add-hook 'outline-minor-mode-hook
>           (lambda () (when (and outline-minor-mode
>                                 (derived-mode-p 'emacs-lisp-mode))
>             (hide-sublevels 1000))))
>
> which starts outline-minor-mode by hiding all the bodies of
> functions.  I also use `reveal-mode' which automatically unhides...

Good reminder.  `outline-minor-mode' and `reveal-mode' are oldies but
goodies.

Not a complete answer here, though, since `o-m-mode' hides also the
doc strings.  (And even part of the signature, if it ends on another
line.)

Re: Best way to get hang of an elisp file?

[Sean Sieger]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> they /do/ instead of how they are implemented, I'm curious whether
>> there exists something like "outline mode", hiding everything but the
>
> Yes, it's called outline-minor-mode ;-)
> For Elisp, I additionally use:
>
> (add-hook 'outline-minor-mode-hook
>           (lambda ()
>             (when (and outline-minor-mode (derived-mode-p 'emacs-lisp-mode))
>               (hide-sublevels 1000))))
>
> which starts outline-minor-mode by hiding all the bodies of functions.
> I also use `reveal-mode' which automatically unhides the bodies when you
> try to move the cursor into them (so you don't need to remember the key
> sequences to use for opening/closing elements).
>
>
>         Stefan

Thanks.

I would like to compare the two elisp libraries, BBDB 2 and BBDB 3, for
copyright purposes and would appreciate any other suggestions that'll
aid a plebe such as myself in the endeavor.

How to differentiate, for instance, Jamie's work from Roland's work?

No diff list like GNU Emacs has?

Re: Best way to get hang of an elisp file?

[Stefan Monnier]

> I would like to compare the two elisp libraries, BBDB 2 and BBDB 3, for
> copyright purposes and would appreciate any other suggestions that'll
> aid a plebe such as myself in the endeavor.
> How to differentiate, for instance, Jamie's work from Roland's work?

That can be fairly difficult, indeed.

The way I do it, usually, is to look at all the commits by authors for
whom we don't have copyright papers yet.  I group them by author.

For all authors whose sum of commits is small enough to be considered
"trivial", we don't need paperwork, so I take them out.

For all remaining authors, I look at all their commits and try to track
that code's subsequent life, to see if it has been removed/overwritten
and figure out where it can still be found in the latest version of
the code (in case it was moved, reindented, ...).

In the case of BBDB, this is rather difficult because Jamie's code is
fairly large, so it's a lot of work to track his code through all of
Roland's changes to see what remains.

So I think we'd need to use some other approach.  E.g. Roland should be
able to give us some important indications like "all this file is only
mine", "all that file was completely rewritten".


        Stefan

Re: Best way to get hang of an elisp file?

[Sean Sieger]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> That can be fairly difficult, indeed.
>
> The way I do it, usually, is to look at all the commits by authors for
> whom we don't have copyright papers yet.  I group them by author.
>
> For all authors whose sum of commits is small enough to be considered
> "trivial", we don't need paperwork, so I take them out.
>
> For all remaining authors, I look at all their commits and try to track
> that code's subsequent life, to see if it has been removed/overwritten
> and figure out where it can still be found in the latest version of
> the code (in case it was moved, reindented, ...).
>
> In the case of BBDB, this is rather difficult because Jamie's code is
> fairly large, so it's a lot of work to track his code through all of
> Roland's changes to see what remains.
>
> So I think we'd need to use some other approach.  E.g. Roland should be
> able to give us some important indications like "all this file is only
> mine", "all that file was completely rewritten".
>
>
>         Stefan

Thank you for your time, Stefan.

I have been trying to compare the two versions and this will help, as
have Roland's comments---posts as of recent.  I would like to volunteer
my help on this, and if anyone else has guidance to offer, I'm all
ears.