4 ms·

Don't forget that since you can safely assume somebody learning emacs lisp is using emacs. You could provide some text as a commented emacs lisp buffer that can

Don't forget that since you can safely assume somebody learning emacs lisp is using emacs. You could provide some text as a commented emacs lisp buffer that can be evaluated in place, like a variant of literate programming.

gordonguthrie 16y ago
One of the problems that I am trying to solve is 'finding the information' so using a traditional HTML/PDF documentation generating package (Sphinx from Python Docs) is the way I decided to go. That is why there is a big focus on 'key words in URL's' and link-juice and so on and so forth... I also need to write a set of documentation for another project that couldn't be evaluated in place as a commented lisp buffer and this is kind of a practice for that, so...
- silentbicycle 16y ago
  No worries, just a suggestion.
jrockway 16y ago
And, Emacs comes with documentation on both Elisp and every built-in feature of Emacs itself... but apparently nobody reads that. It really confuses me, as the built-in documentation is like the whole point of Emacs...
- silentbicycle 16y ago
  No kidding! I've led a couple sessions where I've taught other developers how to use Emacs (basic or advanced usage), and I continually emphasize that the built-in help system (including info) is very good. You just have to get comfortable with the idiosyncratic terminology, and you can pick up half of that just from the C-h t tutorial.
  - gordonguthrie 16y ago
    I can't make the help documentation work in Emacs - and I use it every day and have done for 6 or 7 years... I can open it but I don't know how the navigation works.
    - silentbicycle 16y ago
      Press C-h C-h (or type M-x help) and look at the menu that comes up. These are the essential ones, IMHO (I cut out about half): You have typed M-x h e l p, the help character. Type a Help option: (Use SPC or DEL to scroll through this text. Type q to exit the Help command.) a command-apropos. Give a substring, and see a list of commands (functions interactively callable) that contain that substring. See also the apropos command. f describe-function. Type a function name and get documentation of it. i info. The info documentation reader. k describe-key. Type a command key sequence; it displays the full documentation. m describe-mode. Print documentation of current minor modes, and the current major mode, including their special commands. t help-with-tutorial. Select the Emacs learn-by-doing tutorial. v describe-variable. Type name of a variable; it displays the variable's documentation and value. w where-is. Type command name; it prints which keystrokes invoke that command. For example, type C-h a (command-apropos) and then type "compile". That brings up a list of commands with "compile" in their name. Each is also a hyperlink; moving the cursor to them and pressing Enter brings you to their documentation, which also usually includes a link to their definition in elisp. "apropos" is a good example of using an idiosyncratic term used by the help system. Also: kill-ring, "window" vs. "frame", "point". You just need to learn these, but you can pick them up from the tutorial and Emacs docs in the info pages. (Most of the terms come out of old Lisp culture, AFAICT.)
eschulte 16y ago
also Emacs has a build-in (as of Emacs 24) mode which exports to pdf and html, and allows code snippets to be evaluated /in-situ/ -- see http://orgmode.org http://orgmode.org
- gordonguthrie 16y ago
  That might have been the way to do it, but I started in Sphinx and 'tis done

gordonguthrie 16y ago

One of the problems that I am trying to solve is 'finding the information' so using a traditional HTML/PDF documentation generating package (Sphinx from Python Docs) is the way I decided to go. That is why there is a big focus on 'key words in URL's' and link-juice and so on and so forth... I also need to write a set of documentation for another project that couldn't be evaluated in place as a commented lisp buffer and this is kind of a practice for that, so...

silentbicycle 16y ago
No worries, just a suggestion.

jrockway 16y ago

And, Emacs comes with documentation on both Elisp and every built-in feature of Emacs itself... but apparently nobody reads that. It really confuses me, as the built-in documentation is like the whole point of Emacs...

silentbicycle 16y ago
No kidding! I've led a couple sessions where I've taught other developers how to use Emacs (basic or advanced usage), and I continually emphasize that the built-in help system (including info) is very good. You just have to get comfortable with the idiosyncratic terminology, and you can pick up half of that just from the C-h t tutorial.
- gordonguthrie 16y ago
  I can't make the help documentation work in Emacs - and I use it every day and have done for 6 or 7 years... I can open it but I don't know how the navigation works.
  - silentbicycle 16y ago
    Press C-h C-h (or type M-x help) and look at the menu that comes up. These are the essential ones, IMHO (I cut out about half): You have typed M-x h e l p, the help character. Type a Help option: (Use SPC or DEL to scroll through this text. Type q to exit the Help command.) a command-apropos. Give a substring, and see a list of commands (functions interactively callable) that contain that substring. See also the apropos command. f describe-function. Type a function name and get documentation of it. i info. The info documentation reader. k describe-key. Type a command key sequence; it displays the full documentation. m describe-mode. Print documentation of current minor modes, and the current major mode, including their special commands. t help-with-tutorial. Select the Emacs learn-by-doing tutorial. v describe-variable. Type name of a variable; it displays the variable's documentation and value. w where-is. Type command name; it prints which keystrokes invoke that command. For example, type C-h a (command-apropos) and then type "compile". That brings up a list of commands with "compile" in their name. Each is also a hyperlink; moving the cursor to them and pressing Enter brings you to their documentation, which also usually includes a link to their definition in elisp. "apropos" is a good example of using an idiosyncratic term used by the help system. Also: kill-ring, "window" vs. "frame", "point". You just need to learn these, but you can pick them up from the tutorial and Emacs docs in the info pages. (Most of the terms come out of old Lisp culture, AFAICT.)

eschulte 16y ago

also Emacs has a build-in (as of Emacs 24) mode which exports to pdf and html, and allows code snippets to be evaluated /in-situ/ -- see http://orgmode.org http://orgmode.org

gordonguthrie 16y ago
That might have been the way to do it, but I started in Sphinx and 'tis done