It's a rather simple question, but I can't find the answer anywhere.
The Emacs documentation suggests to save macros in the .emacs file. Is there a convenient way to save macros in Spacemacs? Which file should I use?
You have two options. You can save your macros :
in your .spacemacs file, in the dotspacemacs/user-config function
in a private configuration layer (see documentation)
Related
I've been using Org-mode a few months, and as I customize Emacs, I'm having a lot of difficulty finding documentation on how to specifically customize various variables.
Example: I've successfully set up archiving, but want to customize the org-archive-save-context-info variable to reduce the info that's archived along with the task. I do not want to do this per-file, but in my config file. Despite my best efforts, I don't see documentation on syntax and parameters for customizing this.
I do see some documentation when I customize the variable in the Emacs UI--but I'm looking for documentation so I can see syntax and parameters for customizing this myself via a config file. I can learn it backwards this way (via 'easy customization'): customize a variable, see what Emacs wrote to the config, try tweaking that, etc.
[EDIT] I'm talking about info below the task that appears after archiving, like this:
:PROPERTIES:
:ARCHIVE_TIME: 2018-09-10 Mon 11:24
:ARCHIVE_FILE: ~/Dropbox/logs/capture.org
:ARCHIVE_OLPATH: Tasks
:ARCHIVE_CATEGORY: capture
:ARCHIVE_TODO: DONE
:END:
Is this intentional? Do I just need to 'know ELisp' first? Is the intention that you use the Emacs point-and-click UI to customize things like this? Happy to RTFM if I could find the FM.
Is the intention that you use the Emacs point-and-click UI to customize things like this?
It's certainly intended that you would use the customize interface if you don't know elisp (and you might well choose to use it even if you do).
Do I just need to 'know ELisp' first?
Yes, you'll need at least some familiarity with elisp in order to understand the documentation and be able to write your own config changes. This is because elisp is the configuration language for Emacs, and so the documentation is written in that context. (It wouldn't make sense for basic lisp concepts to be explained and repeated in every piece of documentation which used them.)
That said, many people get by just copying and pasting from config examples -- and you're likely to pick up the basics this way, even if you don't fully understand them. If you're serious about Emacs, though, spending some time to learn about elisp will be hugely beneficial to you in future.
I can learn it backwards this way (via 'easy customization'): customize a variable, see what Emacs wrote to the config, try tweaking that, etc.
That's an entirely reasonable thing to do.
FWIW C-hv org-archive-save-context-info is actually very clear if you have the background understanding.
This variable can be a list of any of the following symbols:
time The time of archiving.
file The file where the entry originates.
ltags The local tags, in the headline of the subtree.
itags The tags the subtree inherits from further up the hierarchy.
todo The pre-archive TODO state.
category The category, taken from file name or #+CATEGORY lines.
olpath The outline path to the item. These are all headlines above
the current item, separated by /, like a file path.
That tells you that you might use the following in your config file:
(setq org-archive-save-context-info '(time file todo))
Happy to RTFM if I could find the FM.
You can start learning about elisp in the "Emacs Lisp Intro" manual, which you should find near the top of the Info directory, or jump to directly with C-hig (eintr) RET. Type h from there if you need to learn how to use the Info reader.
When learning a new programming language, "read source code" is a common advice received by the experts. However, with such a huge system like emacs, build over decades by many people, it is not so easy for the beginner to figure out which libraries are the best examples of idiomatic Elisp progamming. Therefore I would like to get some recommendations with regards to the following criteria:
idiomatic elisp programming style
adherence to emacs programming guidelines
clever use of the cl-package in accordance to emacs guidelines
clever use of eieio-package
exemplary organisation of a single .el file library
exemplary organisation of a multi-file/multi-package library
any criteria you consider important
Giving the reasons why you recommend certain libraries for auto-didactic studies would certainly be informative to beginners in Emacs lisp programming.
As Trey said, use the elisp from Emacs itself to learn. I usually do one of two things:
1) If I'm trying to find out how to use a specific function, I'll bring up a dired window and do:
% g foobar
where foobar is the name of the function I'm interested in learning how to use. That will mark all of the files that use foobar and then I go and search through them to see how to call it, in what context it's being called, etc.
2) If I'm trying to figure out how to do something, and I know a mode that does something similar, I'll go look at that mode's source code to see how they do it. If you don't know where to start, but you know how to execute what it is you want to do, a handy thing to do is to look it up by key-binding. For example, in a dired buffer, do the following:
C-h k % g
and that will bring up:
% g runs the command dired-mark-files-containing-regexp, which is an
% interactive compiled Lisp function in `dired.el'.
It is bound to % g, <menu-bar> <regexp> <mark-cont>.
(dired-mark-files-containing-regexp regexp &optional marker-char)
Mark all files with contents containing regexp for use in later
commands. A prefix argument means to unmark them instead.
`.' and `..' are never marked.
Clicking on dired.el in the above text (in an emacs buffer) will open up the source code and take you right to that function definition. It's a great way to learn by example.
Don't forget the elisp debugger as a way to see exactly what's going on and following along as the code executes step-by-step. You can mark the code for debugging using edebug-defun and then invoke it as usual, at which point emacs will step you through the code.
The source code I'd recommend would be that of Emacs itself. Start off with the simple stuff (pun intended), and look at other files as you are wont.
M-x find-library simple RET
I think it's self-explanatory as to why Emacs' own lisp code is a good example of Emacs lisp.
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.
GNU Emacs 23.1.1
I am maintaining someones code. There are many files and directories for the headers and source files.
I am wondering if there is a easy way to use emacs that when I highlight a variable name I can go straight to where it is declared?
Some of the structures I am working in are declared in other header files, rather than go searching for them, I just want to be taken straight to them.
Many thanks for any suggestions,
Look into the etags command which builds a tags database. Once the tag DB is built and loaded, you can use M-. on any keyword to jump directly to the definition.
It's also pretty easy to hit C-h v RET on the variable name, to get its *Help*, then hit RET (or click) the file-name link to get to the source definition.
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.