Related
I am a newbie on Emacs. I was going to learn how to close a buffer, so I typed M-x apropos-documentation RET close buffer. Then I got a lot of useless information.
Given the above senario, what's the right way to find what I wanna know using the self-documenting system?
Or the self-documenting system is useless compared to Google in the modern day?
When you are just beginning with Emacs, the best documentation to start with is the tutorial. You can get there with C-h t. A half hour spent doing the tutorial will show you all the basics, including buffer management. This will save you a lot of time compared to searching for each command individually, either via Google or apropos.
Another benefit of the tutorial is that you'll get a quick overview of Emacs' idiosyncratic terminology. For example, the word 'kill' is used as a near-synonym for 'delete'. Searching for 'kill buffer' with apropos would likely have answered your question.
You are better off with Google until you know the terminology and maybe even after that. I've used the emacs documentation system a lot, but mainly for looking up something which I already knew about, or something for which I already knew the exact terminology.
If you are unsure how to search for something in the documentation then Google is much more effective, because it also takes synoyms into account and it finds questions similar to yours from forums and stuff. It does not only apply to Emacs, but to any other software as well. Regardless of the software I always try a Google search first, because in most cases Google throws out the answer much more quickly than browsing the documentation,
So a basic terminology problem tripped you up here. I would say that Emacs doesn't help here by not catering for this case in the glossary, and naming the relevant menu item "Close" and binding it to a different function to the C-xk sequence (which would be to avoid prompting you again). I note that the tooltip for that menu item does at least indicate the "kill" terminology, however, which certainly would have assisted your search.
That mismatch was always going to cause problems for searching with apropos, but the self-documentation in Emacs goes beyond that. Really, the tutorial or user manual should have been your next step. (The tutorial should be your first step, in fact.)
Any of the following would have found you the answer fairly quickly, even without knowing the "kill" term.
Go through the tutorial: C-ht
Look for "buffer" in the manual's contents page: C-hr
Search the manual's index C-hrI buffers RET
(admittedly searching for buffer (singular) provides more cluttered results)
Search the keybindings: C-hbM-x occur RET buffer RET
(occur is a bit more advanced, but C-s would work too)
C-hk click the "File" -> "Close" menu item
(which is not the same binding as C-xk as commented on above; but this would also have shown the "kill" terminology)
I think it's a bit of a shame that the accepted answer for a question entitled "How to effectively use the self-documenting system of Emacs?" is one which steers you away from those systems, as once you know your way around them you'll rarely need anything other than Emacs' own documentation.
First of all, just because you did not understand the information, it does not mean that it is useless.
Second of all, once you have even the slightest idea what commands are called, you can do M-x, and tab-expand the command. Once you've invoked it, emacs will also flash up a message telling you the key binding for that command if there is one.
I wrote an extensive tutorial on learning Emacs via its built-in help and elisp source code: http://david.rothlis.net/emacs/howtolearn.html
Several people have found it very useful.
The self-documenting nature of Emacs is amazing (once you learn your way around).
Also
emacs-index-search
elisp-index-search
Get aquainted with th C-h chords [1]:
C-h a command-apropos What commands work like this...?
C-h c describe-key-briefly What command does this key sequence do?
C-h b describe-bindings What are the key bindings for this buffer?
C-h k describe-key What command does this sequence do?
C-h l view-lossage What are the last 100 characters typed?
C-h w where-is What is the key binding for this?
C-h f describe-function What does this function do?
C-h v describe-variable What is this variable?
C-h o describe-symbol What is this symbol? (function, variable or face)
C-h m describe-mode Tell me about this mode.
C-h s describe-syntax What is the syntax table for this buffer?
Although they wouldn't have helped with the particular query you were after, they come in handy very often. As for apropos, give up. Use Google and the Emacs Wiki instead.
I am not a very good at using Emacs, but the feature I would like the most would be some integration with help/documentation for a particular language/API I use at the moment. I would imagine that there would be help displayed in another buffer depending on where I put my cursor while editing.
I wonder if there is a package that does that, even if it would be very simple, just displaying some file based on the keyword. I think there is, but I cannot find it ("help" is a too generic word).
(In particular, I would like to have this help for Common Lisp, but other languages, such as Java or C, could be useful.)
ILISP and SLIME provide several methods for looking up a function; see the Emacs wiki and the SLIME documentation. Or just built into Emacs itself, there are functions like C-h f to get function help or M-x man; both use the text at the point by default. You could pretty easily adapt them to work for another language of your choice.
Assuming you are using SLIME for common-lisp, you can take a look at slime-autodoc-mode.
Sorry, can't help with a generic solution for this.
You can set up the CLHS root for SLIME in your .emacs file:
(setq common-lisp-hyperspec-root "/usr/share/doc/hyperspec/HyperSpec/")
Adjust the path to where you put your HyperSpec.
Then, C-c C-d h with point at a symbol will look it up there in your browser.
One thing you might like to enable is eldoc-mode, by adding (turn-on-eldoc-mode) to your mode hook functions for the appropriate programming modes.
In ElDoc mode, the echo area displays information about a
function or variable in the text where point is. If point is
on a documented variable, it displays the first line of that
variable's doc string. Otherwise it displays the argument list
of the function called in the expression point is on.
This is probably less than you were after, but it still makes a good companion to a fuller-featured contextual help system, and there are a number of programming modes that support it.
I am switching to Emacs from TextMate. One feature of TextMate that I would really like to have in Emacs is the "Find in Project" search box that uses fuzzy matching. Emacs sort of has this with ido, but ido does not search recursively through child directories. It searches only within one directory.
Is there a way to give ido a root directory and to search everything under it?
Update:
The questions below pertain to find-file-in-project.el from Michał Marczyk's answer.
If anything in this message sounds obvious it's because I have used Emacs for less than one week. :-)
As I understand it, project-local-variables lets me define things in a .emacs-project file that I keep in my project root.
How do I point find-file-in-project to my project root?
I am not familiar with regex syntax in Emacs Lisp. The default value for ffip-regexp is:
".*\\.\\(rb\\|js\\|css\\|yml\\|yaml\\|rhtml\\|erb\\|html\\|el\\)"
I presume that I can just switch the extensions to the ones appropriate for my project.
Could you explain the ffip-find-options? From the file:
(defvar ffip-find-options
""
"Extra options to pass to `find' when using find-file-in-project.
Use this to exclude portions of your project: \"-not -regex \\".vendor.\\"\"")
What does this mean exactly and how do I use it to exclude files/directories?
Could you share an example .emacs-project file?
I use M-x rgrep for this. It automatically skips a lot of things you don't want, like .svn directories.
(Updated primarily in order to include actual setup instructions for use with the below mentioned find-file-in-project.el from the RINARI distribution. Original answer left intact; the new bits come after the second horizontal rule.)
Have a look at the TextMate page of the EmacsWiki. The most promising thing they mention is probably this Emacs Lisp script, which provides recursive search under a "project directory" guided by some variables. That file begins with an extensive comments section describing how to use it.
What makes it particularly promising is the following bit:
;; If `ido-mode' is enabled, the menu will use `ido-completing-read'
;; instead of `completing-read'.
Note I haven't used it myself... Though I may very well give it a try now that I've found it! :-)
HTH.
(BTW, that script is part of -- to quote the description from GitHub -- "Rinari Is Not A Rails IDE (it is an Emacs minor mode for Rails)". If you're doing any Rails development, you might want to check out the whole thing.)
Before proceeding any further, configure ido.el. Seriously, it's a must-have on its own and it will improve your experience with find-file-in-project. See this screencast by Stuart Halloway (which I've already mentioned in a comment on this answer) to learn why you need to use it. Also, Stu demonstrates how flexible ido is by emulating TextMate's project-scoped file-finding facility in his own way; if his function suits your needs, read no further.
Ok, so here's how to set up RINARI's find-file-in-project.el:
Obtain find-file-in-project.el and project-local-variables.el from the RINARI distribution and put someplace where Emacs can find them (which means in one of the directories in the load-path variable; you can use (add-to-list 'load-path "/path/to/some/directory") to add new directories to it).
Add (require 'find-file-in-project) to your .emacs file. Also add the following to have the C-x C-M-f sequence bring up the find-file-in-project prompt: (global-set-key (kbd "C-x C-M-f") 'find-file-in-project).
Create a file called .emacs-project in your projects root directory. At a minimum it should contain something like this: (setl ffip-regexp ".*\\.\\(clj\\|py\\)$"). This will make it so that only files whose names and in clj or py will be searched for; please adjust the regex to match your needs. (Note that this regular expression will be passed to the Unix find utility and should use find's preferred regular expression syntax. You still have to double every backslash in regexes as is usual in Emacs; whether you also have to put backslashes before parens / pipes (|) if you want to use their 'magic' regex meaning depends on your find's expectations. The example given above works for me on an Ubuntu box. Look up additional info on regexes in case of doubt.) (Note: this paragraph has been revised in the last edit to fix some confusion w.r.t. regular expression syntax.)
C-x C-M-f away.
There's a number of possible customisations; in particular, you can use (setl ffip-find-options "...") to pass additional options to the Unix find command, which is what find-file-in-project.el calls out to under the hood.
If things appear not to work, please check and double check your spelling -- I did something like (setl ffip-regex ...) once (note the lack of the final 'p' in the variable name) and were initially quite puzzled to discover that no files were being found.
Surprised nobody mentioned https://github.com/defunkt/textmate.el (now gotta make it work on Windows...)
eproject has eproject-grep, which does exactly what you want.
With the right project definition, it will only search project files; it will ignore version control, build artifacts, generated files, whatever. The only downside is that it requires a grep command on your system; this dependency will be eliminated soon.
You can get the effect you want by using GNU Global or IDUtils. They are not Emacs specific, but they has Emacs scripts that integrate that effect. (I don't know too much about them myself.)
You could also opt to use CEDET and the EDE project system. EDE is probably a bit heavy weight, but it has a way to just mark the top of a project. If you also keep GNU Global or IDUtils index files with your project, EDE can use it to find a file by name anywhere, or you can use `semantic-symref' to find references to symbols in your source files. CEDET is at http://cedet.sf.net
For pure, unadulterated speed, I highly recommend a combination of the command-line tool The Silver Searcher (a.k.a. 'ag') with ag.el. The ag-project interactive function will make an educated guess of your project root if you are using git, hg or svn and search the entire project.
FileCache may also be an option. However you would need to add your project directory manually with file-cache-add-directory-recursively.
See these links for info about how Icicles can help here:
find files anywhere, matching any parts of their name (including directory parts)
projects: create, organize, manage, search them
Icicles completion matching can be substring, regexp, fuzzy (various kinds), or combinations of these. You can also combine simple patterns, intersecting the matches or complementing (subtracting) a subset of them
We're struggling to come up with a command name for our all purpose "developer helper" tool, which we are using on our project. It's like a wrapper for our existing tools like cmake and hg. The purpose of the command is really just to make our lives easier by combining multiple commands into one (for example, publishing packages). For example, we have commands like:
do conf
do build
do install
do publish
We've considered a few ambiguous names like do (as above) and run, but obviously, do is a Linux bash command and run is pretty ambiguous.
We'd like our command to be 2 chars short, preferably - but who thinks we're asking the impossible? Is there a practical way to check the availability of command names (other than just typing them into your terminal), or is it just a case of choose one and hope nobody else will use it? Are we worrying about nothing?
Since it's a "developer helper" tool why not use hm [run|build|port|deploy|test], Help Me ...
Give it a verbose name, then let everyone alias it to whatever they want. Make sure you use the verbose name in other scripts so that it removes ambiguity.
This way, each user gets to use whatever makes sense to him/her, and the scripts are more readable and more easily searchable (for example, grepping four "our_cool_tool" will usually yield better results than grepping for "run").
How many 2-character words are useful in this context? I think you need four. With that in mind, here are some suggestions.
omni
torq
fluf
mega
spif
crnk
splt
argh
quat
drul
scud
prun
sqat
zoom
sizl
I have more if you need them.
Pick one: http://en.wikipedia.org/wiki/List_of_all_two-letter_combinations
To check the availability of command names, I suggest looking for all two-letter filenames that are in the directories in your path. You can use a script like this
for item in `echo $PATH | sed 's/:/ /g'` ; do
ls -1d $item/??
done
It won't show builtins in your shell (like "do" as you mentioned) but it's a good start.
Change ?? to ??? for three-letter files, etc.
I'm going to vote for qp (quick package?) since it's easy to pronounce, easy to type, and easy to remember where the keys are on the keyboard.
I use "asd". it's short and most developers type it without thinking
(oh, and you can always claim later that it stands for some "Advanced Script for Developers" if you need to justify yourself a few years from now)
How about fu? As in Kung Fu. It's a special purpose tool. And it's really easy to type.
I think that run is a good name, at least anybody that will download your project will know what to do. Calling it without parameters should reveal your options.
Even 'do' will do, I think you can use backquotes to run it from bash scripts.
Also remember that running the tools without parameters will tell you what options you have.
Use makefiles to do everything for you.
How about calling it something descriptive, like 'build_runner', and then just aliasing it to 'br' (or preferred acronym) in your .bashrc?
There is a really crappy tool called cleartool (part of clearcase), and people will alias it on their machine to "ct". Perhaps you can have a longer command and suggest users alias it.
It would probably be best to do something like ire_and_curses suggested, name it descriptively then alias it to a 2 letter command. If I was choosing, I would name it dev_help and alias it to dh.
I think you're worrying about nothing. Install the program as 'the-command-to-do-evertyhing-and-if-you-dont-make-your-own-alias-for-it-you-should'. I don't think that will be too long for any modern filesystems, but you might need to shorten it to 'tctdeaiydmyoafiys'. See what common aliases are used, and then change the program's name to that. In other words: don't decide, let natural selection decide for you. If you are working with a team of < 10, this should not even remotely cause any problems.
Call it devtool alias to dt
Custom tools like that I like to start with the prefix 'jj-'. I can type (with big index-finger power) 'jj ' and see all my personal commands. Also, they group together in alphabetical lists. 'J' is not a very common character for built-inc commands, but you can pick your own.
Since you want two characters, you can use just 'zz', or something starting with 'z'.
Are you sure you want to put all your functionality in one command? That might be simultaneously over-constraining and over-loading the interface a little.
do conf
do build
do install
do publish
I have been using Emacs for more than three years now but it still takes me days to write even small functions in Lisp. I've looked through GNU Emacs Lisp Reference Manual but it's huge and structured completely opposite from JavaDoc, not from functions to descriptions but the other way around.
What will make my life much easier is some sort of small JavaDoc like document with most commonly used Emacs internal functions and they quick description.
(point) - returns current position in buffer
(save-excursion (p)) - saves current position in buffer before
executing (p) and restores it afterward.
Does anyone know where I can find something like that?
Have you tried the build-in manual in emacs? Open any lisp buffer (or any buffer in lisp mode), move your point to any function or variable, and hit C-h f (for function) or C-h v (for variable). Emacs will give you a fairly concise description of the function/variable.
For example, the manual content for (save-excursion) is
save-excursion is a special form in `C source code'.
(save-excursion &rest BODY)
Save point, mark, and current buffer; execute BODY; restore those things.
Executes BODY just like `progn'.
The values of point, mark and the current buffer are restored
even in case of abnormal exit (throw or error).
The state of activation of the mark is also restored.
This construct does not save `deactivate-mark', and therefore
functions that change the buffer will still cause deactivation
of the mark at the end of the command. To prevent that, bind
`deactivate-mark' with `let'.
The good thing also is the build-in manual give you "link" to to the source code of the function and to other functions that might be related, which make it nice to browse around.
Of course you can't learn lisp this way, but for looking up documentation of function this is a nice starter. When you find the build-in manual not understandable (which sometimes does happen), then it's time for you to google the function ;)
This site has some emacs lisp summary information that may be useful: http://xahlee.org/emacs/elisp.html.
In particularly, check out these links on that page: Basic Text-editing Functions, Emacs Lisp Idioms and Batch Text Processing
The GNU Introduction to emacs lisp is certainly more approachable than the reference manual.
I would add a couple of things:
M-x apropos - searches functions and variables for whatever string you specify (e.g. directory). Note that this is slightly different than C-h a, which only finds interactive functions
find a similar piece of code and copy it - you can learn an awful lot about how to do things by looking at what's already done. If you have a particular function you want to see examples of, one good way is to visit the main lisp source directory in dired (e.g. d:/product/emacs/lisp or /usr/share/lib/emacs/lisp) and do % g which will grep through all files looking for whatever string you type. Open up that file and see what other people have done with it.
C-h f and C-h v - as someone else mentioned, you can open up source, position point over a function or variable and then get documentation on it.
Check out the Emacs wiki, which has a crap-load of Emacs lisp modules for you to peruse.
I think you are taking the wrong approach. When learning a
programming language and set of libraries (collectively, "Emacs
Lisp"), you need to approach it on both the micro and macro scale.
Before you can start writing software, you need to know what tools you
have available. That is what the Emacs Lisp manual aims to educate
you on. You really need to sit down and read the whole thing. That
way you know what features Emacs provides.
After you do that, you need "micro-level" information. There are
a number of sources that provide this. If you have a general idea of
what you need to do ("working with buffers"), then the Lisp reference
is a good place to figure out what you need to know. If you know that
there's a function that does what you want, but don't quite remember
the name, then M-x apropos (C-u C-h a) will help you search the
documentation. If you know what function you want to use, but don't
remember quite how it works, then M-x describe-function (C-h f)
will sort that out for you.
So anyway, the key is to learn Emacs Lisp, and then let Emacs help you
with the details. A list of functions isn't going to teach you much.
(Oh, one more thing -- you should familiarize yourself with Common
Lisp. Most Emacs libraries use cl, which are the useful CL
functions implemented in Emacs Lisp. loop, destructuring-bind,
defun*, and so on are all there, and they are very helpful.)
Good suggestions from others -- Emacs help system is your friend.
In addition:
http://www.emacswiki.org/emacs/EmacsNewbieWithIcicles
http://www.emacswiki.org/emacs/Icicles_-_Progressive_Completion
http://www.emacswiki.org/emacs/Icicles_-_Nutshell_View#ChippingAway
In order to understand what's on, quite often it's useful having a look at the source code.
http://repo.or.cz/w/elbb.git/blob/HEAD:/code/Go-to-Emacs-Lisp-Definition.el
Have you tryed <f1> f ? It is bound to describe-function. Example with point:
point is a built-in function in C source code.
(point)
Return value of point, as an integer.
Beginning of buffer is position (point-min).
[back]
Like most Lisp systeme, Emacs has an integrated documentation tool!
Any Lisp function or variable can declare an optional doc string.
Almost all standard command or function do declare a usefull doc string.
Emacs (like most Lisp systems) allows you to display the doc string of any function or variable (<f1> f and <f1> v) at any time.
When displayed, the doc string is browsable, meaning that you can click on symbols to see their doc string, or go to the source of the corresponding function or variable.
As soon as you evaluate any defun or defvar, its doc string is available through describe-function or describe-variable: this doc is alive!
M-x find-library RET <library name> is all you really need
If you're willing to fork over money for a dead tree, I'd recommend
(source: oreilly.com)
In XEmacs, and I believe in Emacs as well,
pressing C-h f, then the tab key for tab completion, which at that point is all functions, will give you a list of functions the editor knows about.
You just use cursor keys and scroll to one you want to know about and press enter to see details.
If a list of functions, with further info available, is what you want, that will give it to you.
This list is all currently available functions, so if you have packages of lisp installed, it shows the functions those packages supply as well as native functions. In my copy of XEmacs, today, I have 6,586 functions in the list. Emacs will be similar.
The problem is that not all functions have names that make them context-meaningful (ie not all menu variables/functions have the word menu in them, so you will miss some things if you go by names only.
You can use the INFO pages (on the menu) to view them more topically arranged, and get to the same usage information.
Download source code for Emacs. Go to src/ folder and type:
grep -r DEFUN *
You will get list of all primitive Lisp functions of Emacs.